06. Claude Agent SDK をサブスクモードで使う

@anthropic-ai/claude-agent-sdk は API キーなし で動作できる「サブスクモード」を持つ。ユーザーがインストール済みの Claude Code セッション を流用するので、別途課金が不要。スタックちゃんの bridge ではこれを採用している。

動作モード比較

モード	認証	課金	用途
API キー	`ANTHROPIC_API_KEY=sk-ant-...`	トークン従量	CI / 本番 / Claude Code が動いてない端末
サブスクモード	(なし) → Claude Code セッションを流用	サブスク内	開発機、Claude Code 入ってる端末

サブスクモードの条件

Mac に Claude Code がインストール済み (claude --version で確認)
Claude Code でログイン済 (Claude Pro / Team / Enterprise)
ANTHROPIC_API_KEY 環境変数が 未設定

process.env.ANTHROPIC_API_KEY が空のとき SDK は Claude Code 経由のセッション認証を試みる。

最小サンプル

import { query } from '@anthropic-ai/claude-agent-sdk';

// サブスクモード: ANTHROPIC_API_KEY を削除
delete process.env.ANTHROPIC_API_KEY;

const result = query({
  prompt: 'こんにちは、自己紹介してね',
  options: {
    systemPrompt: 'あなたは Donack、緑帽子の AI アヒル。日本語で短く。',
    allowedTools: [],  // 純粋な対話なら空
  },
});

for await (const msg of result) {
  if (msg.type === 'assistant' && msg.message?.content) {
    for (const block of msg.message.content) {
      if (block.type === 'text') console.log(block.text);
    }
  }
}

ツール許可

allowedTools で組込ツールを指定:

allowedTools: [
  'Read',          // ファイル読み取り
  'Glob',          // ファイル検索
  'Grep',          // 全文検索
  'Bash',          // シェル実行 (gh CLI / sqlite3 etc)
  // 'Write',      // 書き込み (有効化は要検討)
  // 'Edit',       // 編集 (同上)
]

書き込み系 (Write/Edit) を許可すると コードが勝手に書き換わる ので、本プロジェクトでは読み取り系に絞ってあります（vibe coding 完全有効化は別 issue）。

MCP サーバーを渡す

カスタムツールを Claude に追加するには mcpServers で stdio MCP server を起動:

const result = query({
  prompt: '...',
  options: {
    mcpServers: {
      memory: {
        type: 'stdio',
        command: 'node',
        args: ['--import', 'tsx', '/path/to/memory-server.ts'],
      },
    },
    allowedTools: [
      ...,
      'mcp__memory__memory_list_parts',
      'mcp__memory__shopping_list_top',
      // tool 名は `mcp__<server>__<tool>` 形式
    ],
  },
});

MCP server の書き方は 07. MCP stdio server を自前実装を参照。

peer dep の衝突 (zod)

@anthropic-ai/claude-agent-sdk は zod の peer dependency を ^3.25.0 || ^4.0.0 で要求する。本プロジェクトの他依存が zod@^3.23.8 を持つので衝突する。

対処:

bash

npm install --legacy-peer-deps @anthropic-ai/claude-agent-sdk

または package.json で zod を ^3.25.0 に上げる。--legacy-peer-deps のほうが影響範囲が狭いので推奨。

動作確認

bash

cd mac-studio/bridge
npm run start
# 別ターミナル
node test_ws.mjs
# WS で agent.run を投げて agent.delta が返ってくれば OK

詳しい設定は mac-studio/bridge/src/backends/claude.ts 参照。

トラブル

症状	対処
`unauthenticated` エラー	Claude Code でログインしてない。`claude /login`
`ANTHROPIC_API_KEY is invalid`	環境変数を意図せず設定している。`unset ANTHROPIC_API_KEY`
`package not found` (npm install)	peer dep 衝突。`--legacy-peer-deps`
Tool が呼ばれない	`allowedTools` に追加し忘れ。`mcp__<server>__<tool>` の形式注意

06. Claude Agent SDK をサブスクモードで使う ​

動作モード比較 ​

サブスクモードの条件 ​

最小サンプル ​

ツール許可 ​

MCP サーバーを渡す ​

peer dep の衝突 (zod) ​

動作確認 ​

トラブル ​

関連 ​