agent-onboarding

name	agent-onboarding
description	为 OpenClaw 新增或修复 Feishu Agent 的标准入职 Skill。覆盖配置 upsert、identity(open_id)补齐、角色文档模板渲染、飞书与任务合同规范校验、roster/board 同步与重启前审计。
license	MIT
version	4.4.0

Agent Onboarding Skill

用于把新 Agent 入职为"可被 @、可派单、可追踪"的标准员工。

这是新 Agent 入职的唯一入口；如果需要调整 onboarding 流程，应优先修改这个 Skill 及其脚本，而不是在 openclaw-feishu-delivery 项目里再维护第二套独立 onboarding 文档。

何时使用

• 新增一个 Feishu bot
• 现有 agent 能收到群消息但 @ 不触发
• agent 已存在但 identity/open_id、角色文档、派单看板不完整

OpenClaw 入职基础要件（16 项）

一个可上线的 Agent，至少需要以下 16 项全部满足：

新增说明（Feishu 私聊策略）：

• 官方默认是 dmPolicy="pairing"，未知用户私聊会收到 pairing code
• 如果业务要求"任何员工都可直接私聊"，必须显式改为 dmPolicy="open" 且 allowFrom=["*"]
• 如果业务要求"仅部分人可私聊"，应配置 dmPolicy="allowlist"
• 当目标策略是 allowlist 时，onboarding 默认走半自动 auto-dm：先临时 pairing，等待 owner 首次私聊，再自动回填该账号视角下的真实 open_id
• 如果该 Agent 不应接受私聊，应配置 dmPolicy="disabled"

1. openclaw.json.agents.list 有该 agent
2. openclaw.json.bindings 有 channel=feishu + accountId={agent-id}
3. openclaw.json.channels.feishu.accounts 有 appId/appSecret
4. openclaw.json.channels.feishu.userIdentities[{identity-key}][agent-id] 有 operator open_id
5. $OPENCLAW_HOME/agents/{agent-id}/agent 目录存在
6. $OPENCLAW_HOME/agents/{agent-id}/sessions 目录存在
7. workspace-{agent-id} 存在且有 IDENTITY.md
8. IDENTITY.md 含三要素：Name / 岗位职责 / 核心工作(>=3)
9. MEMORY.md 已由注入脚本写入项目化消息铁律（send_message.py + runtime 配置 + contract 文档）
10. openclaw-feishu-delivery 项目目录存在且可读
11. openclaw-feishu-delivery/runtime/accounts.local.json 已有该 agent runtime account
12. 目标群组已完成加群（默认 onboarding 群）
13. agent-roster.json 已纳入该 agent
14. dispatch-board.json 已出现可用窗口（runtime 或 binding）
15. TASK_POLICY.md 已落地并通过任务合同校验（单任务单责任人 + 创建人回执）
16. 已通过首次真实私聊获取 pairing 信息，并按业务范围把该 Agent 收口为正式策略：指定人群用 allowlist，全员对外用 open + ["*"]，不允许长期停在模糊状态

M1 任务积分体系硬约束（新增）

入职完成后，Agent 必须能在任务积分体系中被稳定调度，要求：

1. 任务必须有 creator_type + creator_id
2. 任务必须有且仅有一个 assignee_agent_id
3. 任务必须有 expected_output + acceptance_criteria
4. 任务 done 后必须有回执记录（receipt）
5. 任务审核通过后必须可写入积分流水（score ledger）

官方文档对标（2026-03-05）

按 docs.openclaw.ai，新 Agent 入职后至少还要满足：

1. openclaw agents list --bindings 可见确定性路由（multi-agent）
2. openclaw channels status --probe 中 Feishu 为 ok（channel health）
3. dmPolicy="open" 时必须 allowFrom 包含 "*"（Feishu dmPolicy）
4. 目标群建议显式配置 groups.<chat_id>.requireMention=true（group mention gating）
5. 配置变更后执行 openclaw doctor --fix 与 openclaw gateway restart（配置收敛）

