运行
启动 Gateway 进程并读取其配置的 Token。属于 openclaw gateway 参考文档的一部分。
运行 Gateway¶
启动行为
- 除非在
~/.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 18789)。
<ParamField path="--bind loopback(默认)、lan、tailnet、auto、custom。
<ParamField path="--token connect.params.auth.token 的共享 Token。设置 OPENCLAW_GATEWAY_TOKEN 时默认使用该值。
<ParamField path="--auth none、token、password、trusted-proxy。
<ParamField path="--password --auth password 使用的密码。
<ParamField path="--password-file
<ParamField path="--tailscale off、serve、funnel。
--allow-unconfiguredboolean (path)- 启动时不强制要求
gateway.mode=local。仅用于临时/开发引导;不会持久化或修复配置。
--devboolean (path)- 若缺少开发配置和工作区,则创建(跳过
BOOTSTRAP.md)。
--ambient-channelsboolean (path)- 允许 Gateway 为此进程从环境变量自动配置通道,包括配置重新加载时。默认情况下,前台、开发和服务的 Gateway 需要显式的
channels.<id>配置,例如channels.discord.enabled=true。已配置的通道仍可从环境变量读取凭据。对于托管服务,请添加通道配置块;服务安装不会持久化此标志。
--dev-ambient-channelsboolean (path)--ambient-channels的已弃用别名。
--resetboolean (path)- 重置开发配置、凭据、会话和工作区。需要
--dev。
--force布尔值 (路径)- 启动前终止目标端口上任何现有监听器。在非交互式 shell 中,此选项会拒绝终止已验证的 Gateway 监听器;请改用
--dev或带有空闲端口的隔离--profile。
--verbose布尔值 (路径)- 向 stdout/stderr 输出详细日志。
--cli-backend-logs布尔值 (路径)- 仅在控制台显示 CLI 后端日志(同时启用 stdout/stderr)。
<ParamField path="--ws-log