agenthub/docs/AGENT_REGISTRATION.md

39 KiB
Raw Permalink Blame History

Agent 接入规范(v2)

这份文档是接一个 Agent 上 hub 的唯一规范:nanobot、DeepSeek Harness(dsh)、OpenClaw、 OpenAI 兼容服务、自研框架都按它来。它描述的是当前代码的真实行为,不是提案 —— 每条都能在仓库里找到对应实现,改行为时同步改这里。

先读第 0 节,能覆盖 90% 的接入;排障直接跳第 9 节。

层 代码位置
hub 协议与登记 backend/agenthub/api/routes_gateway.py、api/routes_agents.py、services/registry.py
帧格式 / 驱动契约 backend/agenthub/gateway/frames.py、backend/agenthub/adapters/base.py
外拨通道(hub 侧驱动) backend/agenthub/adapters/connector.py
接入片段生成 backend/agenthub/deploy/snippets.py(CLI agenthub config、GET /deploy/templates)
nanobot 接入件(渠道) deploy/nanobot-gateway/channel/agenthub/
dsh 接入件(插件) plugins/dsh-agenthub/
单文件 Python SDK deploy/nanobot-gateway/channel/agenthub/agenthub_client.py

0. 一页速查

0.1 三种接入形态

形态 谁发起连接 Agent 侧要什么 hub 侧要什么 典型场景
外拨 embedded Agent 进程内的接入件外拨 WS 连接配置 + 身份 无 nanobot 内嵌渠道、dsh 插件(推荐)
外拨 connector(桥接) Agent 同机/旁边的桥接进程外拨 WS 同上(写在那个进程里) 无 无头 CLI:deploy/cli-bridge/bridge.py(codex / claude / WorkBuddy);改不动也拨不进的 Agent 贴一份 SDK
直连 direct hub 拨 Agent 的 HTTP/WS 无 AgentHub 配置 base_url + auth nanobot serve、OpenAI 兼容服务。「接入」向导不提供这一类,只能手工登记

外拨两种形态在 hub 侧是同一个驱动(connector):hub 从不需要能"拨到" Agent,所以笔记本、 无 ingress 的容器、跳板机后的云主机都能接。

0.2 一条凭证路径

外拨形态只有一种接法,五套 Agent 一字不差:

  1. hub 签发凭证:控制台「接入」页点一下,或 agenthub agent add --show-token,拿到 属于这台 Agent 的 ag_…;
  2. Agent 侧填两样:hub 的 IP+端口(server)+ 这个凭证,别的一律不填;
  3. 注册验证 = 它上线:Agent 外拨 WS /api/v1/gateway/ws?agent_token=ag_…,hub 从凭证 反查出它是谁,并在 hub.hello 里把 agent_id 告诉它 —— 所以连 agent id 都不用抄。

没有 enrollment 入场令牌,没有 Hub ID,没有预注册/自注册之分。凭证就是身份: 建档案 → 签凭证 → 填凭证 → 上线,每一步都只有这一条路。

直连(direct)没有 AgentHub 凭证 —— 不是 Agent 拨 hub,是 hub 拨它,用登记表里的 base_url + auth(那台服务自己的 key,跟 ag_… 无关)。它是 hub 侧的一种驱动能力, 不在「接入」向导里:向导只给两类接入(插件 / 渠道、桥接),这一类要用 agenthub agent add --connection direct 手工登记。

0.3 每个类型的最小接入

# A. 桥接(codex / claude / WorkBuddy 这类无头 CLI):在装有该 CLI 的机器上跑一个桥接进程
python3 deploy/cli-bridge/bridge.py --hub http://127.0.0.1:8100 \
  --token ag_… --name workbuddy --cli workbuddy --workdir ~/code/目标仓库 --mode write

# B. nanobot:贴进 ~/.nanobot/config.json 的 channels.agenthub,重启 nanobot
#    {"enabled": true, "server": "http://127.0.0.1:8100", "name": "alpha", "agent_token": "ag_…"}

# C. dsh:贴进 ~/.dsh/profiles/<profile>/cordis.patch.yml 的插件 config,起 dsh
#    - insert:
#        - id: dsh-agenthub
#          name: '@nex/dsh-agenthub'
#          config: { server: http://127.0.0.1:8100, name: dsh-web, agentToken: ag_… }

# D. 自研 Agent:一个进程贴一份单文件 SDK(6.7),同样只有 hub_url + agent_token 两样

# E. 直连(自带 HTTP/WS 服务的 Agent,向导外手工登记):Agent 侧一行都不配
agenthub agent add --name ow-1 --driver openclaw --connection direct --base-url ws://127.0.0.1:18789

# 生成片段:agenthub config --name alpha --kind bridge|nanobot|dsh|claw
#   已建档的 Agent 直接印出真凭证(第 0.2 步签的那把,见第 7 节);没建档的留 <agent_token> 占位
# 控制台等价入口:接入 → ① 选是哪套 Agent → ② 签发凭证、贴过去、看它 online