路径约定补充：

1. 默认配置文件位于 ~/.openclaw/openclaw.json
2. 若设置 OPENCLAW_CONFIG_PATH，应优先读取该路径
3. 若设置 OPENCLAW_STATE_DIR（兼容 OPENCLAW_HOME），应优先读取该状态目录

为什么很多 agent 会"没有 identity"

常见根因只有三类：

1. 只做了 agents/bindings/accounts，漏写 userIdentities
2. userIdentities 写到了错误 key（例如实际运行读 default，你写在了 prod）
3. onboard 后未跑审计脚本，问题一直没暴露

直接后果：群里虽然能收消息，但提及判定可能失败（表现为"did not mention bot"）。

执行流程（ASCII）

[收集入职参数]
      |
      v
[Step1 upsert配置 + identity]
      |
      v
[Step1.5 明确 DM 接入策略(open/allowlist/disabled)]
      |
      v
[Step1.6 若目标是 allowlist，临时 pairing 并等待 owner 首次私聊]
      |
      v
[Step2 接入 delivery runtime]
      |
      v
[Step3 渲染角色模板文档]
      |
      v
[Step3.5 注入 MEMORY 项目铁律]
      |
      v
[Step4 校验 identity/memory/runtime/task-policy]
      |
      v
[Step5 环境预检(requests)]
      |
      v
[Step6 加入默认群组]
      |
      v
[Step7 同步 roster/board + 审计]
      |
      v
[Step8 重启后回归验证]
      |
      v
[Step9 条件交接给 coach]
      |
      v
[交接: 可被@ + 可派单 + 可接入消息项目]

入职参数（最小必填）

• agent-id：英文 ID（如 security）
• agent-name：中文岗位名（如 安全专家）
• role-summary：一句话岗位职责
• core-work：3-5 条核心工作
• app-id
• app-secret
• operator-open-id：必须，用于 userIdentities
• identity-key：可选；不传会自动沿用现有 key（推荐）

标准命令

Step 1：配置 upsert（先 dry-run）

python3 scripts/ensure_feishu_agent.py upsert \
  --agent-id {agent-id} \
  --agent-name "{agent-name}" \
  --app-id {app-id} \
  --app-secret {app-secret} \
  --operator-open-id {operator-open-id} \
  --dry-run

正式执行：

python3 scripts/ensure_feishu_agent.py upsert \
  --agent-id {agent-id} \
  --agent-name "{agent-name}" \
  --app-id {app-id} \
  --app-secret {app-secret} \
  --operator-open-id {operator-open-id}

Step 1.5：明确 Feishu 私聊接入策略（新增）

在写配置前，先确认该 Agent 的业务范围，但 onboarding 默认先走 pairing：

1. pairing：默认入口。用于拿到该账号视角下的真实 open_id 与 pairing code
2. allowlist：当业务范围是指定人群时，拿到 pairing 信息后收口为账号级 allowlist
3. open：当业务范围是面向全员或对外服务时，拿到 pairing 信息后收口为 open + ["*"]
4. disabled：不接受私聊，只允许群内或其他路由入口

推荐规则：

• onboarding 默认：先 pairing
• 面向指定人群：后续收口成 allowlist
• 面向全员/对外：后续收口成 open + ["*"]
• 仅用于群组值守/系统任务：优先 disabled
• 不明确时不要停留在模糊状态；拿到 pairing 信息后必须按业务范围收口成最终策略

Step 1.6：默认走半自动 auto-dm，先 pairing 再收口

执行原则：

1. 不要求人工预填 owner open_id
2. 不依赖 sessions_send 伪造入站消息
3. 必须以该账号真实收到的首次 Feishu 私聊为准，采集该账号视角下的 sender open_id
4. 回填位置必须是账号级配置：channels.feishu.accounts.<accountId>.allowFrom

建议执行顺序：

