古法编程

Appearance

OpenClaw Gateway 是一个常驻进程，统一处理路由、控制平面和渠道连接。本手册提供从首次启动到生产运维的完整操作步骤：5分钟内启动并通过 openclaw gateway status 验证健康、用 openclaw channels status --probe 检查渠道就绪、配置热重载（默认hybrid模式）、管理服务监督（launchd/systemd/Scheduled Task）、通过SSH隧道或Tailscale远程访问。常见故障包括端口冲突、认证失败、bind without auth 等，均附诊断命令。

OpenClaw Gateway 启动配置与故障排查指南 ​

5 分钟本地启动 ​

第一步：启动 Gateway

bash
openclaw gateway --port 18789
# 调试/追踪输出到标准输出
openclaw gateway --port 18789 --verbose
# 强制终止选定端口的监听器后启动
openclaw gateway --force

第二步：验证服务健康

bash
openclaw gateway status
openclaw status
openclaw logs --follow

健康基线：Runtime: running、Connectivity probe: ok，以及与你期望匹配的 Capability: ...。当需要只读RPC证明（不仅是可达性）时，使用 openclaw gateway status --require-rpc。

第三步：验证渠道就绪

bash
openclaw channels status --probe

Gateway 可达时执行每账号实时渠道探测和可选审计。Gateway 不可达时，CLI 降级为仅基于配置的渠道摘要输出。

Gateway 配置热重载监控当前激活的配置文件路径（从 profile/state 默认值解析，或设置了 OPENCLAW_CONFIG_PATH 时使用该值）。默认模式为 gateway.reload.mode="hybrid"。首次成功加载后，运行中的进程使用内存配置快照；成功重载原子化替换该快照。

运行时模型 ​

  • 一个常驻进程负责路由、控制平面和渠道连接。
  • 单个复用端口用于：
    • WebSocket 控制/RPC
    • HTTP API（/v1/models、/v1/embeddings、/v1/chat/completions、/v1/responses、/tools/invoke）
    • 可选的插件 HTTP 路由（如 /api/v1/admin/rpc）
    • 控制面板和 hooks
  • 默认绑定模式：loopback
  • 默认需要认证。共享密钥设置使用 gateway.auth.token / gateway.auth.password（或 OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD），非回环反向代理设置可使用 gateway.auth.mode: "trusted-proxy"

OpenAI 兼容端点 ​

OpenClaw 当前最重要的兼容接口：

  • GET /v1/models
  • GET /v1/models/{id}
  • POST /v1/embeddings
  • POST /v1/chat/completions
  • POST /v1/responses

为什么这组端点重要：

  • 大多数 Open WebUI、LobeChat、LibreChat 集成首先探测 /v1/models
  • 很多 RAG 和记忆管道期望 /v1/embeddings
  • Agent 原生客户端越来越偏好 /v1/responses

注意事项：

  • /v1/models 以 Agent 为中心：返回 openclaw、openclaw/default 和 openclaw/<agentId>
  • openclaw/default 是稳定别名，始终映射到配置的默认 Agent
  • 覆盖后端提供商/模型时在请求头中使用 x-openclaw-model；否则选中 Agent 的正常模型和嵌入设置保持控制

所有端点运行在主 Gateway 端口，使用与其他 Gateway HTTP API 相同的信任操作员认证边界。

端口和绑定优先级 ​

设置解析顺序
Gateway 端口--port → OPENCLAW_GATEWAY_PORT → gateway.port → 18789
绑定模式CLI/覆盖 → gateway.bind → loopback

在非回环绑定时，Gateway 启动会使用相同的有效端口和绑定来种子本地 Control UI 来源。例如，--bind lan --port 3000 在运行时验证前种子 http://localhost:3000 和 http://127.0.0.1:3000。任何远程浏览器来源（如 HTTPS 代理 URL）需显式添加到 gateway.controlUi.allowedOrigins。

热重载模式 ​

gateway.reload.mode行为
off不重载配置
hot仅应用热安全变更
restart需要重启时重启
hybrid（默认）安全时热应用，需要时重启

操作命令集 ​

bash
openclaw gateway status
openclaw gateway status --deep   # 添加系统级服务扫描
openclaw gateway status --json
openclaw gateway install
openclaw gateway restart
openclaw gateway stop
openclaw secrets reload
openclaw logs --follow
openclaw doctor

gateway status --deep 用于额外服务发现（LaunchDaemons/systemd系统单元/schtasks），不是更深层的 RPC 健康探测。

远程访问 ​

首选：Tailscale/VPN。
备选：SSH 隧道。

bash
ssh -N -L 18789:127.0.0.1:18789 user@host

然后客户端本地连接 ws://127.0.0.1:18789。

SSH 隧道不绕过 Gateway 认证。共享密钥认证模式下，客户端即使通过隧道也必须发送 token/password。身份承载模式同样需要满足认证路径。

详见：远程 Gateway、认证、Tailscale。

服务生命周期管理 ​

生产环境使用受监督的运行方式以获得更高可靠性。

macOS（launchd） ​

bash
openclaw gateway install
openclaw gateway status
openclaw gateway restart
openclaw gateway stop

重启时使用 openclaw gateway restart，不要链式执行 stop + start。在 macOS 上，gateway stop 默认使用 launchctl bootout —— 这会将 LaunchAgent 从当前启动会话中移除而不持久化禁用，因此 KeepAlive 自动恢复仍能在意外崩溃后工作，gateway start 能干净地重新启用。要持久阻止跨重启自动重生成，使用 --disable：openclaw gateway stop --disable。

LaunchAgent 标签为 ai.openclaw.gateway（默认）或 ai.openclaw.&lt;profile&gt;（命名 profile）。openclaw doctor 可审计并修复服务配置漂移。

Linux（systemd 用户服务） ​

bash
openclaw gateway install
systemctl --user enable --now openclaw-gateway[-<profile>].service
openclaw gateway status

注销后保持持久，启用 lingering：

bash
sudo loginctl enable-linger <user>

自定义用户单元示例：

ini
[Unit]
Description=OpenClaw Gateway
After=network-online.target
Wants=network-online.target

[Service]
ExecStart=/usr/local/bin/openclaw gateway --port 18789
Restart=always
RestartSec=5
TimeoutStopSec=30
TimeoutStartSec=30
SuccessExitStatus=0 143
KillMode=control-group

[Install]
WantedBy=default.target

Linux（系统服务） ​

用于多用户/常开主机：

bash
sudo systemctl daemon-reload
sudo systemctl enable --now openclaw-gateway[-<profile>].service

使用与用户单元相同的服务体，安装到 /etc/systemd/system/openclaw-gateway[-&lt;profile&gt;].service，并根据 openclaw 二进制位置调整 ExecStart=。

不要让 openclaw doctor --fix 再为同一 profile/port 安装一个用户级 Gateway 服务。Doctor 在发现系统级 OpenClaw Gateway 服务时会拒绝自动安装；使用 OPENCLAW_SERVICE_REPAIR_POLICY=external 让系统单元拥有生命周期。

Windows（原生） ​

powershell
openclaw gateway install
openclaw gateway status --json
openclaw gateway restart
openclaw gateway stop

原生 Windows 托管启动使用名为 OpenClaw Gateway（或带命名 profile 的 OpenClaw Gateway (&lt;profile&gt;)）的计划任务。如果计划任务创建被拒绝，OpenClaw 降级为指向 state 目录中 gateway.cmd 的每用户启动文件夹启动器。

Dev profile 快速路径 ​

bash
openclaw --dev setup
openclaw --dev gateway --allow-unconfigured
openclaw --dev status

默认包含隔离的 state/config 和基础 Gateway 端口 19001。

协议快速参考（操作员视角） ​

  • 第一帧必须是 connect
  • Gateway 返回 hello-ok 快照（包含 presence、health、stateVersion、uptimeMs、限制/策略）
  • hello-ok.features.methods / events 是保守发现的列表，不是所有可调用辅助路由的生成转储
  • 请求：req(method, params) → res(ok/payload|error)
  • 常见事件包括 connect.challenge、agent、chat、session.message、session.operation、session.tool、sessions.changed、presence、tick、health、heartbeat、配对/批准生命周期事件和 shutdown

Agent 运行分两阶段：

  1. 立即接受确认（status:"accepted"）
  2. 最终完成响应（status:"ok"|"error"），中间穿插流式 agent 事件

完整协议文档：Gateway 协议。

操作检查 ​

存活检查 ​

  • 打开 WebSocket 并发送 connect
  • 期望收到 hello-ok 响应和快照

就绪检查 ​

bash
openclaw gateway status
openclaw channels status --probe
openclaw health

间隙恢复 ​

事件不会重放。发生序列间隙时，在继续之前刷新状态（health、system-presence）。

常见故障特征 ​

特征可能原因
refusing to bind gateway ... without auth非回环绑定但没有有效的 Gateway 认证路径
another gateway instance is already listening / EADDRINUSE端口冲突
Gateway start blocked: set gateway.mode=local配置设为远程模式，或本地模式标记在损坏的配置中丢失
unauthorized during connect客户端与 Gateway 认证不匹配

完整诊断路径，使用 Gateway 故障排查。

安全保证 ​

  • Gateway 协议客户端在 Gateway 不可用时快速失败（无隐式直连渠道降级）
  • 无效/非 connect 首帧被拒绝并关闭连接
  • 优雅关闭在套接字关闭前发出 shutdown 事件

相关链接：

常见问题 ​

为什么启动 Gateway 时提示 "EADDRINUSE" 或 "another gateway instance is already listening"？ ​

端口被占用。检查是否有其他进程占用了同一端口，或之前启动的 Gateway 未正确停止。先用 openclaw gateway stop 停止现有进程，或使用 openclaw gateway --force 强制释放端口。也可以手动指定不同端口：openclaw gateway --port 18790。

配置变更后 Gateway 不生效，怎么办？ ​

默认热重载模式为 hybrid，配置变更会自动热应用（安全部分）或重启（需要重启的部分）。如果变更未生效，检查配置文件路径是否正确（OPENCLAW_CONFIG_PATH 或默认路径）。运行 openclaw gateway status 确认运行中的配置摘要。若变更涉及端口或绑定，需重新安装服务：openclaw gateway install --force。

远程访问时 SSH 隧道连接成功但认证失败？ ​

SSH 隧道不绕过 Gateway 认证。即使通过隧道，客户端仍必须提供 token 或 password（取决于 gateway.auth.token / gateway.auth.password 设置）。检查客户端认证凭据是否与 Gateway 配置一致。若使用共享密钥，在 WebSocket 连接帧中设置 token 参数。

友情链接： 能跑吗 · 打工算 · 车主算 · 开发工具 · 人工不智能

Copyright © 2026 古法编程 | 蜀ICP备2021007188号 | 关于本站 | 隐私政策