ah_… 是控制台的 API Key,不是 Agent 凭证:填进 agentToken / --token 会被明确拒绝, 不是默默失败。


1. 概念模型

1.1 五个正交维度

维度 取值 回答的问题 谁决定
driver connector / nanobot / nanobot_ws / openai_compatible / openclaw / mock / 第三方 entry-point hub 用什么协议跟它说话 hub(控制台可改;未知框架可注册)
agent_type nanobot / deepseek_harness / openclaw / hermes / custom 这一行是哪个产品(决定像素小人形象与徽章) hub 侧登记,留空 = 跟 driver 走
connection_mode embedded / connector / direct 谁发起连接 Agent 自报(外拨)/ hub 登记(直连)
deployment_kind local / docker / cloud 它跑在哪 Agent 自报,或 hub 侧登记
source manual 这行是怎么来的(只剩「hub 侧建档」这一种来源) hub

四者互不影响:同一个 nanobot 既能 direct(hub 拨它的 serve 端点)也能 embedded(进程内渠道); 同一个 connector 驱动既服务 embedded 也服务外挂接入件。

1.2 三层划分

连接层(都必须):server 地址 + connection_mode
身份层(只有外拨要):agent_token 一把凭证(agent_id 由 hub 在 hello 里回给你)
元数据层(hub 侧登记 / Agent 自省上报):
    name、display_name、description、emoji、agent_type、
    role、labels、deployment_kind/ref、max_concurrency、
    capabilities(自省)、model(**只**来自自省)

1.3 字段归属(谁拥有什么)

  • Agent 自己的:模型(nanobot 的 agents.defaults.model、dsh 的默认模型设置)、provider 配置、 工作目录、超时、渠道/插件的行为开关(streaming / sendProgress / sendToolHints / allowFrom)。 hub 只显示 Agent 在心跳里自省上报的模型,不替它决定。
  • hub 侧的:role(团队角色,playbook 选人用)、labels、agent_type、deployment_kind 兜底、 max_concurrency 上限、凭证哈希、source。
  • 两边都不该有的:Agent 侧身份文件(见 3.5 R3)、model 的注册副本、role 的渠道副本。

2. 接入形态

2.1 外拨(embedded / connector)

接入件拨一条出站 WebSocket 到 ws://<hub>/api/v1/gateway/ws?agent_token=ag_…,之后 hub 通过这条 连接下发任务、接入件把事件推回来。两种子形态的差别只在接入件住在哪:

  • embedded:接入件跑在 Agent 进程里(nanobot 渠道、dsh 插件)。推荐形态,没有第二个进程要管。
  • connector:接入件是旁边一个进程(或同机另一个容器),用仓库里的单文件 SDK 起。 Agent 改不动、或宿主语言没有好用的插件机制时用。

hub 侧两者都走 connector 驱动(driver_for() 按 connection_mode 选驱动,所以外拨 Agent 的 driver 字段只说明"它本来是什么框架",派活实际走 socket)。

2.2 直连(direct)

hub 主动拨 base_url,用 auth 里的凭证(这一类不在「接入」向导里,只能手工登记)。存在性判定顺序是 外拨 socket 在线 > 心跳新鲜度 > 主动探测(probe),控制台显示"判定来源"同此。

2.3 怎么选

它是无头 CLI(codex / claude / WorkBuddy…)吗?
└─ 是 → 桥接(connector):在它所在机器上跑 deploy/cli-bridge/bridge.py,不用改它一行代码
能改 Agent 代码或配置吗?
├─ 能 → 它是 nanobot / dsh 吗?
│      ├─ 是 → embedded(用现成接入件,照第 6 节抄配置)
│      └─ 否 → 自己写接入件(6.7 / 6.8),仍然 embedded 或 connector
└─ 不能 → 它自己有可被访问的 HTTP/WS 服务吗?
       ├─ 有 → direct(hub 侧登记 base_url + auth)
       └─ 没有 → 贴一份单文件 SDK 起一个桥接进程(6.7)

3. 身份与凭证

3.1 一条路:建档 → 签发 → 填凭证

agenthub agent add --name alpha --driver nanobot --connection embedded --show-token
agenthub agent rotate alpha            # 轮换(旧凭证默认立即失效)

控制台「接入」页点「签发凭证」就是下面这两个调用:POST /api/v1/agents(body 带 "issue_credential": true,明文在这一次响应里回来)与 POST /api/v1/agents/{ref}/credentials (轮换,可带 grace_seconds 开滚动升级的双活窗口)。另一处等价入口:Agents 列表 → 该行「编辑」→ 凭证卡片「签发/轮换」。

Agent 侧要抄的只有 server + 这一把凭证。agentId 可以填(有些接入件想在 hello 之前 就先知道自己是哪一行),但它只是提示:权威身份始终由 hub 从凭证反查,并在 hub.hello 里给出。

3.2 凭证什么时候被校验

没有独立的「注册」或「验证」接口,也不需要:

时机 调用 结果
接入件启动时先探一次 POST /api/v1/gateway/heartbeat(Bearer ag_…) 200 = 凭证有效,去拨 WS;401/403 = 日志里直接说去哪把新的
建立控制通道 WS /gateway/ws?agent_token=ag_… 凭证不对 4401 关闭;对了就标 online 并回 hub.hello(带 agent_id)
之后每次心跳 agent.heartbeat 帧或 HTTP 心跳 顺带刷新自省字段(model / capabilities / active_tasks)

验证 = 控制台上看到它 online。控制台「接入」页第 ② 步那张卡片读的就是 GET /api/v1/agents/{ref}/presence,它和 Agents 页同源,不会出现"这边绿那边灰"。

3.3 签发、轮换与可见性

  • 明文(ag_…)只在签发/轮换响应里出现一次;库里只存 sha256 哈希 + token_preview (形如 ag_qEv…W2Kd)。控制台任何位置都不回显明文。
  • Agent 列表/详情里的 credential 形状:{ "installed": true, "preview": "ag_…" }。
  • 轮换默认让旧凭证立即失效;grace_seconds > 0 开一个双活窗口(新进程先起来、旧进程 还没走时用),到点自动作废。
  • 换 hub = 换凭证:新 hub 上是新档案、新凭证,没有跨 hub 通用的身份。

3.4 同名语义(单实例)

  • name 是 hub 上的唯一键,也是运维唯一需要记的标识;agent_id 由 hub 生成、跨重启稳定。
  • 建档时同名 → 409:先想清楚是复用那一行(直接拿它的凭证)还是换名字。不静默认领, 也不接管 —— 「谁把谁的档案覆盖了」这类事故全部来自那种聪明行为。
  • 拿着某把凭证连上来 = 你就是那一行(凭证即身份),所以不存在"用新 token 顶掉别人的身份"。
  • 不支持同名多实例:滚动升级先下线旧实例,或给新实例换 name。

3.5 无状态身份的四条硬性要求

接入件不在磁盘保存任何身份(没有 statePath / --state-file / 身份 json)。凭证只来自配置, 运行时只放内存。因此四条硬性要求,所有接入件都必须满足:

  • R1 网络不可达 ≠ 凭证失效:只有 401/403/409 才允许丢弃 token; 连接失败、超时、5xx 必须退避重试。
  • R2 启动阶段的探活必须进重试循环:hub 没起来不能把接入件打死,hub 恢复后自动上线。
  • R3 凭证只进内存:不落盘、不进日志。
  • R4 配置里的凭证是权威:配置里的 agent_token 优先于任何缓存/遗留文件。

历史遗留身份文件(~/.nanobot/agenthub-state.json、~/.agenthub/agent-<name>.json、 --state-file 指向的文件)只读兜底一次:读到就用它上线(升级期内不让人掉线),同时打印 可粘贴进配置的片段提示迁移,之后不再写入。配置里已经写了凭证时完全不读它 —— 老文件里 上一世的 agent_id 拼到新凭证上会 401(真机撞过)。

3.6 安全边界

  • agent_token 按密钥对待:配置文件权限 0600;容器里走 env / secret,不进镜像层、不进日志。
  • 一把凭证 = 一台 Agent:它能领这台 Agent 的活、上报它的状态;读不了别的 Agent, 也碰不到控制台面。
  • 泄漏处置:agenthub agent rotate <name>(或控制台轮换)。旧凭证立刻失效,接入件会在日志里 说清去哪把新的,不需要重启 hub。
  • 控制台 API Key(ah_…,管控制台与管理 API)与 Agent 凭证(ag_…,只管这一台 Agent)是两套 边界;填错位置会被明确拒绝,不会静默按另一套解释。

4. 字段规范

4.1 统一字段表

规范名(JSON 用 snake_case;dsh 插件 config 用 camelCase,语义一一对应;nanobot 两种都读):

概念 规范名 环境变量 必需 说明
服务端地址 server AGENTHUB_SERVER 是(外拨) 含协议与端口,如 http://127.0.0.1:8100
运行凭证 agent_token AGENTHUB_AGENT_TOKEN 是(外拨) ag_…,控制台「接入」页签发;明文可反复回看(GET /agents/{ref}/credentials,认证走的仍是哈希)
Hub 上的名字 name AGENTHUB_NAME 是 唯一键;同名 = 同一个 Agent
Agent 身份 agent_id AGENTHUB_AGENT_ID 否 agt_…;hub 从凭证反查,hello 里回给你
显示名 display_name AGENTHUB_DISPLAY_NAME 否 缺省 = name
描述 description AGENTHUB_DESCRIPTION 否 控制台展示
图标 emoji — 否 控制台展示,各家有默认值
连接模式 connection_mode — 否 接入件自己定:nanobot embedded、dsh embedded、SDK 默认 embedded
部署形态 deployment_kind AGENTHUB_DEPLOYMENT_KIND 否 local / docker / cloud
部署引用 deployment_ref AGENTHUB_DEPLOYMENT_REF 否 容器名 / 主机名 / 云实例
标签 labels AGENTHUB_LABELS(k=v,k=v,nanobot) 否
并发上限 max_concurrency — 否 nanobot 键名 maxConcurrency,缺省 2
协议版本 protocol_version — 自动 当前 1
接入件版本 connector_version — 自动 排障用

