gateway.bind=lan 未配有效鉴权进程直接拒绝启动、OPENCLAW_GATEWAY_TOKEN 只写在交互 shell 而 LaunchAgent 读不到、以及改 config 后误以为 hybrid 热重载能替代 bind 变更所需的完整重启。本文给出 loopback vs lan 决策树与五条痛点、.env 与 openclaw.json 单一事实源对照表、六步跟做命令块、gateway.reload.mode=hybrid 与手动重启分界及 gateway.controlUi.allowedOrigins 配置，并覆盖 refusing to bind without auth、EADDRINUSE、unauthorized 分叉与 M4 对比 M4 Pro 常驻选型；与 launchd token、升级与远程访问、remote Gateway、诊断梯子、install-daemon 交叉阅读。
loopback 还是 lan：2026 年云 Mac 上 OpenClaw Gateway 绑定决策树
OpenClaw Gateway 默认监听回环地址，适合「工程师 SSH 进云 Mac 后在本机打开 Dashboard」或「仅本机 CLI 与 launchd 监督进程通信」的场景。一旦你需要让另一台笔记本上的 Control UI、多台 remote 客户端、或同 VPC 内网探针在不经过 SSH 隧道的情况下访问 18789，就要把 gateway.bind 从 loopback 切到 lan（或等价非回环策略）。2026 年 OpenClaw 对非回环绑定的安全策略已收紧：离开 127.0.0.1 且未配置有效 gateway.auth.token（或等价的 OPENCLAW_GATEWAY_TOKEN 环境注入）时，进程会拒绝启动，日志里常见 refusing to bind without auth 类签名——这不是 bug，而是强制你把「监听面扩大」与「生产认证」绑在一起写进变更单。
决策时不要只看「能不能 ping 通云 Mac」：个人运维仍应优先 loopback + ssh -L 或 Tailnet（见 升级隧道文）；只有当你明确需要内网固定网段直连、或 Control UI 必须从浏览器跨子网打开 Gateway WebSocket 时，才进入 lan + token 路径。下面五条把值班时最常见的误判写成检查顺序，避免在未核对 bind 与 auth 组合之前就去改模型路由或重装 channels。
隧道够用却强行 lan：单人 SSH 本地转发已满足访问，改 bind 只会扩大攻击面并引入 plist 漂移，无收益。
lan 无 token：gateway.bind=lan 已写入 config 但 gateway.auth.mode 未显式设为 token，或 token 为空，Gateway 启动即退出。
token 只在 shell：交互终端 export OPENCLAW_GATEWAY_TOKEN=... 后手动 openclaw gateway 正常，LaunchAgent job 无同变量，表现为 launchd 循环重启。
探针 URL 与 listen 不一致：bind 改为 lan 后仍 curl 127.0.0.1，或 healthz 未带 Authorization，误判为 Gateway 离线。
公网裸暴露 18789：在云厂商安全组放行全网段却未完成应用层 token 与 controlUi.allowedOrigins，扫描流量放大日志噪声。
若你尚未完成初装与 install-daemon，请先走 官方守护跟做 与 安装排错清单，确认 loopback 下 openclaw gateway status --deep 已为 ready，再进入本篇的非回环与生产认证段落；否则会把「监督元数据未就绪」与「bind 策略错误」混在同一工单里。
.env 托管 Token 与 openclaw.json：单一事实源对照表
生产口径下，密钥不应在 openclaw.json、plist、聊天工具与 CI 日志里各存一份明文。OpenClaw 2026 年推荐把 Gateway 认证 token 放在 ~/.openclaw/.env（或监督进程可见的等价路径），由进程启动时加载 OPENCLAW_GATEWAY_TOKEN；openclaw.json 只声明 gateway.bind、gateway.auth.mode、gateway.reload.mode 与 gateway.controlUi.allowedOrigins 等非密钥字段。LaunchAgent plist 的 EnvironmentVariables 应指向同一状态目录，或通过 OPENCLAW_STATE_DIR 固定 home，避免 CI 用户与登录用户双 home 导致「我 cat .env 明明有值」的错觉——这与 launchd token 缺失 文描述的分叉一致，本篇在 lan 场景下把写法写死成可审计表格。
切忌把废弃键名 gateway.token 与新版 gateway.auth.token 混用：升级后旧键会被 schema 静默忽略，Dashboard 反复 unauthorized 而 doctor 未必第一时间标红。若必须从旧机迁移，请只迁结构字段，token 在目标云 Mac 重新生成并写入 .env，不要复制粘贴历史明文。
| 字段 / 文件 | 推荐写法 | 禁止做法 | LaunchAgent 验收点 |
|---|---|---|---|
| ~/.openclaw/.env | OPENCLAW_GATEWAY_TOKEN=<随机 hex>，权限 600 | 提交进 Git、同步盘共享、截图发群 | plist WorkingDirectory 与 CLI 一致 |
| openclaw.json | gateway.bind: "lan"、gateway.auth.mode: "token" | 明文 gateway.auth.token 与 .env 双写 | 改 bind 后必须 restart，非 hybrid 可热更项 |
| gateway.reload.mode | hybrid：路由/通道等软配置热重载 | 误以为改 bind 可仅 SIGHUP | 重启后 meta.lastTouchedVersion 与版本对齐 |
| controlUi.allowedOrigins | 枚举浏览器 Origin，配合 lan 最小暴露 | * wildcard 上生产 | 远程打开 UI 前与 token 一并验收 |
| plist EnvironmentVariables | 注入 PATH、OPENCLAW_STATE_DIR；不重复 token 明文 | 与 shell profile 各写一套冲突值 | launchctl print 与 deep status 对照 |
密钥进 .env，策略进 openclaw.json，监督进程读同一目录——少一个分叉就少一类 401。
多端 remote 客户端场景还要对齐 WS URL 与 token 在 profile 两侧一致，详见 remote Gateway 职责切分；lan 绑定只是把「监听地址」从本机扩展到网卡，并不替代客户端侧的鉴权头与 Origin 策略。
六步跟做：从停旧进程到 lan 绑定、LaunchAgent 与 healthz 验收
下列步骤假设你已在 KVMNODE 独占云 Mac 上以 launchd 跑通 loopback Gateway；变更窗口内请先备份 openclaw.json、plist Label 与 openclaw --version 输出，便于与 全天候稳定运行 文中的回滚段落对齐。全程在Gateway 所在主机执行，不要在本地笔记本改 config 却期望新加坡节点生效。
停旧进程并确认端口 owner：openclaw gateway stop，lsof -i :18789 无遗留调试进程，避免 EADDRINUSE。
写入 .env：生成随机 token 写入 ~/.openclaw/.env，chmod 600；勿把值 echo 进终端历史以外的日志。
设置 bind 与 auth.mode：openclaw config set gateway.bind lan、gateway.auth.mode token、可选 gateway.reload.mode hybrid。
刷新 LaunchAgent：openclaw gateway install --force 后 launchctl kickstart -k 或 gateway restart，对照 plist 与 which openclaw。
healthz 探活：对本机网卡地址或 127.0.0.1 带 Authorization: Bearer 请求 /healthz，确认非 401/503。
客户端带 token 连接：remote CLI 或 Control UI 用同一 token 验收 WS；记录 bind 模式、token 轮换策略与变更时间戳。
export PATH="/opt/homebrew/bin:/usr/local/bin:$PATH"
openclaw gateway stop 2>/dev/null || true
lsof -i :18789
TOKEN=$(openssl rand -hex 32)
echo "OPENCLAW_GATEWAY_TOKEN=${TOKEN}" > ~/.openclaw/.env
chmod 600 ~/.openclaw/.env
openclaw config set gateway.bind lan
openclaw config set gateway.auth.mode token
openclaw config set gateway.reload.mode hybrid
openclaw gateway install --force
openclaw gateway restart
curl -sS -o /dev/null -w "%{http_code}\n" \
-H "Authorization: Bearer ${TOKEN}" \
http://127.0.0.1:18789/healthz
openclaw gateway status --deep
第六步客户端验收时，建议至少覆盖两种路径：同机 openclaw channels probe（若已配置 channels）与另一台笔记本上的 remote profile 连接，确认 Bearer 与 WS URL 中的 host 均指向云 Mac 内网地址而非残留的 127.0.0.1。若仅在本机验收通过、远程仍 401，多半是客户端 profile 仍缓存 loopback 时代的 token 或缺少 Authorization 头，而非 Gateway 未监听 lan。
若 install --force 后仍 split brain，先读 CLI 与 Gateway 对齐，再动第二遍 force；在未对齐二进制路径前反复改 bind 只会把监督元数据搅乱。验收通过后，把 healthz 状态码、deep status 摘要与 plist Label 写入与区域/规格同一工单，方便续租与换区时审计。
hybrid 热重载 vs 手动重启：改哪些字段必须 gateway restart
gateway.reload.mode=hybrid 的价值在于：channels 路由、部分 agent 软配置、探针间隔等变更可在不中断长连接的前提下热加载，适合白天频繁调 Skills 或 peer 规则的生产节点。但绑定地址、监听端口、auth.mode、TLS 相关硬字段仍要求完整重启监督进程；值班若把「改 bind 后 SIGHUP 一下」当成足够，会出现 CLI 读到新 config、运行中进程仍 listen 旧地址的 split 视图。下表可直接贴进 Runbook，与 诊断梯子 L2「Runtime running · probe failed」行对照使用。
| 变更类型 | hybrid 是否足够 | 推荐动作 | 验收信号 |
|---|---|---|---|
| gateway.bind / 端口 | 否 | gateway restart + deep status | lsof 与 config 一致 |
| gateway.auth.mode | 否 | restart；必要时轮换 .env token | healthz 带 Bearer 200 |
| channels / 路由规则 | 通常是 | 改 config 后等待 hybrid 或 gateway reload | channels probe 通过 |
| 模型上游 Key | 通常是 | 热更或短重启视版本而定 | 测试消息非 401 |
| controlUi.allowedOrigins | 视版本；生产建议 restart | 改数组后 restart 并清浏览器缓存 | 远程 UI 无 CORS 拒绝 |
远程浏览器打开 Control UI 时，除 token 外还必须把前端 Origin 写进 gateway.controlUi.allowedOrigins。例如工程师从 https://ops.example.com 经内网 DNS 访问云 Mac 18789，就要在 config 中显式加入该 Origin；缺省仅 localhost 时，即使 token 正确也会表现为 WebSocket 握手失败或控制台 CORS 错误，容易被误判为 Gateway 未启动。lan 绑定 + allowedOrigins 白名单 + Bearer token 三者缺一会出现不同症状，排错时先对表格再查日志，不要交叉替换三个变量。
LaunchAgent 漂移验收应在每次改 bind 或 force install 后执行：openclaw gateway status --deep 扫描重复单元、launchctl print gui/$(id -u)/... 核对 EnvironmentVariables、openclaw doctor 确认 schema 与 token 源可读。漂移未清时开 hybrid 只会让「旧进程 + 新 config 文件」并存更久，夜间 cron 探针会随机报绿随机报红。建议与 cron 健康探针 文并列：探针脚本必须读取与 Gateway 相同的 .env 路径，并在 bind=lan 时改用内网 IP 而非写死 localhost。
高频报错分叉、M4 对比 M4 Pro 与云 Mac 常驻选型
refusing to bind without auth：几乎总是 lan（或非 loopback）与空 token 的组合；回到 §2 表格补 .env 与 gateway.auth.mode token，勿先重装 OpenClaw。EADDRINUSE：18789 被旧 Gateway 或调试进程占用，lsof 找 owner 再 restart，不要在未释放端口时连点 force。unauthorized / 401：客户端 Bearer 与 Gateway 读到的 token 不一致，或 launchd 未加载 .env；按 launchd token 二分法查监督环境。probe failed 但 Runtime running：探针 URL、bind 地址与 Authorization 头三者未对齐，见诊断梯子 L2。
默认端口：Gateway 健康检查仍常用 18789；lan 模式下对内网探针暴露同一端口，须配防火墙最小放行而非 0.0.0.0/0。
healthz 口径：带 Authorization: Bearer 请求 /healthz；裸 curl 200 不等于生产认证已启用。
hybrid 边界：bind/auth 变更后必须 deep status；仅改 channels 时可依赖 hybrid 缩短中断窗。
排错顺序建议：doctor → gateway status --deep → 核对 .env 与 plist → healthz 带 token → 再查客户端 Origin 与 allowedOrigins。与「合盖笔记本当 Gateway 宿主」相比，笔记本 sleep 会直接掐断 lan 监听与所有 remote 会话；家用 NAS 或非 Apple 栈则缺少 launchd 与 OpenClaw 文档的一一对应示例。KVMNODE 独占云 Mac 把 bind 策略、token 轮换、hybrid 与 cron 探针写进同一 Runbook 更省事。
| 档位 | lan + 多端 + CI 同池 | 运维结论 |
|---|---|---|
| Mac Mini M4 16GB | 单 Gateway、少量 remote 客户端、轻量 channels | 生产默认；注意与 xcodebuild 争内存 |
| Mac Mini M4 Pro 24GB+ | 同机 iOS CI + 多 Skills + lan 探针并行 | 统一内存尖峰周 18789 抖动时优先升档 |
| 合盖笔记本 | bind 改 lan 也无法 7×24 | 仅个人试验，不适合作生产认证节点 |
当同一云 Mac 还要跑微信 ClawBot、remote 多端与 nightly CI 时，16GB 统一内存在尖峰周可能让 Gateway 响应变慢而非 auth 失败——此时应参考 同池隔离 升 M4 Pro 或拆池，而不是反复轮换 token。对需要可审计的非回环绑定、.env 密钥托管与 LaunchAgent 漂移验收的团队，KVMNODE Mac Mini 云端租赁通常是更优解：独占主机、六区节点、按天至月租，与 bind、token、hybrid 共用同一套变更单。档位见 定价页，操作见 帮助中心，下单见 订购入口。