本篇与 4 月《子代理配对 1008 + trustedProxies》那篇有什么不同？

旧文侧重大流量子会话与可信代理网段的组合排错；本篇把「网关 URL、双 Token 源、1006 vs 1008、Unix Socket 挂载、共享命名空间」收进同一张连通 Runbook。

能不能只靠宿主机 curl 127.0.0.1:18789 证明容器也通？

不能替代。宿主与容器在不同网络命名空间，必须在 CLI 命名空间内用服务名或 socket 路径验证。

2026 OpenClaw Docker Compose 连通与配对：1006/1008、TOKEN 对齐与 Unix Socket／共享命名空间 Runbook

谁会遇到问题：用 Docker Compose 把 Gateway 与 openclaw CLI 分到不同容器，日志里 Gateway 似乎在跑，CLI 却卡在 gateway closed（WebSocket 1006/1008）、pairing required，或环境与文件里的两处 Token互相打架。本文结论：这不是「重装镜像就能好」的一类问题，而要把网关 URL（服务名或 Unix Socket）、OPENCLAW_GATEWAY_TOKEN 与配置里的 gateway.auth收敛到单一真源，并在必要时用共享网络命名空间收敛调用面。分工：与《子代理配对与 trustedProxies》并列——那边偏大类网段与白名单策略，本篇偏容器内如何「看见」网关与同源 Token；《Docker 网络分诊》《配对与 Token》《卷与权限》可交叉跳转。

Compose 分容器时常踩的五类「看起来像网络问题」的根因

把 Gateway 写成 127.0.0.1：127.0.0.1在每个容器里是自己的回环口，不会去另一个服务；必须用 Compose DNS 名（示例 http://openclaw-gateway:18789）。
双 Token 源未对齐：环境变量OPENCLAW_GATEWAY_TOKEN 可能覆盖配置文件；两侧容器若各读不同挂载副本，会表现为间歇 401／1008 交替出现。
Unix Socket 路径未挂载到同一可读卷：若网关通过 gateway.sock 暴露 Unix 域套接字，CLI 容器必须在完全一致的路径挂载该 socket 或其父目录，且权限与 UID/GID 对齐（见卷权限篇）。
1006 误判成「偶发抖动」：1006多表示非正常关闭链路——常见是网关重启、超时、或被中间层拆掉；需要先对照同时间窗网关日志是否重启，不要直接改配对策略。
需要共享网络命名空间却走了默认 bridge：当文档要求 CLI 进程与 Gateway等价于同台 loopback语义时，可在 Compose 用 network_mode: service:<gateway>（占位服务名），或接受「全部走服务名 TCP」的一致性架构——两者勿混在同一套 env里。

把上述五条当作白板检查项；任何一格仍待定，就不必先辩论「要不要换镜像 tag」——网络合同未闭合时换镜像通常无效。

实战中建议再补一栏时间线对齐：同一 WebSocket 关闭码出现后，截取毫秒级对齐的 Gateway stderr、CLI stdout、Docker events 三件事——半数「偶发」会被证明是另一侧服务重启或健康检查误杀。

症状快照	优先核查（自上而下）	常见落点
`1006` + 网关进程刚重启／OOM	同一时间窗宿主 `dmesg`／Docker 重启策略 → 再找上游超时与健康检查	链路非正常关闭≠配对策略错
`1008` + `pairing required`	对齐 Token 同源 → CLI 网关 URL → 配对状态是否真的写在共享卷	双 Token 或未共享状态目录
`Connection refused` 仅在 CLI 容器内	把探测命令搬进 CLI 容器再跑；宿主 curl 仅能当旁证	127.0.0.1 误区或端口未 publish 到 CLI 视图
改用 Unix Socket 后 ENOENT／Permission denied	`ls -la`挂载点 → 宿主与容器 UID 映射 → 是否套娃目录	socket 父子目录未同框挂载

落地六步：先「能看见网关」，再谈配对是否成功

