ZeroClaw 容器化部署完全指南：Docker、Podman Quadlet 与 Kubernetes 实战-平芜编程栈

ZeroClaw 容器化部署完全指南：Docker、Podman Quadlet 与 Kubernetes 实战

【免费下载链接】zeroclawFast, small, and fully autonomous AI personal assistant infrastructure, any OS, any platform — deploy anywhere, swap anything 🦀项目地址: https://gitcode.com/gh_mirrors/ze/zeroclaw

ZeroClaw 官方支持在 Docker、Podman、Kubernetes 及任意 OCI 运行时中以容器方式运行。本篇基于仓库中的容器部署文档与配套 Dockerfile、Compose、K8s 示例源码，完整覆盖官方镜像选择、最小运行、TUI 终端接入、Compose 网络与安全边界配置、Alpine 本地构建、Podman quadlet 服务化以及 Kubernetes 部署等场景，读完后可在宿主机、Linux 服务器或容器集群中完成一次可复制的容器化部署。

官方镜像

镜像在每个 stable 版本发布时推送至 GitHub Container Registry（ghcr.io），提供三类 tag：

Tag	说明
`ghcr.io/zeroclaw-labs/zeroclaw:latest`	最新 stable 版本，基于 distroless
`ghcr.io/zeroclaw-labs/zeroclaw:v0.7.5`	固定版本示例，生产环境建议固定 tag
`ghcr.io/zeroclaw-labs/zeroclaw:debian`	Debian 基础镜像，体积更大、glibc 兼容面更广

均支持linux/amd64与linux/arm64多架构。

关于 shell 访问：默认的latest镜像有意采用 distroless 构建，内部不包含sh、ash或bash。如果需要在容器内执行 shell（例如docker exec调试），应使用debiantag。

从 Dockerfile 的多阶段结构可以看到这一取舍的实现：release阶段基于gcr.io/distroless/cc-debian13:nonroot，而dev阶段基于debian:trixie-slim并额外安装了ca-certificates、curl、vim-tiny等调试工具。两个运行时阶段都设置了相同的运行时约定：

WORKDIR /zeroclaw-data、HOME=/zeroclaw-data、ZEROCLAW_DATA_DIR=/zeroclaw-data/data；
以非 root 用户USER 65534:65534运行；
EXPOSE 42617，健康检查为zeroclaw status --format=exit-code（间隔 60s、超时 10s、重试 3 次）；
ENTRYPOINT ["zeroclaw"]+CMD ["daemon"]，即默认直接启动守护进程。

Alpine 镜像（本地构建）

仓库提供 Dockerfile.alpine，用于构建可选的 Alpine 镜像：产物是静态链接的 musl 二进制，覆盖linux/amd64与linux/arm64，但不发布到ghcr.io，需要本地构建。构建时通过cargo zigbuild分别交叉编译到x86_64-unknown-linux-musl和aarch64-unknown-linux-musl，运行时阶段基于alpine:3.23并附带bash、curl、git。

本地平台构建：

docker build -f Dockerfile.alpine -t zeroclaw:alpine .

多平台镜像（创建一个 buildx builder 后推送 manifest；若已有选中的 buildx builder 可省略第一条命令）：

docker buildx create --use --name zeroclaw-multiarch docker buildx build -f Dockerfile.alpine \ --platform linux/amd64,linux/arm64 \ -t registry.example.com/zeroclaw:alpine \ --push .

仓库附带的 Compose 示例 docker-compose.alpine.yml 会为当前平台构建镜像：

docker compose -f docker-compose.yml -f docker-compose.alpine.yml up --build

Alpine 镜像沿用与其它官方镜像一致的约定：/zeroclaw-data挂载点、schema-mirror 环境变量覆盖、dashboard 路径（/usr/share/zeroclawlabs/web/dist）和网关端口 42617。

最小运行

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

官方镜像在构建时已经把默认配置烘焙进/zeroclaw-data/.zeroclaw/config.toml。从 Dockerfile 可以看到其中关键字段：

[gateway] port = 42617 host = "[::]" allow_public_bind = true require_pairing = false web_dist_dir = "/usr/share/zeroclawlabs/web/dist"

也就是说docker run示例开箱即达：网关直接绑定[::]并关闭配对认证。而下面的 Compose 示例之所以仍然显式固定两个网关绑定设置，是为了防止挂载的持久卷或自定义配置悄悄把监听器改回 loopback-only。

镜像期望持久化状态位于/zeroclaw-data。首次运行只会引导出一份默认配置，还需要执行 quickstart 才真正可用：

docker exec -it zeroclaw zeroclaw quickstart

运行 zerocode（TUI）

