Gateway 与上下文

这一课你将能做到

1. 熟练使用 openclaw gateway 的 run / install / start / stop / restart / status 全生命周期命令
2. 解释 Gateway 的绑定模式（loopback / lan / tailnet）与鉴权方式（token / password）
3. 理解上下文窗口与会话压缩（compaction）对长会话质量的影响

为什么要学

Gateway 是 OpenClaw 的心脏：渠道连着它、模型调用经过它、会话状态存在它手里。团队 bot 出问题时——「bot 不回了」「群里消息漏了」「重启后失忆」——九成是 Gateway 层的问题。不会运维 Gateway，等于把 bot 当黑盒供着。

人话：Gateway 之于 OpenClaw，相当于 Nginx 之于你的 Web 服务——流量入口、状态枢纽、故障第一现场。

先建立图像

            ┌─────────────── Gateway (127.0.0.1:18789) ───────────────┐
            │                                                          │
  渠道连接 ──┤  Telegram ─┐                          ┌── 会话 A 上下文 ─┤
  (WS/出站)  ├─ Slack   ──┼──→ 路由 ──→ Agent 循环 ──┼── 会话 B 上下文 ─┤
            ├─ Discord ──┘      │                    └── 会话 C 上下文 ─┘
            │                   │
            │              上下文窗口（有限，超了要 compact）
            │
            └── 配置: ~/.openclaw/openclaw.json
                要求: gateway.mode = "local"

关键点：每个会话维护自己的上下文窗口——模型能「记住」的对话历史。窗口有 token 上限，聊得久了必须压缩（compaction），把旧对话摘要成要点，否则要么爆窗要么被截断。

跟着做

步骤 1：前台跑一次看日志

openclaw gateway run --verbose

run 是显式形式（裸 openclaw gateway 等价）。前台模式适合开发调试，日志直接打在终端。Ctrl+C 停止。

步骤 2：服务化运行

openclaw gateway install     # 注册系统服务（LaunchAgent/systemd/计划任务）
openclaw gateway status      # 基础状态
openclaw gateway status --deep  # 深度检查：含 RPC 探测

步骤 3：日常运维三板斧

openclaw gateway restart     # 改配置后重启
openclaw gateway stop        # 停止（Linux 上会抑制 systemd 自动拉起，直到再次 start）
openclaw gateway start       # 启动（会先校验配置有效性）

步骤 4：改端口与绑定模式

临时改（命令行覆盖）：

openclaw gateway run --port 19000 --bind loopback

永久改（写配置）：

openclaw config set gateway.port 19000
openclaw config set gateway.bind loopback
openclaw gateway restart

绑定模式：loopback（默认，只本机）、lan（局域网可达）、tailnet（Tailscale 网络）、custom。绑定到非 loopback 时必须配置鉴权（--auth token 或 --auth password），否则拒绝启动——这是防裸奔的硬保护。

步骤 5：观察上下文行为

在 Control UI 里进行一个超长对话（或喂长文档），观察 token 用量增长；触发压缩后，让 bot 回忆对话开头的细节——你会发现它记得「要点」但忘了「原话」，这就是 compaction 的直接体现。

讲清楚要点

1. 启动有配置守卫：~/.openclaw/openclaw.json 里缺 gateway.mode=local 时拒绝启动，防止误操作把半成品配置拉起来；--allow-unconfigured 只用于临时调试。
2. exit code 有语义：配置非法退出码 78（systemd 见到它不会无限重启循环），读配置失败退出码 1（监督器会重试）。写运维脚本时按退出码分支。
3. gateway stop 不是杀进程：它走优雅停止（drain 在跑任务后退出），Linux 上会同时抑制 systemd 的 Restart=always，维护窗口用 gateway stop --force。
4. 上下文窗口是稀缺资源：长会话靠 compaction 续命——旧消息被摘要替换。设计 bot 行为时别依赖「记住三小时前的原话」，重要结论要落进 MEMORY.md。
5. 重启有两条路：推荐 openclaw gateway restart；OS 信号层面是 SIGUSR2 触发进程内重启（SIGUSR1 被 Node 调试器占用，别用）。

