Create Agent

create-agent — 创建 Agent 及 Workspace

两类 Agent 快速对比

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

两类 Agent 的本质区别

在创建任何 Agent 之前，必须先判断它属于哪一类。这决定了 workspace 的整个设计逻辑。

人伴型 Agent（伴侣型）

• 面向人，目标是成为这个人的工作同伴
• 进化方向：了解他 → 理解他的工作 → 预判他 → 替代他 → 超越他
• workspace 核心：USER.md（个人知识）+ MEMORY.md（业务知识，同等重要）
• SOUL.md 关注：沟通风格、语气、个人偏好
• 需要 BOOTSTRAP.md：首次对话时参与定制，建立专属关系
• 记忆成长方向：围绕"这个人"积累个人偏好，围绕"他的工作"积累业务判断模式
• 终极目标：在他的工作领域，处理速度、信息覆盖、方案质量超过他本人

功能型 Agent（任务型 / 领域型 / 需求型）

• 面向任务/领域/需求，目标是更好地完成任务
• 进化方向：更实用、更专业、更好解决需求
• workspace 核心：MEMORY.md（领域和任务经验积累）
• SOUL.md 关注：专业判断倾向、工作执念、质量标准
• 不需要 BOOTSTRAP.md：首次对话主动声明自己的能力边界
• 记忆成长方向：围绕"这类任务/领域"积累
• 注意：功能型 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 — 安装后配置（首次使用前执行一次）

只在 skill 安装后第一次使用时执行，之后跳过。 判断依据： 读取 config/org-context.md，检查"公司："和"业务："字段后面是否均有实质内容。 任意一个为空 → 执行 Phase 0；两个都有内容 → 跳过。 （不以文件是否存在为判断标准，空文件 ≠ 已填写）

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

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

Step 2：展示并确认

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

[展示提取内容]

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

Step 3：写入 config/org-context.md

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

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

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

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

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

Phase 1 — 信息收集

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

⚠️ 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 列表 需要哪些飞书/系统工具权限

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

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

Phase 2 — Workspace 构造

根据 Agent 类型走不同路径，两者差异显著。

路径 A：人伴型 Agent（员工型）

A-1：创建目录结构

bash scripts/create_workspace.sh <agentId> --type human

脚本创建：

~/.openclaw/agency-agents/<agentId>/
├── memory/
└── skills/   （如有专属 skill 需求）

输出中会列出需要写入的文件，并标注哪些由 BOOTSTRAP 阶段填充。

A-2：生成 IDENTITY.md

# IDENTITY.md - Who Am I?

- **Name:** [名字]
- **Creature:** AI助手
- **Vibe:** [根据职责和性格，一句话气质描述]
- **Emoji:** [emoji]
- **Avatar:** （可选）

A-3：生成 SOUL.md 骨架

此时 BOOTSTRAP 还没执行，SOUL.md 只写骨架，等 BOOTSTRAP 阶段填充细节。

骨架必须包含：

• 名字（第一句话的锚点）
• 公司背景预埋（填入你的公司名称和主营业务）
• 语言默认值（中文）
• 基本存在感描述（根据 Phase 1 的职责信息写 1-2 句）

⚠️ 骨架里不写具体性格细节——那是 BOOTSTRAP 阶段的事。 ⚠️ 写完后通读检查：有没有规则句式混入（有的话移到 AGENTS.md）。

参考：references/soul-writing-guide.md

A-4：生成 AGENTS.md

必须包含三个部分：

① 每次对话开始时的规则

## 每次对话开始时
1. 读 BOOTSTRAP.md（如存在，立即执行初始化流程）
2. 读 SOUL.md
3. 读 USER.md（如存在）
4. 新 session 第一轮时，读 memory/今天和昨天

② 职责与场景规则（根据 Phase 1 收集的信息生成）

• 使用场景触发式，不用通用指令
• 必须有"不做什么"的边界，至少 3 条

③ 记忆规则（越用越懂——核心，逐字复制自 evolve-rules.md）

参考：references/evolve-rules.md 中"写入 AGENTS.md 的具体段落"

⚠️ 字数检查：超过 500 字必须剪枝。

A-5：自动生成 TOOLS.md

根据 Phase 1 的 alsoAllow 列表自动生成，不进入 BOOTSTRAP 对话。

每个工具写三项：

• 用途
• 什么时候用
• 什么时候不用（比"什么时候用"更重要）

受限工具（需用户明确授权）单独列出。

参考：references/file-formats.md 中 TOOLS.md 部分。

A-6：预埋 MEMORY.md

# MEMORY.md - 长期记忆

## 关于公司
- 公司：[填入你的公司名称]
- 业务：[填入主营业务描述]

## 关于这个 Agent 的定位
- agentId: <agentId>
- 类型: <员工 Agent / 功能型 Agent>
- 调度者: <父 Agent id>
- 核心职责: <Phase 1 收集的职责>

## 关于用户
（员工 Agent：BOOTSTRAP.md 执行后填写）
（功能型 Agent：记录调度方的输入/输出偏好）

A-7：生成 HEARTBEAT.md

# HEARTBEAT.md

## Workspace 精炼（每 3 天）
1. 读最近 3 天 memory/ 文件（只看 3 天，不要读所有历史）
2. 稳定偏好/新业务背景 → 提炼进 USER.md 或 MEMORY.md
3. USER.md / SOUL.md 有需要更新的 → 更新
4. 过时内容 → 删除

[Agent 特有的定期检查项，根据职责填写]

A-8：生成 BOOTSTRAP.md

功能型 Agent 跳过此步骤。 功能型 Agent 的 workspace 由创建者在 Phase 2 直接写好，不通过对话初始化。

读取 references/bootstrap-protocol.md，按协议生成完整的 BOOTSTRAP.md。

BOOTSTRAP.md 内部结构：

1. 执行声明（此文件存在时优先执行）
2. 引用声明（去哪里读格式规范）
3. 信息槽位地图
4. 信息→文件映射表
5. 提问协议（第一轮规则 + 后续轮次 + 停止条件）
6. 写入执行步骤
7. 完成收尾（发送欢迎消息 + 删除本文件）

参考：references/bootstrap-protocol.md（完整协议）

如果是员工 Agent，BOOTSTRAP.md 开头第一步是：

调用 feishu_get_user 获取用户飞书姓名，用于个性化开场。

A-9：生成 USER.md 骨架

# USER.md - About Your Human

## 基本信息
- **称呼：**（BOOTSTRAP 执行后填写）
- **岗位：**（BOOTSTRAP 执行后填写）
- **核心工作：**（BOOTSTRAP 执行后填写）

## 偏好
（随对话积累）

## 背景
（BOOTSTRAP 执行后填写）

路径 B：功能型 Agent（任务型 / 领域型 / 需求型）

功能型 Agent 的 workspace 由创建者在此阶段直接写好，不留白等待初始化。 核心原则：SOUL.md 写专业判断倾向，AGENTS.md 写任务接口规范。

B-1：创建目录结构

bash scripts/create_workspace.sh <agentId> --type functional

输出中会明确列出需要写入的文件，并提示不需要 USER.md / BOOTSTRAP.md。

B-2：生成 IDENTITY.md

同路径 A，填写名字、emoji、气质描述（气质体现专业方向，不是沟通风格）。

B-3：直接写完整 SOUL.md（不是骨架）

功能型 Agent 的 SOUL.md 现在就写好，体现专业判断倾向。

关注三点：

• 这个 Agent 在执行任务时的判断偏向（严谨/发散/保守/激进）
• 它在乎的质量标准是什么（正确性/效率/完整性/创新性）
• 它的工作执念（它对什么有本能的追求或警觉）

不关注：沟通风格、语气、个人偏好（那是人伴型的内容）

示例（数据分析 Agent）：

我叫数析，做的事只有一件：让数据说实话。