桥接进程 bridge.py 没有配置文件,同名概念走命令行参数(env 是另一套名字,别混): --hub(AGENTHUB_URL)、--token(AGENTHUB_TOKEN)、--name(AGENTHUB_AGENT)、 --cli、--workdir、--mode。

4.2 兼容读(一个版本窗口)

旧名 新名 处理
hubUrl / hub_url / AGENTHUB_HUB_URL server / AGENTHUB_SERVER 兼容读
AGENTHUB_AGENT_NAME AGENTHUB_NAME 兼容读
statePath / --state-file — 只读兜底一次,不再写入(3.5)
config 里的 enrollment / hubId / takeOver — 不再读,读到就在日志里说一声让你删掉这行

线上协议字段不改名:配置键改了名也不需要两端同时动。

4.3 不该出现在接入配置里的字段

字段 为什么 放哪
model 渠道里那份只是注册时的自报副本,会跟真正跑的模型漂移 Agent 自己的模型配置;hub 只显示心跳里自省上报的值
role 它是 hub 的协作概念(团队角色 / playbook 选人) hub 侧登记那一行(建档时或之后改)
statePath / 身份文件 身份即配置(3.5 R3) 删除

行为开关不属于注册规范,各接入件自己留着:allowFrom、streaming、sendProgress、 sendToolHints、cwd、timeoutS。


5. 协议契约(Gateway)

5.1 Frame 格式

所有面共用一个小信封:

{
  "v": 1,
  "id": "frm_…",                          // 帧 id;应答把它填进 reply_to
  "ts": 1790000000.0,
  "type": "req|res|event|err",
  "kind": "task.run",                     // 处理器 switch 用这个
  "topic": "agent.<id>.task.<id>.event",  // 总线路由用这个(支持 *.> 通配)
  "actor": "hub|agent|<name>",
  "payload": { },
  "reply_to": "frm_…",                    // 可选
  "agent_id": "agt_…",                    // 可选
  "task_id": "tsk_…",                     // 可选
  "run_id": "run_…",                      // 可选
  "seq": 42                               // 可选,总线序号(重连补发用)
}

5.2 上行(Agent → hub)

动作 端点 / kind 说明
心跳 POST /api/v1/gateway/heartbeat(Bearer ag_…) {status, active_tasks, health, capabilities, connector_version}
注销 POST /api/v1/gateway/deregister(Bearer ag_…) 置 offline 并断开控制通道
连控制通道 WS /api/v1/gateway/ws?agent_token=ag_… 连上后 hub 先发 hub.hello
上线问好 agent.hello 可带 capabilities(会写入);client_version → connector_version
在线心跳 agent.heartbeat 与 HTTP 心跳同义,省一次请求
任务事件 agent.event(带 task_id) payload.type ∈ status/delta/reasoning/tool/log/completed/failed/cancelled
应答 type: "res" + reply_to 对 task.run / task.cancel / agent.ping / agent.describe / agent.command 的应答
下线 agent.deregister 主动断开并置 offline

连上控制通道后 hub 先发的 hub.hello(Agent 由此知道自己是哪一行):

{
  "agent_id": "agt_…", "agent_name": "alpha",
  "hub_url": "http://127.0.0.1:8100",
  "ws_url": "ws://127.0.0.1:8100/api/v1/gateway/ws",
  "heartbeat_interval_s": 15, "protocol_version": 1,
  "frame_kinds": ["task.run", "task.cancel", "agent.ping", "agent.describe", "agent.command"]
}

Agent 侧不上报注册字段:name / driver / connection_mode / deployment_* 都在 hub 建档时 就定好了(改这些用控制台/API 改那一行)。心跳里能带的是自省:

{ "status": "online", "active_tasks": 1, "connector_version": "0.1.0",
  "health": { "host": "mb-jiliu" },
  "capabilities": { "streaming": true, "runtime": "nanobot", "model": "qwen3.6-plus" } }

role 归 hub、model 只来自这里的自省 —— 两处都不接受配置副本。

role 与 model 不接受出现在注册请求里(role 归 hub、model 归自省)。

5.3 下行(hub → Agent)

kind payload 应答
task.run {task_id, prompt, session_key, invocation_id, timeout_s, context, provider, provider_config} res.payload.{text, usage};过程中用 agent.event 流式上报
task.cancel {invocation_id} res(收到即算成功)
agent.ping {} res.payload.{rtt_ms, …}
agent.describe {} res.payload:能力/模型/工具等自省信息
agent.command {command, args?} res.payload(接入件自定义解释)

agent.event 的 payload 示例:

{"type": "delta",     "text": "正在回答…"}
{"type": "reasoning", "text": "先看约束…"}
{"type": "tool",      "name": "read_file", "input": {"path": "README.md"}}
{"type": "status",    "message": "thinking"}
{"type": "completed", "text": "最终答案", "usage": {"input_tokens": 120}}
{"type": "failed",    "error": "provider 401"}

5.4 控制台面(了解用)

  • WS /api/v1/stream?api_key=ah_…&topics=…&since=<seq>:控制台订阅全部事件;since 用于重连补发 (先订阅再取快照,不重不漏);{"action":"ping"} → pong。
  • GET /api/v1/gateway/status:在线通道、pending 请求、接入件版本。
  • GET /api/v1/gateway/frames?limit=&kind=&agent_id=:环形缓冲里的最近帧(审计/排障)。

5.5 鉴权

面 凭证 传递方式
控制台 REST ah_…(安装级 API Key) X-API-Key: 或 Authorization: Bearer
控制台 WS ah_… ?api_key=
Agent REST(心跳/注销) ag_… X-Agent-Token: 或 Authorization: Bearer
Agent WS ag_… ?agent_token=(浏览器塞不了 header,所以走 query)
协作接口(blackboard/messages) run grant(HMAC,绑定 run_id + agent_id) Authorization: Bearer

5.6 心跳、重连与存在性

  • 心跳间隔 heartbeat_interval_s(默认 15s),超时 heartbeat_timeout_s(默认 45s)。
  • 判定顺序:外拨 socket 在线 > 心跳新鲜度 > 主动探测。
  • 控制通道断开 → hub 立刻把该 Agent 标 offline(connector_socket_closed),接入件按 R1/R2 退避重连。

6. 各类型接入规范

6.1 nanobot(内嵌渠道 embedded)

接入件:deploy/nanobot-gateway/channel/agenthub/(随 nanobot 装)。配置写在 ~/.nanobot/config.json 的 channels.agenthub:

{
  "agents": { "defaults": { "provider": "dashscope", "model": "qwen3.6-plus" } }, // 模型归这里
  "channels": {
    "agenthub": {
      "enabled": true,
      "server": "http://127.0.0.1:8100",
      "name": "alpha",
      "display_name": "阿尔法",
      "agent_token": "ag_…",       // 只有这一格是凭证:控制台「接入」页签发
      "allowFrom": ["agenthub"],
      "maxConcurrency": 2,
      "streaming": true,
      "sendProgress": true,
      "sendToolHints": true
    }
  }
}
  • 环境变量:AGENTHUB_SERVER / AGENTHUB_NAME / AGENTHUB_DISPLAY_NAME / AGENTHUB_DESCRIPTION / AGENTHUB_AGENT_TOKEN / AGENTHUB_AGENT_ID / AGENTHUB_DEPLOYMENT_KIND / AGENTHUB_DEPLOYMENT_REF / AGENTHUB_LABELS(k=v,k=v)。凭证类以环境变量优先 (compose 注入的 token 要能盖住 config.json 里的陈旧副本),其余以配置文件为准。
  • 自省上报:{streaming, model, runtime: "nanobot"},model 读 nanobot 自己的模型配置。
  • 不写身份文件;旧的 ~/.nanobot/agenthub-state.json 只读兜底一次(3.5)。

6.2 nanobot_ws(直连 nanobot 网关自带的 WS 渠道)

driver: "nanobot_ws" + connection_mode: "direct":hub 说 nanobot 网关自带 WebSocket 渠道的协议 (ready → message{chat_id,content} → delta / reasoning_delta / tool_hint / stream_end / turn_end),hub 的 session_key 映射成稳定的 nanobot chat_id。好处是同一个网关既能被官方 WebUI 用,也能被 hub 派活。

agenthub agent add --name desk --driver nanobot_ws --connection direct --base-url ws://127.0.0.1:8788

6.3 DeepSeek Harness(dsh 插件 embedded)

接入件:plugins/dsh-agenthub/。配置写在 profile 的 cordis.patch.yml:

- insert:
    - id: dsh-agenthub
      name: '@nex/dsh-agenthub'
      config:
        server: http://127.0.0.1:8100
        name: dsh-web
        displayName: DeepSeek Harness
        agentToken: ag_…          # 只有这一格是凭证:控制台「接入」页签发
        deploymentKind: local
        # 行为开关(可选):cwd / timeoutS / maxConcurrency / autoConnect
  • camelCase 键:server / name / displayName / agentToken / agentId(可选)/ deploymentKind / deploymentRef / emoji / cwd / timeoutS / maxConcurrency; env 是同一批概念(AGENTHUB_SERVER / AGENTHUB_NAME / AGENTHUB_AGENT_TOKEN / …)。
  • 老配置里若还写着 enrollment / hubId / takeOver,插件日志会明确报一行让你删掉, 不会默默忽略。
  • 也可以在 dsh 的「设置 → AgentHub」面板填「地址 + 这台 Agent 的凭证」点上线。面板只把 地址和名字落到 ~/.dsh/agenthub.json(不含凭证,那把始终只在内存),「下线」只是断开连接。 插件 config 里写了凭证时 config 赢:那个文件不分 profile,别让上一次连别的 hub 留下的 地址把刚签发的凭证送去敲上一家的门。
  • 装插件与 profile 的完整步骤见 plugins/dsh-agenthub/README.md(有两个真机坑:模板必须是 web,patch 文件末尾那行占位 [] 必须先删)。
  • 热重载只保留一份网关实例;模型来自 harness 的默认模型设置并在心跳里自省上报。