你可能会懵的地方

• 前台 run 和 install 后的服务是两个东西吗？ 同一个二进制，两种监督方式。install 后由系统服务管理（开机自启、崩溃拉起）；前台 run 只是你终端里的一个进程。别同时跑——会抢 18789 端口。

• 改了配置为什么要 restart 才生效？ 大部分配置支持热加载（hot reload），但端口、绑定模式、鉴权这类网络层设置必须重启。拿不准就 restart，成本一秒。

• status 和 status --deep 差在哪？ 前者看「进程在不在、端口听没听」；后者额外做 RPC 探测，验证 Gateway 真的能正常响应请求。值班巡检用 --deep。

• 会话上下文存在哪？ 落盘在 ~/.openclaw/ 的会话存储里（SQLite），Gateway 重启后会话还在，这就是为什么 bot「重启不失忆」。丢上下文只会发生在手动 reset 或压缩策略配置错误时。

• 端口冲突了怎么办？ openclaw gateway status 先看是不是已有实例；确认是别的应用占用再 config set gateway.port 换端口并重启。

错法对照

错法	问题	正解
kill -9 强杀 Gateway	任务没 drain、状态可能写坏	openclaw gateway stop 优雅停止
绑 lan 不配 auth	启动被拒（设计上防裸奔）	--bind lan --auth token --token <强随机值>
依赖长会话记忆所有细节	compaction 后细节丢失	重要事实写 MEMORY.md 或外部文档
改完端口不重启	网络层配置不热加载	openclaw gateway restart
用 SIGUSR1 想触发重启	那是 Node inspector 信号	gateway restart 或 SIGUSR2

卡点急救

1. bot 完全不响应：按序查 gateway status --deep → openclaw logs --tail 50 → openclaw doctor。八成是服务没起或模型 key 失效。
2. 重启后报配置非法（exit 78）：多半是手改 openclaw.json 改坏了，openclaw doctor --fix 能修大部分已知问题；改前养成备份习惯。
3. 长会话越聊越「笨」：上下文接近窗口上限，质量下降是预期行为。开新会话，或先把重要结论存入记忆再继续。

面试常问

• Gateway 的生命周期管理怎么做？ 开发期 openclaw gateway run 前台调试；生产期 gateway install 注册系统服务获得自启与崩溃拉起；变更后 gateway restart；维护窗口 gateway stop（会抑制 systemd 自动拉起）；巡检 gateway status --deep；退出码 78/1 区分「配置非法不重试」与「可重试故障」。

• 上下文窗口爆了会发生什么，怎么应对？ OpenClaw 会触发 compaction：把较早的对话历史摘要压缩，释放 token 空间。代价是细节丢失。应对：重要结论写 MEMORY.md 沉淀到记忆层；超长任务拆成多会话；为长文档场景选更大窗口的模型。

• Gateway 暴露到局域网要注意什么？ 必须配鉴权（token/password/trusted-proxy），非 loopback 无鉴权会被启动守卫拒绝；建议配合防火墙白名单；审计日志（openclaw audit）定期回看；能走 tailnet 就不裸绑 lan。

自测三问

1. gateway install、gateway run、gateway start 三者的关系与使用顺序？
2. 为什么绑定 lan 时必须加鉴权？不加会怎样？
3. compaction 解决了什么问题，带来什么副作用？

小结一句话

Gateway 是常驻流量枢纽：服务化管理它、鉴权保护它、用 compaction 理解上下文窗口，bot 的稳定性就握住了一大半。

延伸

• Gateway runbook
• 配置参考
• 下一课：模型与 Provider——给 Gateway 接上最合适的大脑，Anthropic / OpenAI / Ollama 怎么选。