サービスとデーモン

このページは Setup → Service management の運用面の補足です。あちらのページではサービスのインストールとアンインストールについて説明しています。このページでは、サービスの実行について説明します。チューニング、リソース制限、グレースフルリスタート、マルチワークスペース構成などです。

ユーザーとシステムの範囲の選択

デスクトップLinuxでは、ユーザーサービスがログアウト後も継続して動作するように、ユーザーサービスのlingeringを有効にしてください。

loginctl enable-linger $USER

ユーザースコープのsystemdサービスは、最後のセッションが終了すると停止します。

再起動動作

インストールされた systemd ユーザーユニット (~/.config/systemd/user/zeroclaw.service) は以下を使用します:

Restart=always
RestartSec=3

systemd は終了時に毎回 3 秒のバックオフをおいてデーモンを再起動します。終了コードの許可リストはないため、不正な設定で即座に失敗するデーモンはフラッピングを起こします。サービスがあきらめるのを当てにするのではなく、設定を修正して systemctl --user restart zeroclaw を実行してください。

macOS では、LaunchAgent（~/Library/LaunchAgents/com.zeroclaw.daemon.plist）が RunAtLoad と KeepAlive を true に設定するため、launchd はデーモンを実行し続け、終了するたびに再起動します。

Windows では、zeroclaw service install は LIMITED 実行レベルで ONLOGON をトリガーとするタスク スケジューラ タスクを登録します。これはログオン時にデーモンを起動しますが、障害時の自動再起動ポリシーは追加しません。

グレースフルシャットダウン

Unix では、デーモンは SIGINT と SIGTERM をトラップします。Windows では Ctrl+C (ctrl_c) をトラップします。これらのいずれかによってクリーンシャットダウンがトリガーされます。デーモンはチャネルサーバーとゲートウェイリスナーを停止して終了します。

SIGHUP は無視されます（デーモンは実行され続けます）。/admin/reload エンドポイント経由でリクエストされたリロードは、終了するのではなくデーモンループをその場で再起動します。

会話メモリとセッション状態は、動作中にSQLiteへ逐次書き込まれ、シャットダウン時までバッファリングされることはないため、正常な停止はフラッシュ処理に依存しません。ツールのレシートは、別途ディスク上に記録されるログではなく、会話内のインバンドHMACトークンです。強制的なSIGKILLは正常なチャネルのteardownをスキップしますが、すでにコミット済みのメモリを破損させることはありません。失われるのは、書き込み途中だったエージェントのターンのみです。

デバッグ用の手動起動

サービスをスキップしてデーモンを直接実行する:

zeroclaw service stop     # サービスが実行中の場合はゲートウェイポートを解放する
zeroclaw daemon

zeroclaw daemon はフォアグラウンドで実行され、stderr にログを出力します。これはサービスが実行するプロセスと同じで、サービスハーネスが付いていないだけです。次のような場合に便利です。

• サービスが飲み込んでしまう起動失敗の診断
• gdb / lldb 上で実行中
• コミットする前に設定変更をテストする

Ctrl-C で終了します。SIGTERM と同じグレースフルシャットダウンのセマンティクスです。

リソース制限

Linux: systemd

ドロップインに追加する:

systemctl --user edit zeroclaw.service

[Service]
MemoryMax=2G
CPUQuota=200%            # two cores
LimitNOFILE=16384        # if opening many channel sockets

再読み込みして再起動:

systemctl --user daemon-reload
systemctl --user restart zeroclaw

macOS: launchd

~/Library/LaunchAgents/com.zeroclaw.daemon.plist を編集します:

<key>SoftResourceLimits</key>
<dict>
  <key>NumberOfFiles</key>
  <integer>16384</integer>
</dict>

plistをアンロードしてロードし、変更を適用する：

launchctl unload ~/Library/LaunchAgents/com.zeroclaw.daemon.plist
launchctl load ~/Library/LaunchAgents/com.zeroclaw.daemon.plist

Docker

Compose:

サービス:
  ゼロクロー:
    画像: ghcr.io/zeroclaw-labs/zeroclaw:latest
    `mem_limit`: 2G
    cpus: 2.0
    ulimits:
      nofile: 16384

複数のワークスペースを実行する

各 ZeroClaw デーモンは、1 つの設定ディレクトリ（その中に data/ ディレクトリを含む）を所有します。2 つを並行して実行するには、--config-dir（または ZEROCLAW_CONFIG_DIR 環境変数）を使って、それぞれに専用の設定ディレクトリを指定します。

zeroclaw --config-dir ~/.zeroclaw-home daemon
zeroclaw --config-dir ~/.zeroclaw-work daemon

各インスタンスは、それぞれ独自の設定、独自の data/（メモリ、セッション）、独自のゲートウェイポート（設定ごとに指定）、独自のチャネルバインディングを読み込みます。メモリは分離されたままで、ある設定ディレクトリ内の Telegram ボットは他のものを認識しません。

zeroclaw service install は常にデフォルトの設定ディレクトリを指す単一のユニットをインストールします。インスタンスに名前を付けたりパラメーター化したりするフラグはありません。複数のインスタンスを永続的なサービスとして実行するには、2つ目のユニットファイルを手動で作成し（~/.config/systemd/user/zeroclaw.service を新しい名前にコピー）、その ExecStart で --config-dir <dir> を渡すようにしてから、個別に有効化してください。

2つのデーモンを同じ設定ディレクトリに向けないでください。SQLite はシングルライターであるため、2つ目は起動時に失敗します。

再起動とクラッシュの観察

# Linux
journalctl --user -u zeroclaw --since 1日前 | grep -E 「開始|停止|失敗」

# macOS
log show --predicate 'process == "zeroclaw"' --last 1d | grep -E 'start|stop|error'

再起動が繰り返される場合は、デバッグログを有効にして（unit ファイルの Environment= 経由で RUST_LOG=debug を設定）、もう一度クラッシュを発生させて完全なトレースをキャプチャしてください。

関連項目も参照してください

• セットアップ → サービス管理
• ログと観測性
• トラブルシューティング