6.4 OpenClaw(direct,实验)

OpenClaw 的 gateway 是 WebSocket 帧 RPC(connect.challenge → connect → req/res + event)。 hub 作为客户端拨它,Agent 侧没有 AgentHub 配置:

登记字段 值
driver openclaw
connection_mode direct
base_url ws://…(或放在 config.ws_url)
auth {"token": "…"}:OpenClaw 自己的网关令牌,不是 ag_…

可在 Agent config 里覆盖 method_send / method_abort / session_key / protocol,换网关版本 不用改 hub 代码。该驱动标记 experimental(上游只发 CLI 二进制,测试用脚本化 peer 锁协议)。

6.5 openai_compatible(direct)

任何暴露 OpenAI 风格 HTTP 接口(/v1/models、/v1/chat/completions)的服务:

agenthub agent add --name local-llm --driver openai_compatible --connection direct \
  --base-url http://127.0.0.1:8000
# auth 用控制台/API 填 {"token": "sk-…"}(该服务自己的鉴权,不是 AgentHub 的)

6.6 mock(联调)

driver: "mock":不连任何外部服务,用 config.delay_s 模拟耗时,用来验证"派活 → 事件流 → 完成"的链路。不要用在生产。

6.7 自研接入件 / 单文件 SDK(外拨)

仓库里有一份只用标准库 + websockets 的参考客户端: deploy/nanobot-gateway/channel/agenthub/agenthub_client.py。贴十几行起一个进程,就是一个 connector 形态的接入件:

from agenthub_client import GatewayClient, GatewayConfig

config = GatewayConfig(
    hub_url="http://127.0.0.1:8100",
    name="my-agent",
    agent_token="ag_…",              # 只有这一格:控制台「接入」页签发的凭证
    driver="my-framework",
    connection_mode="connector",
)

async def my_runner(payload, emit) -> str:      # payload["prompt"] → 最终文本
    await emit("status", message="running")
    return await my_framework.run(payload["prompt"])

async def my_capabilities() -> dict:            # 自省:实际模型、runtime、是否流式
    return {"model": "…", "runtime": "my-framework", "streaming": True}

client = GatewayClient(config, my_runner, describe=my_capabilities)
await client.run()           # 内部处理重连、心跳、task.run / task.cancel

要接 agent.command 就再给 command=:async def command(name, args) -> dict。 流式在 runner 里 await emit("delta", text=…) / emit("tool", name=…, input=…), 返回值就是最终文本。

6.8 新类型接入 checklist

  1. 选形态(2.3)——凭证没有第二条路可挑(0.2)。
  2. 照 4.1 的字段表写配置,不要新增字段名变体;model / role 不进接入配置。
  3. 实现帧:上行 agent.hello / agent.heartbeat / agent.event / agent.deregister; 下行 task.run / task.cancel / agent.ping / agent.describe。
  4. 满足 3.5 的 R1–R4(无状态身份、拒绝与不可达分离、启动重试、内存凭证)。
  5. 自省上报 capabilities(实际模型、runtime、是否支持流式)。
  6. 跑离线自检 → 跑真机验收(第 9 节)。

7. 接入片段(snippets)与接入向导

hub 不部署任何 Agent,只给"粘到哪一行 / 跑哪条命令"的片段。四种片段 (GET /api/v1/deploy/templates):

kind 落到哪 内容
bridge 不落盘:在 Agent 那台机器上执行 deploy/cli-bridge/bridge.py 的启动命令(hub 地址 + 凭证 + --cli/--workdir/--mode)
nanobot ~/.nanobot/config.json 的 channels.agenthub server + name + agent_token
dsh profile 的 cordis.patch.yml 插件 config 同上(camelCase)
direct 不落盘:打印登记命令 POST /agents 的 curl(base_url + auth)

生成方式:

agenthub config --name alpha --kind bridge       # 或 nanobot / dsh / claw

连入只有两类,向导也就三步:选类型 → 选 Agent → 生成凭证。

步 做什么
① 选类型 只有两类:插件 / 渠道(Agent 那边有地方贴一段配置 —— DeepSeek Harness 插件、nanobot 内置渠道、OpenClaw 渠道)和桥接(Agent 只有一套 CLI —— codex / claude / WorkBuddy,在它所在机器上跑一个桥接进程)。这一步只决定第 ② 步列出哪几套 Agent、片段贴进哪一格
② 选是哪套 Agent 填名字(=这台 Agent 在 hub 上的唯一身份)和落点参数(桥接:工作目录 + 权限;DSH:profile)。这一步决定片段长什么样、凭证贴进哪一格,不决定凭证本身
③ 生成凭证 点「生成凭证」= hub 建档 + 当场签发这台 Agent 的 ag_…;把「hub 地址 + 凭证」贴到 Agent 那边;下面那行状态读 GET /agents/{ref}/presence,它变绿就是注册验证通过。名字已存在时按钮是「重新签发」(旧的立即失效)——那通常就是同一台 Agent 重新接一次