1. 先把目标账号临时保持为 dmPolicy="pairing"
2. 用 onboarding 收尾话术提示 owner 触发首次私聊，不要把它表述成“去测试机器人”
3. 通过 openclaw pairing list feishu --account <accountId> --json 捕获 pairing request
4. 提取 id(open_id) + code(pairing code)
5. 自动把该 open_id 写入 channels.feishu.accounts.<accountId>.allowFrom
6. 将该账号切换为 dmPolicy="allowlist"
7. 可选：approve pairing，保证首次会话立即打通
8. 提示 owner 再发一条消息做最终验收

推荐收尾话术：

现在接入已经基本完成，最后还差一次首次私聊来获取这位新 Agent 的匹配信息。请你先给新入职的 Agent 发一句任意消息；我拿到匹配信息后，会继续替你完成最后的入职流程。

标准命令：

python3 scripts/capture_feishu_owner_identity.py \
  --account-id {agent-id} \
  --approve-pairing

超时默认 300 秒；在等待期间，owner 需要主动给新 agent 发第一条消息。

验收动作：

openclaw channels status --probe

并至少检查一次：

1. 目标用户首次私聊后，是否成功采集到该账号视角下的 open_id
2. allowlist 是否写入账号级配置而非误写全局配置
3. 再次私聊时，是否不再返回 OpenClaw: access not configured pairing 文案
4. 当前配置是否与业务预期一致

Step 2：接入 delivery runtime（先 dry-run）

python3 scripts/ensure_delivery_runtime_account.py \
  --agent-id {agent-id}

正式执行：

python3 scripts/ensure_delivery_runtime_account.py \
  --agent-id {agent-id} \
  --apply

说明：

• 该步骤会把新 agent 的账号同步到 openclaw-feishu-delivery/runtime/accounts.local.json
• 这样模板里的 route.transport.account={agent-id} 才能稳定引用该 agent

Step 3：渲染角色文档模板

python3 scripts/scaffold_agent_workspace_docs.py \
  --agent-id {agent-id} \
  --agent-name "{agent-name}" \
  --workspace-dir $OPENCLAW_HOME/workspace-{agent-id} \
  --role-summary "{岗位职责}" \
  --core-work "{核心工作1}" \
  --core-work "{核心工作2}" \
  --core-work "{核心工作3}" \
  --force

产物最少包含：

• IDENTITY.md
• USER.md
• MEMORY.md
• AGENTS.md
• TASK_POLICY.md
• 自动创建 workspace-{agent-id}/skills/ 目录（仅建目录，不自动写入 skill 软链接）

模板策略补充：

• 若该 Agent 的职责涉及代码实现、修复、重构、测试或用户明确要求使用 AI 编程工具，生成 AGENTS.md 时必须注入 AI 编程规范段落
• 该段落中的后台执行规则已经固定为：所有任务默认走 tmux + AI 编程工具 + 回调 链路，不再按任务大小区分
• 建议显式传 --ai-coding-agent，不要依赖口头约定

Step 3.5：向该 agent 的 MEMORY.md 注入项目铁律

python3 scripts/inject_agent_memory_rules.py \
  --agent-id {agent-id} \
  --workspace-dir $OPENCLAW_HOME/workspace-{agent-id}

正式执行：

python3 scripts/inject_agent_memory_rules.py \
  --agent-id {agent-id} \
  --workspace-dir $OPENCLAW_HOME/workspace-{agent-id} \
  --apply

要求：

1. 该脚本只处理当前 agent，不允许批量改其他 agent
2. 注入区块是受管区块，可重复执行，重复执行时只更新不重复追加
3. 规则文案以 openclaw-feishu-delivery 项目位置为准，不手写绝对路径

Step 4：强制校验（不通过不得继续）

python3 scripts/ensure_feishu_agent.py audit
python3 scripts/validate_memory_feishu_rules.py --agent-id {agent-id}
python3 scripts/validate_agent_workspace_identity.py \
  --agent-id {agent-id} \
  --agent-name "{agent-name}" \
  --workspace-dir $OPENCLAW_HOME/workspace-{agent-id}
