Skip to main content

Documentation Index

Fetch the complete documentation index at: https://openclaw.zhcndoc.com/llms.txt

Use this file to discover all available pages before exploring further.

在 Gateway 服务的首日启动和次日运维中使用本页。

深度故障排查

以症状为先的诊断，包含精确的命令梯子和日志特征。

配置

面向任务的设置指南 + 完整配置参考。

密钥管理

SecretRef 契约、运行时快照行为，以及迁移/重载操作。

密钥计划契约

secrets apply 的精确目标/路径规则，以及仅引用 auth-profile 的行为。

​
5 分钟本地启动

1

启动 Gateway

openclaw gateway --port 18789
# 调试/跟踪输出镜像到 stdio
openclaw gateway --port 18789 --verbose
# 先强制杀掉所选端口上的监听器，然后启动
openclaw gateway --force
2

验证服务健康状态

openclaw gateway status
openclaw status
openclaw logs --follow
健康基线：Runtime: running、Connectivity probe: ok，以及符合预期的 Capability: ...。当你需要读范围 RPC 证明，而不只是可达性时，请使用 openclaw gateway status --require-rpc。
3

验证通道就绪状态

openclaw channels status --probe
在 gateway 可达时，这会针对每个账号运行实时通道探测和可选审计。 如果 gateway 不可达，CLI 会回退为仅配置的通道摘要， 而不是实时探测输出。
Gateway 配置重载会监视当前活动配置文件路径（从 profile/state 默认值解析而来，或在设置时使用 OPENCLAW_CONFIG_PATH）。 默认模式是 gateway.reload.mode="hybrid"。 首次成功加载后，运行中的进程会提供当前内存中的活动配置快照；成功重载会原子性地切换该快照。

​
运行模型

  • 一个始终在线的进程，负责路由、控制平面和通道连接。
  • 单一多路复用端口，用于：
    • WebSocket 控制/RPC
    • HTTP API，兼容 OpenAI（/v1/models、/v1/embeddings、/v1/chat/completions、/v1/responses、/tools/invoke）
    • 控制 UI 和 hooks
  • 默认绑定模式：loopback。
  • 默认需要认证。共享密钥方案使用 gateway.auth.token / gateway.auth.password（或 OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD），而非 loopback 的 反向代理方案可以使用 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 和 memory 流水线期望有 /v1/embeddings。
  • 原生 agent 客户端越来越倾向于 /v1/responses。
规划说明：
  • /v1/models 以 agent 为先：它返回 openclaw、openclaw/default 和 openclaw/<agentId>。
  • openclaw/default 是稳定别名，始终映射到已配置的默认 agent。
  • 当你想使用后端 provider/model 覆盖时，请使用 x-openclaw-model；否则所选 agent 的常规模型和 embedding 设置会继续生效。
所有这些端点都运行在主 Gateway 端口上，并使用与 Gateway 其余 HTTP API 相同的受信操作员认证边界。

​
端口和绑定优先级

设置解析顺序
Gateway 端口--port → OPENCLAW_GATEWAY_PORT → gateway.port → 18789
绑定模式CLI/override → gateway.bind → loopback
已安装的 gateway 服务会在 supervisor 元数据中记录解析后的 --port。更改 gateway.port 后，请运行 openclaw doctor --fix 或 openclaw gateway install --force，以便 launchd/systemd/schtasks 在新端口上启动进程。 Gateway 启动时会使用相同的有效端口和绑定方式来为非 loopback 绑定播种本地 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（默认）安全时热应用，必要时重启

​
操作员命令集

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 system units/schtasks），而不是更深的 RPC 健康探测。

​
多个 gateway（同一主机）

大多数安装场景应在每台机器上运行一个 gateway。单个 gateway 可以承载多个 agent 和通道。 只有在你有意需要隔离或救援 bot 时，才需要多个 gateway。 有用的检查： 
openclaw gateway status --deep
openclaw gateway probe
预期结果：
  • gateway status --deep 可能会报告 Other gateway-like services detected (best effort)，并在仍存在过期的 launchd/systemd/schtasks 安装时打印清理提示。
  • gateway probe 在有多个目标响应时，可能会警告 multiple reachable gateways。
  • 如果这是有意为之，请为每个 gateway 隔离端口、配置/状态和工作区根目录。
每个实例的检查清单：
  • 唯一的 gateway.port
  • 唯一的 OPENCLAW_CONFIG_PATH
  • 唯一的 OPENCLAW_STATE_DIR
  • 唯一的 agents.defaults.workspace