写清单一真源的 Token：团队先选配置文件或环境变量其一为权威出口，再在 CI 模版里grep/docker compose config校对展开结果，杜绝「两处各写一半」。
统一网关地址语义：要么全走Compose 服务名 + 端口；要么（若官方文档支持 Unix）全走同一挂载下的 socket 路径——两套不要混在同一个变更单里试运行。
挂载 .openclaw／运行时目录：Gateway 与 CLI 必须看到同一份磁盘事实；状态目录只读会直接让配对「看起来永远在第一步」，《卷与权限对照》逐项过。
再跑网关健康与 doctor：openclaw gateway status → openclaw doctor，失败时把时间戳对齐到宿主与容器两侧的进程日志。
若确需等价 loopback：在评审单里写明采用 network_mode: service:<gateway> 或服务网格侧替代方案，并在防火墙白名单上与《trustedProxies 篇》的参数一致。
收口变更证据：贴两张截图——CLI 命名空间内的成功探测命令与展开后的网关 URL／Token hash——再关票；口头「我宿主 curl OK」不算验收。

若团队同时跑着外层 Nginx/Caddy，《反代与 WS》里 Upgrade／Timeout 任一与 Compose 侧的网关 URL口径打架，会先表现为间歇 1006——这类问题只靠改 Gateway bind 往往会把暴露面铺大还治标不治本。

yaml

# 占位示例：请替换为你的服务名与实际路径；合并前请先 docker compose config 校验展开
services:
  openclaw-gateway:
    environment:
      - OPENCLAW_CONFIG_DIR=/data/.openclaw
      # 若坚持用环境 TOKEN，请在所有消费方对齐同一 env_file
      - OPENCLAW_GATEWAY_TOKEN=${OPENCLAW_GATEWAY_TOKEN}
    volumes:
      - oc-data:/data/.openclaw
      # 若启用 Unix Socket，可把 socket 写入该卷下可读路径并与 CLI 共享
    networks: [oc-net]

  openclaw-cli:
    environment:
      - OPENCLAW_CONFIG_DIR=/data/.openclaw
      - OPENCLAW_GATEWAY_URL=http://openclaw-gateway:18789
      - OPENCLAW_GATEWAY_TOKEN=${OPENCLAW_GATEWAY_TOKEN}
    volumes:
      - oc-data:/data/.openclaw
    networks: [oc-net]
    depends_on:
      - openclaw-gateway

networks:
  oc-net:
    driver: bridge

volumes:
  oc-data:

三条「应写进变更单备注」的工程事实（与上游 SLA 无关）

探测命令必须与故障容器同命名空间：否则永远出现「宿主通、流水线不通」的薛定谔网关。
Token hash 漂移应阻断发布：比人工肉眼对字符串更靠谱的是两边的短指纹（文件 hash／env inspect）一致。
配对状态与网关重启强相关：若健康检查过激导致频繁重启，会放大 1006，却被误改成扩大 bind—先用就绪探针与重启策略收口。
跨容器调试的第一条戒律：任何「我本机试一下」的命令，如果没进报错容器镜像执行，都只能算聊天，不计入 RCA。

为什么「拼装临时容器」不适合长期承载 OpenClaw 网关主链路

笔记本上单容器试玩 Gateway 还可以；一旦进入常驻自动化 + 多端配对 + Secrets 轮换，漂移的 Docker 宿主、睡眠策略与零碎挂载会把 Token／配对状态撕开。把 Gateway 固定在可数清重启次数的独占节点上——例如六国可选、可按月／季组合的 Apple Silicon云端 Mac——更利于与同区 CI Runner、密钥管理节奏对齐：MACCOME提供更接近「小规模生产」的拓扑承载面；可先参阅公开租赁档位与帮助中心，再回填本文 Runbook 中的环境字段。

收束：先合同、后救火

OpenClaw 在 Compose 场景的失败模式几乎总是网络命名空间／Token／状态目录三件事未写成一条合同。在未收敛单一真源前，不要盲目「换镜像」「关 TLS」——会把排错带进安全债。评审会上若出现「先改代码还是先改基础设施」的争吵，用一句话压制：哪一侧能展示可重复的容器内握手成功包，就以哪一侧的合同为准——其它讨论一律排队。

对齐后再与《GHCR Control UI Runbook》《反向代理与 TLS》做下一跳集成。