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/zeroclawZeroClaw 官方支持在 Docker、Podman、Kubernetes 及任意 OCI 运行时中以容器方式运行。本篇基于仓库中的容器部署文档与配套 Dockerfile、Compose、K8s 示例源码完整覆盖官方镜像选择、最小运行、TUI 终端接入、Compose 网络与安全边界配置、Alpine 本地构建、Podman quadlet 服务化以及 Kubernetes 部署等场景读完后可在宿主机、Linux 服务器或容器集群中完成一次可复制的容器化部署。官方镜像镜像在每个 stable 版本发布时推送至 GitHub Container Registryghcr.io提供三类 tagTag说明ghcr.io/zeroclaw-labs/zeroclaw:latest最新 stable 版本基于 distrolessghcr.io/zeroclaw-labs/zeroclaw:v0.7.5固定版本示例生产环境建议固定 tagghcr.io/zeroclaw-labs/zeroclaw:debianDebian 基础镜像体积更大、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 --formatexit-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 --buildAlpine 镜像沿用与其它官方镜像一致的约定/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运行 zerocodeTUI镜像同时携带了 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:debianzerocode 需要连接一个正在运行的 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__host0.0.0.0 - ZEROCLAW_gateway__allow_public_bindtrue完整示例还包含 provider API key 注入如ZEROCLAW_providers__models__openrouter__default__api_key、资源限制cpus 2 / memory 512M以及与健康检查一致的healthcheck段可按需取用。容器启动后执行 quickstartdocker compose exec zeroclaw zeroclaw quickstart为什么必须同时固定 host 与 allow_public_bindCompose 应显式同时设置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.0gateway.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__host0.0.0.0 - ZEROCLAW_gateway__allow_public_bindtrue healthcheck: test: [CMD, zeroclaw, status, --formatexit-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:映射仍是限制宿主机侧可达性的边界。macOSOrbStack 与 ColimamacOS 没有原生 Linux 内核因此所有方案Docker Desktop、Podman、OrbStack、Colima都在轻量 Linux VM 中运行容器。对 Mac 开发机值得比较的两个原生 VM 是 OrbStack 和 Colima容器侧都使用上面的docker run/Compose 命令OrbStackColima引擎自研调优 Linux VMApple Silicon 优化Lima VM containerd/Docker许可商业freemium个人免费MIT底层 Lima 为 Apache 2.0界面GUI 应用 CLICLI 优先colima start/stop可脚本化适用场景少折腾、体验顺滑全开源、配置即代码# OrbStack提供 docker CLI brew install --cask orbstack # Colimadocker 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] DescriptionZeroClaw agent runtime Afternetwork-online.target Wantsnetwork-online.target [Container] # 生产环境固定版本:latest 是 distroless无 shell——需要 exec 时用 :debian Imageghcr.io/zeroclaw-labs/zeroclaw:latest ContainerNamezeroclaw PublishPort127.0.0.1:42617:42617 Volumezeroclaw-data:/zeroclaw-data # 仅发布到宿主机 loopback若要服务其他主机去掉 127.0.0.1: 前缀 # 并在之前开启配对或隧道。若挂载 localhost 默认配置 # gateway.host 与 gateway.allow_public_bind 需成对覆盖。 # 可选滚动升级路径——(重新)启动时重新拉取新镜像并纳入 podman auto-update Pullnewer AutoUpdateregistry [Service] Restartalways [Install] WantedBymulti-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 或 digestImageghcr.io/zeroclaw-labs/zeroclaw:v0.7.5或...sha256:...获得可复现、可审计的部署升级就是提交到.container文件里一次可评审的 tag 变更PullnewerAutoUpdateregistry则提供由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] systemdtrue然后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:11434workspace 指向/zeroclaw-data/workspace。通用的 env 覆盖机制可以不编辑配置文件就在运行时设置同一字段。自 V0.8.0 起覆盖语法是 schema-mirrorZEROCLAW_dotted_path_with_double_underscoresvalue每个__是路径分隔符与 TOML 配置一一对应旧的PROVIDER、ZEROCLAW_MODEL、ANTHROPIC_API_KEY、API_KEY等回退已被移除。例如docker run -e ZEROCLAW_providers__models__anthropic__default__api_keysk-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_providerenv 覆盖变量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面向 OpenShiftvanilla 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 且只读根文件系统的securityContextdrop ALL capabilities、RuntimeDefault seccomp以及通过 ConfigMap 只读挂载config.toml。扩展ZeroClaw 对每个 workspace 是单写者。不要水平扩缩每个 agent 只跑一个实例。注意示例中state/workspace卷默认是emptyDiragent 记忆与对话历史不会跨 Pod 重启保留生产环境应替换为 PVC。登出后重新认证在容器中运行时若从 Web UI 登出现有 paircode 会失效。生成新的即可重新登录docker exec -it zeroclaw zeroclaw gateway get-paircode --newCompose 部署则改用docker compose exec zeroclaw zeroclaw gateway get-paircode --new常见坑GotchasmacOS 主机名特性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 是宿主机上的 OllamaDocker Desktop 下uri http://host.docker.internal:11434位于[providers.models.ollama.alias]即可Linux Docker 上可能需要--add-hosthost.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。延伸阅读服务管理裸机 systemd 服务方式网络部署隧道与反向代理的完整方案Provider 配置provider 字段与容器友好覆盖语法。【免费下载链接】zeroclawFast, small, and fully autonomous AI personal assistant infrastructure, any OS, any platform — deploy anywhere, swap anything 项目地址: https://gitcode.com/gh_mirrors/ze/zeroclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 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/zeroclawZeroClaw 官方支持在 Docker、Podman、Kubernetes 及任意 OCI 运行时中以容器方式运行。本篇基于仓库中的容器部署文档与配套 Dockerfile、Compose、K8s 示例源码完整覆盖官方镜像选择、最小运行、TUI 终端接入、Compose 网络与安全边界配置、Alpine 本地构建、Podman quadlet 服务化以及 Kubernetes 部署等场景读完后可在宿主机、Linux 服务器或容器集群中完成一次可复制的容器化部署。官方镜像镜像在每个 stable 版本发布时推送至 GitHub Container Registryghcr.io提供三类 tagTag说明ghcr.io/zeroclaw-labs/zeroclaw:latest最新 stable 版本基于 distrolessghcr.io/zeroclaw-labs/zeroclaw:v0.7.5固定版本示例生产环境建议固定 tagghcr.io/zeroclaw-labs/zeroclaw:debianDebian 基础镜像体积更大、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 --formatexit-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 --buildAlpine 镜像沿用与其它官方镜像一致的约定/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运行 zerocodeTUI镜像同时携带了 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:debianzerocode 需要连接一个正在运行的 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__host0.0.0.0 - ZEROCLAW_gateway__allow_public_bindtrue完整示例还包含 provider API key 注入如ZEROCLAW_providers__models__openrouter__default__api_key、资源限制cpus 2 / memory 512M以及与健康检查一致的healthcheck段可按需取用。容器启动后执行 quickstartdocker compose exec zeroclaw zeroclaw quickstart为什么必须同时固定 host 与 allow_public_bindCompose 应显式同时设置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.0gateway.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__host0.0.0.0 - ZEROCLAW_gateway__allow_public_bindtrue healthcheck: test: [CMD, zeroclaw, status, --formatexit-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:映射仍是限制宿主机侧可达性的边界。macOSOrbStack 与 ColimamacOS 没有原生 Linux 内核因此所有方案Docker Desktop、Podman、OrbStack、Colima都在轻量 Linux VM 中运行容器。对 Mac 开发机值得比较的两个原生 VM 是 OrbStack 和 Colima容器侧都使用上面的docker run/Compose 命令OrbStackColima引擎自研调优 Linux VMApple Silicon 优化Lima VM containerd/Docker许可商业freemium个人免费MIT底层 Lima 为 Apache 2.0界面GUI 应用 CLICLI 优先colima start/stop可脚本化适用场景少折腾、体验顺滑全开源、配置即代码# OrbStack提供 docker CLI brew install --cask orbstack # Colimadocker 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] DescriptionZeroClaw agent runtime Afternetwork-online.target Wantsnetwork-online.target [Container] # 生产环境固定版本:latest 是 distroless无 shell——需要 exec 时用 :debian Imageghcr.io/zeroclaw-labs/zeroclaw:latest ContainerNamezeroclaw PublishPort127.0.0.1:42617:42617 Volumezeroclaw-data:/zeroclaw-data # 仅发布到宿主机 loopback若要服务其他主机去掉 127.0.0.1: 前缀 # 并在之前开启配对或隧道。若挂载 localhost 默认配置 # gateway.host 与 gateway.allow_public_bind 需成对覆盖。 # 可选滚动升级路径——(重新)启动时重新拉取新镜像并纳入 podman auto-update Pullnewer AutoUpdateregistry [Service] Restartalways [Install] WantedBymulti-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 或 digestImageghcr.io/zeroclaw-labs/zeroclaw:v0.7.5或...sha256:...获得可复现、可审计的部署升级就是提交到.container文件里一次可评审的 tag 变更PullnewerAutoUpdateregistry则提供由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] systemdtrue然后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:11434workspace 指向/zeroclaw-data/workspace。通用的 env 覆盖机制可以不编辑配置文件就在运行时设置同一字段。自 V0.8.0 起覆盖语法是 schema-mirrorZEROCLAW_dotted_path_with_double_underscoresvalue每个__是路径分隔符与 TOML 配置一一对应旧的PROVIDER、ZEROCLAW_MODEL、ANTHROPIC_API_KEY、API_KEY等回退已被移除。例如docker run -e ZEROCLAW_providers__models__anthropic__default__api_keysk-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_providerenv 覆盖变量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面向 OpenShiftvanilla 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 且只读根文件系统的securityContextdrop ALL capabilities、RuntimeDefault seccomp以及通过 ConfigMap 只读挂载config.toml。扩展ZeroClaw 对每个 workspace 是单写者。不要水平扩缩每个 agent 只跑一个实例。注意示例中state/workspace卷默认是emptyDiragent 记忆与对话历史不会跨 Pod 重启保留生产环境应替换为 PVC。登出后重新认证在容器中运行时若从 Web UI 登出现有 paircode 会失效。生成新的即可重新登录docker exec -it zeroclaw zeroclaw gateway get-paircode --newCompose 部署则改用docker compose exec zeroclaw zeroclaw gateway get-paircode --new常见坑GotchasmacOS 主机名特性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 是宿主机上的 OllamaDocker Desktop 下uri http://host.docker.internal:11434位于[providers.models.ollama.alias]即可Linux Docker 上可能需要--add-hosthost.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。延伸阅读服务管理裸机 systemd 服务方式网络部署隧道与反向代理的完整方案Provider 配置provider 字段与容器友好覆盖语法。【免费下载链接】zeroclawFast, small, and fully autonomous AI personal assistant infrastructure, any OS, any platform — deploy anywhere, swap anything 项目地址: https://gitcode.com/gh_mirrors/ze/zeroclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考