操作：概述

如何在生产环境中运行 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 和 /api/status 获取。通道、提供方及其他长期运行的组件在启动、报告正常或出错时，会将自身注册到 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": …, "restart_count": 0},
      channel:matrix:   {状态: 错误, "updated_at": …, "last_ok": …, "restart_count": 3}
    }
  }
}

公开的 /health 响应中，每个组件都包含 status（starting / ok / error）、updated_at、last_ok 和 restart_count。请注意 status: "error" 以及持续增长的 restart_count。公开响应不包含 last_error；如需查看组件的详细错误信息，请使用已配置 API 认证的 /api/health 或 /api/status。

在通道确认能够真正连接到其服务之前（而不仅仅是监听器启动），通道显示为 starting，且 last_ok 为 null。部分通道会报告其与服务通信时的观察结果，因此，监听器虽在运行但从未完成一次交互的，仍保持 starting 而非 ok；调用持续失败的，则显示为 error。以曾报告过 ok 的别名重新启动的通道，会回到 starting，直到其自身产生一次成功的交互。插件通道（channel:plugin.<alias>）在插件轮询失败时显示为 error；如果插件实现了健康检查，则跟随该检查的结果。宿主大约每 30 秒请求一次该检查，检查的覆盖范围由插件自行决定。不提供此类信号的通道，只要其监听器在运行，就会被标记为 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