操作: 概要

本番環境で ZeroClaw を実行する方法。運用面は意図的に小さく保たれています: 1 つのバイナリ、1 つの設定ファイル、および少数のランタイムストアを持つ 1 つのインストールルート。ほとんどの「運用」は「systemd と journald」です。

このセクションでは、以下を扱います：

Service & daemon: プロセスを存続させる
ログと可観測性: エージェントが行った処理の確認
コスト追跡: トークン消費量とモデルごとのコスト
トラブルシューティング: 問題が発生したとき
ネットワークデプロイ: ゲートウェイの公開、トンネル、リバースプロキシ

デプロイメントの形状

一般的な常時稼働の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）、ログの出力先はデフォルトでプラットフォームネイティブです。ストアマップの全体については、ランタイム状態と永続化を参照してください。

監視対象

重要な4つのシグナル：

1. サービスの死活監視

プロセスは実行されていますか？

Linux

systemctl --user is-active zeroclaw

macOS

launchctl list | grep -c com.zeroclaw.daemon

Windows

schtasks /Query /TN "ZeroClaw Daemon" /FO LIST | findstr Status

繰り返し終了する場合は、トラブルシューティング → デーモンが再起動し続けるを確認してください。

2. チャネルとコンポーネントの正常性

ゲートウェイは /health で公開のコンポーネント稼働状態スナップショットを提供します。コンポーネントの詳細なエラーは、認証が必要な診断ルート /api/health と /api/status で引き続き確認できます。チャネル、プロバイダー、その他の長時間稼働するコンポーネントは、起動時、OK を報告したとき、またはエラーを報告したときに、自身を components マップに登録します。

sh

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

{
  「status」: "ok",
  paired: true,
  require_pairing: true,
  ランタイム: {
    pid: 4821,
    "updated_at": 2026-06-08T09:00:00+00:00,
    uptime_seconds: 3600,
    components: {
      "channel:telegram": {「status」: "ok", "updated_at": …, "last_ok": …, "restart_count": 0},
      channel:matrix:   {「status」: 「エラー」, "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 を利用してください。

チャネルは、リスナーが起動しただけでなく、サービスに実際に到達できることを確認するまで、last_ok が null の starting と表示されます。一部のチャネルは、サービスとのやり取り中に観測した内容を報告します。そのため、リスナーは稼働していても一度も通信が完了していない場合は、ok ではなく starting のままです。呼び出しが失敗している場合は error と表示されます。以前 ok を報告していたエイリアスでチャネルが再起動すると、そのチャネル自身の通信が成功するまで starting に戻ります。プラグインチャネル（channel:plugin.<alias>）は、プラグインのポーリングが失敗すると error と表示されます。プラグインがヘルスチェックを実装している場合は、そのチェックに従います。ホストはこのチェックを約30秒ごとに要求します。チェックの対象範囲はプラグインに委ねられます。そのようなシグナルを提供しないチャネルは、リスナーが動作している間は ok とマークされます。

3. プロバイダーの信頼性

プロバイダーは、同じ /health スナップショット内のコンポーネントとして表示されます。リクエストレベルのシグナル（レイテンシ、成功率、トークン数）については、/metrics（下記参照）をスクレイプし、zeroclaw_llm_requests_total と zeroclaw_request_latency_seconds を読み取ってください。

4. ツールコールのボリュームとメトリクス

/metrics は Prometheus テキスト形式の出力を返します。設定で [observability] backend = "prometheus" が必要です。これがない場合、エンドポイントは「backend not enabled」のヒントを1行返します。

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 があります。

容量

1つのZeroClawインスタンスは以下を処理できます：

すべてのチャンネルで複数の同時会話
プロバイダーとサンドボックスが許容する速度でツール呼び出し
長時間実行されるエージェントのループ（20回以上の呼び出しを含むツールチェーン）

ワークスペースごとに1つのインスタンスを実行して水平方向にスケールします。同じワークスペースで2つのデーモンを実行しようとしないでください。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 リリースまたは Discord の #releases チャンネル：Contributing → Communication を参照）を購読してください。一般的な更新頻度：

リリースノートを読む
~/.zeroclaw/ をバックアップする
バイナリを更新する（brew upgrade、ブートストラップの再実行、または cargo install --force）
zeroclaw service restart
/health エンドポイントが、どのコンポーネントも error 状態でなく status: "ok" を報告することを確認します

新しいバージョンで設定の移行が必要な場合、起動ログに警告が表示され、バイナリは通常自動的に移行を行います。アップグレード後に値を確認するには zeroclaw config list を、保留中のスキーマ移行を手動で適用するには zeroclaw config migrate を使用してください。

ZeroClaw Docs