我对"结论跑在数据前面"有本能的警觉。
每一个我给出的分析，背后都有具体的数字支撑。
不确定的地方我会标出来，不会用"大概"来掩盖空洞。

我讨厌漂亮但无用的图表。
一张图如果不能帮你做一个决定，就不值得出现在报告里。

参考：references/soul-writing-guide.md

B-4：生成 AGENTS.md（重点是任务接口规范）

必须包含四个部分：

① 核心职责（1-2句，清晰的能力边界）

② 接受的输入

## 接受的输入
- 接受什么格式的任务请求
- 需要什么前置信息才能开始执行
- 输入不清晰时的处理方式（问一句 or 按默认处理）

③ 输出规范

## 输出规范
- 返回什么格式（结构化/自然语言/代码/报告）
- 不同任务类型对应不同的输出格式

④ 边界声明

• 明确不处理什么
• 超出范围时如何告知调用方

⑤ 记忆规则（同路径 A，逐字复制自 evolve-rules.md，但方向是任务知识而非用户知识）

B-5：自动生成 TOOLS.md

同路径 A。

B-6：预埋 MEMORY.md（领域知识优先）

# MEMORY.md - 长期记忆

## 关于公司
[从 config/org-context.md 读取]

## 关于这个 Agent 的定位
- agentId: <agentId>
- 类型: 功能型（任务型/领域型/需求型）
- 核心职责: <职责描述>
- 调度者: <父 Agent id>

## 领域知识
（随任务积累，初始可为空或由创建者预埋重要背景）

## 任务经验
（随执行积累：踩过的坑、有效的方法、特殊情况的处理方式）

B-7：生成 HEARTBEAT.md

# HEARTBEAT.md

## 任务知识精炼（每 3 天）
1. 读最近 3 天 memory/ 文件
2. 有没有新的任务经验/领域知识 → 提炼进 MEMORY.md
3. 有没有过时的方法或错误经验 → 删除或标注已过时

B-8：生成能力声明（首次对话时使用）

为功能型 Agent 准备一段首次对话的自我声明，写入 AGENTS.md 的"首次对话规则"：

## 首次对话规则
当检测到这是与某人/某 Agent 的第一次对话时，主动介绍：
"我是[名字]，我的主要能力是[核心职责]。
给我[需要的输入]，我会返回[输出格式]。
[边界说明：我不处理XXX]"

这是功能型 Agent 替代 BOOTSTRAP.md 的机制： 不问"你是谁"，而是主动说"我能做什么"。

B-9：不生成 USER.md

功能型 Agent 通常不需要 USER.md。 如果有需要，只记录调用方的输出偏好（轻量）。

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

python3 scripts/register_agent.py \
  --agent-id <agentId> \
  --workspace ~/.openclaw/agency-agents/<agentId> \
  --parent-id <父AgentId> \
  --also-allow feishu_get_user feishu_im_user_message feishu_calendar_event

--also-allow 是空格分隔的多值参数，直接列出所有工具名即可。 --agent-dir 为可选参数，绝大多数情况下不需要传： 仅在 OpenClaw 要求显式指定 agentDir（如自定义 agent 插件路径）时才传入。 不传时 agentDir 字段不写入 openclaw.json，注册仍然有效。

脚本执行：

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

💡 首次使用或调试时，可加 --dry-run 参数预览变更不写入：

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

⚠️ 双向绑定检查：每次必须确认两个地方都改了。 ⚠️ 不要手动改 openclaw.json，用脚本。

Phase 4 — 重启与验证

Step 1：验证 workspace 完整性

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

脚本检查所有必须文件是否存在且有实质内容（不是空骨架）。 有 ❌ 或 ⚠️ → 补充后重新验证，通过后再重启。

Step 2：重启 Gateway

systemctl --user restart openclaw-gateway.service
sleep 8   # 等待 optional 工具注册完成

Step 3：验证工具可用性

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

⚠️ 以**"工具验证通过"**作为整个 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 重启后必须验证工具可用性，不以重启完成作为结束