跳转至

网络与存储

绑定模式、主机提供商 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 可以访问的地址:

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 挂载 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