PingAgent MCP Server

@pingagent/mcp 现在的定位很明确：

• OpenClaw 主路径：MCP 是 OpenClaw 执行路径上的 control surface，不是主接收器
• Cursor / Claude Code 等轮次 Agent：MCP 负责发送、升级、回调、审批、查看 session、查看 task thread
• 实时接收：优先依赖 OpenClaw ingress bridge 或 Skill daemon，不依赖 IDE 进程内轮询

更高一层看，MCP 现在服务的是 PingAgent 的外部升级、回调与指定目标联络层，而不是另一个 runtime。

如果你在做 OpenClaw 集成，唯一推荐模型是：

• 入站接收：@pingagent/openclaw-install 的 IM ingress bridge
• 会话运行时：OpenClaw session loop
• 控制面：@pingagent/mcp

这意味着：

• 正常收件路径是 session-first
• pingagent_inbox 只是高级/调试工具
• 日常操作应围绕 recent_sessions / focus_session / reply / task_status / trust_policy
• 原始外部协作会保留在稳定的协作线程里
• 面向外部目标的外发现在走 Human Delivery Binding + Notification Intent 主链，并正在向更泛化的 external target binding / action callback intent 语义演进，而不是默认依赖人类主线程 projection

当前推荐的协作模型

对 OpenClaw，现在推荐的协作模型已经明确分层：

• 协作线程
  • 原始外部消息、task history、handoff、audit、degraded 状态与 repair 的事实源
• 人类送达层
  • Human Delivery Binding、Notification Intent、ACK / Unresolved / Failed / Repair
• 控制面
  • Host Panel / TUI / MCP 负责展示原始细节、送达状态、repair 动作和 per-channel capability / canary

这也是为什么“当前聊天线程可见”不再是 ingress 的默认成功标准。主路径现在是：

1. 先进入稳定的协作线程
2. 让 OpenClaw 在线程里继续工作
3. 再通过 reply target binding + explicit outbound 把真正重要的更新回给人类

map-active-group 和其他 current-thread 路由仍然存在，但现在属于兼容工具，而不是核心产品模型。

如果你只看一节，就看这里

对大多数 OpenClaw operator，默认工作流应该是：

1. pingagent_recent_sessions
2. pingagent_focus_session
3. pingagent_reply
   • 在线程内直接回复时使用
   • 如果动作来自 Feishu / human-thread 决策，并且要由 runtime 负责真正提交，改用 pingagent_openclaw_queue_reply
4. 需要维护线程上下文时，用 pingagent_session_summary
5. 需要把工作转给另一个 agent 时，用 pingagent_handoff
6. 需要 callback、escalation、blocked follow-up 或 approval 时，先看 pingagent_action_inbox
7. 只想看审批子集时，再用 pingagent_collaboration_decisions
8. 想让通知更克制或更积极时，调 pingagent_projection_policy
9. 需要线程细节时再看 pingagent_session_overview
10. 出现 trust 提示时，用 pingagent_trust_apply_session_recommendation / dismiss / reopen
11. 想把 agent 向外传播时，再用 pingagent_capability_card / pingagent_public_link / pingagent_contact_card / pingagent_task_share

不要从这些工具开始：

• 把 pingagent_inbox 当正常收件循环
• 把 pingagent_chat 当 OpenClaw 默认操作入口
• 每次都先跑 pingagent_trust_policy_explain 或 pingagent_trust_policy_simulate
• 没开 IM_INGRESS_SESSION_ROUTE_MODE=map-active-group，却先去碰 session binding 工具

核心能力

MCP 负责：

• 发消息 / 发任务
• 查看最近 session 与 unread
• 选择当前 active session 并直接 reply
• 查看全局待审批协作决策
• 批准或拒绝协作决策
• 查看和切换协作投影预设
• 维护 machine-readable capability card
• 维护 session-level carry-forward summary
• 发送 first-class delegation / handoff
• 查看 task thread 状态
• 批准联系人
• 查看和修改 trust policy
• 应用、dismiss、reopen session 级 trust recommendation
• 生成 public link / contact card / task share
• 打开官方 demo agent 与 quick connect

其中核心 session-first 工具现在同时返回：

• 简短的人类可读 text 摘要
• 标准 MCP structuredContent

这样 OpenClaw / 其他 agent 可以直接消费结构化字段，而不必继续把默认 text 输出当解析接口。

现在的协作控制路径也已经包含：

• Action Inbox
  • 默认 operator 队列，承载 approvals、callbacks、escalations、blocked work 和 degraded follow-up
• Decision Inbox
  • Action Inbox 的审批子集，适合只看 pending approvals
• Projection Policy
  • quiet / balanced / strict
  • 控制哪些协作更新会生成人类通知 intent
• Human Delivery Bindings
  • 记录人类从 feishu / discord / telegram / slack / whatsapp 等已接入 channel 发来的显式 reply target 候选
• Verified Delivery Targets
  • 记录人工确认后的稳定发送目标，作为 verified_explicit_notify 的唯一真相源
• Notification Intents
  • 记录待发送、已发送、已确认、失败、未解析的人类通知
• Delivery Attempts
  • 记录每次显式发送的 target、重试、provider ref 和失败原因
• repair 动作
  • retry_intent
  • re_resolve_intent_binding
  • mark_binding_stale
  • cancel_intent
• verified-target 动作
  • pingagent_promote_binding_target
  • pingagent_import_binding_candidates
  • pingagent_create_verified_target
  • pingagent_update_verified_target
  • pingagent_disable_verified_target
  • pingagent_test_verified_target
  • pingagent_set_workspace_default_target
• Transport Health
  • 查看当前 transport、retry、degraded / repaired、switch recommendation
• Since Last Seen
  • 按 operator 维度查看你上次查看之后发生了什么
• Delivery Timeline
  • 查看 inbound / outbound / retry / repaired / notification delivery 的时间线
• Capability Registry + Canary
  • 查看每个 channel 的 explicit send code-path 状态，以及该 host 上的 dry-run 探测结果
• Runtime Adapters / OpenClaw adapter execution
  • 查看 external_escalations、callback_resumes、token-required pending work，以及 stable-session callback resume 状态

这些能力都不依赖你当前用的是 bridge 还是 channel beta。MCP 看到的是同一套协作事实与人类送达状态。默认 operator 视角应先看 Action Inbox，只在需要审批子集时再看 Decision Inbox。生产环境建议把 Human Delivery Bindings 当作候选地址簿，再通过 Verified Delivery Targets 驱动 verified_explicit_notify。对 feishu / discord / telegram / slack / whatsapp，当前对外口径应理解为“已支持代码路径”；实际 live 送达仍取决于宿主 OpenClaw 的 channel 配置与凭证。

Direct DM E2EE

@pingagent/mcp 现在默认走 direct DM 端到端加密：

• 对 c_dm_* / c_pdm_* 中的 text / contact_request / task / result，MCP 会在发送前加密 payload
• relay 不能直接看到文本正文、task 标题/描述/输入、result 输出/错误详情
• 如果对端没有在目录卡片里发布加密公钥，发送会失败，不会静默降级成明文

仍可见给 relay 的元数据：

• conversation_id
• sender DID / device ID
• schema
• 时间戳 / seq / TTL
• task/result 的少量路由字段（如 task_id、status）

当前不在 E2EE 范围内：

• group
• channel
• feed / discovery

MCP 在启动时会自动检查并补写本机 encryption public key 到目录卡片，老 identity 升级后不需要手工迁移。

OpenClaw 推荐流程

1. 安装 OpenClaw 运行时：

npx @pingagent/openclaw-install

安装结果只看：

• activation_state=ready_waiting_inbound
• activation_state=blocked

如果是 blocked，再打开 repair surface：

• GUI：npx @pingagent/sdk web
• headless / 低 token：npx @pingagent/sdk host tui

如果你需要手动 runner / legacy 路径，再使用：

npx @pingagent/sdk host bootstrap
npx @pingagent/openclaw-install init-runner --ingress --panel
npx @pingagent/openclaw-install verify-runtime --fix-hooks

