网关 Runbook

Use this page for day-1 startup and day-2 operations of the Gateway service.

深度故障排查

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

配置

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

密钥管理

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

密钥计划契约

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

5 分钟本地启动¶

1. 启动 Gateway

openclaw gateway --port 18789
# debug/trace mirrored to stdio
openclaw gateway --port 18789 --verbose
# force-kill listener on selected port, then start
openclaw gateway --force

2. 验证服务健康

openclaw gateway status
openclaw status
openclaw logs --follow

健康基线：Runtime: running、Connectivity probe: ok，以及一行与你预期匹配的 Capability。使用 openclaw gateway status --require-rpc 获取读范围 RPC 证明，而不仅仅是可达性。

3. 验证通道就绪状态

openclaw channels status --probe

当 Gateway 可达时，这会运行实时的按账户通道探测和可选审计。如果 Gateway 不可达，CLI 会回退到仅配置通道摘要。

Note

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
控制 UI 和钩子
默认绑定模式：loopback。在检测到的容器环境中，有效默认值为 auto（解析为 0.0.0.0 以进行端口转发），除非 Tailscale serve/funnel 处于活动状态，此时始终强制为 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 和内存管道期望 /v1/embeddings。
Agent 原生客户端越来越倾向于使用 /v1/responses。

/v1/models 以 Agent 为先：它为每个已配置的 Agent 返回 openclaw、openclaw/default 和 openclaw/<agentId>。openclaw/default 是稳定别名，始终映射到已配置的默认 Agent。当你想要后端 provider/model 覆盖时，发送 x-openclaw-model；否则所选 Agent 的常规模型和嵌入设置保持控制。

所有这些都在主 Gateway 端口上运行，并使用与 Gateway HTTP API 其余部分相同的受信任操作员身份验证边界。

Admin HTTP RPC（POST /api/v1/admin/rpc）是一个独立的、默认关闭的插件路由，用于无法使用 WebSocket RPC 的主机工具。参见 Admin HTTP RPC。

端口和绑定优先级¶

设置	解析顺序
Gateway 端口	`--port` → `OPENCLAW_GATEWAY_PORT` → `gateway.port` → `18789`
绑定模式	CLI/覆盖 → `gateway.bind` → `loopback`（容器内为 `auto`）

已安装的 Gateway 服务会在 supervisor 元数据中记录解析后的 --port。更改 gateway.port 后，运行 openclaw doctor --fix 或 openclaw gateway install --force，以便 launchd/systemd/schtasks 在新端口上启动进程。

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

热重载模式¶

`gateway.reload.mode`	行为
`off`	不重新加载配置
`hybrid`（默认）	安全时热应用，必要时重启

早前的 hot 和 restart 模式已在 v2026.7.2-beta.4 中退役，并从 v2026.8.1 起稳定。openclaw doctor --fix 将两者都映射到 hybrid。

操作员命令集¶

openclaw gateway status
openclaw gateway status --deep   # adds a system-level service scan
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 健康探测。

多个 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 可能会在多个不同的 Gateway 响应时，或当 OpenClaw 无法证明可达目标是同一个 Gateway 时，警告 multiple reachable gateway identities。指向同一个 Gateway 的 SSH 隧道、代理 URL 或已配置的远程 URL 是一个具有多个传输的 Gateway，即使传输端口不同也是如此。
如果这是有意为之，请为每个 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。

远程访问¶

首选：Tailscale/VPN。回退：SSH 隧道。

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

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

Warning

SSH 隧道不会绕过网关身份验证。对于共享密钥身份验证，客户端即使通过隧道也必须发送 token/password。对于携带身份信息的模式，请求仍必须满足该身份验证路径。

参见：远程网关、身份验证、Tailscale。

监督与服务生命周期¶

原生服务控制命令仅接收操作系统环境，用于可执行文件查找、账户身份、区域设置和服务管理器路由。它们不会继承应用凭据或任意 shell 变量。网关负载及其已安装的服务定义保留其单独配置的环境。

使用受监督的运行以获得类似生产环境的可靠性。

macOS（launchd）Linux（systemd 用户）

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

重启请使用 openclaw gateway restart。不要将 openclaw gateway stop 和 openclaw gateway start 串联作为重启的替代方式。

在 macOS 上，gateway stop 使用 launchctl bootout，并在报告成功之前验证 LaunchAgent 已卸载且其进程已退出。这会从当前启动会话中移除 LaunchAgent，但不会持久化禁用状态，因此 KeepAlive 自动恢复在意外崩溃后仍然有效，并且 gateway start 可以干净地重新启用。若要跨重启持久抑制自动重新生成，请传递 --disable：openclaw gateway stop --disable。

