本文面向已在 leanvps 德国法兰克福远程 Mac 上运行 OpenClaw、但希望比「把网关开在局域网」更小暴露面 的团队:网关监听 回环(loopback),按官方 gateway auth 使用令牌鉴权,运维机经 SSH LocalForward 访问控制面,并把
openclaw doctor --non-interactive 与 openclaw config validate 纳入合并门禁。行为请以上游公开文档为准:Configuration reference(gateway bind 与 gateway auth)、Configuration(配置值中的环境变量替换)、CLI doctor、Gateway doctor(含非交互模式说明)。
目标:回环控制面 + 最小暴露
OpenClaw 网关默认在 18789 端口复用 WebSocket 与 HTTP。官方配置参考说明:gateway.bind: "loopback" 将监听限制在本机;若绑定到非回环地址,则须配置 gateway 鉴权(token、password 或受控的 trusted-proxy 等)。在共享远程 Mac 上,推荐组合是 loopback + token 模式:远端不向公网暴露 18789,人员与自动化通过加密隧道访问同端口。
与守护进程、出站白名单等基线可对照姊妹篇 OpenClaw 德国节点:守护进程与合规向基线。需要开通或扩容德国实例时,请使用站内公开页 德国购买指南,并在 规格与定价 核对统一内存档位是否与浏览器、本地模型并发匹配。
127.0.0.1
回环绑定
SSH -L
本地端口转发
CI
校验 + doctor
最小可复现步骤(远程 Mac)
请先在 staging 主机跑通同一套 plist、SSH 片段与 CI Job,绿测后再推广到生产。
- SSH 基线。 为 OpenClaw 创建专用 macOS 用户,仅安装组织批准的构建;用密钥验证非交互 SSH(若策略允许,对该账号在
sshd_config中关闭密码登录)。 - 在 JSON5 中声明 bind 与 auth。 在
~/.openclaw/openclaw.json保持gateway.mode: "local",gateway.bind: "loopback",并配置gateway.auth.mode: "token"与gateway.auth.token: "${OPENCLAW_GATEWAY_TOKEN}",写法见官方 Configuration 中「配置值里的环境变量替换」。若 token 与 password 配置并存,参考文档要求显式gateway.auth.mode,务必写死,避免启动时语义歧义。 - 令牌注入,勿把密钥路径提交进 Git。 通过 LaunchDaemon 的
EnvironmentVariables或 root 所有的环境文件导出OPENCLAW_GATEWAY_TOKEN,权限收紧到0600。在受控管理 shell 中可按 CLI doctor 使用openclaw doctor --generate-gateway-token做一次性引导,随后轮换并迁入组织密钥体系。 - 无头健康检查。 依次执行
openclaw config validate与openclaw doctor --non-interactive。Gateway doctor 说明:--non-interactive跳过交互提示、应用安全迁移,并避免交互式 OAuth 刷新,适合 cron 与 CI。 - 安装或重启网关服务。 使用已标准化的厂商流程(例如带固定参数的
openclaw gateway install)。用openclaw gateway status确认仅监听回环。 - 从运维机做 SSH LocalForward。 执行
ssh -N -L 18789:127.0.0.1:18789 openclaw-svc@你的德国主机(替换用户与主机名)。本地工具访问ws://127.0.0.1:18789,流量经 SSH 封装;长驻隧道可加-o ExitOnForwardFailure=yes,并在客户端用 systemd 或 launchd 托管。 - 令牌路径冒烟。 隧道建立后,用运行手册中的 Bearer 方式连本机
127.0.0.1:18789;故意发送错误令牌一次,应得到明确鉴权失败而非静默成功,以证明端到端 enforcement。
为何不直接绑 LAN? 在无补偿控制下把 18789 绑到
0.0.0.0 会放大发现面与爆破面。若确需非 SSH 访问,应在 mTLS 或受控内网入口后终止 TLS,并重读 configuration reference 中 trusted-proxy 与 gateway auth 章节,而不是跳过鉴权。
合规向:最小暴露面检查(工程习惯)
下列条目不构成法律意见,仅把「最小权限」落成安全评审可 grep 的门禁;与 GDPR 等义务的关系请以贵司法务解释为准。
- 禁止把明文令牌写进 shell history: 秘密由 LaunchDaemon 或 CI Secret 注入,禁止在共享 screen 里随手
export。 - 人机账号与守护进程账号分离: 个人 UNIX 主目录与 OpenClaw 服务用户解耦,降低横向移动面。
- PR 强制审 gateway 相关 diff: 触及
gateway.bind、gateway.auth、hooks、gateway.http的变更建议双人评审。 - doctor 迁移前备份配置: 升级前为
openclaw.json打时间戳副本;若迁移误删鉴权元数据,从制品库恢复并重启服务。 - 应急扩面须工单闭环: 事故中临时放宽 bind 须登记工单,在 SLA 内回滚并复盘。
合并门禁(类 GitHub Actions 伪代码)
仓库中只放脱敏模板或只读 fixture,绝不提交生产令牌。从 CI Secret 注入测试用 OPENCLAW_GATEWAY_TOKEN,以便配置校验能解析环境变量占位。Job 建议顺序:
- 安装与生产锁定的 OpenClaw 次版本一致。
- 对检出模板合并测试密钥后运行
openclaw config validate。 - 运行
openclaw doctor --non-interactive;若输出越过策略阈值(常见做法:出现「auth missing」类告警即失败)则令 Job 失败。 - 可选:夜间跑
openclaw doctor --deep,勿在每个 PR 上默认开启(耗时与权限需求更高)。
开通、SSH 或账单问题请走内部 runbook;对外公开说明与购买入口见文末 CTA。
本文为运维与工程实践说明;OpenClaw 各版本参数可能变化,上线自动化前请对照上文引用之官方文档复核默认值与 flag。