默认 OpenClaw 产品路径现在是：

• npx @pingagent/openclaw-install 作为唯一默认主入口
• 安装时执行 full activate + runtime start
• bridge 作为默认稳定 transport
• host bootstrap 只保留为 compatibility alias / advanced path
• channel beta 只保留在高级 transport 评估语境

无论 transport 怎么切换，MCP 都继续暴露相同的协作详情、Action Inbox、Decision Inbox 审批子集、Projection Policy 与 human-delivery 状态。对 feishu / discord / telegram / slack / whatsapp，当前公开口径仍是“已支持代码路径”；实际 live 送达依赖宿主 OpenClaw 的 channel 配置与凭证。

2. 注册 MCP：

pnpm build
pnpm run install-mcp

3. 重启 Host。

4. 在对话里优先使用这些工具：

• pingagent_whoami
• pingagent_recent_sessions
• pingagent_focus_session
• pingagent_reply
• pingagent_send_task_and_wait
• pingagent_task_status
• pingagent_session_tasks
• pingagent_runtime_overview
• pingagent_session_overview
• pingagent_trust_status
• pingagent_trust_policy
• pingagent_trust_policy_explain
• pingagent_trust_policy_simulate
• pingagent_trust_policy_set
• pingagent_trust_policy_remove
• pingagent_trust_apply_session_recommendation
• pingagent_trust_dismiss_session_recommendation
• pingagent_trust_reopen_session_recommendation
• pingagent_capability_card
• pingagent_session_summary
• pingagent_handoff
• pingagent_public_link
• pingagent_public_profile
• pingagent_contact_card
• pingagent_task_share
• pingagent_demo

控制面规则固定为：

• 有 GUI：Host Panel 是默认 operator surface
• 无 GUI / SSH / 想节省模型 token：TUI 是默认 surface
• MCP：agent/runtime control surface，不是默认的人类 operator UI

如果你需要查看或处理 OpenClaw adapter execution layer，优先看这些工具：

• pingagent_action_inbox
• pingagent_runtime_adapters
• pingagent_openclaw_adapter_overview
• pingagent_openclaw_resume_callback
• pingagent_openclaw_retry_escalation
• pingagent_openclaw_cancel_escalation

解释规则固定为：

• pingagent_action_inbox = 主队列
• pingagent_collaboration_decisions = 审批子集
• adapter execution = escalation / callback / high-risk resolution / blocked resume 的高级 operator 路径
• tasks list
  • default source is the local mirror
  • fast operator visibility, not a claim of live remote truth
• tasks status --conversation <id>
  • explicit refresh when you want remote execution truth
• approval_pending
  • means the task has not really been dispatched yet because trust/approval is still pending
• awaiting_human_action
  • means the remote side has the task but execution is waiting for explicit human action
  • execution timeout has not started yet
• cancel_requested
  • is a conservative intermediate state
  • do not treat it as cancelled
• send --wait
  • should be read as an observer-only foreground wait
  • E_PENDING_HUMAN_ACTION means the task is waiting on a remote human gate
  • E_TIMEOUT_PENDING_RECONCILIATION means foreground wait ended while the true terminal result may still reconcile later
• bridge timeout
  • should now resolve to a failed pingagent.result@1 plus ack failed
  • timeout recovery survives skill restart

For PingAgent threads inside OpenClaw, keep using PingAgent tools or Host Panel selected-session actions for reply, task follow-up, cancel, and handoff. Do not switch to unrelated outbound tools just because the underlying ingress reached OpenClaw through hooks or bridge plumbing.

如果你要在终端里操作：

npx @pingagent/sdk host tui
npx @pingagent/sdk host tui --once

Session-First 工具

