引言在上一篇《OpenClaw基础入门从“养虾”概念到第一个智能体程序》中我们成功搭建了OpenClaw的开发环境并运行了第一个简单的交互任务。那只“小龙虾”已经能听懂我们的话并且动手创建了文件。但是你是否好奇过它背后的运行逻辑为什么它能像搭积木一样组合各种能力如果你希望从“使用者”进阶为“开发者”真正掌握OpenClaw的编程模型那么这篇文章就是为你准备的。今天我们将深入OpenClaw的核心概念与基本语法彻底搞懂数据类型、配置文件、节点、主题、服务这些基础构件。最后我们将亲手编写一个完整的控制程序让我们的智能体具备更复杂的协作能力。无论你是AI初学者还是寻求自动化提效的开发者这篇文章都将为你打开一扇新的大门。一、OpenClaw的数据结构与类型系统任何编程都离不开数据。OpenClaw作为一个智能体框架其内部流转的数据不仅有传统的编程语言类型还扩展了适合AI场景的特殊类型。理解这些类型是编写可靠技能的前提。1.1 基础数据类型OpenClaw的核心运行时Pi Runtime采用Python实现因此天然支持Python的所有基础类型。但在配置文件和跨语言通信如Node.js Gateway与Python技能之间时OpenClaw定义了一套标准化的数据交换格式通常是JSON兼容的。字符串String用于表示文本消息、文件路径、命令等。整数Integer和浮点数Float用于数值计算、配置参数。布尔值Booleantrue/false用于开关控制。列表Array有序集合例如技能参数列表、权限列表。字典Object键值对用于复杂配置和结构化数据。1.2 扩展的AI专用类型为了让AI更好地理解上下文OpenClaw引入了一些语义化的数据类型Message消息这是最核心的通信单元。一条消息包含id全局唯一标识。timestamp时间戳。from/to发送者和接收者通常是节点或主题。type消息类型textcommandeventerror等。payload实际内容可以是任意基础类型。metadata元数据如来源技能、会话ID等。Skill技能描述当AI需要调用某个功能时它会收到一个技能描述对象。该对象包含name技能名称。description技能的功能描述供AI理解。parameters参数列表每个参数包含名称、类型、描述、是否必需。command实际执行的命令或函数入口。NodeInfo节点信息描述一个执行节点的状态包括idnametypelocal/docker/ssh。statusonline/offline/busy。capabilities该节点支持的能力列表如“文件操作”“网络请求”。Topic主题实际上主题本身不是一个数据值而是一个字符串标识符但我们可以将其视为一种“地址类型”。在消息路由中主题用于过滤和分发。1.3 类型系统的作用这种明确的类型系统有两个好处AI理解更准确大模型通过读取参数的类型和描述能更准确地生成调用参数。跨语言互操作Python写的技能可以被Node.js网关调用底层通过JSON序列化保证类型不失真。二、配置文件的结构与编写方法OpenClaw的配置体系是其灵活性的关键。几乎所有的实体——智能体、节点、技能、服务——都可以通过YAML或JSON文件进行声明式配置。2.1 配置文件的位置与加载默认情况下OpenClaw会在用户目录下的.openclaw/config/中查找配置文件。你也可以通过环境变量OPENCLAW_CONFIG_DIR指定其他路径。主要配置文件包括agent.yaml定义智能体的全局设置。nodes.yaml注册可用的执行节点。skills.yaml声明加载的技能。topics.yaml定义主题的权限和路由规则。2.2 YAML语法快速入门OpenClaw偏好YAML因为它更易读。如果你不熟悉YAML只需记住几条规则缩进表示层级使用空格不能用Tab。key value形式冒号后必须有空格。列表用短横线-开头。注释用#。例如# 一个简单的技能配置skills-name file_operator path ./skills/file_operator enabled true permissions-read-write2.3 编写一个完整的智能体配置文件让我们通过一个实际例子来学习配置文件的各个部分。假设我们要创建一个名为“MyBot”的智能体它能监听特定主题并调用文件操作技能。agent.yamlname MyBot description 一个测试用的文件操作智能体 version 1.0.0# 基础设置settings language zh-CN timezone Asia/Shanghai log_level info# 模型配置支持多种LLMmodel provider openai# 可选 openai, deepseek, ollama, claudemodel_name gpt-3.5-turbo api_key ${OPENAI_API_KEY}# 支持环境变量引用parameters temperature 0.7 max_tokens 2000# 连接的节点nodes-local_node# 引用 nodes.yaml 中定义的节点# 启用的技能skills-file_operator# 引用 skills.yaml 中定义的技能# 主题订阅topics subscribe-topic “command/file” handler file_operator.handle_command# 指定处理函数# 服务后台任务services-name heartbeat schedule “*/5* * **”# 每5分钟一次action system.heartbeatnodes.yaml同级目录下nodes-id local_node name 本地节点 type local work_dir /home/user/openclaw_workspace max_concurrent_tasks 5skills.yamlskills-id file_operator name 文件操作器 entry file_operatormain# Python模块函数description 提供文件的读写、删除、列表功能 parameters-name operation type string description 操作类型可选 read/write/delete/list required true-name path type string description 文件路径 required true-name content type string description 写入的内容当operationwrite时需要 required false permissions-filesystemread-filesystemwrite2.4 配置文件的加载优先级OpenClaw支持多层配置覆盖默认值 → 基础配置文件 → 环境变量 → 命令行参数。这种设计使得在不同环境开发、测试、生产之间切换变得非常容易。三、核心概念深度解析节点、主题、服务掌握了配置语法后我们需要理解这些配置背后代表的物理意义。节点、主题、服务是OpenClaw分布式架构的三大支柱。3.1 节点Node能力的物理载体节点是实际执行任务的进程或容器。OpenClaw的设计哲学是“计算靠近数据”——你可以将任务调度到不同的节点上以实现负载均衡或数据本地化。节点类型本地节点与Gateway运行在同一台机器上通过本地进程调用。Docker节点在Docker容器中执行任务提供环境隔离。SSH节点通过SSH连接到远程服务器执行命令用于管理云端资源。Kubernetes节点在K8s Pod中运行适合大规模集群。节点生命周期节点启动时向Gateway注册报告自己的能力和负载。Gateway通过心跳检测节点存活状态。当任务到来时Gateway根据调度策略选择合适的节点。节点配置示例Docker节点-id docker_node type docker image python3.10-slim command[“python” “-m” “openclaw.node”]volumes-/host/data/data environment-ENVproduction3.2 主题Topic消息的通信总线主题是OpenClaw中实现松耦合通信的关键机制。它类似于MQTT的主题或Redis的发布/订阅频道。工作原理任何组件技能、服务、外部系统都可以向一个主题发布消息。订阅了该主题的组件会收到消息的副本。主题支持通配符如command/#匹配所有以command/开头的主题。主题的用途任务分发Gateway将用户指令发布到task/主题多个工作节点订阅并竞争处理。事件通知技能执行完毕后可以向event/task_done发布完成事件供其他服务监听。日志聚合所有节点将日志发布到log/主题由中心日志服务收集。权限控制在topics.yaml中可以定义谁可以发布/订阅某个主题实现安全隔离。3.3 服务Service后台的守护者服务是一种长期运行的、自主触发的任务。它们不是由用户指令直接启动的而是基于时间、事件或条件自动执行。服务类型定时服务类似Cron按设定的时间间隔执行。监听服务监听某个主题当有消息到达时触发。条件服务监控系统状态如CPU负载、文件变化满足条件时执行。服务配置示例定时清理服务services-name temp_cleaner type cron schedule “0 2 * **”# 每天凌晨2点action file_operator.clean_temp parameters path /tmp older_than 7d服务与技能的对比技能是被动调用的服务于用户的即时请求。服务是主动运行的服务于系统的自动化需求。四、实战编写第一个控制程序理论讲得再多不如动手写一个程序。我们将创建一个由两个智能体组成的协作系统Commander负责接收用户指令通过Web界面解析后发布到主题。Worker订阅指令主题执行实际操作比如创建文件、查询天气。这样设计体现了OpenClaw的核心思想解耦与分布式执行。4.1 环境准备确保你已完成上一篇的环境搭建。我们将在一个项目目录中工作mkdirmy_openclaw_projectcdmy_openclaw_project4.2 定义配置文件agent_commander.yamlname Commander description 指令分发智能体 version 1.0.0 model provider openai model_name gpt-3.5-turbo api_key ${OPENAI_API_KEY}nodes-local_node skills-command_parser# 自定义技能topics publish-topic “command/#” # 允许发布到所有command/子主题subscribe-topic “event/result”# 监听执行结果handler commander.handle_result services-name web_interface type http port 8080 endpoint /command method POST action commander.web_handleragent_worker.yamlname Worker description 任务执行智能体 version 1.0.0 model provider ollama# 使用本地模型节省成本model_name llama3 nodes-local_node skills-file_operator-weather_query topics subscribe-topic “command/create_file” handler file_operator.create-topic “command/weather” handler weather_query.get publish-topic “event/result”nodes.yaml共用nodes-id local_node type local work_dir ./workspace4.3 编写自定义技能技能就是普通的Python模块。我们在skills/command_parser.py中编写Commander的解析逻辑# skills/command_parser.pyimportrefromopenclaw.skillimportSkillclassCommandParser(Skill)asyncdefhandle(self,message) 解析用户自然语言指令决定发布到哪个主题 textmessage.payload.get(text,)# 简单的规则匹配ifre.search(r创建文件|新建文件,text)# 提取文件名和内容示例中简化处理filenamere.findall(r文件\s*(\S),text)contentre.findall(r内容\s*[是为]?\s*(.),text)payload{path filename[0]iffilenameelsedefault.txt,content content[0]ifcontentelse}awaitself.publish(command/create_file,payload)return{statusok,message任务已分发}elifre.search(r天气|气温,text) cityre.findall(r([\u4e00-\u9fa5])天气,text)payload{city city[0]ifcityelse北京}awaitself.publish(command/weather,payload)return{statusok,messagef正在查询{payload[city]}天气}elsereturn{statuserror,message无法理解指令}asyncdefpublish(self,topic,payload)# 实际发送消息到主题awaitself.context.gateway.publish(topic,payload)注册技能在skills.yaml中添加skills-id command_parser name 指令解析器 entry command_parserCommandParser description 解析用户指令并分发给对应主题-id file_operator# ... 同上-id weather_query name 天气查询 entry weather_queryWeatherQuery description 查询指定城市天气4.4 启动并测试首先启动Gateway如果未运行openclaw gateway start然后分别启动两个智能体可以在两个终端或使用进程管理工具# 终端1启动Commanderopenclaw agent start--configagent_commander.yaml# 终端2启动Workeropenclaw agent start--configagent_worker.yaml现在通过Commander提供的HTTP接口或直接通过OpenClaw Web UI发送指令。例如用curl模拟用户请求curl-XPOST http//localhost8080/command\-H“Content-Type application/json”\-d‘{“text” “帮我创建文件 test.txt内容为 Hello World”}’你应该会收到类似{“status”“ok”“message”“任务已分发”}的响应。然后检查Worker的工作目录./workspace下是否生成了test.txt文件内容是否正确。4.5 观察消息流为了更直观地理解主题通信可以开启OpenClaw的调试模式查看消息流转日志。你会在日志中看到Commander收到用户请求发布消息到command/create_file。Worker订阅了该主题收到消息后调用file_operator.create。文件创建完成后Worker发布结果到event/result。Commander订阅了event/result收到结果后可能通过Web界面反馈给用户。这样一个完整的控制-执行-反馈闭环就形成了。五、总结与进阶预告通过本文的学习你已经掌握了OpenClaw的核心编程模型数据类型让AI和组件之间能够精确沟通。配置文件让你能以声明式的方式定义智能体的行为。节点、主题、服务构成了分布式、可扩展的智能体网络。实战演练让你亲手搭建了一个多智能体协作系统。这只是一个开始。在后续的系列文章中我们将深入更高级的主题如何开发复杂的自定义技能包括调用外部API、操作数据库、处理音视频。智能体的记忆与学习利用长期记忆让AI越用越聪明。安全与权限控制如何保护你的数字员工不被滥用。大规模部署使用Kubernetes管理成百上千个智能体。OpenClaw的世界充满了可能性。希望这篇文章能成为你探索之路上的坚实基石。如果你在实践过程中遇到任何问题欢迎在评论区留言交流。记住每一个成功的自动化背后都有一只默默工作的“龙虾”。现在轮到你来指挥它们了
OpenClaw核心概念与基本语法：从零掌握节点、主题与服务，写出第一个控制程序
发布时间：2026/7/29 22:45:04
引言在上一篇《OpenClaw基础入门从“养虾”概念到第一个智能体程序》中我们成功搭建了OpenClaw的开发环境并运行了第一个简单的交互任务。那只“小龙虾”已经能听懂我们的话并且动手创建了文件。但是你是否好奇过它背后的运行逻辑为什么它能像搭积木一样组合各种能力如果你希望从“使用者”进阶为“开发者”真正掌握OpenClaw的编程模型那么这篇文章就是为你准备的。今天我们将深入OpenClaw的核心概念与基本语法彻底搞懂数据类型、配置文件、节点、主题、服务这些基础构件。最后我们将亲手编写一个完整的控制程序让我们的智能体具备更复杂的协作能力。无论你是AI初学者还是寻求自动化提效的开发者这篇文章都将为你打开一扇新的大门。一、OpenClaw的数据结构与类型系统任何编程都离不开数据。OpenClaw作为一个智能体框架其内部流转的数据不仅有传统的编程语言类型还扩展了适合AI场景的特殊类型。理解这些类型是编写可靠技能的前提。1.1 基础数据类型OpenClaw的核心运行时Pi Runtime采用Python实现因此天然支持Python的所有基础类型。但在配置文件和跨语言通信如Node.js Gateway与Python技能之间时OpenClaw定义了一套标准化的数据交换格式通常是JSON兼容的。字符串String用于表示文本消息、文件路径、命令等。整数Integer和浮点数Float用于数值计算、配置参数。布尔值Booleantrue/false用于开关控制。列表Array有序集合例如技能参数列表、权限列表。字典Object键值对用于复杂配置和结构化数据。1.2 扩展的AI专用类型为了让AI更好地理解上下文OpenClaw引入了一些语义化的数据类型Message消息这是最核心的通信单元。一条消息包含id全局唯一标识。timestamp时间戳。from/to发送者和接收者通常是节点或主题。type消息类型textcommandeventerror等。payload实际内容可以是任意基础类型。metadata元数据如来源技能、会话ID等。Skill技能描述当AI需要调用某个功能时它会收到一个技能描述对象。该对象包含name技能名称。description技能的功能描述供AI理解。parameters参数列表每个参数包含名称、类型、描述、是否必需。command实际执行的命令或函数入口。NodeInfo节点信息描述一个执行节点的状态包括idnametypelocal/docker/ssh。statusonline/offline/busy。capabilities该节点支持的能力列表如“文件操作”“网络请求”。Topic主题实际上主题本身不是一个数据值而是一个字符串标识符但我们可以将其视为一种“地址类型”。在消息路由中主题用于过滤和分发。1.3 类型系统的作用这种明确的类型系统有两个好处AI理解更准确大模型通过读取参数的类型和描述能更准确地生成调用参数。跨语言互操作Python写的技能可以被Node.js网关调用底层通过JSON序列化保证类型不失真。二、配置文件的结构与编写方法OpenClaw的配置体系是其灵活性的关键。几乎所有的实体——智能体、节点、技能、服务——都可以通过YAML或JSON文件进行声明式配置。2.1 配置文件的位置与加载默认情况下OpenClaw会在用户目录下的.openclaw/config/中查找配置文件。你也可以通过环境变量OPENCLAW_CONFIG_DIR指定其他路径。主要配置文件包括agent.yaml定义智能体的全局设置。nodes.yaml注册可用的执行节点。skills.yaml声明加载的技能。topics.yaml定义主题的权限和路由规则。2.2 YAML语法快速入门OpenClaw偏好YAML因为它更易读。如果你不熟悉YAML只需记住几条规则缩进表示层级使用空格不能用Tab。key value形式冒号后必须有空格。列表用短横线-开头。注释用#。例如# 一个简单的技能配置skills-name file_operator path ./skills/file_operator enabled true permissions-read-write2.3 编写一个完整的智能体配置文件让我们通过一个实际例子来学习配置文件的各个部分。假设我们要创建一个名为“MyBot”的智能体它能监听特定主题并调用文件操作技能。agent.yamlname MyBot description 一个测试用的文件操作智能体 version 1.0.0# 基础设置settings language zh-CN timezone Asia/Shanghai log_level info# 模型配置支持多种LLMmodel provider openai# 可选 openai, deepseek, ollama, claudemodel_name gpt-3.5-turbo api_key ${OPENAI_API_KEY}# 支持环境变量引用parameters temperature 0.7 max_tokens 2000# 连接的节点nodes-local_node# 引用 nodes.yaml 中定义的节点# 启用的技能skills-file_operator# 引用 skills.yaml 中定义的技能# 主题订阅topics subscribe-topic “command/file” handler file_operator.handle_command# 指定处理函数# 服务后台任务services-name heartbeat schedule “*/5* * **”# 每5分钟一次action system.heartbeatnodes.yaml同级目录下nodes-id local_node name 本地节点 type local work_dir /home/user/openclaw_workspace max_concurrent_tasks 5skills.yamlskills-id file_operator name 文件操作器 entry file_operatormain# Python模块函数description 提供文件的读写、删除、列表功能 parameters-name operation type string description 操作类型可选 read/write/delete/list required true-name path type string description 文件路径 required true-name content type string description 写入的内容当operationwrite时需要 required false permissions-filesystemread-filesystemwrite2.4 配置文件的加载优先级OpenClaw支持多层配置覆盖默认值 → 基础配置文件 → 环境变量 → 命令行参数。这种设计使得在不同环境开发、测试、生产之间切换变得非常容易。三、核心概念深度解析节点、主题、服务掌握了配置语法后我们需要理解这些配置背后代表的物理意义。节点、主题、服务是OpenClaw分布式架构的三大支柱。3.1 节点Node能力的物理载体节点是实际执行任务的进程或容器。OpenClaw的设计哲学是“计算靠近数据”——你可以将任务调度到不同的节点上以实现负载均衡或数据本地化。节点类型本地节点与Gateway运行在同一台机器上通过本地进程调用。Docker节点在Docker容器中执行任务提供环境隔离。SSH节点通过SSH连接到远程服务器执行命令用于管理云端资源。Kubernetes节点在K8s Pod中运行适合大规模集群。节点生命周期节点启动时向Gateway注册报告自己的能力和负载。Gateway通过心跳检测节点存活状态。当任务到来时Gateway根据调度策略选择合适的节点。节点配置示例Docker节点-id docker_node type docker image python3.10-slim command[“python” “-m” “openclaw.node”]volumes-/host/data/data environment-ENVproduction3.2 主题Topic消息的通信总线主题是OpenClaw中实现松耦合通信的关键机制。它类似于MQTT的主题或Redis的发布/订阅频道。工作原理任何组件技能、服务、外部系统都可以向一个主题发布消息。订阅了该主题的组件会收到消息的副本。主题支持通配符如command/#匹配所有以command/开头的主题。主题的用途任务分发Gateway将用户指令发布到task/主题多个工作节点订阅并竞争处理。事件通知技能执行完毕后可以向event/task_done发布完成事件供其他服务监听。日志聚合所有节点将日志发布到log/主题由中心日志服务收集。权限控制在topics.yaml中可以定义谁可以发布/订阅某个主题实现安全隔离。3.3 服务Service后台的守护者服务是一种长期运行的、自主触发的任务。它们不是由用户指令直接启动的而是基于时间、事件或条件自动执行。服务类型定时服务类似Cron按设定的时间间隔执行。监听服务监听某个主题当有消息到达时触发。条件服务监控系统状态如CPU负载、文件变化满足条件时执行。服务配置示例定时清理服务services-name temp_cleaner type cron schedule “0 2 * **”# 每天凌晨2点action file_operator.clean_temp parameters path /tmp older_than 7d服务与技能的对比技能是被动调用的服务于用户的即时请求。服务是主动运行的服务于系统的自动化需求。四、实战编写第一个控制程序理论讲得再多不如动手写一个程序。我们将创建一个由两个智能体组成的协作系统Commander负责接收用户指令通过Web界面解析后发布到主题。Worker订阅指令主题执行实际操作比如创建文件、查询天气。这样设计体现了OpenClaw的核心思想解耦与分布式执行。4.1 环境准备确保你已完成上一篇的环境搭建。我们将在一个项目目录中工作mkdirmy_openclaw_projectcdmy_openclaw_project4.2 定义配置文件agent_commander.yamlname Commander description 指令分发智能体 version 1.0.0 model provider openai model_name gpt-3.5-turbo api_key ${OPENAI_API_KEY}nodes-local_node skills-command_parser# 自定义技能topics publish-topic “command/#” # 允许发布到所有command/子主题subscribe-topic “event/result”# 监听执行结果handler commander.handle_result services-name web_interface type http port 8080 endpoint /command method POST action commander.web_handleragent_worker.yamlname Worker description 任务执行智能体 version 1.0.0 model provider ollama# 使用本地模型节省成本model_name llama3 nodes-local_node skills-file_operator-weather_query topics subscribe-topic “command/create_file” handler file_operator.create-topic “command/weather” handler weather_query.get publish-topic “event/result”nodes.yaml共用nodes-id local_node type local work_dir ./workspace4.3 编写自定义技能技能就是普通的Python模块。我们在skills/command_parser.py中编写Commander的解析逻辑# skills/command_parser.pyimportrefromopenclaw.skillimportSkillclassCommandParser(Skill)asyncdefhandle(self,message) 解析用户自然语言指令决定发布到哪个主题 textmessage.payload.get(text,)# 简单的规则匹配ifre.search(r创建文件|新建文件,text)# 提取文件名和内容示例中简化处理filenamere.findall(r文件\s*(\S),text)contentre.findall(r内容\s*[是为]?\s*(.),text)payload{path filename[0]iffilenameelsedefault.txt,content content[0]ifcontentelse}awaitself.publish(command/create_file,payload)return{statusok,message任务已分发}elifre.search(r天气|气温,text) cityre.findall(r([\u4e00-\u9fa5])天气,text)payload{city city[0]ifcityelse北京}awaitself.publish(command/weather,payload)return{statusok,messagef正在查询{payload[city]}天气}elsereturn{statuserror,message无法理解指令}asyncdefpublish(self,topic,payload)# 实际发送消息到主题awaitself.context.gateway.publish(topic,payload)注册技能在skills.yaml中添加skills-id command_parser name 指令解析器 entry command_parserCommandParser description 解析用户指令并分发给对应主题-id file_operator# ... 同上-id weather_query name 天气查询 entry weather_queryWeatherQuery description 查询指定城市天气4.4 启动并测试首先启动Gateway如果未运行openclaw gateway start然后分别启动两个智能体可以在两个终端或使用进程管理工具# 终端1启动Commanderopenclaw agent start--configagent_commander.yaml# 终端2启动Workeropenclaw agent start--configagent_worker.yaml现在通过Commander提供的HTTP接口或直接通过OpenClaw Web UI发送指令。例如用curl模拟用户请求curl-XPOST http//localhost8080/command\-H“Content-Type application/json”\-d‘{“text” “帮我创建文件 test.txt内容为 Hello World”}’你应该会收到类似{“status”“ok”“message”“任务已分发”}的响应。然后检查Worker的工作目录./workspace下是否生成了test.txt文件内容是否正确。4.5 观察消息流为了更直观地理解主题通信可以开启OpenClaw的调试模式查看消息流转日志。你会在日志中看到Commander收到用户请求发布消息到command/create_file。Worker订阅了该主题收到消息后调用file_operator.create。文件创建完成后Worker发布结果到event/result。Commander订阅了event/result收到结果后可能通过Web界面反馈给用户。这样一个完整的控制-执行-反馈闭环就形成了。五、总结与进阶预告通过本文的学习你已经掌握了OpenClaw的核心编程模型数据类型让AI和组件之间能够精确沟通。配置文件让你能以声明式的方式定义智能体的行为。节点、主题、服务构成了分布式、可扩展的智能体网络。实战演练让你亲手搭建了一个多智能体协作系统。这只是一个开始。在后续的系列文章中我们将深入更高级的主题如何开发复杂的自定义技能包括调用外部API、操作数据库、处理音视频。智能体的记忆与学习利用长期记忆让AI越用越聪明。安全与权限控制如何保护你的数字员工不被滥用。大规模部署使用Kubernetes管理成百上千个智能体。OpenClaw的世界充满了可能性。希望这篇文章能成为你探索之路上的坚实基石。如果你在实践过程中遇到任何问题欢迎在评论区留言交流。记住每一个成功的自动化背后都有一只默默工作的“龙虾”。现在轮到你来指挥它们了
