网络与存储

绑定模式、主机提供方 URL、Claude CLI 后端、Bonjour/mDNS 以及挂载状态。属于 Docker 指南的一部分。

LAN 与 loopback¶

scripts/docker/setup.sh 默认将 OPENCLAW_GATEWAY_BIND 设为 lan，因此主机上的 http://127.0.0.1:18789 可通过 Docker 端口发布正常访问。

• lan（默认）：主机浏览器和主机 CLI 可以访问已发布的网关端口。
• loopback：只有容器网络命名空间内的进程才能直接访问网关。

主机本地提供方¶

在容器内部，127.0.0.1 指向容器自身，而非主机。对于运行在主机上的提供方，请使用 host.docker.internal：

捆绑的设置脚本将这些 URL 用作 LM Studio/Ollama 的入门默认值，并且 docker-compose.yml 在 Linux Docker Engine 上将 host.docker.internal 映射到主机网关（Docker Desktop 在 macOS/Windows 上提供相同的别名）。主机服务必须监听 Docker 可以访问的地址：

lms server start --port 1234 --bind 0.0.0.0
OLLAMA_HOST=0.0.0.0:11434 ollama serve

使用自己的 Compose 文件或 docker run？请自行添加相同的映射，例如 --add-host=host.docker.internal:host-gateway。

Docker 中的 Claude CLI 后端¶

官方镜像不会预装 Claude Code。请在容器的 node 用户下安装并登录，然后持久化该容器的主目录，以便镜像升级时不会清除二进制文件或认证状态。

对于全新安装，请在运行设置脚本之前启用持久的 /home/node 卷：

export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
export OPENCLAW_HOME_VOLUME="openclaw_home"
./scripts/docker/setup.sh

对于现有安装，请先停止堆栈并重新加载当前的 .env 值——设置脚本总是根据当前 shell 和默认值重写 .env，它不会自行读取该文件：

set -a
. ./.env
set +a
export OPENCLAW_HOME_VOLUME="${OPENCLAW_HOME_VOLUME:-openclaw_home}"
./scripts/docker/setup.sh

如果 .env 包含你的 shell 无法 source 的值，请先手动重新导出你所依赖的项（OPENCLAW_IMAGE、端口、绑定模式、自定义路径、OPENCLAW_EXTRA_MOUNTS、sandbox、skip-onboarding）。生成的 overlay 会为 openclaw-gateway 和 openclaw-cli 同时挂载主目录卷；请使用该 overlay 运行其余命令（如果你使用 docker-compose.override.yml，请先包含它）：

docker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \
  --entrypoint sh openclaw-cli -lc \
  'curl -fsSL https://claude.ai/install.sh | bash'

原生安装程序会将 claude 写入 /home/node/.local/bin/claude。OpenClaw 镜像将 /home/node/.local/bin 包含在 PATH 中，因此捆绑的 Anthropic 插件无需适配器配置覆盖即可解析到它。

从同一持久化主目录登录并验证：

docker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \
  --entrypoint /home/node/.local/bin/claude openclaw-cli auth login
docker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \
  --entrypoint /home/node/.local/bin/claude openclaw-cli auth status --text
docker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \
  openclaw-cli models auth login \
  --provider anthropic --method cli --set-default
docker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \
  openclaw-cli models list --provider anthropic

然后使用捆绑的 claude-cli 后端：

docker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \
  openclaw-cli agent \
  --agent main \
  --model claude-cli/claude-sonnet-4-6 \
  --message "Say hello from Docker Claude CLI"

OPENCLAW_HOME_VOLUME 会持久化 /home/node/.local/bin 和 /home/node/.local/share/claude 下的原生安装，以及 /home/node/.claude 和 /home/node/.claude.json 下的 Claude Code 设置/认证。仅持久化 /home/node/.openclaw 是不够的；如果你使用 OPENCLAW_EXTRA_MOUNTS 而不是主目录卷，请将所有这些 Claude 路径都挂载到两个服务中。

Bonjour / mDNS¶

Docker 桥接网络通常无法可靠地转发 Bonjour/mDNS 多播（224.0.0.251:5353）。当 OPENCLAW_DISABLE_BONJOUR 未设置时，捆绑的 Bonjour 插件一旦检测到自己运行在容器中，便会自动禁用 LAN 通告，因此不会因桥接丢弃多播而崩溃循环重试。设置 OPENCLAW_DISABLE_BONJOUR=1 可无视检测结果强制关闭，设置为 0 则强制开启（仅在主机网络、macvlan 或其他已知 mDNS 多播可用的网络上）。

否则，对于 Docker 主机，请使用已发布的 Gateway URL、Tailscale 或广域 DNS-SD。有关注意事项和故障排查，请参阅 Bonjour 发现。

存储与持久化¶

Docker Compose 会将 OPENCLAW_CONFIG_DIR 绑定挂载到 /home/node/.openclaw，将 OPENCLAW_WORKSPACE_DIR 绑定挂载到 /home/node/.openclaw/workspace，并将 OPENCLAW_AUTH_PROFILE_SECRET_DIR 绑定挂载到 /home/node/.config/openclaw，因此这些路径在容器替换后仍然保留。当变量未设置时，docker-compose.yml 会回退到 ${HOME} 下，如果 HOME 本身也不存在，则回退到 /tmp，因此 docker compose up 在裸环境中绝不会生成空来源的卷规格。

该挂载的配置目录包含：

• openclaw.json——行为配置
• state/openclaw.sqlite——共享提供方认证；agents/<agentId>/agent/openclaw-agent.sqlite——agent 本地的 OAuth/API 密钥配置
• .env——基于环境变量的运行时机密，例如 OPENCLAW_GATEWAY_TOKEN

auth-profile 密钥目录存储着用于恢复旧版加密 OAuth sidecar 凭据的本地加密密钥。请将其与 Docker 主机状态保存在一起，但需与 OPENCLAW_CONFIG_DIR 分开存放。

当前的 OAuth token 材料以明文形式存储在 OPENCLAW_CONFIG_DIR 下的 SQLite 中，包括 access、refresh 和 ID-token 值。单独的密钥挂载不会加密当前的 SQLite 行，也无法在仅包含状态的备份或复制中保护这些 token。请将配置目录及其备份视为凭据。

已安装的可下载插件会将包状态存储在挂载的 OpenClaw home 目录下，因此安装记录和包根目录在容器替换后依然存在；Gateway 启动时不会重新生成捆绑插件的依赖树。

有关 VM 持久化的完整详情，请参阅 Docker VM 运行时 - 数据持久化位置。

磁盘增长热点： media/、每个 agent 的 SQLite 数据库、旧版会话 JSONL 记录、共享的 SQLite 状态数据库、已安装插件的包根目录，以及 /tmp/openclaw/ 下的滚动文件日志。