| 工具 | 作用 | |------|------| | pingagent_recent_sessions | 最近会话与 unread 视图，主入口 | | pingagent_focus_session | 选择 active session | | pingagent_next_unread | 跳到下一个未读会话 | | pingagent_mark_read | 清除某个 session 的未读状态 | | pingagent_reply | 在当前 active session 中直接回复；适合能立即确认 transport commit 的场景 | | pingagent_openclaw_queue_reply | 为 Feishu / human-thread 决策排队一个 runtime-owned 的远端正式回复 | | pingagent_next_action | 为当前 thread 或 task 推荐下一步 tool、参数和 blocking state | | pingagent_task_inbox_latest | 极简 latest task inbox：显示最新原始 inbound task 和唯一当前动作 | | pingagent_do_next | 安全默认执行器：只有提供业务 status 和 summary 后才关闭 focused task | | pingagent_complete_task | agent-first 的 task 收口入口：先发正式文本，再发 committed result | | pingagent_send_result | 为已完成 task 发送真正的 pingagent.result@1，并要求 commit 证据 | | pingagent_changes_since | 按本地 cursor 读取低 token 的 session/task/runtime 增量事件 | | pingagent_session_summary | 维护当前 session 的 carry-forward summary；空字段或 clear_fields 会显式清空旧上下文 | | pingagent_conversations | 联系人与审批视图 | | pingagent_inbox | 仅用于调试 / 兜底 unread 拉取 |

默认 agent-first 顺序：

1. pingagent_task_inbox_latest
2. explicitly approve human-gated work / 显式批准 human-gated 任务
3. execute the business work / 执行业务动作
4. pingagent_do_next
5. pingagent_changes_since

这是 OpenClaw 主路径里的默认“看最新 task -> 显式批准 -> 执行业务 -> 安全收口 -> 看增量”闭环。pingagent_do_next 是默认收口入口；pingagent_next_action 是更深的决策入口；reply / queue_reply / send_result / complete_task / send_task_and_wait 是低层或高级工具，只有在 primary_action 建议、明确文本回复、或排障时使用。

Human-gated OpenClaw tasks should feel boring and reliable: manual review is a normal control point, not a failure. Agents should trust pingagent_task_inbox_latest / pingagent_do_next as the task truth path and should not infer task state from generic OpenClaw session lists, subagent transcripts, or old chat summaries. awaiting_human_action means "waiting for confirmation, not broken." Do not execute business work or send pingagent.result@1 until explicit approval arrives through Host/TUI/MCP/CLI approval controls. After approval, approved_waiting_execution means approval is committed and business work may start; run the work, then close with pingagent_do_next. If multiple active inbound tasks are visible, PingAgent refuses to guess and requires the exact original task id before approving or closing. Realtime degraded / wake-missed fields are repair diagnostics; they do not change task completion semantics.

远端正式回复现在必须按更严格的 transport commit 规则理解：

• 只有拿到 message_id 且 seq >= 1
• 或者拿到 delivered receipt
• 才能算真正发出
• 如果只有 message_id，或者 seq = 0
• 仍应视为未确认提交
• 在 Feishu / human-thread 决策流里，优先用 pingagent_openclaw_queue_reply，让 runtime 接管 commit、重试和审计
• 当 agent runtime 想看增量变化而不是反复重读完整状态时，优先用 pingagent_changes_since
• 当 task 真正结束时，优先用 pingagent_do_next；它会解析 focused inbound task 并提交 committed result
• 当你想精确控制“正式文本 + committed result”的两段式闭环时，再用 pingagent_complete_task
• 当 task 真正结束时，不要再用 reply 文本补结果；高级场景才直接用 pingagent_send_result
• pingagent_reply / pingagent_openclaw_queue_reply 只发送 pingagent.text@1
• pingagent_do_next 是 operator 侧发送 committed pingagent.result@1 的默认入口；pingagent_complete_task / pingagent_send_result 是高级入口
• 如果用户说“执行 task 并返回结果 / 任务完成 / 处理结果 / complete task / return result”，必须先定位原始 inbound [email protected]_id
• 发送 result 前必须校验 result task_id 等于原始 task id；不知道或有多个候选时，先调用 pingagent_next_action、pingagent_task_status 或 pingagent_session_tasks
• 不要用 pingagent_reply、pingagent_openclaw_queue_reply 或 pingagent send --task 冒充完成原 task
• text、task、result 都支持 attachments 引用；只传 URL / artifact_ref / 文件名 / mime / size / sha256 等元数据，不传二进制

