create-agent — 创建 Agent 及 Workspace

两类 Agent 快速对比

在创建任何 Agent 之前，必须先判断它属于哪一类。两类路径差异显著，确认后再收集信息。

核心设计原则

skill 负责骨架，BOOTSTRAP.md（人伴型专属）负责灵魂。

• 人伴型：skill 产出 workspace 骨架 + BOOTSTRAP.md，首次对话时由用户参与填充
• 功能型：skill 直接产出完整的 workspace，包含精心设计的 SOUL.md 和能力声明
• 两类共同：workspace 通过触发式写入 + heartbeat 精炼持续生长

执行前必须阅读：

• references/file-formats.md — 每个文件"写好"的标准
• references/soul-writing-guide.md — SOUL.md 专项写作指南
• references/evolve-rules.md — workspace 持续生长规则
• references/bootstrap-protocol.md — BOOTSTRAP.md 动态对话协议

Phase 0 — 安装后配置（首次使用前执行一次）

判断依据（按顺序检查）：

1. 读取 org-context.md：~/.openclaw/workspace/agents-config/org-context.md 不存在 → 尝试从 MEMORY.md 自动提取公司背景 → 仍无法提取 → 执行 Phase 0

2. 检查"公司："和"业务："字段是否均有实质内容。 任意一个为空 → 执行 Phase 0（跳过有效期检查）；两个都有内容 → 执行步骤 2。

3. 检查 last_updated 字段，计算距今天数。 超过 30 天 → 提示用户确认（不强制阻断，用户确认无需调整则继续）。 未超过 30 天 → 直接跳过 Phase 0。

（不以文件是否存在为判断标准，空文件 ≠ 已填写）

Step 1：读取记忆，自动提取

读取：MEMORY.md + 最近 3 天 memory/ 文件
提取：
  □ 公司名称
  □ 主营业务
  □ 已有的 Agent 列表和分工
  □ 其他稳定的组织背景

Step 2：展示并确认

"我从记忆里整理了以下信息，将作为新 Agent 的背景预埋：

[展示提取内容]

有需要补充或修改的吗？"

Step 3：写入 ~/.openclaw/workspace/agents-config/org-context.md

# org-context.md — 组织背景预埋信息

## 元信息
- last_updated: YYYY-MM-DD

## 公司信息
- 公司：[自动填入或用户补充]
- 业务：[自动填入或用户补充]

## 现有 Agent 架构
[自动填入已知的 Agent 列表和分工]

## 其他背景
[用户补充的信息]

后续每次创建 Agent，自动读取此文件，不再重复询问。

Phase 1 — 信息收集

所有信息必须确认后才能进入 Phase 2，不猜测，不假设。

快速路径判断（可选，减少轻量场景的收集成本）

在开始详细收集前，先判断是否适合快速路径：

问用户：这是给刚配对的员工建基础 Agent，还是有特定职责的专业 Agent？

如果回答是"刚配对的员工"且用户没有额外要求 → 快速路径：

只收集 3 项：

□ agentId        staff-<open_id前几位>
□ open_id        用于 --notify-open-id（HEARTBEAT.md 闲置通知）
□ 基础工具权限    默认：feishu_get_user feishu_im_user_message feishu_search_user

其余全部自动处理：

• 名字/emoji：AI 根据飞书姓名自动生成（Phase 2 A-2）
• SOUL.md：骨架（BOOTSTRAP 阶段填充）
• AGENTS.md：最小规则集（不含场景规则，仅基础记忆规则）
• alsoAllow：仅 3 个基础工具
• 核心职责/边界/父 Agent：全部使用默认值（"服务配对员工的日常工作"，父 Agent = main）

快速路径跳过功能型专有字段和可选字段，直接进入 Phase 2。Phase 2 中 AGENTS.md 的场景规则和明确不做的事留空（由 BOOTSTRAP 或后续使用中补充）。

如果不适合快速路径 → 继续下面的详细收集。

⚠️ Agent 类型必须第一个确认，它决定 Phase 2 走哪条路径，两条路差异显著。 收集顺序：先定类型 → 再按对应路径收集剩余信息。

通用必填（按此顺序收集）

□ Agent 类型     【第一个确认】员工 Agent（有真人用户直接对话）
                              还是功能型 Agent（面向任务/被其他 Agent 调度）
□ agentId        全小写，字母+连字符（如 staff-ou_xxx、data-analyst）
□ 名字 + emoji   用于 IDENTITY.md，也是 SOUL.md 的叙事起点
□ 核心职责       1-2句话（这个 Agent 主要干什么）
□ 明确不做什么   至少说出 2-3 条边界
□ 父 Agent id    谁来调度它（用于 allowAgents 白名单）
□ alsoAllow 列表 需要哪些飞书/系统工具权限

如果是员工 Agent，agentId 通常是 staff-<open_id前几位>。

功能型专有必填（仅当类型为功能型时收集）

□ 判断偏向      遇到不确定性时默认保守还是激进
                 （比如：宁可多问一句不瞎猜 / 给个方向等反馈 / 先按最常见情况处理）
□ 输入模糊时    收到的信息不完整时的默认行为
的默认行为        （追问 / 按默认假设执行并标注 / 拒绝执行并说明缺什么）
□ 质量标准排序  正确性 / 完整性 / 效率 / 创新性——哪个优先
                 （比如：宁可慢但要准 / 快速给粗糙结论再迭代）
□ 最不能容忍    这个 Agent 在执行中最不该出现的行为
的输出缺陷        （比如：给了一个看起来完整但实际有错的答案 / 推理过程有跳跃）

可选

○ 是否需要专属 skills
○ 特殊的工具限制或安全约束

Phase 2 — Workspace 构造

根据 Agent 类型走不同路径。确认类型后只读对应文件，不读另一个。

人伴型（路径 A）： 读取 references/human-path.md，按步骤执行 A-1 到 A-9。

功能型（路径 B）： 读取 references/functional-path.md，按步骤执行 B-1 到 B-9。

Phase 3 — 系统注册（高危，严格执行）

python3 scripts/register_agent.py \
  --agent-id <agentId> \
  --workspace ~/.openclaw/agency-agents/<agentId> \
  --parent-id <父AgentId> \
  --agent-type human \
  --core-duty "核心职责一句话描述" \
  --also-allow feishu_get_user feishu_im_user_message feishu_calendar_event

可选参数：

• --model：指定模型（不传则继承默认）
• --heartbeat-interval：心跳间隔分钟数（默认 60）
• --agent-dir：极少数情况才需要，不传则不写入此字段
• --dry-run：预览变更不写入

脚本执行顺序：

1. 备份 openclaw.json（带时间戳）
2. 在 agents.list 追加新 Agent 定义（含 heartbeat + 可选 model）
3. 在父 Agent 的 subagents.allowAgents 追加新 agentId（双向绑定）
4. 执行 openclaw config validate
5. validate 通过 → 在父 Agent MEMORY.md 追加子 Agent 档案 → 继续 validate 失败 → 自动回滚，报错退出

💡 首次使用或调试时，先加 --dry-run 预览：

python3 scripts/register_agent.py --agent-id <agentId> ... --dry-run

⚠️ 不要手动改 openclaw.json，用脚本。

注销 Agent（废弃 / 员工离职）

python3 scripts/deregister_agent.py --agent-id <agentId>
# 预览：python3 scripts/deregister_agent.py --agent-id <agentId> --dry-run

脚本执行：

1. 从 agents.list 移除目标 Agent
2. 从所有父 Agent 的 allowAgents 移除该 id（自动扫描，不会遗漏）
3. validate + 回滚机制同注册
4. workspace 存档到 ~/.openclaw/agency-agents/.archived/<agentId>-<时间戳>/（不删除）