python3 scripts/validate_agent_task_contract_rules.py --agent-id {agent-id}
openclaw doctor --fix
openclaw agents list --bindings
openclaw channels status --probe

Step 4.5：若 onboarding 同时定义首个消息任务，必须用项目脚手架

python3 /root/.openclaw/projects/openclaw-feishu-delivery/scripts/scaffold_agent_task.py --help

要求：

1. 不手写 route / topic / thread / account 配置
2. 模板、job spec、payload example 都通过项目脚手架生成
3. prompt 只保留 business payload contract，不再手写旧飞书规范

Step 5：环境预检（requests 依赖）

群组入群脚本依赖 requests。先在当前执行环境做依赖守卫：

python3 scripts/ensure_python_dependency.py \
  --module requests \
  --package requests

预期结果：

1. 若环境已安装 requests，直接返回 status=ok
2. 若未安装，自动执行 python3 -m pip install requests
3. 安装后再次 import requests 验证成功才允许继续 Step 5

说明：

• scripts/feishu_group_membership.py 在正式执行时也会再次自检并尝试自动补装
• 但标准流程仍要求先跑本步骤，把环境问题前置暴露

Step 6：加入默认群组

python3 scripts/feishu_group_membership.py ensure-bot-groups \
  --target-account-id {agent-id} \
  --scenario agent_onboarding \
  --dry-run

python3 scripts/feishu_group_membership.py ensure-bot-groups \
  --target-account-id {agent-id} \
  --scenario agent_onboarding

Step 7：同步派单面

python3 scripts/sync_agent_roster.py
python3 $OPENCLAW_HOME/workspace/scripts/repair_feishu_native_sessions.py --repair
python3 $OPENCLAW_HOME/workspace/scripts/refresh_dispatch_board.py
python3 $OPENCLAW_HOME/workspace/scripts/audit_dispatch_integrity.py

Step 8：重启与回归

当前会话若经过 gateway，使用延迟重启；否则直接重启。

systemctl --user restart openclaw-gateway.service
journalctl --user -u openclaw-gateway.service --since "2 minutes ago" --no-pager

成功信号：

• 服务 active (running)
• 没有 Invalid config
• 新 agent 出现 Feishu 启动日志
• 群里 @单个 / @多个 都能触发目标 agent

Step 9：条件交接给 coach 开训

入职确认通过后，若 coach agent + workspace-coach + openclaw-training 观察任务脚本 都存在，则自动触发教练接手培训；否则返回 status=skipped 并继续完成 onboarding 收尾，不再强行执行教练开训。

python3 scripts/trigger_coach_training_handoff.py \
  --agent-id {agent-id} \
  --agent-name "{agent-name}" \
  --role-summary "{岗位职责}" \
  --observe-days 14 \
  --notify-timeout 45 \
  --notify

满足条件时，该步骤会自动完成：

1. 生成 onboarding->training 交接单（intake）
2. 调用 openclaw-training 脚本生成观察期定时考核任务 JSON
3. 写入教练 intake 队列
4. 自动向 coach 派发开训指令（--notify）

跳过条件：

1. openclaw.json 中不存在 coach agent
2. workspace-coach 不存在
3. workspace-coach/skills/openclaw-training/scripts/generate_coach_observation_jobs.py 不存在

Step 10：连通运营后台（可选但建议）

如果已部署任务积分后台（Ops Backend），入职通过后同步事件：

curl -X POST http://127.0.0.1:8088/api/onboarding/confirm \
  -H 'Content-Type: application/json' \
  -d '{
    "agent_id":"{agent-id}",
    "agent_name":"{agent-name}",
    "role_summary":"{岗位职责}",
    "creator_type":"human",
    "creator_id":"supervisor"
  }'

预期结果：

1. 生成 onboarding 记录
2. 自动创建 coach 培训 run
3. 进入"考试 -> 观察 -> 门禁"闭环

