@agent-hubs/runtime-client

@agent-hubs/runtime-client

Agent Hub 本机 Runtime Client，用于把本机 Codex CLI 接入共享 Gateway。

安装后会提供两个命令：

• agent-runtime：推荐正式命令
• gateway：兼容旧脚本的别名

前置要求

• Node.js >=20
• 本机已安装并登录 Codex CLI

先确认本机能执行：

codex --help

Windows：

where codex
codex --help

安装

正式安装方式：

npm install -g @agent-hubs/runtime-client

安装后验证：

agent-runtime --help

如果使用本地 tarball 调试：

npm install -g agent-hubs-runtime-client-0.1.0.tgz

启动本机 Runtime Client

Mac/Linux：

agent-runtime runtime serve --provider codex --gateway-url http://<gateway-host>:3010

Windows CMD：

agent-runtime runtime serve --provider codex --gateway-url http://<gateway-host>:3010

启动后会自动：

• 探测本机 codex 可执行文件
• 执行 codex --help 自检
• 注册到共享 Gateway
• 定时发送心跳
• 领取任务并在本机执行 Codex CLI
• 执行中每 20s 续租一次任务 lease，保持 Platform 侧任务所有权
• 执行中每 3s 查询一次任务 control-state；用户取消后会尝试终止本机 Codex/Provider 子进程
• 回传结果

任务 lease 规则：

• 每次领取获得 60s lease，本机执行期间定时续租。
• 如果 Gateway 或网络故障超过 lease 窗口，Platform liveness sweep 会将任务安全标记为失败并隔离 thread，不自动重复执行；恢复后需要从会话异常任务入口人工重放。

绑定机器人

先在平台机器人编辑页重新签发 botKey，然后在同一台 runtime 机器上执行：

交互式引导：

agent-runtime onboard

执行后会依次提示：

• 选择 Agent 类型：codex / claude_code / custom
• 输入 Gateway URL
• 输入 Platform API URL
• 输入 botKey

非交互式命令：

agent-runtime onboard \
  --provider codex \
  --gateway-url http://<gateway-host>:3010 \
  --platform-url http://<api-host>:3001/api/v1 \
  --bot-key botkey_xxx

Windows CMD 单行：

agent-runtime onboard --provider codex --gateway-url http://<gateway-host>:3010 --platform-url http://<api-host>:3001/api/v1 --bot-key botkey_xxx

发布与升级

维护者发布新版本前先升级版本号：

npm version patch --workspace @agent-hubs/runtime-client

发布到 npm registry：

npm publish --workspace @agent-hubs/runtime-client --access public --otp <6位验证码>

发布成功后验证：

npm view @agent-hubs/runtime-client version
npm install -g @agent-hubs/runtime-client
agent-runtime --help

说明：

• @agent-hubs/runtime-client 是 npm 包名。
• agent-runtime 是安装后提供的命令名。
• 如果 npm 账号开启了发布 2FA，发布时需要传 --otp。

查看状态

agent-runtime sessions --provider codex --gateway-url http://<gateway-host>:3010

解绑

agent-runtime unbind --provider codex --gateway-url http://<gateway-host>:3010 --session-id codex-session-xxx

环境变量

• AGENT_HUB_GATEWAY_URL
• AGENT_HUB_PLATFORM_URL
• GATEWAY_CODEX_TIMEOUT_MS

示例：

AGENT_HUB_GATEWAY_URL=http://127.0.0.1:3010 agent-runtime runtime serve --provider codex