📦 OGP — 联邦代理通信

前置条件

OGP 必须已安装并运行：

npm install -g @dp-pcs/ogp
ogp setup # 首次交互式配置
ogp agent-comms interview # 重新配置委托授权 / 人工投递行为
ogp config show # 验证已启用框架 + 默认框架
ogp start # 启动默认框架
ogp status # 验证守护进程正在运行

如果提示 ogp: command not found，请先安装。

框架选择（多框架环境必须）

当启用多个框架时，必须显式指定：

ogp --for openclaw status
ogp --for hermes status
ogp --for openclaw federation list
ogp --for hermes federation list

• openclaw 通常使用 ~/.ogp
• hermes 通常使用 ~/.ogp-hermes
• 若不清楚当前框架，先运行 ogp config show

若正在本地仓库测试未发布版本，优先使用本地 CLI：

node dist/cli.js --for openclaw status
node dist/cli.js --for hermes federation list

CLI 发现快捷方式

当用户不确定该运行哪条命令时，先教其使用内置帮助，再自定义指引：

ogp ? # 顶级命令地图
ogp federation approve ? # approve 的上下文帮助
ogp config show # 查看已配置/默认框架
ogp config set-default openclaw
ogp completion install zsh # 或 bash

• 框架上下文不清时，优先 ogp config show
• 用户总忘记 --for 时，优先 ogp config set-default
• 常用 OGP 者，建议 ogp completion install

规范公网端点规则

每个框架只应使用一个稳定的公网网关 URL。推荐生产环境使用固定 HTTPS 主机名，通常放在 Cloudflare Tunnel 或其他反向代理后。

• 保持 gatewayUrl 指向稳定的公网主机名
• 不要在配置里留下过期的临时隧道地址
• 验证公网发现卡片与本地框架身份一致

curl -s https://ogp.example.com/.well-known/ogp
curl -s https://hermes.example.com/.well-known/ogp

每张发现卡片上的公钥必须与目标框架身份匹配。若两个框架意外出现相同公钥，请先停止并修正框架选择/状态隔离，再继续联邦。

可选会合发现（v0.2.14+）

会合服务器（rendezvous.elelem.expert）是可选的发现/邀请服务。用于公钥查询或短邀请码，仅当对端本身已可公网访问时使用。不能当作 NAT 穿透或公网网关 URL 的替代品。

邀请流程（最简单 — v0.2.15+）

发起邀请（你生成代码）：

ogp federation invite
# 输出：Your invite code: a3f7k2 (expires in 10 minutes)
# 把代码发给对端 — 对端运行：
ogp federation accept a3f7k2

接受他人邀请：

ogp federation accept 
# 输出：Connected to a3f7k2... via rendezvous ✅

通过公钥连接（v0.2.14+）

ogp federation connect 
# 先从会合服务查询对端当前连接提示，再直连

在配置中启用会合

添加到 ~/.ogp/config.json：

{
  "rendezvous": {
    "enabled": true,
    "url": "https://rendezvous.elelem.expert"
  }
}

启用后，守护进程启动时自动注册并每 30 秒心跳一次。

配置

Agent ID（v0.2.28+）

agentId 字段指明哪个 OpenClaw 代理拥有此 OGP 网关。执行 ogp setup 时，向导会自动从 OpenClaw 配置中发现可用代理：

Available agents:
🦝 Junior (main)
✍️ Scribe (scribe)
⚡ Optimus (optimus)
Which agent owns this gateway? (number or ID) [1]:

带 agentId 的配置示例：

{
  "daemonPort": 18790,
  "openclawUrl": "http://localhost:18789",
  "openclawToken": "your-token",
  "gatewayUrl": "https://your-gateway.example.com",
  "displayName": "Alice",
  "email": "alice@example.com",
  "stateDir": "~/.ogp",
  "agentId": "main"
}

通知路由 — notifyTargets（v0.2.28+）

notifyTargets 字段支持按代理分流通知。OGP 向本地 OpenClaw 实例发送通知时，会依据消息上下文路由到特定代理。对于 OpenClaw，面向人类的联邦工作现在主要通过 POST /hooks/agent 完成，而非猜测“当前”会话。