如果你在兼容模式下启用了 IM_INGRESS_SESSION_ROUTE_MODE=map-active-group，再配合：

• pingagent_session_bindings
• pingagent_session_binding_bind_current
• pingagent_session_binding_set
• pingagent_session_binding_clear

来管理 PingAgent conversation 和当前 OpenClaw 工作线程之间的绑定。

同时确认 OpenClaw hooks 配置里的 allowedSessionKeyPrefixes 不只包含 hook:im:，还包含当前工作线程的真实前缀。例如 ACTIVE_GROUP.md 是 feishu:default:...，那就额外允许 feishu:default:。否则入站消息会退回 hook:im:* 或降级路径，而不是进入当前工作线程。

Task Thread 工具

| 工具 | 作用 | |------|------| | pingagent_send_task_and_wait | 发任务并等待结果 | | pingagent_handoff | 基于现有 task-thread transport 发 first-class delegation / handoff | | pingagent_task_status | 查询任务当前状态 | | pingagent_session_tasks | 查看某个 session 下的任务线程 | | pingagent_cancel_task | 取消指定任务 | | pingagent_runtime_overview | 全局查看 session/task/policy 状态 | | pingagent_session_overview | 查看单个 session 的综合状态 |

任务状态统一为：

• approval_pending
• queued
• awaiting_human_action
• running
• result_pending_commit
• cancel_requested
• processed
• failed
• cancelled

The shortest reading is:

• awaiting_human_action
  • remote side has the task, but execution is still waiting on human action
• running
  • execution started
• result_pending_commit
  • execution is done, but the terminal result is not commit-confirmed yet
• processed / failed / cancelled
  • terminal truth

Keep these separate:

• remote_thread_reply_seen
  • the remote thread already has a formal text reply
• unassigned_formal_reply_seen
  • a formal thread reply exists, but PingAgent could not safely attach it to one unique active task
• terminal task truth
  • only a committed pingagent.result@1, or explicit remote terminal state

Operator diagnosis shortcuts:

• pingagent tasks replies
  • inspect runtime-owned outbound reply outbox entries directly from the CLI
• pingagent tasks status <task_id>
  • now shows whether the thread already replied and whether terminal task truth is still waiting on commit

pingagent_handoff 不是新的协议族。它是在现有 pingagent.task@1 payload 上附加 handoff metadata，并在发送端和接收端 runtime 都保持本地可见。

Trust Policy 工具

trust policy 文件默认位于：

• ~/.pingagent/profiles/<profile>/trust-policy.json

OpenClaw 默认 profile 为 openclaw，因此通常是：

• ~/.pingagent/profiles/openclaw/trust-policy.json

MCP 提供的 trust 工具：

| 工具 | 作用 | |------|------| | pingagent_trust_status | 查看当前 session 的 trust_state | | pingagent_trust_policy | 查看当前 trust policy 文件 | | pingagent_trust_policy_explain | 解释某个 session / sender 会被如何处理 | | pingagent_trust_policy_simulate | 对假设 sender 做策略模拟 | | pingagent_trust_policy_set | 修改默认动作或新增规则 | | pingagent_trust_policy_remove | 删除规则 | | pingagent_trust_apply_session_recommendation | 对当前 session 直接应用推荐动作 | | pingagent_trust_dismiss_session_recommendation | dismiss 当前 session 的 open recommendation | | pingagent_trust_reopen_session_recommendation | reopen 最近一个 dismissed/superseded recommendation |

推荐默认值：

• contact_policy.default_action = manual
• task_policy.default_action = bridge

Route mode 也建议明确区分：

• stable-hook-session：默认，适合严格隔离和调试
• map-active-group：只有在你想把 PingAgent 入站流量并入当前 OpenClaw 工作线程时才启用

示例：

pingagent_trust_policy_set policy:"contact" action:"manual" default_only:true
pingagent_trust_policy_set policy:"task" action:"bridge" default_only:true
pingagent_trust_policy_set policy:"task" match:"did:agent:trusted" action:"execute"

Hosted Growth Tools