如果无法验证关机，命令将失败，并给出需要在服务所有者的已登录 macOS 会话的外部终端中运行的确切 launchctl bootout gui/<uid>/<label> 命令。仅有一个空闲的网关端口并不能证明服务已停止。

LaunchAgent 标签为 ai.openclaw.gateway（默认）或 ai.openclaw.<profile>（命名配置文件）。openclaw doctor 会审计并修复服务配置漂移。

现有系统 LaunchDaemons¶

OpenClaw 安装并管理每个用户的 LaunchAgent。它不安装或管理系统 LaunchDaemons。如果自定义 LaunchDaemon 已经使用相同的网关标签，OpenClaw 会拒绝写入、启动、重启或修复用户 LaunchAgent，因为两个 KeepAlive 管理器可能会反复重启同一个网关。

所有权检查会读取 launchctl print system/<label>，并检查 /Library/LaunchDaemons 下已安装的 plist。当无法验证系统所有权时，它会失败关闭，并且 --force 不会绕过它。openclaw gateway status 会报告已加载的同标签系统作业；添加 --deep 以扫描已安装的系统服务文件。

运行时和独立更新器使用原生解析器解析捕获的 plist 字节。如果端点保护在分离式重启期间拒绝路径名解析，其所有权扫描会尝试有界读取，并改为解析捕获的字节。实际的权限拒绝读取会被跳过，而格式错误的数据和其他读取失败仍会阻止激活。已加载的同标签作业仍会被阻止；被读取拒绝隐藏的未加载同标签 plist 无法被检测到。分离式重启回退使用 macOS 的 /usr/bin/perl；如果该读取器不可用，扫描仍会拒绝无法验证的激活。这不会更改端点保护策略，也不会抑制其警报。

重试前请选择一个生命周期所有者：

若要保留自定义系统 LaunchDaemon，请移除任何竞争的用户 LaunchAgent，并在运行 Doctor 时设置 OPENCLAW_SERVICE_REPAIR_POLICY=external，使其对服务生命周期仅保持诊断功能。
若要返回受支持的用户 LaunchAgent，请使用 sudo launchctl bootout system/<label> 卸载系统作业，移除或迁移其实际 plist，以目标用户身份登录 macOS 桌面，然后运行 openclaw gateway install。

对于默认配置文件，<label> 为 ai.openclaw.gateway。命名配置文件使用 ai.openclaw.<profile>。

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

若要在注销后保持持久性，请启用持续登录（lingering）：

sudo loginctl enable-linger $(whoami)

在没有桌面会话的无头服务器上，重试 systemctl --user 命令之前，也请确保已设置 XDG_RUNTIME_DIR（export XDG_RUNTIME_DIR=/run/user/$(id -u)）。

服务检查会保留一个能够到达用户管理器的显式 DBUS_SESSION_BUS_ADDRESS。否则，它会尝试 $XDG_RUNTIME_DIR/bus，然后尝试用于检查的私有管理器套接字。安装、状态和更新准入会复用所选路由；gateway status --deep 会显示它。更新准入会重新检查在早期发现期间超时的路由。仅存在套接字并不能替代一个可用的自定义总线。如果没有路由到达管理器，请检查 XDG_RUNTIME_DIR，登录一次或启用持续登录（lingering），并验证 systemctl --user status。在 Debian/Ubuntu 上，dbus-user-session 提供用户总线；如有需要，使用 systemctl --user start dbus.socket 启动它。缺失的单元可以安全安装；无法读取的现有定义必须先由其所有者修复。

当你需要自定义安装路径时，手动用户单元示例：

[Unit]
Description=OpenClaw Gateway
After=network-online.target
Wants=network-online.target
StartLimitBurst=10
StartLimitIntervalSec=300

[Service]
ExecStart=/usr/local/bin/openclaw gateway --port 18789
Restart=always
RestartSec=5
RestartPreventExitStatus=78
TimeoutStopSec=330
TimeoutStartSec=30
SuccessExitStatus=0 143
OOMPolicy=continue
KillMode=mixed

[Install]
WantedBy=default.target

TimeoutStopSec=330 覆盖 Gateway 最大 315 秒的停止排空，外加 15 秒的清理和退出余量。Gateway 会将其排空时间限制在安装单元的有效停止超时范围内；参见 Systemd 停止截止时间。要检查当前托管单元主体，请运行 systemctl --user cat openclaw-gateway.service（对于命名 profile，请运行 systemctl --user cat openclaw-gateway-<profile>.service）。

Windows（原生）Linux（系统服务）

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

原生 Windows 托管启动使用名为 OpenClaw Gateway 的计划任务（对于命名 profile，为 OpenClaw Gateway (<profile>)）。如果创建计划任务被拒绝，OpenClaw 会回退到指向状态目录内 gateway.cmd 的按用户启动文件夹启动器。

对于多用户/常驻主机，请使用系统单元。

从用户单元示例开始，将其安装到 /etc/systemd/system/openclaw-gateway[-<profile>].service，如果你的 openclaw 二进制文件位于其他位置，请调整 ExecStart=，并在其 [Service] 部分添加 User=：

[Service]
User=<user>

将 <user> 替换为拥有 OpenClaw 状态和配置的非 root 账户。没有 User= 的系统单元会以 root 身份运行。在此配置中，以 root 身份运行 Gateway 及其 agent 命令是不安全的，且不受支持。

当省略 Group= 时，systemd 会使用所选账户的主组。默认情况下，User= 还会提供该账户的 HOME，OpenClaw 使用它进行常规状态和配置查找。对于有意使用的自定义位置，请在单元环境中设置 OPENCLAW_STATE_DIR 和 OPENCLAW_CONFIG_PATH。不要将配置复制到 root 的主目录作为变通方法。在单用户主机上，上述用户单元配合 loginctl enable-linger 是保持 Gateway 在无登录会话时运行的受支持方式。

也不要让 openclaw doctor --fix 为同一 profile/端口安装用户级 gateway 服务。当 Doctor 发现系统级 OpenClaw gateway 服务时，它会拒绝该自动安装；当系统单元拥有生命周期时，请使用 OPENCLAW_SERVICE_REPAIR_POLICY=external。

openclaw gateway status --deep 会检查已安装的系统单元并报告 systemd system。请从具有相同状态和配置路径的非 root User= 账户运行 Doctor。对于离线修复，请先通过其系统服务所有者停止单元，运行 openclaw doctor --fix，然后通过该所有者启动单元。 Doctor 可以验证已停止的系统单元，而无需重写其定义或创建竞争的用户服务。不可用的管理器或未验证的服务账户仍会阻止维护。

写入单元后，重新加载 systemd 并启用它：

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

无效配置错误会以代码 78 退出。Linux systemd 单元使用 RestartPreventExitStatus=78 在配置修复前停止重新启动。launchd 和 Windows Task Scheduler 没有等效的按退出代码停止规则，因此 Gateway 还会持久化快速非正常启动历史，并在重复启动失败后抑制 channel/provider 账户自动启动。在该安全模式下，控制平面仍会启动以供检查和修复，配置热重载和 secrets.reload 会拒绝自动 channel 重启，而显式的操作员 channels.start 请求可以覆盖该抑制。逐步恢复说明位于重启恢复。

开发 profile 快速路径¶

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

默认值包括隔离的状态/配置和基础 gateway 端口 19001。

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

第一个客户端帧必须是 connect。
Gateway 返回带有 snapshot（presence、health、stateVersion、uptimeMs）以及 policy 限制（maxPayload、maxBufferedBytes、tickIntervalMs）的 hello-ok 帧。
hello-ok.features.methods / events 是一个保守的发现列表，而不是每个可调用 helper 路由的生成转储。
请求：req(method, params) → res(ok/payload|error)。
常见事件包括 connect.challenge、agent、chat、 session.message、session.operation、session.tool、可选加入的 session.approval、sessions.changed、presence、tick、health、 heartbeat、配对/审批生命周期事件，以及 shutdown。

Agent 运行分为两个阶段：

立即的已接受确认（status:"accepted"）
最终完成响应（status:"ok"|"error"），中间带有流式 agent 事件。

完整协议文档参见：Gateway 协议。

运维检查¶

存活性¶

打开 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`	配置设置为远程模式，或损坏的配置中缺少 `gateway.mode`

特征	可能的问题
`unauthorized` 连接时	客户端与 Gateway 之间的身份验证不匹配

如需完整的诊断步骤，请使用 Gateway 故障排查。

安全保证¶

当 Gateway 不可用时，Gateway 协议客户端会快速失败（没有隐式的直接通道回退）。
无效/非连接首帧会被拒绝并关闭。
优雅关闭会在套接字关闭前发出 shutdown 事件。

配置
Gateway 故障排查
后台 exec 和进程工具 — 面向代理的 exec 和进程工具，不是 Gateway 服务控制
健康
Doctor
身份验证
远程访问
密钥管理
CLI 后端 — 将外部 CLI 代理作为 Gateway 后端运行

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw