使用手册 · 系统

连接器

将 ClawButler 连接到 OpenClaw gateway 与 Runtime Hosts。OpenClaw 仍是当前唯一完整支持的 connector 路径；Hermes / Claude Code / Codex 目前通过 Runtime Host 发现与 attach-mode sync 接入。

/connectors

概述#

Connectors 页面现在覆盖三条路径：Cloud 优先配对 Runtime Host 做本地 runtime 发现；自托管或高级环境可手动添加 OpenClaw connector；本地 `scan-local` 则继续作为旧 OpenClaw 场景的便捷补充。

Runtime Host 可以在已配对机器上发现 Hermes、Claude Code、Codex 与 OpenClaw 实例。发现后，你可以选择哪些实例变成 connector，并在支持时把 attach-mode 会话同步到 ClawButler。OpenClaw 仍是当前唯一完整的 provider-native connector 路径。

前置条件#

前置条件
  • 一个 ClawButler 账号，以及对目标机器或 gateway 的访问权
  • 如果走 Runtime Host 配对：ClawButler 展示的 `/pair?kind=runtime-host&code=...` 链接或配对码
  • 如果走手动 OpenClaw connector：gateway URL 与 operator token

接入方式与支持边界#

对 Cloud 用户，推荐路径是 Runtime Host 配对。先在配对页批准目标机器，然后回到 Connectors 对这台主机执行 Discover。

对自托管或高级环境，手动 OpenClaw connector 仍然受支持。本地 `scan-local` 依然适合旧的或附近的 OpenClaw 场景，但它不再是主 onboarding 路径。

当前支持边界
OpenClaw 仍然是当前唯一完整支持的 connector 路径。Hermes / Claude Code / Codex 目前仅支持 discovery、connector 创建和 attach-mode session sync，尚未提供 provider-native 审批、成本归因、时间线和托管控制。

在 ClawButler 中的配置流程#

根据环境选择路径：Cloud 优先 Runtime Host 配对；附近旧 OpenClaw 场景可用本地 `scan-local`；自托管与高级场景则使用手动 connector 录入。

路径 A：配对 Runtime Host（Cloud 推荐）

在目标机器上打开配对流程（`/pair?kind=runtime-host&code=...`），批准 Runtime Host 后回到 Connectors，执行 Discover。

路径 B：用于旧 OpenClaw 场景的本地 `scan-local`

当你已经在同一台机器或局域网运行 OpenClaw，并希望快速导入时，可以使用本地扫描。这条路径对旧本地场景仍然有用，但不再是 Cloud 主推荐流程。

路径 C：自托管 / 高级环境的手动 connector

1
点击 `Add Connector`
当你已经知道 gateway URL 和 operator token，或 `scan-local` 无法触达目标 OpenClaw 部署时，使用这条路径。
2
填写 gateway 信息
输入易识别的名称、WebSocket URL 和 operator token。
3
先测试，再诊断
先执行 Test；如果有需要，再继续跑 Diagnosis / Security Check，再把 connector 投入正常使用。
4
同步并确认结果
执行 Sync 发现 Agent，然后确认 connector 卡片、Agent 数量以及任何会话投影是否已就绪。

使用反馈#

完成配对或添加 connector 后，你应该看到：

  • Runtime Host 卡片或 connector 卡片，展示状态、last seen / last sync 与支持的 provider
  • 在 batch-add 前看到发现到的 Hermes / Claude Code / Codex / OpenClaw 实例，或对手动 OpenClaw connector 看到同步后的 Agent 数量
  • 被选中的 runtime 实例进入主 connector 列表，成为正式 connector
  • 在 provider 支持投影时，可供同步的 attach-mode 会话

Web 端操作#

从 System 分区进入 `Connectors`。这个页面现在同时承载 connector 管理和 Runtime Host 操作。

这个页面上的常见操作：

  • Pair / Approve — 把一台机器授权为 Runtime Host
  • Discover — 对已配对主机扫描 Hermes / Claude Code / Codex / OpenClaw 实例
  • Add Selected — 只为选中的发现结果创建 connector
  • Sync Sessions — 把 attach-mode runtime 会话投影进 ClawButler
  • Test / Diagnose — 验证 connector 健康并调查问题
  • Edit / Delete — 更新已保存的 connector 信息，或删除不再使用的记录

Runtime Host 工作流

典型的 Web 流程是 Pair Runtime Host → Discover → Add Selected → Sync Sessions。OpenClaw connector 如果配置了 IM 渠道，相关 IM 操作仍然保留在 connector 卡片上。

CLI 端操作#

CLI 同时覆盖 Runtime Host 接入闭环和传统 connector 运维。

Terminal
$ ap runtime-host list
列出已配对 Runtime Host，并查看每台主机支持发现哪些 provider
Terminal
$ ap runtime-host discover <runtime-host-id>
对指定主机执行发现，检查 Hermes / Claude Code / Codex / OpenClaw 实例
Terminal
$ ap runtime-host batch-add <runtime-host-id> --instance-key <instance-key>
只为选中的发现结果创建 connector
Terminal
$ ap runtime-host sync-sessions <runtime-host-id> --instance-key <instance-key>
把选定 runtime 实例的 attach-mode 会话投影进 ClawButler
Terminal
$ ap connector discovery scan-local
为旧 `scan-local` 路径发现本地或附近的 OpenClaw 候选项
Terminal
$ ap connector discovery import-local --candidate-url http://127.0.0.1:8080 --name local-dev
把某个发现到的 OpenClaw 候选导入成 connector
Terminal
$ ap connector list
列出所有通过手动录入、discovery import 或 Runtime Host batch-add 创建的 connector
Terminal
$ ap connector test <id>
测试指定 connector 的连通性
Terminal
$ ap connector sync <id>
从 OpenClaw connector 重新同步 Agent 或 connector 状态
Terminal
$ ap connector security-check <id>
对 connector 执行安全检查
Terminal
$ ap connector diagnosis <id>
对 connector 执行诊断

移动端操作#

移动端可以查看 connector 健康与同步状态，但当前没有对外提供 Runtime Host 配对入口。

Runtime Host 的配对、发现、batch-add 和 session sync 仍需使用 Web 或 CLI；移动端目前以 connector 状态查看为主。

常见问题#

问：Runtime Host 和 connector 有什么区别？
答：Runtime Host 是已配对、可以执行发现的那台机器；connector 是你从发现结果里选中后创建出来的受治理记录，或者是手动添加的 OpenClaw gateway 记录。
问：Hermes / Claude Code / Codex 现在具体支持哪些能力？
答：当前支持 discovery、connector 创建和 attach-mode session sync；还不支持完整的 OpenClaw-native 审批、成本、时间线和托管控制能力。
问：什么时候应该用 scan-local 或手动 connector，而不是 Runtime Host 配对？
答：Cloud 和现代本地 runtime 发现优先使用 Runtime Host 配对；旧的附近 OpenClaw 场景可用 `scan-local`；当你已经知道远程 gateway URL/token，或需要高级自托管控制时，使用手动 connector。
连接器 — ClawButler 用户手册