跳到主要内容

网关 CLI

网关（Gateway）是 Clawdbot 的 WebSocket 服务器（负责频道、节点、会话、钩子）。

本页面中的子命令位于 clawdbot gateway … 之下。

相关文档：

运行网关 (Run the Gateway)​

运行本地网关进程：

clawdbot gateway

前台运行别名：

clawdbot gateway run

注意事项：

  • 默认情况下，除非在 ~/.clawdbot/clawdbot.json 中设置了 gateway.mode=local，否则网关拒绝启动。对于临时/开发运行，请使用 --allow-unconfigured。
  • 禁止在没有身份验证的情况下绑定到回环地址（loopback）以外的接口（安全保护措施）。
  • 获得授权后，SIGUSR1 会触发进程内重启（启用 commands.restart 或使用网关工具/配置应用/更新）。
  • SIGINT/SIGTERM 处理程序会停止网关进程，但不会恢复任何自定义终端状态。如果您使用 TUI 或原始模式输入包装了 CLI，请在退出前恢复终端。

选项​

  • --port <port>：WebSocket 端口（默认来自配置/环境变量；通常为 18789）。
  • --bind <loopback|lan|tailnet|auto|custom>：监听器绑定模式。
  • --auth <token|password>：身份验证模式覆盖。
  • --token <token>：令牌覆盖（同时为进程设置 CLAWDBOT_GATEWAY_TOKEN）。
  • --password <password>：密码覆盖（同时为进程设置 CLAWDBOT_GATEWAY_PASSWORD）。
  • --tailscale <off|serve|funnel>：通过 Tailscale 暴露网关。
  • --tailscale-reset-on-exit：关闭时重置 Tailscale serve/funnel 配置。
  • --allow-unconfigured：允许在配置中没有 gateway.mode=local 的情况下启动网关。
  • --dev：如果缺失，则创建开发配置 + 工作区（跳过 BOOTSTRAP.md）。
  • --reset：重置开发配置 + 凭据 + 会话 + 工作区（需要 --dev）。
  • --force：启动前强制杀死选定端口上的任何现有监听器。
  • --verbose：详细日志。
  • --claude-cli-logs：仅在控制台中显示 claude-cli 日志（并启用其 stdout/stderr）。
  • --ws-log <auto|full|compact>：WebSocket 日志样式（默认 auto）。
  • --compact：--ws-log compact 的别名。
  • --raw-stream：将原始模型流事件记录到 jsonl。
  • --raw-stream-path <path>：原始流 jsonl 路径。

查询运行中的网关 (Query a running Gateway)​

所有查询命令均使用 WebSocket RPC。

输出模式：

  • 默认：人类可读（在 TTY 中着色）。
  • --json：机器可读的 JSON（无样式/加载动画）。
  • --no-color (或 NO_COLOR=1)：禁用 ANSI，同时保持人类可读的布局。

共享选项（在支持的情况下）：

  • --url <url>：网关 WebSocket URL。
  • --token <token>：网关令牌。
  • --password <password>：网关密码。
  • --timeout <ms>：超时/预算（因命令而异）。
  • --expect-final：等待“最终”响应（代理调用）。

gateway health​

clawdbot gateway health --url ws://127.0.0.1:18789

gateway status​

gateway status 显示网关服务（launchd/systemd/schtasks）以及可选的 RPC 探测。

clawdbot gateway status
clawdbot gateway status --json

选项：

  • --url <url>：覆盖探测 URL。
  • --token <token>：探测的令牌验证。
  • --password <password>：探测的密码验证。
  • --timeout <ms>：探测超时（默认 10000）。
  • --no-probe：跳过 RPC 探测（仅查看服务状态）。
  • --deep：同时扫描系统级服务。

gateway probe​

gateway probe 是“调试一切”的命令。它始终探测：

  • 您配置的远程网关（如果已设置），以及
  • 本地主机（回环地址），即使配置了远程网关。

如果多个网关可达，它会打印所有网关。当您使用隔离的配置文件/端口（例如救援机器人）时支持多个网关，但大多数安装仍然运行单个网关。

clawdbot gateway probe
clawdbot gateway probe --json

通过 SSH 远程连接（与 Mac 应用一致）​

macOS 应用的“通过 SSH 远程连接”模式使用本地端口转发，因此远程网关（可能仅绑定到回环地址）可以通过 ws://127.0.0.1:<port> 访问。

CLI 等效命令：

clawdbot gateway probe --ssh user@gateway-host

选项：

  • --ssh <target>：user@host 或 user@host:port（端口默认为 22）。
  • --ssh-identity <path>：身份文件。
  • --ssh-auto：选择第一个发现的网关主机作为 SSH 目标（仅限 LAN/WAB）。

配置（可选，用作默认值）：

  • gateway.remote.sshTarget
  • gateway.remote.sshIdentity

gateway call <method>​

低级 RPC 助手。

clawdbot gateway call status
clawdbot gateway call logs.tail --params '{"sinceMs": 60000}'

管理网关服务 (Manage the Gateway service)​

clawdbot gateway install
clawdbot gateway start
clawdbot gateway stop
clawdbot gateway restart
clawdbot gateway uninstall

注意事项：

  • gateway install 支持 --port、--runtime、--token、--force、--json。
  • 生命周期命令接受 --json 以用于脚本编写。

发现网关 (Bonjour)​

gateway discover 扫描网关信标 (_clawdbot-gw._tcp)。

  • 多播 DNS-SD：local.
  • 单播 DNS-SD (Wide-Area Bonjour)：clawdbot.internal.（需要分屏 DNS + DNS 服务器；参见 /gateway/bonjour）

只有启用了 Bonjour 发现（默认启用）的网关才会发布信标。

广域发现记录包括 (TXT)：

  • role（网关角色提示）
  • transport（传输提示，例如 gateway）
  • gatewayPort（WebSocket 端口，通常为 18789）
  • sshPort（SSH 端口；如果不存在则默认为 22）
  • tailnetDns（MagicDNS 主机名，如果可用）
  • gatewayTls / gatewayTlsSha256（启用 TLS + 证书指纹）
  • cliPath（远程安装的可选提示）

gateway discover​

clawdbot gateway discover

选项：

  • --timeout <ms>：每个命令的超时时间（浏览/解析）；默认 2000。
  • --json：机器可读的输出（同时禁用样式/加载动画）。

示例：

clawdbot gateway discover --timeout 4000
clawdbot gateway discover --json | jq '.beacons[].wsUrl'