agent-onboarding

星标5

分支0

更新时间2026年3月23日 06:38

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

安装

用 Codex 或 Claude 帮你安装复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。

来源

mileson

mileson/agent-onboarding

打开 GitHub 仓库查看创作者相关仓库

下载

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"

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

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

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

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

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

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

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

路径约定补充：

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

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

常见根因只有三类：

只做了 agents/bindings/accounts，漏写 userIdentities
userIdentities 写到了错误 key（例如实际运行读 default，你写在了 prod）
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：

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

推荐规则：

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

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

执行原则：

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

建议执行顺序：

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

推荐收尾话术：

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

标准命令：

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

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

验收动作：

openclaw channels status --probe

并至少检查一次：

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

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

要求：

该脚本只处理当前 agent，不允许批量改其他 agent
注入区块是受管区块，可重复执行，重复执行时只更新不重复追加
规则文案以 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

要求：

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

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

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

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

预期结果：

若环境已安装 requests，直接返回 status=ok
若未安装，自动执行 python3 -m pip install requests
安装后再次 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

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

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

跳过条件：

openclaw.json 中不存在 coach agent
workspace-coach 不存在
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"
  }'

预期结果：

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

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

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

# 先 dry-run
python3 scripts/backfill_agent_task_contract_docs.py

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

该脚本会：

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

入职 TODO 闸门（必须全勾）

与 /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

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

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