跳转至

运行

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

运行 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 进程中的临时 schema 所有者完成操作。显式离线维护仍会阻止访问,且争用耗尽仍属于读取失败,退出码为 1。
  • 启动时不会仅为了收集针对有效配置的建议性修复规则而加载插件 Doctor 模块。无效配置仍会包含插件修复指导;openclaw doctor 即使在配置有效时也会检查修复规则。
  • 配置恢复、共享状态就绪以及待处理的插件迁移读取共享当前的准入快照。注册表刷新在同时持有迁移和插件生命周期租约时会重新检查准入,然后验证持久化的替换内容。修复在写入前仍会比较当前状态。这不会改变更新迁移或存储的数据。
  • openclaw onboard --mode local 和 openclaw setup 会写入 gateway.mode=local。如果配置文件存在但缺少 gateway.mode,则视为损坏/被覆盖的配置,Gateway 不会替你猜测 local —— 请重新运行 onboard 流程、手动设置该键,或传入 --allow-unconfigured。
  • 禁止在无认证的情况下绑定到 loopback 之外。
  • --bind 的值 lan、tailnet 和 custom 仅通过 IPv4 路径解析;纯 IPv6 的自带主机设置需要在 Gateway 前部署 IPv4 sidecar 或代理。
  • SIGUSR2 在获得授权时会触发进程内重启。commands.restart(默认:启用)控制外部发送的 SIGUSR2;将其设置为 false 可阻止手动 OS 信号重启。面向 agent 的 gateway 工具是只读的;agent 通过 openclaw 委托工具请求重启。Effective Full Access(含 Default (Full Access))无需审批提示即可授权允许的委托更改;受限运行需要人工审批。参见 委托设置与修复。
  • SIGUSR1 保留给 Node 的 inspector,因此附加调试器不会重启 Gateway。重启时请优先使用 openclaw gateway restart;请更新手动重启脚本以发送 SIGUSR2。
  • SIGINT/SIGTERM 会停止进程,但不会恢复自定义终端状态 —— 如果你将 CLI 包装在 TUI 或 raw-mode 输入中,请在退出前自行恢复终端。

选项

<ParamField path="--port " type="number"> WebSocket 端口(默认来自配置/环境变量;通常为 18789)。

<ParamField path="--bind " type="string"> 绑定模式:loopback(默认)、lan、tailnet、auto、custom。

<ParamField path="--token " type="string"> 用于 connect.params.auth.token 的共享 Token。设置 OPENCLAW_GATEWAY_TOKEN 时默认使用该值。

<ParamField path="--auth " type="string"> 认证模式:none、token、password、trusted-proxy。

<ParamField path="--password " type="string"> --auth password 使用的密码。 <ParamField path="--password-file " type="string"> 从文件读取 Gateway 密码。

<ParamField path="--tailscale " type="string"> Tailscale 暴露方式:off、serve、funnel。

--allow-unconfigured boolean (path)
启动时不强制要求 gateway.mode=local。仅用于临时/开发引导;不会持久化或修复配置。

--dev boolean (path)
若缺少开发配置和工作区,则创建(跳过 BOOTSTRAP.md)。

--ambient-channels boolean (path)
允许 Gateway 为此进程从环境变量自动配置通道,包括配置重新加载时。默认情况下,前台、开发和服务的 Gateway 需要显式的 channels.<id> 配置,例如 channels.discord.enabled=true。已配置的通道仍可从环境变量读取凭据。对于托管服务,请添加通道配置块;服务安装不会持久化此标志。

--dev-ambient-channels boolean (path)
--ambient-channels 的已弃用别名。

--reset boolean (path)
重置开发配置、凭据、会话和工作区。需要 --dev。

--force 布尔值 (路径)
启动前终止目标端口上任何现有监听器。在非交互式 shell 中,此选项会拒绝终止已验证的 Gateway 监听器;请改用 --dev 或带有空闲端口的隔离 --profile。

--verbose 布尔值 (路径)
向 stdout/stderr 输出详细日志。

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

<ParamField path="--ws-log