示例： 
OPENCLAW_CONFIG_PATH=~/.openclaw/a.json OPENCLAW_STATE_DIR=~/.openclaw-a openclaw gateway --port 19001
OPENCLAW_CONFIG_PATH=~/.openclaw/b.json OPENCLAW_STATE_DIR=~/.openclaw-b openclaw gateway --port 19002
详细设置：/gateway/multiple-gateways。

​
VoiceClaw 实时大脑端点

OpenClaw 提供一个与 VoiceClaw 兼容的实时 WebSocket 端点，位于 /voiceclaw/realtime。当 VoiceClaw 桌面客户端应直接与实时 OpenClaw 大脑通信，而不是经过单独的中继进程时，请使用它。 该端点使用 Gemini Live 处理实时音频，并通过将 OpenClaw 工具直接暴露给 Gemini Live 来把 OpenClaw 作为大脑调用。工具调用会立即返回一个 working 结果，以保持语音轮次的响应性，然后 OpenClaw 异步执行实际工具并将结果注入回实时会话。请在 gateway 进程环境中设置 GEMINI_API_KEY。如果启用了 gateway 认证，桌面客户端会在其第一条 session.config 消息中发送 gateway token 或 password。 实时大脑访问会运行经过所有者授权的 OpenClaw agent 命令。请将 gateway.auth.mode: "none" 仅限制在 loopback-only 的测试实例中。非本地实时大脑连接需要 gateway 认证。 对于隔离的测试 gateway，请使用各自独立的端口、配置和状态运行一个单独实例： 
OPENCLAW_CONFIG_PATH=/path/to/openclaw-realtime/openclaw.json \
OPENCLAW_STATE_DIR=/path/to/openclaw-realtime/state \
OPENCLAW_SKIP_CHANNELS=1 \
GEMINI_API_KEY=... \
openclaw gateway --port 19789
然后将 VoiceClaw 配置为使用： 
ws://127.0.0.1:19789/voiceclaw/realtime

​
远程访问

首选：Tailscale/VPN。 备选：SSH 隧道。 
ssh -N -L 18789:127.0.0.1:18789 user@host
然后在本地将客户端连接到 ws://127.0.0.1:18789。
SSH 隧道不会绕过 gateway 认证。对于共享密钥认证，即使通过隧道，客户端仍然必须发送 token/password。对于带身份的模式，请求仍然必须满足该认证路径。
参见：Remote Gateway、Authentication、Tailscale。

​
监督与服务生命周期

生产级可靠性请使用受监督运行。 
openclaw gateway install
openclaw gateway status
openclaw gateway restart
openclaw gateway stop
重启请使用 openclaw gateway restart。不要连续执行 openclaw gateway stop 和 openclaw gateway start；在 macOS 上，gateway stop 会在停止前有意禁用 LaunchAgent。LaunchAgent 标签为 ai.openclaw.gateway（默认）或 ai.openclaw.<profile>（命名 profile）。openclaw doctor 会审计并修复服务配置漂移。

​
开发者配置快速路径

openclaw --dev setup
openclaw --dev gateway --allow-unconfigured
openclaw --dev status
默认包含隔离的状态/配置以及基础 gateway 端口 19001。

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

  • 第一个客户端帧必须是 connect。
  • Gateway 返回 hello-ok 快照（presence、health、stateVersion、uptimeMs、限制/策略）。
  • hello-ok.features.methods / events 是保守的发现列表，不是 一个生成的、包含所有可调用 helper 路由的完整转储。
  • 请求：req(method, params) → res(ok/payload|error)。
  • 常见事件包括 connect.challenge、agent、chat、 session.message、session.tool、sessions.changed、presence、tick、 health、heartbeat、配对/审批生命周期事件，以及 shutdown。
Agent 运行分为两个阶段：
  1. 立即返回已接受确认（status:"accepted"）
  2. 最终完成响应（status:"ok"|"error"），中间会有流式的 agent 事件。
查看完整协议文档：Gateway Protocol。

​
运行检查

​
存活性

  • 打开 WS 并发送 connect。
  • 期望返回带快照的 hello-ok 响应。

​
就绪性

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 Troubleshooting。

​
安全保障

  • 当 Gateway 不可用时，Gateway 协议客户端会快速失败（不隐式回退到 direct-channel）。
  • 非法/非 connect 的首帧会被拒绝并关闭。
  • 优雅关闭会在 socket 关闭前发出 shutdown 事件。
相关：

​
相关内容