镜像同时携带了 zerocode 终端界面和zeroclaw二进制。由于默认ENTRYPOINT是zeroclaw，启动 zerocode 需要覆盖入口点并提供交互式 TTY（-it），两种发布变体均可：

# distroless（:latest） docker run -it --entrypoint zerocode ghcr.io/zeroclaw-labs/zeroclaw:latest # debian docker run -it --entrypoint zerocode ghcr.io/zeroclaw-labs/zeroclaw:debian

zerocode 需要连接一个正在运行的 ZeroClaw 守护进程：

同容器内守护进程：用docker exec -it zeroclaw zerocode在已运行 daemon 的容器内启动，通过本地 IPC socket 连接；
远程守护进程：使用zerocode --connect wss://<host>:<port>通过 WebSocket Secure 连接，详见 Remote setup (WSS)。这是从自己的终端驱动容器化或远程守护进程的可移植方式。

无论哪种方式都应持久化/zeroclaw-data（同“最小运行”一节），保证 zerocode 读取的配置与身份和守护进程使用的完全一致。

Compose 部署

仓库根目录提供了 docker-compose.yml，其核心结构与注释值得直接作为部署模板参考：

services: zeroclaw: image: ghcr.io/zeroclaw-labs/zeroclaw:latest restart: unless-stopped ports: - "127.0.0.1:42617:42617" # 网关仅发布到宿主机 loopback volumes: - ./data:/zeroclaw-data environment: # host 选择容器内监听网卡；allow_public_bind 仅确认 # 非 loopback 监听并消除启动警告 - ZEROCLAW_gateway__host=0.0.0.0 - ZEROCLAW_gateway__allow_public_bind=true

完整示例还包含 provider API key 注入（如ZEROCLAW_providers__models__openrouter__default__api_key）、资源限制（cpus 2 / memory 512M）以及与健康检查一致的healthcheck段，可按需取用。

容器启动后执行 quickstart：

docker compose exec zeroclaw zeroclaw quickstart

为什么必须同时固定 host 与 allow_public_bind

Compose 应显式同时设置gateway.host与gateway.allow_public_bind。发布端口并不会让绑定到容器内127.0.0.1的网关变得可达，而allow_public_bind = true只是“确认”公网绑定，并不选择绑定。将这两个覆盖放在一起，也能让带有 localhost 默认值的既有卷或自定义配置表现一致。

这涉及两个边界，但只有一个由 Docker 强制执行：

gateway.host = 0.0.0.0选择容器内的监听网卡。Docker bridge 流量不会经过容器 loopback 到达，因此要让发布端口真正触达网关，它必须保持0.0.0.0；
gateway.allow_public_bind是确认项而非闸门：为false时网关会记录启动警告但照样绑定；设为true只是消除警告，不要依赖它保持监听器私有；
真正由 Docker 强制的边界是 Compose 的ports:映射。"127.0.0.1:42617:42617"只发布到容器所在宿主机；"42617:42617"则发布到宿主机所有网卡。

认证边界由gateway.require_pairing决定：它在 schema 中默认为true，但镜像烘焙配置中为false。关闭配对时，网关会对/webhook、/api/config、/api/memory、/api/browse及会话端点响应未认证请求。若要服务其他主机，去掉127.0.0.1:前缀的同时必须开启配对，或把网关放在带认证的反向代理/隧道之后。

Rootless Compose + Debian 镜像

针对需要容器内 shell 工具的 rootless Docker 或 Podman Compose 部署，使用 Debian 镜像并绑定宿主机数据目录：

services: zeroclaw: image: ghcr.io/zeroclaw-labs/zeroclaw:debian container_name: zeroclaw restart: unless-stopped ports: - "127.0.0.1:42617:42617" volumes: - ./data:/zeroclaw-data environment: - ZEROCLAW_gateway__host=0.0.0.0 - ZEROCLAW_gateway__allow_public_bind=true healthcheck: test: ["CMD", "zeroclaw", "status", "--format=exit-code"] interval: 60s timeout: 10s retries: 3 start_period: 10s

当前 Debian 镜像把打包的 dashboard 放在/zeroclaw-data之外（/usr/share/zeroclawlabs/web/dist），因此绑定挂载不会遮蔽它，也无需覆盖gateway.web_dist_dir。网关覆盖项采用 docker-compose.yml 中展示的 schema-mirror 拼写（ZEROCLAW_gateway__host等），优先级高于持久化的 localhost 默认配置，而 loopback 限定的ports:映射仍是限制宿主机侧可达性的边界。

macOS：OrbStack 与 Colima

