39 KiB
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 一字不差:
- hub 签发凭证:控制台「接入」页点一下,或
agenthub agent add --show-token,拿到 属于这台 Agent 的ag_…; - Agent 侧填两样:hub 的 IP+端口(
server)+ 这个凭证,别的一律不填; - 注册验证 = 它上线: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
- 选形态(2.3)——凭证没有第二条路可挑(0.2)。
- 照 4.1 的字段表写配置,不要新增字段名变体;
model/role不进接入配置。 - 实现帧:上行
agent.hello/agent.heartbeat/agent.event/agent.deregister; 下行task.run/task.cancel/agent.ping/agent.describe。 - 满足 3.5 的 R1–R4(无状态身份、拒绝与不可达分离、启动重试、内存凭证)。
- 自省上报
capabilities(实际模型、runtime、是否支持流式)。 - 跑离线自检 → 跑真机验收(第 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):
- 建档带
issue_credential→ 拿到明文ag_…→ 用它拨 WS 上线;没有凭证或凭证不对被明确拒。 - 轮换 → 旧凭证立刻失效;带
grace_seconds时双活到点才失效。 - 任何读接口都不回显明文(只有
credential.preview)。 - 旧路由
/gateway/register、/gateway/join、/enrollment、/meta/hub-id全是 404 —— 它们是被删掉的第二、第三条路,别再往回加。 - 旧字段名(
hubUrl/AGENTHUB_AGENT_NAME)仍可读;旧凭证字段(enrollment/hubId)不再被读。 - 缺
server时接入件明确拒绝启动,而不是默默连127.0.0.1。
真机:
agenthub agent add --show-token→ 把agent_token写进 nanobot / dsh 配置 → 控制台 online; 删掉任何身份文件后重启 → 仍然 online。- 控制台轮换凭证 → 接入件日志里说清去哪把新的;重填新凭证后恢复在线(不用重启 hub)。
- 桥接(codex / claude / WorkBuddy):控制台派活 → 事件流完整
status → delta/reasoning/tool → completed,答案文本回到任务里。 - 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 直接印真凭证。措辞上「边车」统一改叫「桥接」。 |