運用
サーバーの起動と停止
Web サーバーは job_runner・hitl-worker と同様に LaunchAgent で常駐させます。
初回のみ make install-all(Web サーバーだけなら make install-web)で登録します。
make start / make stop # job_runner
make restart # job_runner + Web サーバー + hitl-worker を再起動
make restart-web # Web サーバーのみ再起動(コード変更時)
make status-web # Web サーバーの状態
make logs-web / make errorlogs-web
make reload-web # plist 再読み込み(設定変更時)
メッセージの読み上げで ローカルの MLX エンジン(tts.provider: mlx_audio) を
使う場合だけ、音声エンジンも常駐させます
(AIエージェント)。
openai_compatible を使う場合、MLX のセットアップと LaunchAgent は不要です。
make install-all と通常の make restart は MLX LaunchAgent を登録・再起動しません。
make setup-tts # 初回のみ(mlx-audio の venv・辞書)
make install-tts # MLX を使う場合の初回登録
make restart-tts # モデル・設定変更時
make status-tts # 状態
make logs-tts / make errorlogs-tts
MLX の音声エンジンは 127.0.0.1:8768 でのみ待ち受け、認証を持ちません。tailnet や
リバースプロキシの背後に置かないでください。停止していても Web サーバーは動作し、
読み上げボタンを押したときだけエラーになります。
OpenAI 互換プロバイダを使う場合は、接続先・model・voice を
設定の YAML に、TTS_API_KEY を .env に
置きます。非 loopback は HTTPS が必須です。
フロントエンドを変更した場合は make npm-build で dist を更新してから
make restart-web を実行します。
開発時にフォアグラウンドで動かす場合のみ(人間の端末専用):
make serve # 起動(uv run -m obsidian_ai_hub --serve)
make serve-debug # 自動リロード + 詳細ログ
make serve はエージェント向きではありませんmake serve / make serve-restart は端末を占有するフォアグラウンドのプロセスです。
エージェントのシェルから起動してもプロセスが残らないため、常駐確認には
LaunchAgent の make restart-web を使ってください。
常駐ワーカー
次のワーカーは Web サーバーの FastAPI lifespan に同居します。
- Task worker — Task の計画・実行。
- Workflow worker — ワークフロー Run の実行。
- Agent / Coding worker — 各実行の処理。
Web サーバー停止中は新しい計画・実行が進まず、Task や Run はキューに残ります。
停止時に running だったものは interrupted になり、自動再実行されません。
再開後、Task は 再計画、Run は 再開 で明示的に戻してください。
HITL は別の常駐ワーカーで動かします。
make restart-hitl-worker
make logs-hitl-worker / make errorlogs-hitl-worker
ジョブ実行
- job runner は LaunchAgent から 60 秒ごとに起動します。
- 手動で 1 サイクル実行するには
uv run -m obsidian_ai_hub.job_runnerを使います。 - 終了時や再起動後は、未実行のワンショットジョブが
interruptedとして扱われ、自動再試行されません。 - 定期・ワンショット Job は公開 Workflow を対象にでき、発火ごとに Workflow Run を 1 件作成します。作成された Run の実行は Web サーバーの Workflow worker が担います。
- 発火枠は
workflow_schedule_dispatchesに記録され、runner 再起動でも Run は二重作成されません。承認待ち Run は自動失効しないため、必要に応じて Run 詳細で取消するか Job を無効化します。
データの保存先
| データ | 既定の場所 |
|---|---|
| メモリ / Task / ワークフロー / 実行ログ | ~/.config/obsidian-ai-hub/memory.sqlite3 |
| ヘルスケア | ~/.config/obsidian-ai-hub/healthcare.sqlite3 |
| ジョブの最終実行時刻 | jobs/last_run.json |
| Vault 検索インデックス | vault_index.sqlite_path / chroma_path の設定値 |
保持期間
- 終端 Task・Plan・Event — 終端化から 30 日後に削除。
- 終端 Workflow Run・Node・Activation・Event — 30 日後に削除。
- ワンショットジョブの終端履歴 — 30 日後に削除。
- LINE webhook / 実行ログ —
--cleanup-line-webhooks/--cleanup-execution-logsで 30 日より古いものを削除。 - 空の Web chat セッション —
--cleanup-execution-logs実行時に、タイトルが「新しい会話」で前日以前に作成され、メッセージがないものを削除。 - 一時会話セッション —
--cleanup-execution-logs実行時に、最終更新から 24 時間経過したものを削除(メッセージの有無を問わない)。
非終端のものは削除されません。
実行ログを見る
- 実行ログ → ログ(
/execution-logs/logs)— 過去 30 日の CLI 実行ログと LLM コール履歴(閲覧専用)。LLM 詳細では、そのコールで実際に送信されたシステムプロンプトとプロンプト全文を展開して確認できます(システムプロンプトは既定で折りたたみ。対象は新規に記録されたログのみ)。要求した Tool 名・引数・実行結果(状態、エラー、伏せ字済み JSON 等)も横断的に監査できます(1 tool call あたりの実行結果保存上限は 20,000 文字で、超過時は打ち切りが明示されます)。失敗した LLM コールには HTTP ステータス・リクエスト ID・試行回数・応答本文の要約([llm-diagnostics])が保存され、プロバイダへの問い合わせに使えます。 Workflow Run 詳細の Agent 子 Run からは、その Agent Run に帰属する LLM コールへ直接リンクできます(?llm_call_id=...)。帰属機能より前の Run と 30 日を過ぎたログにはリンクが表示されません。 - 実行ログ → ジョブ状態(
/execution-logs/job-states)— 定期・高頻度ジョブの最終確認・空振り・成功/スキップ/失敗。 - プロセス強制終了などで終了状態が記録されなかった実行は、スケジューラ起動時に
failed(例外種別StaleRunning)へ回収されます。長時間runningのまま残ることはありません(猶予はsystem_maintenance.stale_running_hours、既定 6 時間)。
ネットワークとセキュリティ
- API はすべて Bearer トークン認証を要求します。ループバックでも免除されません。
- 外部公開する場合は
--serve-hostで待ち受け、TLS をリバースプロキシ等で終端してください。 - 実行ログや HITL には機密情報が含まれうるため、公開範囲に注意してください。
テスト環境
ENV=test で本番データを触らずにコマンドを試せます。
テストを実行する場合は uv run pytest tests/ を使います。
tests/conftest.py が本番の .env を読み込まず、書き込み先を一時領域へ隔離します。