Docker 与容器

在 Docker、Podman、Kubernetes 或任何 OCI 运行时中运行 ZeroClaw。

官方镜像

Pushed to GitHub Container Registry (ghcr.io) on every stable release:

ghcr.io/zeroclaw-labs/zeroclaw:latest — latest stable
ghcr.io/zeroclaw-labs/zeroclaw:v0.7.5 — pinned
ghcr.io/zeroclaw-labs/zeroclaw:debian — Debian-based image (larger, broader glibc support)

多架构：linux/amd64、linux/arm64。

Note on shell access: The default latest image is intentionally distroless and does not include sh, ash, or bash. Use the debian tag if you need a shell inside the container (for example, to run docker exec for debugging).

最小运行

docker run -d \
  --name zeroclaw \
  -v zeroclaw-data:/zeroclaw-data \
  -p 42617:42617 \
  ghcr.io/zeroclaw-labs/zeroclaw:latest

该镜像期望在 /zeroclaw-data 处存在持久化状态。首次运行时，它会引导生成一个默认配置——但在完成初始设置之前，它尚无法正常使用：

docker exec -it zeroclaw zeroclaw onboard

组成

一个最小的 docker-compose.yml：

服务:
  zeroclaw:
    图像: ghcr.io/zeroclaw-labs/zeroclaw:latest
    重启: 除非停止
    端口:
      - "42617:42617"      # 网关
    volumes:
      - ./data:/zeroclaw-data
    环境:
      ZEROCLAW_ALLOW_PUBLIC_BIND: "1"   # 仅当网关必须在局域网中可达时

After the container starts, run onboarding:

docker compose exec zeroclaw zeroclaw onboard

如果只需要本地访问，请移除 ZEROCLAW_ALLOW_PUBLIC_BIND。

容器内的配置

该镜像期望在 /zeroclaw-data/.zeroclaw/config.toml 处存在配置文件。请将本地配置文件挂载到：

docker run -d --name zeroclaw \
  -v $(pwd)/my-config.toml:/zeroclaw-data/.zeroclaw/config.toml:ro \
  -v zeroclaw-state:/zeroclaw-data/workspace \
  -p 42617:42617 \
  ghcr.io/zeroclaw-labs/zeroclaw:latest

For container workloads, set uri on each [providers.models.<type>.<alias>] to a container-reachable address (e.g. http://host.docker.internal:11434 for an Ollama server on the Docker Desktop host). The ZEROCLAW_providers__models__<type>__<alias>__uri=... env override can do the same at runtime without editing config.toml.

轮询通道（Telegram、电子邮件）—— 直接可用

由出站发起的通道不需要任何特殊的容器配置。Telegram 轮询、IMAP、MQTT、Nostr 中继——全部为拉取模式；容器仅需出站连接。

接收 Webhook 的通道——需要入口

Discord、Slack、GitHub 以及大多数 webhook 通道需要入站 HTTP。有两种选择：

暴露网关 — -p 42617:42617 + 前置 TLS 反向代理，将 webhook URL 指向公网地址
使用隧道 — ngrok、Cloudflare Tunnel 或 Tailscale Funnel；将隧道 URL 设置为 webhook 目标

zeroclaw onboard tunnel configures ngrok or Cloudflare tunnels directly; the resulting public URL is what you point your webhook senders at.

Kubernetes

Helm chart templates are published to the zeroclaw-templates repo. Typical manifest fragment:

apiVersion: apps/v1
类型: 部署
元数据:
  名称: zeroclaw
规格:
  副本: 1
  策略:
    类型: 重新创建         # ZeroClaw 每个工作区仅一个实例
  模板:
    规格:
      容器:
        - 名称: zeroclaw
          图像: ghcr.io/zeroclaw-labs/zeroclaw:v0.7.5
          端口:
            - 容器端口: 42617
          volumeMounts:
            - 名称: 数据
              挂载路径: /zeroclaw-data
          环境变量:
            - 名称: ZEROCLAW_ALLOW_PUBLIC_BIND
              值: "1"
      卷:
        - 名称: 数据
          持久卷声明:
            claimName: zeroclaw-data

扩展性： ZeroClaw 每个工作区仅支持单写入器。请勿水平扩展——为每个代理运行一个实例。

Re-authenticating after logout

If you log out of the web UI while running in a container, the existing paircode becomes invalid. Generate a new one to log back in:

docker exec -it zeroclaw zeroclaw gateway get-paircode --new

For Compose deployments, use docker compose exec instead:

docker compose exec zeroclaw zeroclaw gateway get-paircode --new

注意事项

macOS 主机名 quirks（Docker Desktop、colima、Rancher Desktop）。 在 macOS 上，Docker Desktop 开箱即用支持 host.docker.internal。在 colima 中，只有在使用 colima start --network-address 安装时才能访问该主机名（否则容器完全无法看到宿主机——需通过 VM 的网关 IP（通常为 192.168.5.2）连接，或通过共享网络隧道连接）。Rancher Desktop 在较新版本中行为与 Docker Desktop 类似，但在旧版本中曾出现 host.docker.internal 解析失败的问题。如果调用 provider 时向 host.docker.internal 发起连接返回 connection refused，请使用 docker run --rm alpine getent hosts host.docker.internal 进行验证——若输出为空，则说明该主机名无法解析，需要显式指定 IP。
Host-side services. If a provider is Ollama on the host, uri = "http://host.docker.internal:11434" (under [providers.models.ollama.<alias>]) works on Docker Desktop. On Linux Docker you may need --add-host=host.docker.internal:host-gateway.
内存持久化。 SQLite 内存文件位于 /zeroclaw-data/workspace/ 内。如果不挂载该卷，每次重启都会丢失对话历史。
Bind-mounting /zeroclaw-data. A host bind mount on /zeroclaw-data replaces the entire image directory, including the default config.toml and (previously) the dashboard bundle. The dashboard is now installed at /usr/share/zeroclawlabs/web/dist — outside the mount — so a bind mount no longer hides it. On first run, mount an empty host directory and the container bootstraps a fresh config; the gateway auto-detects the dashboard from its image path.
默认情况下不支持硬件直通。 GPIO / USB 需要显式指定 --device 参数（例如 --device /dev/ttyUSB0），并且容器用户需要具有 dialout/gpio 组的匹配 GID。

下一个

服务管理
操作 → 网络部署 — 隧道、反向代理

Keyboard shortcuts

ZeroClaw Docs