跳转至

运行

启动 Gateway 进程并读取其已配置的 Token。属于 openclaw gateway 参考的一部分。

Run the Gateway

openclaw gateway
openclaw gateway run   # equivalent, explicit form
启动行为
  • 除非在 ~/.openclaw/openclaw.json 中设置 gateway.mode=local，否则拒绝启动。对于临时/开发运行，请使用 --allow-unconfigured；它会绕过该检查，而不会写入或修复配置。
  • 启动时会自动对符合条件的无效单文件配置应用确定性的、无需提示的旧版键迁移，包括在非交互式服务运行中。它只在完整验证（包括插件）之后写入，并将之前的配置保留在 .bak 环中。使用 $include 的配置、由 Nix 管理的配置以及由更新版本写入的配置会被排除。参见 旧版配置键迁移。
  • 如果自动迁移无法使配置有效，交互式终端可以提示运行 openclaw doctor --fix，并在同意后重试一次启动。非交互式运行会改为打印该命令。如果修复后的配置仍然无效，启动将保持停止。
  • 配置读取失败（包括 SQLite 检查期间存储不可用）会以退出码 1 停止启动，以便服务监督可以重试。它们不会触发配置修复。无效配置和必需的离线迁移保留退出码 78，以防止 systemd 重启循环；重启前请先解决报告的问题。
  • openclaw onboard --mode local 和 openclaw setup 会写入 gateway.mode=local。如果配置文件存在但缺少 gateway.mode，则被视为损坏/被覆盖的配置，Gateway 不会替你猜测 local — 重新运行入门设置、手动设置该键，或传入 --allow-unconfigured。
  • 阻止在未启用认证的情况下绑定到 loopback 之外。
  • --bind 值 lan、tailnet 和 custom 通过仅 IPv4 的路径解析；仅 IPv6 的自带主机设置需要在 Gateway 前面配置 IPv4 sidecar 或代理。
  • 在获得授权时，SIGUSR2 会触发进程内重启。commands.restart（默认：启用）控制外部发送的 SIGUSR2；将其设置为 false 可阻止手动操作系统信号重启。面向 agent 的 gateway 工具是只读的；agent 通过 openclaw 委托工具请求重启。有效的 Full Access（包括 Default (Full Access)）授权允许的委托更改，无需审批提示；受限运行需要人工审批。参见 委托设置和修复。
  • SIGUSR1 保留给 Node 的 inspector，因此附加调试器不会重启 Gateway。重启时请优先使用 openclaw gateway restart；更新手动重启脚本以发送 SIGUSR2。
  • SIGINT/SIGTERM 会停止进程，但不会恢复自定义终端状态 — 如果你将 CLI 包装在 TUI 或 raw-mode 输入中，请在退出前自行恢复终端。

Options

WebSocket 端口（默认来自配置/环境变量；通常为 18789）。

绑定模式：loopback（默认）、lan、tailnet、auto、custom。

connect.params.auth.token 的共享 Token。设置时默认为 OPENCLAW_GATEWAY_TOKEN。

认证模式：none、token、password、trusted-proxy。

--auth password 的密码。 从文件读取 Gateway 密码。

Tailscale 暴露方式：off、serve、funnel。

--allow-unconfigured 布尔（路径）
在不强制 gateway.mode=local 的情况下启动。仅用于临时/开发引导；不会持久化或修复配置。

--dev 布尔（路径）
如果缺少开发配置和工作区，则创建它们（跳过 BOOTSTRAP.md）。

--ambient-channels 布尔（路径）
允许 Gateway 为本进程从环境中的环境变量自动配置频道，包括配置重载。默认情况下，前台、开发和服务 Gateway 需要显式的 channels.<id> 配置，例如 channels.discord.enabled=true。已配置的频道仍可从环境变量读取凭据。对于托管服务，请添加频道配置块；此标志不会被服务安装持久化。

--dev-ambient-channels 布尔（路径）
--ambient-channels 的已弃用别名。

--reset 布尔（路径）
重置开发配置、凭据、会话和工作区。需要 --dev。

--force 布尔（路径）
启动前终止目标端口上任何现有监听器。在非交互式 shell 中，此操作会拒绝终止已验证的 Gateway 监听器；请改用 --dev 或带有空闲端口的隔离 --profile。

--verbose 布尔（路径）
向 stdout/stderr 输出详细日志。

--cli-backend-logs 布尔（路径）
仅在控制台显示 CLI 后端日志（同时启用 stdout/stderr）。

WebSocket 日志样式：auto、full、compact。

--compact 布尔（路径）
--ws-log compact 的别名。

--raw-stream 布尔（路径）
将原始模型流事件记录到 JSONL。

原始流 JSONL 路径。

--claude-cli-logs 是 --cli-backend-logs 的已弃用别名。

对于 --bind custom，将 gateway.customBindHost 设置为 IPv4 地址。除 127.0.0.1 或 0.0.0.0 以外的任何地址，还要求在同一端口上为同主机客户端使用 127.0.0.1；如果任一监听器无法绑定，启动将失败。通配符 0.0.0.0 不会添加单独的必需别名。仅使用 IPv6 的自带主机设置需要在 Gateway 前面配置 IPv4 sidecar 或代理。

显示已配置的令牌

当客户端需要已配置的共享令牌时，在 Gateway 主机上运行以下命令：

openclaw gateway auth-token --show

该命令会解析 gateway.auth.token、OPENCLAW_GATEWAY_TOKEN 和已配置的 SecretRefs，然后仅打印令牌。它要求交互式终端，并拒绝重定向或管道输出，以免凭据悄悄进入命令日志。请将终端输出视为机密。

如果未配置持久令牌，请运行 openclaw doctor --generate-gateway-token，重启 Gateway，然后重新运行该命令。通用的 openclaw config get 输出仍会保持脱敏，包括 --json。

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