两类要填的东西一字不差:server(hub 的 IP+端口)+ agent_token(这把 ag_…)。 签过的凭证随时能查回来:第 ③ 步的「查看凭证」走 GET /agents/{ref}/credentials(管理员 key), 不必为了再看一眼明文而轮换一次。

OpenClaw 走的是 claw 渠道片段:hub 照签一把 ag_… 并渲染出 {"agenthub": {server, name, agent_token}},但 OpenClaw 侧的 agenthub 渠道实现不在本仓库, 要那侧先有对应配置才接得上。hub 里原有的 openclaw 驱动(hub 直拨它的 gateway, connection_mode: direct)没有删除,只是不再出现在向导里,登记办法见 2.2。

agenthub config 命令行没有"当场签发"这一步:已建档的 Agent 它直接印出真凭证(库里存着 一份可解开的封存副本),还没建档的才留 <agent_token> 占位。


8. 端到端时序(一条路长什么样)

控制台「接入」①②  选类型 + 选 Agent   → 只决定片段长什么样(bridge|nanobot|dsh|claw)
控制台「接入」③   点「生成凭证」      POST /api/v1/agents {issue_credential:true} → ag_…(之后 GET 同一把)
    Agent 侧      填 server + ag_…    照抄片段,一格都不多填
    接入件        先探一次            POST /gateway/heartbeat(Bearer ag_…)→ 200 才去拨 WS
    接入件        拨控制通道          WS /gateway/ws?agent_token=ag_…
    hub           从凭证反查 → online hub.hello{agent_id, heartbeat_interval_s, frame_kinds}
    接入件        agent.hello         capabilities(自省:model / runtime / streaming)
    之后          agent.heartbeat ×N  hub 侧判定:外拨 socket 在线 > 心跳新鲜 > 主动 probe

派活时的下行与上行见 5.2 / 5.3。整条路上操作员只需要记住两件事:hub 的地址 和 那一把凭证。别的标识(agent_id)由 hub 在 hello 里给;出问题时的第一现场是接入件日志 + GET /api/v1/gateway/status,不是配置文件里抄来的某个 id。


9. 排障与验收

现象 原因 处置
401 missing agent token / WS 上来就 4401 Agent 侧那一格凭证是空的 填控制台「接入」页签的 ag_…(agent_token / agentToken / --token)
403 unknown or rotated agent token 凭证被轮换/删掉了,或粘的是别的 hub 签的那份 agenthub agent rotate <name>(或控制台轮换)后重填;换 hub 得重新建档
403 且提示"这是 hub 的 API Key" 把 ah_… 填进了 Agent 凭证那一格 换成 ag_…;ah_… 只管控制台与管理 API
日志说 enrollment / hubId 已取消 配置里还留着旧机制那两行 删掉它们,只填 agentToken
409(建档那一步) 同名那一行已经存在 用那一行现有的凭证,或换名字(3.4)
Agent 显示 offline 但进程活着 控制通道断了(NAT 超时 / 网络抖动) 接入件按 R1/R2 重连;看 GET /gateway/status
派活立刻失败 "no live connector session" 外拨 Agent 不在线 等它重连;或改用 direct
模型显示为空 Agent 没在心跳里自省上报 接入件补 capabilities.model(模型来自 Agent 自己,不是配置副本)
派活报 no API key for provider route(DSH) 接入链路已经通了,缺的是模型凭证 在这个 DSH 的 Settings → Models 存 key,或起进程前 export DEEPSEEK_API_KEY
控制台一片 TypeError: Failed to fetch CSP 没放行 hub origin 见 README「常见坑」:重设 NEXT_PUBLIC_HUB_URL 后重新构建

9.2 验收清单

离线(不依赖真 hub):

  1. 建档带 issue_credential → 拿到明文 ag_… → 用它拨 WS 上线;没有凭证或凭证不对被明确拒。
  2. 轮换 → 旧凭证立刻失效;带 grace_seconds 时双活到点才失效。
  3. 任何读接口都不回显明文(只有 credential.preview)。
  4. 旧路由 /gateway/register、/gateway/join、/enrollment、/meta/hub-id 全是 404 —— 它们是被删掉的第二、第三条路,别再往回加。
  5. 旧字段名(hubUrl / AGENTHUB_AGENT_NAME)仍可读;旧凭证字段(enrollment / hubId)不再被读。
  6. 缺 server 时接入件明确拒绝启动,而不是默默连 127.0.0.1。

真机:

  1. agenthub agent add --show-token → 把 agent_token 写进 nanobot / dsh 配置 → 控制台 online; 删掉任何身份文件后重启 → 仍然 online。
  2. 控制台轮换凭证 → 接入件日志里说清去哪把新的;重填新凭证后恢复在线(不用重启 hub)。
  3. 桥接(codex / claude / WorkBuddy):控制台派活 → 事件流完整 status → delta/reasoning/tool → completed,答案文本回到任务里。
  4. DSH:照 plugins/dsh-agenthub/README.md 那四步(模板必须是 web、先删 patch 末尾的 []) → 日志出现 dialing → 控制台 online。

9.3 对应测试

测试 覆盖
tests/test_api_agents.py 建档 / 凭证签发与轮换(含宽限窗口)/ 心跳自省 / 探活 / describe / /meta 枚举;旧自注册与加入路由必须 404
tests/test_gateway_ws.py 真实 WS 帧:凭证鉴权、派活、探活、取消只发一条、控制台 ?since= 补发
tests/test_channel_config.py nanobot 渠道配置读取:config 为准、凭证 env 优先、旧字段名兼容读、缺 server 直接拒
tests/test_client_lifecycle_api.py 单文件 SDK 的生命周期:方法不被实例属性遮蔽、request_stop() 可 await
tests/test_cli.py init / doctor / status / agent add / agent rotate / config 脱机可跑;片段里不出现旧凭证字样
tests/test_snippets.py 四种接入片段的内容与占位符;Agent 侧文案不许指向步骤号
tests/test_driver_nanobot_ws.py nanobot WS 渠道协议(ready / message / delta / … / turn_end、session_key→chat_id)
tests/test_driver_openclaw.py OpenClaw 帧协议(challenge / connect / req-res / stream / abort)
tests/test_driver_plugins.py 第三方驱动 entry-point 注册;坏插件不拖垮内置驱动
tests/test_interop_nanobot.py 真 nanobot 互操作(health / models / 派活 / 它自己的 api key)
plugins/dsh-agenthub/selfcheck.mjs 插件接线与 Gateway 帧协议离线自检

10. 附录

10.1 术语

词 含义
hub 本仓库的控制平面(REST + WS);DB 是唯一权威
driver hub 侧的通信实现;connector 服务于所有外拨接入件
接入件 跑在 Agent 侧、说 Gateway 协议的那段代码(nanobot 渠道 / dsh 插件 / 自研 SDK 进程)
agent_token ag_…,一台 Agent 的唯一凭证(=身份);明文可随时查回(第 7 节)
run grant 协作接口用的短期 HMAC 凭证,绑定 run_id + agent_id

10.2 变更记录

时间 变更
2026-09-25 身份即配置:取消 Agent 侧身份文件(旧文件只读兜底一个版本);手工登记可签发 agent_id+agent_token;role/model 从注册字段里删除(role 归 hub,model 靠心跳自省);connector 产品面(CLI / Dockerfile / 演示栈 / 部署产物生成器)删除,只保留驱动与单文件 SDK;agenthub deploy → agenthub config(接入片段);新增 Hub ID 加入路径。
2026-09-26 设置项与枚举去重:删除幽灵设置「本机部署」与重复的 /meta.driver_names、GET /agents/drivers;drivers / agent_types / connection_modes / deployment_kinds 统一由 GET /api/v1/meta 下发,控制台不再各自硬编码(编辑弹窗的驱动 / 类型 / 接入方式 / 部署形态下拉改由 meta 驱动);本规范重写为 v2 —— 去掉提案与落地记录,只留当前行为。
2026-10-14 接入向导收成三步:第 ① 步只剩「Agent 主动外拨 / hub 直连过去」两种模式,第 ② 步才选是哪套 Agent,第 ③ 步建档并签发(直连那一类给登记命令,不签凭证)。Agent 侧的配置面仍然是 hub 地址 + 一把 ag_ 凭证,一格都没多。
2026-10-14 接入只剩一条路:删掉 enrollment 入场令牌与 Hub ID 加入两条备用路径(POST /gateway/register、/gateway/join、/enrollment、/meta/hub-id 一并删除),统一成「hub 签发一把 ag_ 凭证 → Agent 填 hub 地址 + 这把凭证 → 连上即注册验证」;控制台「接入」页收成一条路(选是哪套 Agent → 签发凭证并验证),不再区分预注册/自注册;dsh 插件与 nanobot 渠道同步取消 enrollment / hubId 配置键(读到就报一行让你删);grace_seconds 轮换窗口实装。
2026-10-15 连入只有两类:向导第 ① 步改成「插件 / 渠道」与「桥接」,第 ③ 步改名「生成凭证」;「hub 直连过去」这一类从向导里删除(direct 片段 kind 一并删除,OpenClaw 改出 claw 渠道片段,connection_mode: direct 作为驱动能力保留)。新增 GET /agents/{ref}/credentials:已签发的凭证可反复查回,库里为此另存一份 seal 过的副本(密钥 = secret_key),认证仍只读哈希;agenthub config 对已建档的 Agent 直接印真凭证。措辞上「边车」统一改叫「桥接」。