Step 11：存量 Agent 任务合同补齐（一次性）

如果要把"任务驱动 + 积分激励"快速扩到现有全部 agent，执行：

# 先 dry-run
python3 scripts/backfill_agent_task_contract_docs.py

# 确认后正式写入
python3 scripts/backfill_agent_task_contract_docs.py --apply

该脚本会：

1. 为缺失的 workspace 生成 TASK_POLICY.md
2. 给 AGENTS.md 追加"任务合同铁律"段落（缺失才追加）
3. 给 MEMORY.md 追加"任务执行铁律"段落（缺失才追加）

入职 TODO 闸门（必须全勾）

• onboarding 已默认从 pairing 启动，并成功获取首次真实私聊的 pairing 信息
• 若业务范围是指定人群，已收口为 allowlist
• 若业务范围是全员/对外，已收口为 open 且 allowFrom=["*"]
• 若最终策略是 allowlist，已自动采集 owner open_id
• 若最终策略是 allowlist，allowFrom 已写入账号级配置而非误写全局配置
• 已实际从目标用户视角做过一次 DM 验收，不再返回 pairing code
• upsert --dry-run 输出无关键缺口
• upsert 已写入 agents/bindings/accounts/userIdentities
• ensure_delivery_runtime_account.py --agent-id {agent-id} dry-run 正常
• ensure_delivery_runtime_account.py --agent-id {agent-id} --apply 已写入 runtime account
• scaffold 已生成 IDENTITY.md/USER.md/MEMORY.md/AGENTS.md/TASK_POLICY.md
• validate_agent_workspace_identity.py 通过
• validate_memory_feishu_rules.py 通过
• validate_agent_task_contract_rules.py 通过
• openclaw doctor 无 Feishu 关键告警（尤其 dmPolicy=open 时 allowFrom=["*"]）
• openclaw agents list --bindings 可见 feishu accountId={agent-id} 路由
• openclaw channels status --probe 中 Feishu 为 ok
• ensure_python_dependency.py --module requests 已通过（或返回已安装）
• 默认群组加群 dry-run + 正式执行完成
• sync_agent_roster.py 已刷新员工清单
• refresh_dispatch_board.py 已刷新窗口
• audit_dispatch_integrity.py 无关键阻塞
• gateway 重启后，群内 @{agent-name} 可回
• gateway 重启后，群内 @1个 与 @多个 目标都能命中对应 agent
• 若 coach 基础设施齐全，已执行 trigger_coach_training_handoff.py 并生成 intake + observation jobs
• 若 coach 基础设施齐全，coach 已收到开训派单（或 intake 队列状态为 notified）
• 若 coach 不存在，交接步骤返回 status=skipped 且 reason 明确
• 运营后台（如已部署）可查询到该 Agent（/api/agents）
• 可为该 Agent 创建并派发单负责人任务（/api/tasks + /dispatch）

与 /skill-creator 对齐点

• 核心流程留在 SKILL.md，细节模板下沉到 references/ 与 assets/
• 把脆弱操作（配置 upsert / 校验）固化为 scripts/，减少自由发挥
• 通过 TODO 闸门把"流程完成"变成"验收完成"

资源目录

• scripts/ensure_feishu_agent.py
• scripts/ensure_python_dependency.py
• scripts/feishu_group_membership.py
• scripts/scaffold_agent_workspace_docs.py
• scripts/validate_memory_feishu_rules.py
• scripts/validate_agent_workspace_identity.py
• scripts/validate_agent_task_contract_rules.py
• scripts/sync_agent_roster.py
• scripts/trigger_coach_training_handoff.py
• scripts/backfill_agent_task_contract_docs.py
• references/agent-responsibilities.md
• references/identity-template.md
• references/memory-template.md
• references/task-contract-spec.md
• assets/agent-template/*.tpl ory-template.md`
• references/task-contract-spec.md
• assets/agent-template/*.tpl template.md`
• references/task-contract-spec.md
• assets/agent-template/*.tpl