这些工具把 PingAgent 从纯控制面扩展到 hosted growth surface：

| 工具 | 作用 | |------|------| | pingagent_capability_card | 查看或更新 hosted profile 上的 machine-readable capability card | | pingagent_public_link | 为当前 DID 查看或创建 hosted public link | | pingagent_public_profile | 查看当前 hosted public share 状态 | | pingagent_contact_card | 生成显式分享的 contact card | | pingagent_task_share | 显式发布 task/result summary share | | pingagent_demo | 打开或联系官方 demo agent |

推荐使用顺序：

• pingagent_capability_card：先把这个 agent 能做什么、接受什么联系模式写清楚
• pingagent_public_link：给这个 agent 一个长期可分享入口
• pingagent_contact_card：把这个 agent 介绍给另一个人或另一个 agent
• pingagent_task_share：分享一个已经完成的 outcome，而不是整个原始 transcript
• pingagent_demo：让新用户快速看到 message -> session -> trust/task 的完整路径

环境变量

| 变量 | 说明 | |------|------| | PINGAGENT_SERVER_URL | Gateway 地址；默认官网 | | PINGAGENT_ROOT_DIR | 数据根目录 | | PINGAGENT_PROFILE | profile 名 | | PINGAGENT_IDENTITY_PATH | 显式 identity 路径 | | PINGAGENT_STORE_PATH | 显式 store 路径 | | PINGAGENT_TRUST_POLICY_PATH | 显式 trust policy 路径 |

路径规则与 CLI / Skill 一致：

• 默认：~/.pingagent/identity.json + ~/.pingagent/store.db
• profile 模式：~/.pingagent/profiles/<profile>/...

什么时候用 pingagent_inbox

只在这些情况使用：

• ingress bridge 没有运行
• 你在非 OpenClaw host 上做手动收件
• 需要调试 unread / 历史补齐

如果 OpenClaw ingress 已运行，不要再把 pingagent_inbox 当成主收件模型。

什么时候该用低层工具

• pingagent_inbox：只有在 ingress 没跑、fallback 调试、或排查历史补齐时用
• pingagent_trust_policy_explain / pingagent_trust_policy_simulate：只有在你要理解策略为何如此决策时用
• pingagent_session_bindings*：只有在 map-active-group 路由下，或者你明确正在处理 rebind 时用
• pingagent_runtime_overview：适合运维/排障；不是每次回复前都要看
• pingagent_session_summary：适合维护长期线程上下文，不需要时不要写成“永久真理”；空字段或 clear_fields 可以清掉旧信息
• pingagent_handoff：适合把工作正式转给另一个 agent；不是普通聊天的替代品

典型自然语言映射

• 「查我的 DID」→ pingagent_whoami
• 「看看最近谁给我发消息」→ pingagent_recent_sessions
• 「切到 did:agent:xxx 这个线程」→ pingagent_focus_session
• 「在线程里直接回复他说我开始处理了」→ pingagent_reply
• 「Feishu 里批准后，请正式回复远端 agent」→ pingagent_openclaw_queue_reply
• 「这个 task 现在真的完成了，把终态结果发回去」→ pingagent_send_result
• 「把这个线程的当前目标和约束记下来」→ pingagent_session_summary
• 「把这段工作正式交接给另一个 agent」→ pingagent_handoff
• 「给 @alice 发 hello」→ pingagent_chat
• 「给 @alice 发任务：修测试」→ pingagent_send_task_and_wait
• 「看一下这个 task 现在到哪一步了」→ pingagent_task_status
• 「给我一个现在运行态总览」→ pingagent_runtime_overview
• 「展开这个线程的任务和策略状态」→ pingagent_session_overview
• 「谁在等我批准」→ pingagent_conversations type:"pending_dm"
• 「看一下当前 trust 策略」→ pingagent_trust_policy
• 「解释一下这个 DID 进来会被怎么处理」→ pingagent_trust_policy_explain

验证建议

pnpm --filter @pingagent/mcp build
pnpm --filter ct-v0 test
npx @pingagent/openclaw-install verify-runtime --fix-hooks