macOS 没有原生 Linux 内核，因此所有方案（Docker Desktop、Podman、OrbStack、Colima）都在轻量 Linux VM 中运行容器。对 Mac 开发机，值得比较的两个原生 VM 是 OrbStack 和 Colima，容器侧都使用上面的docker run/Compose 命令：

OrbStack	Colima
引擎	自研调优 Linux VM（Apple Silicon 优化）	Lima VM + containerd/Docker
许可	商业，freemium（个人免费）	MIT（底层 Lima 为 Apache 2.0）
界面	GUI 应用 + CLI	CLI 优先（`colima start/stop`），可脚本化
适用场景	少折腾、体验顺滑	全开源、配置即代码

# OrbStack：提供 docker CLI brew install --cask orbstack # Colima：docker CLI 与 colima 的 VM 通信 brew install colima docker docker-compose # docker-compose 是 Compose v2 插件，需要 `docker compose` 时安装 colima start --cpu 4 --memory 8 # 需要把 VM IP 暴露给 macOS 时加 --network-address

典型开发负载下两者性能相当，真正的差异在许可（商业 vs 开源）和 UX 偏好，而非原始速度；如果空闲内存或构建吞吐重要，请在自己的机器上实测。注意 systemd quadlet（下一节）是 Linux 宿主特性，在 macOS 上不适用。

Podman 与 systemd quadlet

在 Linux 服务器上长期运行容器，最干净的方式是 Podmanquadlet：一个声明式单元文件，由 systemd 生成真正的服务。它提供systemctl生命周期、journald 日志、自动重启与开机顺序，无需守护进程、无--restart技巧，而且单元文件是可以提交到 git 的配置。这是推荐的服务器模式；docker run/Compose 适合笔记本场景。

quadlet 是*.container文件（同族还有.pod、.volume、.network、.kube、.build、.image）。Podman 的 systemd generator 在每次daemon-reload时读取它并写入一个瞬态.service——你永远不需要手写.service。有 root 权限的单元放/etc/containers/systemd/，rootless 放~/.config/containers/systemd/。

/etc/containers/systemd/zeroclaw.container：

[Unit] Description=ZeroClaw agent runtime After=network-online.target Wants=network-online.target [Container] # 生产环境固定版本；:latest 是 distroless（无 shell——需要 exec 时用 :debian） Image=ghcr.io/zeroclaw-labs/zeroclaw:latest ContainerName=zeroclaw PublishPort=127.0.0.1:42617:42617 Volume=zeroclaw-data:/zeroclaw-data # 仅发布到宿主机 loopback；若要服务其他主机，去掉 127.0.0.1: 前缀， # 并在之前开启配对或隧道。若挂载 localhost 默认配置， # gateway.host 与 gateway.allow_public_bind 需成对覆盖。 # 可选滚动升级路径——(重新)启动时重新拉取新镜像并纳入 `podman auto-update`： Pull=newer AutoUpdate=registry [Service] Restart=always [Install] WantedBy=multi-user.target default.target

部署（幂等，可重复执行；重复应用会使运行中的容器收敛，绝不产生重复）：

sudo cp zeroclaw.container /etc/containers/systemd/ sudo systemctl daemon-reload # generator 把 .container 变成 zeroclaw.service sudo systemctl restart zeroclaw

随后一次性完成引导，之后像管理任何服务一样管理它：

sudo podman exec -it zeroclaw zeroclaw quickstart systemctl status zeroclaw journalctl -u zeroclaw -f

生成的单元没有systemctl enable步骤：[Install] WantedBy=行就是让它随开机启动的机制。

三个补充要点：

版本固定 vs:latest。用 tag 或 digest（Image=ghcr.io/zeroclaw-labs/zeroclaw:v0.7.5或...@sha256:...）获得可复现、可审计的部署，升级就是提交到.container文件里一次可评审的 tag 变更；Pull=newer+AutoUpdate=registry则提供由podman-auto-update.timer驱动的滚动升级（sudo systemctl enable --now podman-auto-update.timer）。可复现性与新度二选一，部署循环相同。
Rootless 变体。文件放入~/.config/containers/systemd/，用systemctl --user daemon-reload && systemctl --user restart zeroclaw，并执行loginctl enable-linger $USER使其在登出后存活（与 Service & daemon 中的 lingering 说明一致）。
WSL2。现代 WSL2 可运行 systemd（/etc/wsl.conf中[boot] systemd=true，然后wsl --shutdown），因此这套 quadlet 模式可以直接在 WSL 发行版内使用，无需 Windows 专属方言。

容器内配置

镜像期望配置位于/zeroclaw-data/.zeroclaw/。可以把本地配置挂载进去：

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

