引言
在上一篇《OpenClaw基础入门：从“养虾”概念到第一个智能体程序》中，我们成功搭建了OpenClaw的开发环境，并运行了第一个简单的交互任务。那只“小龙虾”已经能听懂我们的话，并且动手创建了文件。但是，你是否好奇过它背后的运行逻辑？为什么它能像搭积木一样组合各种能力？
如果你希望从“使用者”进阶为“开发者”，真正掌握OpenClaw的编程模型，那么这篇文章就是为你准备的。今天，我们将深入OpenClaw的核心概念与基本语法，彻底搞懂数据类型、配置文件、节点、主题、服务这些基础构件。最后，我们将亲手编写一个完整的控制程序，让我们的智能体具备更复杂的协作能力。
无论你是AI初学者，还是寻求自动化提效的开发者，这篇文章都将为你打开一扇新的大门。
一、OpenClaw的数据结构与类型系统
任何编程都离不开数据。OpenClaw作为一个智能体框架，其内部流转的数据不仅有传统的编程语言类型，还扩展了适合AI场景的特殊类型。理解这些类型是编写可靠技能的前提。
1.1 基础数据类型
OpenClaw的核心运行时（Pi Runtime）采用Python实现，因此天然支持Python的所有基础类型。但在配置文件和跨语言通信（如Node.js Gateway与Python技能之间）时，OpenClaw定义了一套标准化的数据交换格式，通常是JSON兼容的。
- 字符串（String）：用于表示文本消息、文件路径、命令等。
- 整数（Integer）和浮点数（Float）：用于数值计算、配置参数。
- 布尔值（Boolean）：true/false，用于开关控制。
- 列表（Array）：有序集合，例如技能参数列表、权限列表。
- 字典（Object）：键值对，用于复杂配置和结构化数据。
1.2 扩展的AI专用类型
为了让AI更好地理解上下文，OpenClaw引入了一些语义化的数据类型：
-
Message（消息）：这是最核心的通信单元。一条消息包含：
- id：全局唯一标识。
- timestamp：时间戳。
- from/to：发送者和接收者（通常是节点或主题）。
- type：消息类型（text， command， event， error等）。
- payload：实际内容，可以是任意基础类型。
- metadata：元数据，如来源技能、会话ID等。
-
Skill（技能描述）：当AI需要调用某个功能时，它会收到一个技能描述对象。该对象包含：
- name：技能名称。
- description：技能的功能描述（供AI理解）。
- parameters：参数列表，每个参数包含名称、类型、描述、是否必需。
- command：实际执行的命令或函数入口。
-
NodeInfo（节点信息）：描述一个执行节点的状态，包括：
- id， name， type（local/docker/ssh）。
- status（online/offline/busy）。
- capabilities：该节点支持的能力列表（如“文件操作”，“网络请求”）。
-
Topic（主题）：实际上主题本身不是一个数据值，而是一个字符串标识符，但我们可以将其视为一种“地址类型”。在消息路由中，主题用于过滤和分发。
1.3 类型系统的作用
这种明确的类型系统有两个好处：
二、配置文件的结构与编写方法
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
– write
2.3 编写一个完整的智能体配置文件
让我们通过一个实际例子来学习配置文件的各个部分。假设我们要创建一个名为“MyBot”的智能体，它能监听特定主题，并调用文件操作技能。
agent.yaml：
name： MyBot
description： 一个测试用的文件操作智能体
version： 1.0.0
# 基础设置
settings：
language： zh–CN
timezone： Asia/Shanghai
log_level： info
# 模型配置（支持多种LLM）
model：
provider： openai # 可选 openai, deepseek, ollama, claude
model_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.heartbeat
nodes.yaml（同级目录下）：
nodes：
– id： local_node
name： 本地节点
type： local
work_dir： /home/user/openclaw_workspace
max_concurrent_tasks： 5
skills.yaml：
skills：
– id： file_operator
name： 文件操作器
entry： file_operator：main # 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： 写入的内容（当operation=write时需要）
required： false
permissions：
– filesystem：read
– filesystem：write
2.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： python：3.10–slim
command： [“python”， “–m”， “openclaw.node”]
volumes：
– /host/data：/data
environment：
– ENV=production
3.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 环境准备
确保你已完成上一篇的环境搭建。我们将在一个项目目录中工作：
mkdir my_openclaw_project
cd my_openclaw_project
4.2 定义配置文件
agent_commander.yaml：
name： 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_handler
agent_worker.yaml：
name： 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： ./workspace
4.3 编写自定义技能
技能就是普通的Python模块。我们在 skills/command_parser.py 中编写Commander的解析逻辑：
# skills/command_parser.py
import re
from openclaw.skill import Skill
class CommandParser(Skill)：
async def handle(self, message)：
"""
解析用户自然语言指令，决定发布到哪个主题
"""
text = message.payload.get('text', '')
# 简单的规则匹配
if re.search(r'创建文件|新建文件', text)：
# 提取文件名和内容（示例中简化处理）
filename = re.findall(r'文件\\s*(\\S+)', text)
content = re.findall(r'内容\\s*[是为：]?\\s*(.+)', text)
payload = {
'path'： filename[0] if filename else 'default.txt',
'content'： content[0] if content else ''
}
await self.publish('command/create_file', payload)
return {'status'： 'ok', 'message'： '任务已分发'}
elif re.search(r'天气|气温', text)：
city = re.findall(r'([\\u4e00-\\u9fa5]+)天气', text)
payload = {'city'： city[0] if city else '北京'}
await self.publish('command/weather', payload)
return {'status'： 'ok', 'message'： f'正在查询{payload["city"]}天气'}
else：
return {'status'： 'error', 'message'： '无法理解指令'}
async def publish(self, topic, payload)：
# 实际发送消息到主题
await self.context.gateway.publish(topic, payload)
注册技能：在 skills.yaml 中添加：
skills：
– id： command_parser
name： 指令解析器
entry： command_parser：CommandParser
description： 解析用户指令并分发给对应主题
– id： file_operator
# … 同上
– id： weather_query
name： 天气查询
entry： weather_query：WeatherQuery
description： 查询指定城市天气
4.4 启动并测试
首先启动Gateway（如果未运行）：
openclaw gateway start
然后分别启动两个智能体（可以在两个终端，或使用进程管理工具）：
# 终端1：启动Commander
openclaw agent start –config agent_commander.yaml
# 终端2：启动Worker
openclaw agent start –config agent_worker.yaml
现在，通过Commander提供的HTTP接口（或直接通过OpenClaw Web UI）发送指令。例如，用curl模拟用户请求：
curl -X POST http：//localhost：8080/command \\
-H “Content-Type： application/json” \\
-d ‘{“text”： “帮我创建文件 test.txt，内容为 Hello World”}’
你应该会收到类似 {“status”：“ok”，“message”：“任务已分发”} 的响应。然后检查Worker的工作目录 ./workspace 下是否生成了 test.txt 文件，内容是否正确。
4.5 观察消息流
为了更直观地理解主题通信，可以开启OpenClaw的调试模式，查看消息流转日志。你会在日志中看到：
这样一个完整的控制-执行-反馈闭环就形成了。
五、总结与进阶预告
通过本文的学习，你已经掌握了OpenClaw的核心编程模型：
- 数据类型 让AI和组件之间能够精确沟通。
- 配置文件 让你能以声明式的方式定义智能体的行为。
- 节点、主题、服务 构成了分布式、可扩展的智能体网络。
- 实战演练 让你亲手搭建了一个多智能体协作系统。
这只是一个开始。在后续的系列文章中，我们将深入更高级的主题：
- 如何开发复杂的自定义技能：包括调用外部API、操作数据库、处理音视频。
- 智能体的记忆与学习：利用长期记忆让AI越用越聪明。
- 安全与权限控制：如何保护你的数字员工不被滥用。
- 大规模部署：使用Kubernetes管理成百上千个智能体。
OpenClaw的世界充满了可能性。希望这篇文章能成为你探索之路上的坚实基石。如果你在实践过程中遇到任何问题，欢迎在评论区留言交流。
记住，每一个成功的自动化背后，都有一只默默工作的“龙虾”。现在，轮到你来指挥它们了！
