操作：概述

如何在生产环境中运行 ZeroClaw。其表面故意保持得很小：一个二进制文件、一个配置文件，以及一个包含少量运行时存储的安装根目录。大多数“运维”就是“systemd 和 journald”。

本节涵盖：

服务与守护进程：保持进程持续运行
日志与可观测性：查看智能体执行的操作
成本跟踪：令牌花费和每个模型的成本
故障排查：当出现问题时
网络部署：暴露网关、隧道、反向代理

部署的形状

典型的始终开启的 ZeroClaw 安装配置如下：

zeroclaw service                          — systemd / launchctl / Windows Service
└── zeroclaw daemon                       — the single long-running process
    ├── gateway listener  :42617          — REST / WebSocket / webhook intake
    ├── channel pollers                   — Telegram, IMAP, Nostr relays (outbound poll)
    ├── channel listeners                 — Discord / Slack / Matrix / WebSocket (inbound stream)
    ├── cron scheduler                    — scheduled SOPs and jobs
    └── agent loop  (one per session)     — provider call + tool execution
                                            ▲ driven by any listener, poller,
                                              gateway request, or cron fire

on disk (everything but the binary can move)
├── ~/.zeroclaw/config.toml               — configuration
├── ~/.zeroclaw/.secret_key               — master key for the encrypted secrets store
└── ~/.zeroclaw/data/                     — runtime state
    ├── memory/                           — agent memory backend
    ├── sessions/                         — per-session conversation stores
    └── state/                            — scheduler, cost, health, misc runtime state

logs                                      — journald / launchctl / Windows Event Log (platform-native)

除二进制文件外，其他内容都可以移动。数据目录默认是 ~/.zeroclaw/data/（仍然接受旧的 ~/.zeroclaw/workspace/ 名称）；配置路径按环境解析（Homebrew、bootstrap 或 XDG），日志目标默认使用平台原生位置。完整的存储映射请参见 Runtime state and persistence。

需要监控的内容

四个信号很重要：

2. 通道与组件运行状况

网关在 /health（公开，不含敏感信息）和 /api/health（需身份验证）处提供组件健康状况快照。通道、提供程序及其他长时间运行的组件会在启动、报告 OK 或报告错误时，将自身注册到 components 映射中。

sh

curl -s http://localhost:42617/health | jq

{
  状态: “好的”,
  paired: true,
  require_pairing: true,
  runtime: {
    "pid": 4821,
    "updated_at": 2026-06-08T09:00:00+00:00,
    uptime_seconds: 3600,
    组件: {
      channel:telegram: {状态: “好的”, "updated_at": …, "last_ok": …, "last_error": null, "restart_count": 0},
      channel:matrix:   {状态: 错误, "updated_at": …, "last_ok": …, "last_error": "401 未授权", "restart_count": 3}
    }
  }
}

每个组件都包含 status（starting / ok / error）、last_ok、last_error 和 restart_count。请留意 status: "error" 以及不断攀升的 restart_count。

通道会显示为 starting，且 last_ok 为 null，直到确认能够实际访问其服务，而不只是监听器已启动。某些通道会报告其与服务通信时观察到的情况，因此，正在运行但从未完成过一次交互的监听器会保持 starting 而不是 ok，而调用失败的监听器则显示为 error。以此前报告为 ok 的别名重启的通道会恢复为 starting，直到完成一次自身成功的交互。无法提供此类信号的通道，只要其监听器在运行，就会标记为 ok。

3. 提供商可靠性

提供方在同一份 /health 快照中以组件形式呈现。如需请求级别的信号（延迟、成功率、token 计数），请抓取 /metrics（见下文）并读取 zeroclaw_llm_requests_total 和 zeroclaw_request_latency_seconds。

4. 工具调用量和指标

/metrics 返回 Prometheus 文本格式的指标数据。它需要在配置中设置 [observability] backend = "prometheus"；若未设置，该端点会返回一行 “backend not enabled” 提示。

sh

curl -s http://localhost:42617/metrics

zeroclaw_tool_calls_total{success="true",tool="shell"} 342
zeroclaw_tool_calls_total{success="false",tool="shell"} 6
zeroclaw_tool_calls_total{success="true",tool="file_write"} 89

zeroclaw_tool_calls_total 计数器按 tool 和 success（"true"/"false"）进行标记。某个工具的 success="false" 计数持续上升时值得关注：可能是策略拦截、代理行为异常，或工具不稳定。其他有用的指标序列包括 zeroclaw_llm_requests_total、zeroclaw_errors_total、zeroclaw_active_sessions 以及 zeroclaw_tokens_input_total / zeroclaw_tokens_output_total。

容量

单个 ZeroClaw 实例可以处理：

跨所有频道的多个并发对话
以提供商和沙箱允许的任意速率进行工具调用
长时间运行的智能体循环（包含 20 多次调用的工具链）

通过为每个工作区运行一个实例来横向扩展。不要尝试在同一工作区上运行两个守护进程：SQLite 的单写入者模型会导致锁竞争，并最终造成数据损坏。

对于多租户托管，请参阅 #2765 中的提案（已关闭、历史记录，进程内多工作区路由的架构）。

备份

需要备份的内容：

~/.zeroclaw/data/memory/*.db：SQLite 对话记忆（brain.db，以及 audit.db）
~/.zeroclaw/data/sessions/：持久化的会话状态
~/.zeroclaw/.secret_key：加密机密存储的主密钥（如果使用）。没有它，配置中的加密机密将无法恢复。

一条简单的 tar czf zeroclaw-$(date +%F).tar.gz ~/.zeroclaw 命令即可覆盖所有内容。对于增量备份，Restic、borg 或 Duplicacy 都能很好地工作。

~/.zeroclaw/data/memory/response_cache.db 是可重新生成的 LLM 响应缓存；将其包含在整目录备份中或为节省空间而排除均无妨。工具回执是会话历史中的带内 HMAC 令牌（参见工具回执），并非磁盘上的日志，因此无需为其单独备份。

更新

该服务不会自动更新。请订阅发布动态（GitHub releases 或 Discord #releases 频道：参见 Contributing → Communication）。典型的更新频率：

阅读发布说明
备份 ~/.zeroclaw/
更新二进制文件（brew upgrade、重新运行引导程序，或 cargo install --force）
zeroclaw service restart
验证 /health 端点报告 status: "ok" 且没有任何组件处于 error 状态

如果新版本需要配置迁移，启动日志会发出警告，并且二进制文件通常会自动进行迁移。升级后，请检查 zeroclaw config list 以抽查配置值，并使用 zeroclaw config migrate 手动应用任何待处理的架构迁移。

ZeroClaw Docs

操作：概述

部署的形状

需要监控的内容

1. 服务存活

Linux

macOS

Windows

2. 通道与组件运行状况

sh

3. 提供商可靠性

4. 工具调用量和指标

sh

容量

备份

更新

另见

Keyboard shortcuts

ZeroClaw Docs