Phase 4 — 重启与验证

Step 1：验证 workspace 完整性

bash scripts/verify_workspace.sh <agentId> --type human      # 人伴型
bash scripts/verify_workspace.sh <agentId> --type functional # 功能型

脚本执行两层检查：

1. 存在性 + 行数：文件存在且有足够有效行
2. 内容特征：无未填充占位符、SOUL.md 含名字、AGENTS.md 含边界声明、MEMORY.md 公司已填写

有 ❌ 或 ⚠️ → 补充后重新验证，通过后再重启。

Step 2：重启 Gateway

if systemctl --user status openclaw-gateway.service &>/dev/null 2>&1; then
  systemctl --user restart openclaw-gateway.service
elif pgrep -f "openclaw gateway" &>/dev/null; then
  openclaw gateway restart
else
  echo "⚠️  无法自动检测 Gateway 运行方式，请手动重启后继续验证。"
fi
sleep 8

Step 3：验证工具可用性

1. 确认新 Agent 在 Gateway 日志里出现
2. 确认 alsoAllow 里的工具已注册（不以"重启完成"作为结束）

Step 4：首次激活自检

通过 sessions_send 向新 Agent 发一条激活消息：

请读取你的 workspace，用一段话说清楚：你是谁、主要职责是什么、有哪些明确不做的事。

收到回应后：

• 检查回应是否包含 Agent 名字、核心职责、边界声明三要素
• 将回应写入新 Agent 的 memory/<今天日期>.md 作为第一条记录（标题："首次激活自检"）
• 回应缺少三要素之一 → workspace 有问题，检查对应文件后重新自检

Step 5：最小场景化行为验证

自检通过后，根据 Agent 类型发送测试消息。

人伴型： 根据 Phase 1 收集的"明确不做什么"，构造一条超出边界的请求：

帮我做一下 [某条明确不做的事]

验证标准： Agent 明确拒绝 + 说明边界，不尝试执行。 不通过时： 检查 SOUL.md 边界 + AGENTS.md 场景规则。

功能型（两项测试，全部通过才算完成）：

测试 1 — 输入完整性测试：

帮我处理一下数据

验证标准： Agent 按能力卡点响应（追问必要输入 / 说明需要什么信息 / 指出输入不完整），不直接猜测执行。 不通过时： 检查 AGENTS.md "接受的输入" 部分。

测试 2 — 判断边界测试：

这是一个 [Agent 职责领域] 的任务：[具体但处于能力边界的情况描述]

验证标准：

• Agent 没有直接跳过判断就执行（说明"工作执念"生效）
• Agent 的回应中体现了 Phase 1 收集的"判断偏向"
• Agent 对不确定的部分有标注（不是假装确定） 不通过时： 检查 SOUL.md 是否包含判断偏向素材 + AGENTS.md 边界声明是否覆盖灰色地带。

⚠️ 以**"自检三要素通过 + 场景行为验证通过"**作为整个 skill 的完成标志。

完成后告知

Agent [名字] 已创建完成：
- agentId: <agentId>
- workspace: ~/.openclaw/agency-agents/<agentId>
- 工具权限: <alsoAllow 列表>
- 状态: 等待用户首次对话完成个性化初始化

员工首次与 Agent 对话时，BOOTSTRAP.md 会自动触发，
通过动态对话完成 workspace 的内容层定制。

注意事项

• 每个 Agent 必须有独立 workspace，不能多个 Agent 共用
• SOUL.md 和 AGENTS.md 不能内容重叠：性格在 SOUL，规则在 AGENTS
• TOOLS.md 不进 BOOTSTRAP 对话：由 skill 根据 alsoAllow 自动生成
• MEMORY.md 和 memory/ 严格区分：长期知识 vs 日期事件
• Gateway 重启后必须验证工具可用性，不以重启完成作为结束
• 记忆规则从 references/evolve-rules.md 读取后写入 AGENTS.md，不手写