OpenClaw Agent 创建器

在 ~/.openclaw/ 路径下创建并配置 Arch 的 OpenClaw 多智能体系统中的 agent。

系统上下文

• 所有者：Archit（Arch），Linux 用户 archit，时区 America/Denver
• 网关：运行于端口 18789 的单进程，统一管理全部 agent
• Bot：所有 agent 共享一个 Telegram bot —— 路由逻辑决定哪个 agent 处理哪条聊天消息
• 现有 agent 列表：查看 ~/.openclaw/openclaw.json → agents.list[] 获取当前注册的 agent 清单
• 实现历史：参考 ~/.openclaw/implementation-docs/ 中 Wire agent 的参考实现

Agent 创建流程

1. 收集需求

开始创建前，请先与 Arch 明确以下事项：

• Agent 名称及 ID（ID 必须为小写字母，不可含空格）
• 角色与职责（需具体明确，避免模糊表述）
• 模型层级：廉价方案（仅 Kimi K2.5）或完整级联方案（包含 Claude Sonnet）
• 是否需要专属 Telegram 群组用于问答（Q&A）
• 是否需要定时任务（cron jobs）—— 若需要，请明确调度周期与执行内容
• 是否启用心跳机制（heartbeat）

2. 停止网关

openclaw gateway stop

此步骤为强制要求：在编辑 openclaw.json 或 cron/jobs.json 前，必须先停止网关。网关在每次 cron 执行后会主动向 jobs.json 写入任务状态；若在网关运行期间编辑该文件，将引发竞态条件并导致数据丢失。

3. 备份配置

cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.backup.$(date +%Y%m%d%H%M%S)

4. 创建目录结构

mkdir -p ~/.openclaw/workspace-/memory
mkdir -p ~/.openclaw/agents//agent

严禁跨 agent 复用 agentDir —— 否则将导致认证/会话冲突。

5. 编写 Workspace 文件

以 assets/templates/ 中的模板为起点进行定制。每个 agent 必须包含以下文件：

SOUL.md 是最重要的文件。 请对职责作具体描述；若 agent 在不同上下文中行为差异显著（例如 briefing 模式 vs chat 模式），请明确定义对应的行为模式。

6. 编辑 openclaw.json —— 添加 Agent 条目

向 agents.list[] 中添加新条目。所有合法字段详见 references/config-schema.md。

最小化配置示例：

{
  "id": "",
  "name": "",
  "workspace": "/home/archit/.openclaw/workspace-",
  "agentDir": "/home/archit/.openclaw/agents//agent",
  "identity": { "name": "" }
}

常见可选字段：

• "model" —— 覆盖默认模型级联策略；对 worker 类型 agent 可排除高成本模型
• "heartbeat": { "every": "0" } —— 为纯 cron 类 agent 禁用心跳机制
• "groupChat": { "mentionPatterns": ["@", "@"] } —— 启用群组内 @ 提及功能

仅允许 ONE 个 agent 设置 "default": true（当前为 Fossil）。该默认 agent 将接收所有未被显式路由的消息。

7. 编辑 openclaw.json —— Telegram 路由配置（如需）

必须完成 THREE 项独立配置变更。 缺失任一项均会导致静默失败。完整说明详见 references/telegram-routing.md。

1. 群组配置：位于 channels.telegram.groups 下：

   "-100XXXXXXXXXX": { "requireMention": false }
   

2. 绑定规则：位于 bindings[] 中：

   { "agentId": "", "match": { "channel": "telegram", "peer": { "kind": "group", "id": "-100XXXXXXXXXX" } } }
   

3. @提及模式：已在第 6 步中完成（若第 6 步已添加 groupChat 字段）。

8. 创建定时任务（如需）

编辑 cron/jobs.json。每个 cron job 的 prompt 必须包含以下要素：

• 动态解析 Telegram 群组 ID 的前置说明（严禁硬编码 Telegram 群组 ID）：

  FIRST: Resolve your Telegram group ID by running:
  jq -r '.bindings[] | select(.agentId == "") | .match.peer.id' ~/.openclaw/openclaw.json
  Use the output as the target for all Telegram messages in this task.
  

• 日期注入：前置说明之后，插入 $(date '+%A, %B %d, %Y')
• 显式约束：包括来源白名单、时效性规则、格式模板等
• 投递指令：使用占位符 target=''（由前置说明自动解析）

该自愈型模式可确保 cron job 在 Telegram 群组 ID 迁移后仍能正常运行。完整模式见 references/prompt-patterns.md，原理说明见 references/telegram-routing.md。

关键提醒：若从其他 agent 的 workspace 复制文件或 prompt，请务必 使用 grep 检查并替换所有硬编码路径。

9. 重启网关并验证

openclaw gateway start

通过日志验证：

• Agent 是否成功注册：agent registered:
• 消息是否正确路由：lane enqueue: lane=session:agent::...

若向 Telegram 群组发送的消息在日志中显示 skip: no-mention，说明缺失 channels.telegram.groups 配置（详见 references/bugs-and-pitfalls.md）。

参考文档

模板文件

Workspace 文件的初始模板位于 assets/templates/ 目录下。请按需复制并为各 agent 单独定制。