文档
CLI 命令参考
网关 CLI

网关 CLI

适用范围

使用本页面当：

  • 从 CLI 运行网关（开发环境或服务器）
  • 调试网关鉴权、绑定模式和连接性
  • 通过 Bonjour 发现网关（局域网 + tailnet）

网关是 Moltbot 的 WebSocket 服务器（渠道、节点、会话、钩子）。

本页面的子命令位于 moltbot gateway … 下。

相关文档：

运行网关

运行本地网关进程：

moltbot gateway

前台别名：

moltbot gateway run

说明：

  • 默认情况下，除非在 ~/.moltbot/moltbot.json 中设置了 gateway.mode=local，否则网关拒绝启动。使用 --allow-unconfigured 进行临时/开发运行。
  • 没有鉴权的非环回绑定被阻止（安全防护）。
  • SIGUSR1 在获得授权时触发进程内重启（启用 commands.restart 或使用网关工具/config apply/update）。
  • SIGINT/SIGTERM 处理器会停止网关进程，但不会恢复任何自定义终端状态。如果使用 TUI 或原始模式输入包装 CLI，请在退出前恢复终端。

选项

  • --port <port>: WebSocket 端口（默认值来自配置/环境；通常为 18789）。
  • --bind <loopback|lan|tailnet|auto|custom>: 监听器绑定模式。
  • --auth <token|password>: 鉴权模式覆盖。
  • --token <token>: token 覆盖（同时为进程设置 MOLTBOT_GATEWAY_TOKEN）。
  • --password <password>: 密码覆盖（同时为进程设置 MOLTBOT_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 路径。

查询运行中的网关

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

输出模式：

  • 默认：人类可读（TTY 中带颜色）。
  • --json: 机器可读的 JSON（无样式/旋转器）。
  • --no-color（或 NO_COLOR=1）：禁用 ANSI，同时保持人类布局。

共享选项（在支持的地方）：

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

gateway health 

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

gateway status

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

moltbot gateway status
moltbot gateway status --json

选项：

  • --url <url>: 覆盖探测 URL。
  • --token <token>: 探测的 token 鉴权。
  • --password <password>: 探测的密码鉴权。
  • --timeout <ms>: 探测超时（默认 10000）。
  • --no-probe: 跳过 RPC 探测（仅服务视图）。
  • --deep: 同时扫描系统级服务。

gateway probe

gateway probe 是"调试所有内容"的命令。它始终探测：

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

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

moltbot gateway probe
moltbot gateway probe --json

通过 SSH 远程探测（Mac 应用对等）

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

CLI 等效命令：

moltbot 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 辅助工具。

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

管理网关服务 

moltbot gateway install
moltbot gateway start
moltbot gateway stop
moltbot gateway restart
moltbot gateway uninstall

说明：

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

发现网关（Bonjour）

gateway discover 扫描网关信标（_moltbot-gw._tcp）。

  • 多播 DNS-SD：local.
  • 单播 DNS-SD（广域 Bonjour）：moltbot.internal.（需要拆分 DNS + DNS 服务器；参见 /gateway/bonjour)

仅启用 Bonjour 发现（默认）的网关会广播信标。

广域发现记录包括（TXT）：

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

gateway discover 

moltbot gateway discover

选项：

  • --timeout <ms>: 每命令超时（浏览/解析）；默认 2000。
  • --json: 机器可读输出（也禁用样式/旋转器）。

示例：

moltbot gateway discover --timeout 4000
moltbot gateway discover --json | jq '.beacons[].wsUrl'
沙箱 CLI