notifyTargets 回答“哪个本地代理拥有这项工作？” humanDeliveryTarget 回答“人类后续跟进该去哪？”

配置字段：

• notifyTarget（遗留，字符串）：所有消息共用单一通知目标，向后兼容
• notifyTargets（对象）：代理名到通知目标的映射。例：{"main": "telegram:...", "scribe": "telegram:..."}
• humanDeliveryTarget（推荐用于人类跟进）：OGP 触发摘要/ Relay 义务的显式目的地

多代理配置示例：

{
  "daemonPort": 18790,
  "openclawUrl": "http://localhost:18789",
  "openclawToken": "your-token",
  "gatewayUrl": "https://your-gateway.example.com",
  "displayName": "Alice",
  "email": "alice@example.com",
  "stateDir": "~/.ogp",
  "agentId": "main",
  "notifyTarget": "telegram:123456789",
  "humanDeliveryTarget": "telegram:123456789",
  "inboundFederationPolicy": {
    "mode": "summarize"
  },
  "notifyTargets": {
    "main": "telegram:123456789",
    "scribe": "telegram:987654321",
    "optimus": "telegram:555666777"
  }
}

解析优先级：

OGP 按以下顺序决定通知目标：

• humanDeliveryTarget — 若设置，用作显式人类面目的地
• notifyTargets[agent] — 若代理存在于此映射，则使用
• notifyTarget — 回退到遗留单目标
• 默认 — 若均未设置，则使用代理默认会话

由此可以：

• 依据上下文把联邦消息路由给不同代理
• 明确区分“拥有网关的代理”与“人类跟进频道”
• 保持单代理旧配置兼容
• 逐步迁移到多代理路由而不中断现有部署

人工投递偏好（v0.4.2+）

不要把“当前活跃会话”默认当成满足对端“通知人类”请求的地点。用以下字段分离路由与行为：

• humanDeliveryTarget：OGP 触发的人类面目的地

• inboundFederationPolicy.mode：对端请求的默认处理方式。支持：

示例：

{
  "humanDeliveryTarget": "telegram:123456789",
  "inboundFederationPolicy": {
    "mode": "summarize"
  }
}

对于 OpenClaw：

• OGP 以 POST /hooks/agent 作为主要投递路径，本地代理解析并处理
• 若需直接会话注入，当 OpenClaw 网关启用 TLS 时，OGP 通过 wss:// 使用 Gateway RPC
• 只有实际使用配置的人类通道或平台确认 hook 任务完成，才算投递成功

OGP 现按多层规则解析委托授权：全局默认、对端默认、消息类别规则（human-relay、agent-work、approval-request、status-update）及主题覆盖，依次决定转发、摘要、自主执行或等待批准。

仅当 OpenClaw 设置 hooks.allowRequestSessionKey=true 且请求键匹配 hooks.allowedSessionKeyPrefixes 时，hook 才使用精确人类会话键；否则 OGP 记录警告并以默认 hook 会话运行，即 Telegram 投递仍表现为注入/cli 内容，这是 v0.4.2 的已知限制，详见 README/更新日志。

首次配置请用 ogp setup。之后仅想重新配置委托授权/人工投递，可运行：

ogp --for openclaw agent-comms interview
ogp --for hermes agent-comms interview

当对端说“告诉 David X”，即产生投递义务。不能仅因信息出现在其他活跃会话就视为完成。

联邦管理

列出所有对端

ogp --for openclaw federation list
ogp --for openclaw federation list --status pending
ogp --for hermes federation list --status approved

请求与新对端联邦

ogp --for  federation request  [--alias ]
# 示例：
ogp --for openclaw federation request https://hermes.example.com --alias apollo
# 若省略别名，会自动解析网关展示名：
ogp --for openclaw federation request https://hermes.example.com

批准入站联邦请求

# 自动镜像对端提供的意图（对称联邦）
ogp --for hermes federation approve 
# 或带自定义作用域（非对称）：
ogp --for hermes federation approve  --intents "message,agent-comms,project.join,project.contribute,project.query,project.status"

注意（OGP 0.2.24+）： 对端 ID 现为公钥前缀（如 302a300506032b65）
意图协商： 批准时默认镜像对端提供的意图，双方获得对称能力

为已有对端授权或更新作用域

ogp --for openclaw federation grant  --intents "message,agent-comms,project.join,project.contribute,project.query,project.status"

查看与对端互授作用域

ogp --for openclaw federation scopes 
# 显示：
# - GRANTED TO PEER（对端可调用你的网关）
# - RECEIVED FROM PEER（你可调用对端网关）

ping 对端

ogp --for openclaw federation ping 

发送原始联邦消息

ogp --for openclaw federation send   ''

发送代理间消息（agent-comms）

ogp --for openclaw federation agent   ""
# 示例：
ogp --for openclaw federation agent apollo general "Hey, can you check on project synapse?"

管理 agent-comms 策略（响应哪些主题）

联邦作用域与 agent-comms 策略是两层独立。批准时自动处理作用域。策略控制你的代理实际响应什么 — 批准时默认开启 general，其余默认 off。

# 状态页 — 显示允许/阻止及建议
ogp --for openclaw agent-comms policies 
# 全局所有对端视图
ogp --for openclaw agent-comms policies
# 允许某主题
ogp --for openclaw agent-comms add-topic   --level summary
# 阻止某主题
ogp --for openclaw agent-comms set-topic   off
# 对某对端默认全部开启
ogp --for openclaw agent-comms set-default  summary
# 查看活动日志
ogp --for openclaw agent-comms activity [peer-id]

响应级别：full（完整内容给代理）、summary（摘要）、escalate（转给用户）、off（阻止 — 发送方收到幽默拒答）

作用域参考

联邦工作流

新方式 — 邀请流程（v0.2.15+，推荐）

1. 运行：ogp federation invite → 获得 6 位代码
把代码发给对端（Telegram、Slack 等）
对端运行：ogp federation accept 

作用域自动授予 + "general" 主题自动启用 ✓
测试：ogp --for  federation agent  general "hello"

旧方式 — 手动交换 URL（仍可用）

1. 获得对端网关 URL（对端发给你）
检查其卡片：curl -s /.well-known/ogp | python3 -m json.tool
请求联邦：ogp --for  federation request 
对端在其侧批准（或若对端已请求，你批准）
   
→ 作用域自动授予 + "general" 主题自动启用 ✓
检查 agent-comms 状态：ogp --for  agent-comms policies 
按需添加更多主题：ogp --for  agent-comms add-topic  
测试：ogp --for  federation ping 
测试 agent-comms：ogp --for  federation agent  general "hello"
（可选）创建或加入共享项目

项目协作（通过 OGP）

完整项目管理请使用 ogp-project 技能。速查：

# 创建项目
ogp --for openclaw project create  "" --description ""
# 邀请对端加入
ogp --for openclaw project request-join   ""
# 记录贡献
ogp --for openclaw project contribute   ""
# 类型：progress, decision, blocker, context, idea, context.description, context.repository
# 查询项目活动
ogp --for openclaw project query  [--type ] [--limit 10]
ogp --for openclaw project status 
# 查询对端项目数据
ogp --for openclaw project query-peer  

故障排除

ogp config show
ogp --for openclaw status
ogp --for hermes status
# 或查看日志：
tail -f ~/.ogp/daemon.log
tail -f ~/.ogp-hermes/daemon.log

ogp --for openclaw stop
ogp --for openclaw start --background
ogp --for hermes stop
ogp --for hermes start --background

cp ~/.ogp/peers.json ~/.ogp/peers.json.backup.$(date +%Y%m%d-%H%M%S)
printf '[]\n' > ~/.ogp/peers.json
cp ~/.ogp-hermes/peers.json ~/.ogp-hermes/peers.json.backup.$(date +%Y%m%d-%H%M%S)
printf '[]\n' > ~/.ogp-hermes/peers.json