网络与存储
绑定模式、主机提供商 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:只有容器网络命名空间内的进程才能直接访问网关。
Note
在 gateway.bind 中使用绑定模式值(lan / loopback / custom / tailnet / auto),不要使用 0.0.0.0 或 127.0.0.1 之类的主机别名。
主机本地提供商¶
在容器内部,127.0.0.1 是容器本身,而不是主机。对于运行在主机上的提供商,请使用 host.docker.internal:
| 提供商 | 主机默认 URL | Docker 设置 URL |
|---|---|---|
| LM Studio | http://127.0.0.1:1234 |
http://host.docker.internal:1234 |
| Ollama | http://127.0.0.1:11434 |
http://host.docker.internal:11434 |
内置设置将这些 URL 用作 LM Studio/Ollama 的入门默认值,并且 docker-compose.yml 在 Linux Docker Engine 上将 host.docker.internal 映射到主机网关(Docker Desktop 在 macOS/Windows 上提供相同别名)。主机服务必须监听 Docker 可以访问的地址:
如果你使用自己的 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 挂载 home 卷;使用该 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 镜像的 PATH 中包含 /home/node/.local/bin,因此内置的
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
登录会保留 anthropic/* 模型引用,并通过内置的 claude-cli 后端运行它们:
docker compose -f docker-compose.yml -f docker-compose.extra.yml run --rm \
openclaw-cli agent \
--agent main \
--model anthropic/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 而不是 home 卷,请将所有这些 Claude 路径都挂载到两个服务中。
Note
对于共享生产自动化或可预测的 Anthropic 计费,请优先使用 Anthropic API 密钥路径。Claude CLI 复用遵循 Claude Code 的安装版本、账户登录、计费和更新行为。
Bonjour / mDNS¶
Docker 桥接网络通常无法可靠转发 Bonjour/mDNS 多播(224.0.0.251:5353)。当 OPENCLAW_DISABLE_BONJOUR 未设置时,内置的 Bonjour 插件一旦检测到正在容器中运行,就会自动禁用 LAN 广播,因此不会因重试被桥接丢弃的多播而陷入崩溃循环。设置 OPENCLAW_DISABLE_BONJOUR=1 可强制关闭,无论检测结果如何;或设置 0 强制开启(仅在 host 网络、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用于代理本地 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 主目录下,因此安装记录和包根目录会在容器替换后保留;网关启动不会重新生成捆绑插件依赖树。
有关完整的 VM 持久化详情,请参阅 Docker VM Runtime - 哪些内容持久化在哪里。
磁盘增长热点: media/、每个 agent 的 SQLite 数据库、旧版会话 JSONL 转录、共享 SQLite 状态数据库、已安装插件包根目录,以及 /tmp/openclaw/ 下的滚动文件日志。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw