GhostClaw エージェント デバッグガイド

このガイドはエージェント実行システムのデバッグについて説明します。

アーキテクチャ概要

Host (macOS/Linux)
───────────────────────────────────────────────
src/index.ts                   agent-runner/
    │                               │
    │ spawns child process          │ runs Claude Agent SDK
    │ with env vars                 │ with MCP servers
    │                               │
    ├── GHOSTCLAW_GROUP_DIR ──> groups/{folder}/
    ├── GHOSTCLAW_IPC_DIR ───> data/ipc/{folder}/
    ├── GHOSTCLAW_GLOBAL_DIR > groups/global/
    ├── CLAUDE_CONFIG_DIR ───> data/sessions/{folder}/.claude/
    └── HOME ────────────────> (inherited, real home)

重要: エージェントはコンテナではなく、直接の Node.js 子プロセスとして実行されます。CLAUDE_CONFIG_DIR はグループごとのセッション分離を提供し、HOME は変更されないため、gh、Gmail OAuth などのツールが自然に認証情報を見つけることができます。

ログの場所

ログ	場所	内容
メインアプリログ	logs/ghostclaw.log	ルーティング、エージェント起動、スケジューリング
メインアプリエラー	logs/ghostclaw.error.log	ホスト側のエラー
エージェント実行ログ	groups/{folder}/logs/agent-*.log	実行ごと: 入力、stderr、stdout
Claude セッション	data/sessions/{folder}/.claude/projects/	Claude Code セッション履歴

デバッグログを有効にする

詳細な出力を得るために LOG_LEVEL=debug を設定します:

# 開発用
LOG_LEVEL=debug npm run dev

# launchd サービス (macOS) の場合、plist の EnvironmentVariables に追加:
<key>LOG_LEVEL</key>
<string>debug</string>
# systemd サービス (Linux) の場合、ユニットの [Service] セクションに追加:
# Environment=LOG_LEVEL=debug

デバッグレベルでは以下が表示されます:

• 完全な環境設定
• エージェントプロセス引数
• リアルタイムエージェント stderr

一般的な問題

1. 「Claude Code process exited with code 1」

groups/{folder}/logs/agent-*.log のエージェントログファイルを確認してください

一般的な原因:

認証がない

Invalid API key · Please run /login

修正: .env ファイルが OAuth トークンまたは API キーで存在することを確認します:

cat .env  # 以下のいずれかが表示されるべき:
# CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-...  (subscription)
# ANTHROPIC_API_KEY=sk-ant-api03-...        (pay-per-use)

2. 環境変数

シークレットは stdin を介してエージェントに渡され、ディスクに書き込まれることはありません。エージェントは以下を受け取ります:

• CLAUDE_CODE_OAUTH_TOKEN または ANTHROPIC_API_KEY
• ELEVENLABS_API_KEY、ELEVENLABS_VOICE_ID

GHOSTCLAW_* パス経由で設定された環境変数:

• GHOSTCLAW_GROUP_DIR — グループの作業ディレクトリ
• GHOSTCLAW_IPC_DIR — IPC 通信ディレクトリ
• GHOSTCLAW_GLOBAL_DIR — グローバル共有ディレクトリ
• CLAUDE_CONFIG_DIR — グループごとの Claude セッション分離

環境変数が正しいことを確認するには、エージェントログを確認してください (最初の数行に入力 JSON が表示されます)。

3. セッションが再開されない

セッションが再開されない場合 (毎回新しいセッション ID):

根本原因: SDK は $CLAUDE_CONFIG_DIR/projects/ でセッションを探します。各グループのセッションは data/sessions/{folder}/.claude/ に保存されます。

セッションが存在することを確認:

ls -la data/sessions/*/

ログでセッション継続性を確認:

grep "Session initialized" logs/ghostclaw.log | tail -5
# 同じグループ内の連続したメッセージでは同じセッション ID が表示されるべき

4. MCP サーバー失敗

MCP サーバーが起動に失敗した場合、エージェントは終了する可能性があります。MCP 初期化エラーについてはエージェントログを確認してください。

MCP サーバーは data/sessions/{folder}/.claude/settings.json で設定されます。グローバルサーバーは agent-spawner.ts:buildGlobalMcpServers() から自動的に同期されます。

5. エージェント タイムアウト

デフォルトタイムアウトは 300 秒です。エージェントに時間がかかる場合:

• ログを確認して、何をしているか確認 (長いツール呼び出し、大きなファイル読み込み)
• 登録されたグループの containerConfig.timeout 経由でタイムアウトを増加させます

SDK オプション リファレンス

エージェント-ランナーは以下の Claude Agent SDK オプションを使用します:

query({
  prompt: input.prompt,
  options: {
    cwd: groupDir,
    allowedTools: ['Bash', 'Read', 'Write', ...],
    permissionMode: 'bypassPermissions',
    allowDangerouslySkipPermissions: true,
    settingSources: ['project'],
    mcpServers: { ... }
  }
})

重要: permissionMode: 'bypassPermissions' を使用する場合、allowDangerouslySkipPermissions: true が必要です。これがないと Claude Code はコード 1 で終了します。

変更後の再ビルド

# メインアプリを再ビルド
npm run build

# エージェント-ランナーを再ビルド
cd agent-runner && npm run build && cd ../..

# サービスを再起動
launchctl kickstart -k gui/$(id -u)/com.ghostclaw  # macOS
# systemctl --user restart ghostclaw                # Linux

セッション永続性

Claude セッションはセキュリティ分離のため data/sessions/{group}/.claude/ にグループごとに保存されます。各グループは独自のセッションディレクトリを持ち、グループ間の会話履歴へのアクセスを防ぎます。

セッションをクリアするには:

# すべてのグループのすべてのセッションをクリア
rm -rf data/sessions/

# 特定のグループのセッションをクリア
rm -rf data/sessions/{groupFolder}/.claude/

IPC デバッグ

エージェントは data/ipc/{folder}/ 内のファイル経由でホストと通信します:

# 保留中のメッセージを確認
ls -la data/ipc/*/messages/

# 保留中のタスク操作を確認
ls -la data/ipc/*/tasks/

# 特定の IPC ファイルを読む
cat data/ipc/*/messages/*.json

# 利用可能なグループを確認 (メインチャネルのみ)
cat data/ipc/main/available_groups.json

# 現在のタスクスナップショットを確認
cat data/ipc/{groupFolder}/current_tasks.json

IPC ファイルタイプ:

• messages/*.json - エージェントが書き込み: 送信メッセージ
• tasks/*.json - エージェントが書き込み: タスク操作 (schedule、pause、resume、cancel、refresh_groups)
• current_tasks.json - ホストが書き込み: スケジュール済みタスクの読み取り専用スナップショット
• available_groups.json - ホストが書き込み: グループの読み取り専用リスト (メインのみ)

クイック診断スクリプト

一般的な問題をチェックするために以下を実行:

echo "=== Checking GhostClaw Setup ==="

echo -e "\n1. Authentication configured?"
[ -f .env ] && (grep -q "CLAUDE_CODE_OAUTH_TOKEN=sk-" .env || grep -q "ANTHROPIC_API_KEY=sk-" .env) && echo "OK" || echo "MISSING - add CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY to .env"

echo -e "\n2. Node.js available?"
node --version 2>/dev/null && echo "OK" || echo "NOT FOUND - install Node.js 20+"

echo -e "\n3. Built?"
[ -d dist ] && echo "OK" || echo "MISSING - run npm run build"

echo -e "\n4. Agent runner built?"
[ -d agent-runner/dist ] && echo "OK" || echo "MISSING - run cd agent-runner && npm run build"

echo -e "\n5. Groups directory?"
ls -la groups/ 2>/dev/null || echo "MISSING - run /setup-ghostclaw"

echo -e "\n6. Service running?"
launchctl list 2>/dev/null | grep ghostclaw && echo "OK" || echo "NOT RUNNING"

echo -e "\n7. Recent agent logs?"
ls -t groups/*/logs/agent-*.log 2>/dev/null | head -3 || echo "No agent logs yet"

echo -e "\n8. Session continuity working?"
SESSIONS=$(grep "Session initialized" logs/ghostclaw.log 2>/dev/null | tail -5 | awk '{print $NF}' | sort -u | wc -l)
[ "$SESSIONS" -le 2 ] && echo "OK (recent sessions reusing IDs)" || echo "CHECK - multiple different session IDs, may indicate resumption issues"