Specialist Builder

通过多轮对话，帮你从零创建任意专业领域的专属 Agent。

工作流程

第一阶段：设计层（10步）

第二阶段：执行层（11步）

第三阶段：收尾层（5步）

第三阶段详解：两阶段注册 + 失败预案

核心原则

最小配置优先：先验证能启动，再补全配置
每步都验证：出错即停，自动回滚
零风险：任何失败都不留半坏状态

阶段 A：最小配置注册（验证可启动）

目的： 用最小配置注册，验证 Agent 能正常启动。

Patch 内容（仅 id + name + workspace）：

{
  agents: {
    list: [
      { existing agents... },
      {
        id: "<id>",
        name: "<name>",
        workspace: "/home/strong/.openclaw/workspace-<id>"
      }
    ]
  }
}

A1. 强制备份

cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak-$(date +%H%M%S)

A2. 构造最小 Patch 文件

创建 /tmp/agent-register-a.json5：

{
  agents: {
    list: [
      { 从 openclaw config get agents.list 获取现有 agents },
      {
        id: "<新agent-id>",
        name: "<新agent名称>",
        workspace: "/home/strong/.openclaw/workspace-<id>"
      }
    ]
  }
}

A3. Dry-Run 验证

openclaw config patch --replace-path agents.list --file /tmp/agent-register-a.json5 --dry-run

→ 输出 "Dry run successful" 才继续

A4. 正式写入

openclaw config patch --replace-path agents.list --file /tmp/agent-register-a.json5

A5. 配置校验

openclaw config validate

A6. 重启网关

openclaw gateway restart

A7. 验证新 Agent 启动

sessions_send --sessionKey agent:<id>:main --message "你好"

→ 得到正常回复？继续阶段B

→ 失败？执行回滚（见失败预案）

阶段 B：完整配置补全

目的： 阶段A成功后，补充完整配置（model、heartbeat等）。

Patch 内容：

{
  agents: {
    list: [
      { existing agents... },
      {
        id: "<新agent-id>",
        name: "<新agent名称>",
        workspace: "/home/strong/.openclaw/workspace-<id>",
        model: {
          primary: "minimax-portal/MiniMax-M2.7-highspeed"
        },
        heartbeat: {
          every: "15m",
          target: "none",
          lightContext: true,
          isolatedSession: true
        }
      }
    ]
  }
}

B1. 构造完整 Patch 文件

创建 /tmp/agent-register-b.json5

B2-B7. 同阶段A的验证流程

B2: Dry-Run 验证
B3: 正式写入
B4: 配置校验
B5: 重启网关
B6: 验证启动
B7: 成功 → 完成 | 失败 → 回滚

失败预案

如果任何步骤失败：
  1. 报告错误（哪一步失败、什么错误）
  2. 执行回滚
     cp ~/.openclaw/openclaw.json.bak-<时间戳> ~/.openclaw/openclaw.json
  3. 重启网关
     openclaw gateway restart
  4. 报告：注册失败，已回滚到操作前状态

流程图

开始
  ↓
[阶段A：最小配置注册]
  ↓
A1: 备份
  ↓
A2: 构造最小Patch（只有id+name+workspace）
  ↓
A3: Dry-Run 验证
  ↓
A4: 正式写入
  ↓
A5: 配置校验
  ↓
A6: 重启网关
  ↓
A7: 验证启动
  ↓
  成功？ ──否──→ [回滚] → 报告失败 → 结束
  │
  是
  ↓
[阶段B：完整配置补全]
  ↓
B1: 构造完整Patch
  ↓
B2: Dry-Run 验证
  ↓
B3: 正式写入
  ↓
B4: 配置校验
  ↓
B5: 重启网关
  ↓
B6: 验证启动
  ↓
  成功？ ──否──→ [回滚] → 报告失败 → 结束
  │
  是
  ↓
报告：注册完成 → 交付报告
  ↓
结束

注册命令参考

正确命令

# 替换整个 agents.list（需要 --replace-path）
openclaw config patch --replace-path agents.list --file <path>
openclaw config patch --replace-path agents.list --file <path> --dry-run

# 从 stdin 读取
cat <(echo '{"agents":{"list":[...和新agent...]}}') | openclaw config patch --stdin

错误命令（不要用）

# 以下命令是错误的，不要使用
openclaw config set agents.list ... --strict-json --merge
openclaw config patch agents.list --append --value <json>
openclaw config patch --append <json>

删除 Agent 流程

如果要删除已注册的 Agent，使用相同的两阶段安全流程：

第一阶段：备份 + Dry-Run + 写入

# 1. 备份
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak-$(date +%H%M%S)

# 2. 获取当前列表，去除要删除的 agent，构造 patch 文件
# 3. Dry-Run
openclaw config patch --replace-path agents.list --file /tmp/remove-agent.json5 --dry-run

# 4. 正式写入
openclaw config patch --replace-path agents.list --file /tmp/remove-agent.json5

第二阶段：重启 + 验证

# 5. 重启网关
openclaw gateway restart

# 6. 验证删除结果
openclaw config get agents.list | grep <agent-id> && echo "未删除" || echo "已删除"

原则

1. 每个问题只问一个，不要一口气问完
2. 确认用户回答后再问下一个
3. 文件生成后展示完整结构，征求修改意见
4. 注册前必须用户确认
5. 任何配置修改前必须备份
6. 任何配置修改必须先 dry-run 验证

教训本

> 2026-05-22 事故：修改 openclaw.json 时覆盖错了条目。
>
> 2026-05-25 事故：注册 agent 时使用错误命令语法，
> 直接编辑 openclaw.json，造成系统短暂瘫痪。

配置修改 checklist（必须遵守）：

1. cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak-$(date +%H%M%S)
2. 构造 patch 文件
3. openclaw config patch --replace-path agents.list --file <path> --dry-run
4. 确认 "Dry run successful"
5. openclaw config patch --replace-path agents.list --file <path>
6. openclaw config validate
7. openclaw gateway restart
8. 验证结果

本技能由 specialist-builder 技能创建工具生成
最新更新：2026-05-25
版本：2.0（两阶段注册 + 失败预案）