对容器内工作负载，应把每个providers.models.<type>.<alias>的uri设为容器可达的地址（例如宿主机上运行 Docker Desktop 时，Ollama 用http://host.docker.internal:11434）。仓库的开发模板 dev/config.template.toml 正是这种写法：[providers.models.ollama.default]的uri指向http://host.docker.internal:11434，workspace 指向/zeroclaw-data/workspace。

通用的 env 覆盖机制可以不编辑配置文件就在运行时设置同一字段。自 V0.8.0 起，覆盖语法是 schema-mirror：ZEROCLAW_<dotted_path_with_double_underscores>=<value>，每个__是路径分隔符，与 TOML 配置一一对应；旧的PROVIDER、ZEROCLAW_MODEL、ANTHROPIC_API_KEY、API_KEY等回退已被移除。例如：

docker run -e ZEROCLAW_providers__models__anthropic__default__api_key=sk-ant-... ...

具体 provider 字段的覆盖写法见 Providers 容器友好覆盖。

轮询型通道（Telegram、邮件）：开箱即用

主动外发的通道不需要任何特殊容器配置。Telegram 轮询、IMAP、MQTT、Nostr relay 都是拉取模式，容器只需要出站网络。

接收 webhook 的通道：需要入站

Discord、Slack、GitHub 及大多数 webhook 通道需要入站 HTTP，两种方式：

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

隧道通过顶层[tunnel]的tunnel_provider（env 覆盖变量ZEROCLAW_tunnel__tunnel_provider）配置为受支持的 provider 之一，并填写对应的tunnel.*块。从配置 schema 源码 crates/zeroclaw-config/src/schema.rs 可以看到，tunnel_provider支持cloudflare、tailscale、ngrok、openvpn、custom五类，每类有独立的配置块。生成的公网 URL 就是 webhook 发送方应指向的地址。

Kubernetes

仓库在 deploy-k8s/ 提供示例 manifest（面向 OpenShift，vanilla K8s 下把Route换成 Ingress 即可）。典型 Deployment 片段：

apiVersion: apps/v1 kind: Deployment metadata: name: zeroclaw spec: replicas: 1 strategy: type: Recreate # ZeroClaw 每个 workspace 单实例 template: spec: containers: - name: zeroclaw image: ghcr.io/zeroclaw-labs/zeroclaw:v0.7.5 ports: - containerPort: 42617 volumeMounts: - name: data mountPath: /zeroclaw-data # `containerPort` 不发布到宿主机；暴露由 Service 或 Ingress 决定。 # 若挂载 localhost 默认配置，gateway.host 与 # gateway.allow_public_bind 需成对覆盖。 volumes: - name: data persistentVolumeClaim: claimName: zeroclaw-data

仓库的完整示例 deploy-k8s/deployment-sample.yaml 还包含生产化细节：/health端点的 liveness/readiness 探针、64Mi/512Mi 与 250m/2 的资源请求与限制、非 root 且只读根文件系统的securityContext（drop ALL capabilities、RuntimeDefault seccomp），以及通过 ConfigMap 只读挂载config.toml。

扩展：ZeroClaw 对每个 workspace 是单写者。不要水平扩缩；每个 agent 只跑一个实例。注意示例中state/workspace卷默认是emptyDir，agent 记忆与对话历史不会跨 Pod 重启保留，生产环境应替换为 PVC。

登出后重新认证

在容器中运行时，若从 Web UI 登出，现有 paircode 会失效。生成新的即可重新登录：

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

Compose 部署则改用：

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

常见坑（Gotchas）

macOS 主机名特性（Docker Desktop、colima、Rancher Desktop）。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。
宿主机侧服务。若 provider 是宿主机上的 Ollama，Docker Desktop 下uri = "http://host.docker.internal:11434"（位于[providers.models.ollama.<alias>]）即可；Linux Docker 上可能需要--add-host=host.docker.internal:host-gateway。
记忆持久化。Agent 记忆（SQLitebrain.db）位于配置目录下/zeroclaw-data/.zeroclaw/agents/<alias>/workspace/memory/，共享实例数据库在/zeroclaw-data/data/。挂载/zeroclaw-data即可持久化全部内容；不挂卷则每次重启丢失对话历史。
绑定挂载/zeroclaw-data。宿主绑定挂载会替换整个镜像目录，包括默认配置（以及早先版本的 dashboard 包）。dashboard 现安装在挂载点之外的/usr/share/zeroclawlabs/web/dist，因此绑定挂载不再遮蔽它。首次运行挂载空目录即可，容器会引导全新配置，网关从镜像路径自动发现 dashboard。
默认不直通硬件。GPIO / USB 需要显式--device参数（如--device /dev/ttyUSB0），且容器用户需要与dialout/gpio组匹配的 GID。