Documentation 2026-09-11 23:01 UTC to 2026-09-12 03:02 UTC

90WSL 2 ユーティリティ VM 内のプロセスは、Windows 側のエンドポイント検出センサーに表示されません。ディストリビューション内のプロセスとファイルアクティビティを観察するには、エンドポイント検出ベンダーの WSL ガイダンスで、ディストリビューション内で実行できる Linux センサーと、それが必要とする除外を確認してください。Claude Code の [OpenTelemetry ツール実行テレメトリ](/docs/ja/monitoring-usage)は WSL とネイティブセッションで同じように出力されます。90WSL 2 ユーティリティ VM 内のプロセスは、Windows 側のエンドポイント検出センサーに表示されません。ディストリビューション内のプロセスとファイルアクティビティを観察するには、エンドポイント検出ベンダーの WSL ガイダンスで、ディストリビューション内で実行できる Linux センサーと、それが必要とする除外を確認してください。Claude Code の [OpenTelemetry ツール実行テレメトリ](/docs/ja/monitoring-usage)は WSL とネイティブセッションで同じように出力されます。

91 91 

92<h2 id="decide-what-to-enforce">92<h2 id="decide-what-to-enforce">

93 実行する内容を決定する93 実装する内容を決定する

94</h2>94</h2>

95 95 

96マネージド設定は、ツール、サンドボックス実行、MCP サーバーとプラグインソースへのアクセスをロックダウンし、実行されるフックを制御できます。各行は、それを駆動する設定キーを持つ制御サーフェスです。96マネージド設定は、ツール、サンドボックス実行、MCP サーバーとプラグインソース、および実行するフック を制限できます。各行は、それを駆動する設定キーを持つ制御サーフェスです。

97 97 

98| 制御 | 機能 | キー設定 |98| 制御 | 機能 | キー設定 |

99| :------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------- |99| :--------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------- |

100| [Permission rules](/docs/ja/permissions) | 特定のツールとコマンドを許可、確認、または拒否する | `permissions.allow`、`permissions.deny` |100| [権限ルール](/docs/ja/permissions) | 特定のツールとコマンドを許可、確認、または拒否する | `permissions.allow`、`permissions.deny` |

101| [Permission lockdown](/docs/ja/permissions#managed-only-settings) | マネージド設定を [permission ルールの唯一の設定ソース](/docs/ja/settings-reference#allowmanagedpermissionrulesonly) にする。`--dangerously-skip-permissions` を無効化する | `allowManagedPermissionRulesOnly`、`permissions.disableBypassPermissionsMode` |101| [権限ロックダウン](/docs/ja/permissions#managed-only-settings) | マネージド設定を[権限ルールの唯一の設定ソース](/docs/ja/settings-reference#allowmanagedpermissionrulesonly)にします。`--dangerously-skip-permissions` を無効にする | `allowManagedPermissionRulesOnly`、`permissions.disableBypassPermissionsMode` |

102| [Starting permission mode](/docs/ja/permission-modes#which-mode-a-session-starts-in) | 開発者のターミナルセッションが開始する権限モードを選択するか、組み込みの開始権限モードの代わりに自動モードを削除する。VS Code 拡張機能は、Pro、Max、Team プランでのみ設定した `defaultMode` を読み取ります。[Switch permission modes](/docs/ja/permission-modes#switch-permission-modes) は拡張機能が読み取る内容をリストします | `permissions.defaultMode`、`permissions.disableAutoMode` |102| [開始権限モード](/docs/ja/permission-modes#which-mode-a-session-starts-in) | 組み込みの開始権限モードの代わりに、開発者のターミナルセッションが開始する権限モードを選択するか、自動モードを削除します。VS Code 拡張機能は、Pro、Max、Team プランでのみ設定した `defaultMode` を読み取ります。[権限モードの切り替え](/docs/ja/permission-modes#switch-permission-modes)は、拡張機能が読み取る内容を一覧表示します | `permissions.defaultMode`、`permissions.disableAutoMode` |

103| [Sandboxing](/docs/ja/sandboxing) | ドメイン許可リスト付きの OS レベルのファイルシステムとネットワーク分離 | `sandbox.enabled`、`sandbox.network.allowedDomains` |103| [サンドボックス](/docs/ja/sandboxing) | ドメイン許可リスト付きの OS レベルのファイルシステムとネットワーク分離 | `sandbox.enabled`、`sandbox.network.allowedDomains` |

104| [Managed policy CLAUDE.md](/docs/ja/memory#deploy-organization-wide-claude-md) | すべてのセッションで読み込まれる組織全体の指示。除外できない | マネージドポリシーパスのファイル |104| [マネージドポリシー CLAUDE.md](/docs/ja/memory#deploy-organization-wide-claude-md) | すべてのセッションで読み込まれる組織全体の指示。除外できません | マネージドポリシーパスのファイル |

105| [MCP server control](/docs/ja/managed-mcp) | ユーザーが追加または接続できる MCP サーバーを制限するか、固定セットをデプロイするか、すべてのユーザーに独自のサーバーと一緒にリモートサーバーを提供する | `allowedMcpServers`、`deniedMcpServers`、`allowManagedMcpServersOnly`、`managedMcpServers`、またはデプロイされた `managed-mcp.json` ファイル |105| [MCP サーバー制御](/docs/ja/managed-mcp) | ユーザーが追加または接続できる MCP サーバーを制限し、固定セットをデプロイするか、リモートサーバーをすべてのユーザーに提供します | `allowedMcpServers`、`deniedMcpServers`、`allowManagedMcpServersOnly`、`managedMcpServers`、またはデプロイされた `managed-mcp.json` ファイル |

106| [Plugin marketplace control](/docs/ja/plugin-marketplaces#managed-marketplace-restrictions) | ユーザーが追加およびインストールできるマーケットプレイスソースを制限し、単一実行のためにプラグイン、エージェント、MCP サーバーをサイドロードする CLI フラグを拒否し、[`command` プラグインソース](/docs/ja/plugin-marketplaces#command-sources) をブロックし、どのマーケットプレイスのプラグインが提案されるかをホワイトリストに登録する | `strictKnownMarketplaces`、`blockedMarketplaces`、`disableSideloadFlags`、`disableCommandPluginSources`、`pluginSuggestionMarketplaces` |106| [プラグインマーケットプレイス制御](/docs/ja/plugin-marketplaces#managed-marketplace-restrictions) | ユーザーが追加およびインストールできるマーケットプレイスソースを制限し、単一実行のためにプラグイン、エージェント、MCP サーバーをサイドロードする CLI フラグを拒否し、[`command` プラグインソース](/docs/ja/plugin-marketplaces#command-sources)をブロックし、どのマーケットプレイスのプラグインを提案できるかをホワイトリストに登録します | `strictKnownMarketplaces`、`blockedMarketplaces`、`disableSideloadFlags`、`disableCommandPluginSources`、`pluginSuggestionMarketplaces` |

107| [Customization lockdown](/docs/ja/settings-reference#strictpluginonlycustomization) | スキル、エージェント、フック、および MCP サーバーをユーザーおよびプロジェクトソースからブロックし、プラグインまたはマネージド設定からのみ取得できるようにする | `strictPluginOnlyCustomization` |107| [カスタマイズロックダウン](/docs/ja/settings-reference#strictpluginonlycustomization) | スキル、エージェント、フック、MCP サーバーをユーザーおよびプロジェクトソースからブロックし、プラグインまたはマネージド設定からのみ取得できるようにします | `strictPluginOnlyCustomization` |

108| [Hook restrictions](/docs/ja/settings-reference#allowmanagedhooksonly) | 実行されるフックを制限し、HTTP フック URL を制限する。[`allowManagedHooksOnly` の下で実行される内容](/docs/ja/settings-reference#what-runs-under-allowmanagedhooksonly) を参照して、完全な効果リストを確認してください | `allowManagedHooksOnly`、`allowedHttpHookUrls` |108| [フック制限](/docs/ja/settings-reference#allowmanagedhooksonly) | 実行するフックを制限し、HTTP フック URL を制限します。[`allowManagedHooksOnly` で実行される内容](/docs/ja/settings-reference#what-runs-under-allowmanagedhooksonly)の完全な効果リストを参照してください | `allowManagedHooksOnly`、`allowedHttpHookUrls` |

109| [Login enforcement](/docs/ja/settings-reference#forceloginmethod) | ログインを特定の方法または Anthropic 組織に制限する。メソッド制限は VS Code 拡張機能、Agent SDK、`claude setup-token`、`/install-github-app` 全体に適用され、ターミナルのインタラクティブログイン画面は `/login` または初回オンボーディングで到達し、メソッドを強制せずに事前選択します。Claude Code は、ターミナル、VS Code 拡張機能、Agent SDK での claude.ai アカウントログインの組織を検証し、Claude Console ログインまたは [gateway](/docs/ja/claude-apps-gateway) サインインではチェックしません。v2.1.212 より前は、ターミナルログインのみが両方のキーを適用していました。設定されている場合、`ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN`、または `apiKeyHelper` によって認証されたセッションはスタートアップでブロックされます。クラウドプロバイダーセッションは影響を受けません | `forceLoginMethod`、`forceLoginOrgUUID` |109| [ログイン強制](/docs/ja/settings-reference#forceloginmethod) | ログインを特定の方法または Anthropic 組織に制限します。メソッド制限は VS Code 拡張機能、Agent SDK、`claude setup-token`、`/install-github-app` 全体に適用され、ターミナルのインタラクティブログイン画面（`/login` または初回オンボーディングで到達）はメソッドを事前選択しますが強制しません。Claude Code は、ターミナル、VS Code 拡張機能、Agent SDK での claude.ai アカウントログインの組織を検証し、Claude Console ログインまたは[ゲートウェイ](/docs/ja/claude-apps-gateway)サインインではチェックしません。v2.1.212 より前は、ターミナルログインのみが両方のキーを適用していました。設定すると、`ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN`、または `apiKeyHelper` によって認証されたセッションはスタートアップでブロックされます。クラウドプロバイダーセッションは影響を受けません | `forceLoginMethod`、`forceLoginOrgUUID` |

110| [Disable agent view](/docs/ja/agent-view#how-background-sessions-are-hosted) | `claude agents`、`--bg`、`/background`、およびオンデマンドスーパーバイザーをオフにする | `disableAgentView` |110| [エージェントビューを無効にする](/docs/ja/agent-view#how-background-sessions-are-hosted) | `claude agents`、`--bg`、`/background`、およびオンデマンドスーパーバイザーをオフにします | `disableAgentView` |

111| [Configure the corporate launcher](/docs/ja/corporate-launcher) | [バックグラウンドエージェントスーパーバイザー](/docs/ja/agent-view#how-background-sessions-are-hosted)、そのワーカー、および [その他のカバーされたバックグラウンドプロセス](/docs/ja/corporate-launcher#what-the-launcher-covers) に、エージェントビューをオフにする代わりに、必須の企業ランチャーをプレフィックスする | `processWrapper` |111| [企業ランチャーを構成する](/docs/ja/corporate-launcher) | [バックグラウンドエージェントスーパーバイザー](/docs/ja/agent-view#how-background-sessions-are-hosted)、そのワーカー、および[その他のカバーされたバックグラウンドプロセス](/docs/ja/corporate-launcher#what-the-launcher-covers)に、エージェントビューをオフにする代わりに、必須の企業ランチャーをプレフィックスします | `processWrapper` |

112| [Model restrictions](/docs/ja/model-config#restrict-model-selection) | `availableModels` はピッカーに表示されるモデルをフィルタリングします。`enforceAvailableModels` を追加すると、自動選択されるデフォルトモデルも制限されます。この設定が CLI、ウェブ、IDE にどのように到達するかについては、[surface coverage](/docs/ja/model-config#surface-coverage) を参照してください | `availableModels`、`enforceAvailableModels` |112| [モデル制限](/docs/ja/model-config#restrict-model-selection) | `availableModels` はピッカーに表示されるモデルをフィルタリングします。`enforceAvailableModels` を追加すると、自動選択されたデフォルトモデルも制限されます。このセッティングが CLI、ウェブ、IDE にどのように到達するかについては、[サーフェスカバレッジ](/docs/ja/model-config#surface-coverage)を参照してください | `availableModels`、`enforceAvailableModels` |

113| [Version floor](/docs/ja/settings-reference#minimumversion) | 自動更新が組織全体の最小値より下にインストールされるのを防ぐ | `minimumVersion` |113| [エフォートキャップ](/docs/ja/settings-reference#maxeffortlevel) | すべてのモデルまたはモデルごとに、すべてのプロバイダーで[エフォートレベル](/docs/ja/model-config#adjust-effort-level)をキャップします | `maxEffortLevel` |

114| [Required version range](/docs/ja/settings-reference#requiredminimumversion) | 実行中のバージョンが組織承認の範囲外の場合、まったく起動を拒否する。`minimumVersion` より強力で、ダウングレードのみをブロックする | `requiredMinimumVersion`、`requiredMaximumVersion` |114| [バージョンフロア](/docs/ja/settings-reference#minimumversion) | 自動更新が組織全体の最小値以下をインストールするのを防ぎます | `minimumVersion` |

115| [Telemetry opt-out](/docs/ja/data-usage#telemetry-services) | すべてのデバイスで Anthropic にバインドされた使用メトリクス、エラーレポート、調査をオフにする | `env` に `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` を `1` に設定。リンクされたセクションはカテゴリごとの変数をリストします |115| [必須バージョン範囲](/docs/ja/settings-reference#requiredminimumversion) | 実行中のバージョンが組織承認範囲外の場合、まったく起動を拒否します。ダウングレードのみをブロックする `minimumVersion` より強力です | `requiredMinimumVersion`、`requiredMaximumVersion` |

116 116| [テレメトリオプトアウト](/docs/ja/data-usage#telemetry-services) | すべてのデバイスで Anthropic バウンドの使用メトリクス、エラーレポート、およびサーベイをオフにします | `env` に `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` を `1` に設定します。リンクされたセクションはカテゴリごとの変数を一覧表示します |

117claude.ai または Anthropic API を通じて認証するメンバーを持つ組織は、設定をデプロイせずにモデルを管理することもできます。[organization model restrictions](/docs/ja/model-config#organization-model-restrictions) は個別のモデルを無効化し、[organization default model](/docs/ja/model-config#organization-default-model) は新しいセッションが開始するモデルを設定し、[organization effort limits](/docs/ja/model-config#organization-effort-limits) はロールごとのエフォートレベルを制限します。3 つのコントロールすべてに Claude Enterprise プランが必要です。モデル制限とエフォート制限はサーバー側で実行されます。デフォルトモデルは、組織がそれを実行しない限り、ユーザーが変更できる開始点です。実行は限定的な組織セットで利用可能です。可用性については、Anthropic アカウントチームにお問い合わせください。これらのコントロールのいずれも、Amazon Bedrock、Google Cloud の Agent Platform、Microsoft Foundry、または [Claude Platform on AWS](/docs/ja/claude-platform-on-aws) 上のセッションには到達しません。これらのプロバイダーでは、制限に上記の `availableModels` を使用し、マネージド設定の `model` キーをデフォルトに使用してください。117 

118 118メンバーが claude.ai または Anthropic API を通じてサインインし、Claude Enterprise プランを使用している場合、何もデプロイせずに組織の管理者設定からモデルを管理することもできます。

119[Claude Code on the web](/docs/ja/claude-code-on-the-web) には独自の管理サーフェスがあります。管理設定のクラウド環境ページで、オーナーは、メンバーのクラウドセッションの [network access level](/docs/ja/cloud-environments#network-access)、環境変数、セットアップスクリプトを設定する [organization-shared environments](/docs/ja/cloud-environments#organization-shared-environments) を作成します。オーナーは、[claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) で組織のデフォルト環境を別途選択します。119 

120 120* [組織モデル制限](/docs/ja/model-config#organization-model-restrictions)：個別のモデルを無効にします。サーバー側で強制されます。

121パーミッションルールとサンドボックスは異なるレイヤーをカバーします。WebFetch を拒否すると Claude の fetch ツールがブロックされますが、Bash が許可されている場合、`curl` と `wget` は依然として任意の URL に到達できます。サンドボックスは OS レベルで実行されるネットワークドメイン許可リストでそのギャップを閉じます。121* [組織デフォルトモデル](/docs/ja/model-config#organization-default-model)：新しいセッションが開始するモデルを設定します。ユーザーは、組織がデフォルトを強制しない限り変更できます。これは限定的な組織セットで利用可能です。Anthropic アカウントチームにお問い合わせください。

122 122* [組織エフォート制限](/docs/ja/model-config#organization-effort-limits)：ロールごとのエフォートレベルをキャップします。サーバー側で強制されます。

123これらの制御が防御する脅威モデルについては、[Security](/docs/ja/security) を参照してください。123 

124これらの制御は、Amazon Bedrock、Google Cloud の Agent Platform、Microsoft Foundry、または[AWS 上の Claude Platform](/docs/ja/claude-platform-on-aws)のセッションには到達しません。これらのプロバイダーでは、代わりにマネージド設定を使用してください。制限には `availableModels`、デフォルトには `model`、エフォートキャップには [`maxEffortLevel`](/docs/ja/settings-reference#maxeffortlevel) を使用します。

125 

126[Web 上の Claude Code](/docs/ja/claude-code-on-the-web)には独自の管理サーフェスがあります。管理設定のクラウド環境ページで、オーナーは[組織共有環境](/docs/ja/cloud-environments#organization-shared-environments)を作成し、メンバーのクラウドセッションの[ネットワークアクセスレベル](/docs/ja/cloud-environments#network-access)、環境変数、セットアップスクリプトを設定します。オーナーは、[claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) で組織のデフォルト環境を別途選択します。

127 

128権限ルールとサンドボックスは異なるレイヤーをカバーします。WebFetch を拒否すると Claude のフェッチツールがブロックされますが、Bash が許可されている場合、`curl` と `wget` は依然として任意の URL に到達できます。サンドボックスは、OS レベルで強制されるネットワークドメイン許可リストでそのギャップを閉じます。

129 

130これらの制御が防御する脅威モデルについては、[セキュリティ](/docs/ja/security)を参照してください。

124 131 

125<h2 id="set-up-usage-visibility">132<h2 id="set-up-usage-visibility">

126 使用状況の可視性をセットアップする133 使用状況の可視性をセットアップする

48/advisor opus48/advisor opus

49```49```

50 50 

51コマンドは `Advisor set to` で確認し、その後に advisor モデル名が続きます。選択はユーザー設定の `advisorModel` に保存され、セッション全体で保持されます。51コマンドは `Advisor set to` で確認し、その後に advisor モデル名が続きます。選択はユーザー設定の `advisorModel` に保存され、セッション全体で保持されます。ただし、[`advisorModel` エントリ](/docs/ja/settings-reference#advisormodel)が現在のセッションにのみ適用されるとリストしている場合は除きます。

52 

53このコマンドは、ターミナルピッカーがない場所でも機能します。[非対話型モード](/docs/ja/headless)で `-p` を使用する場合、Agent SDK 内、デスクトップアプリ内、および[リモートコントロール](/docs/ja/remote-control)経由です。これには Claude Code v2.1.260 以降が必要です。これらのサーフェスでは、

54 

55* 引数なしで `/advisor` を実行して、現在の advisor モデルとそれが受け入れるエイリアスを出力します。

56* `/advisor opus` などのモデルを使用して `/advisor` を実行して、それを設定します。

57* `/advisor off` を実行してそれをオフにします。

52 58 

53Claude Code は、組織の [`availableModels`](/docs/ja/model-config#restrict-model-selection)許可リストが除外した保存済み advisor を呼び出しません。advisor を使用するには、`/advisor` で許可されたモデルを選択してください。Claude Code は、現在のメインモデルがサポートしていない advisor を引き続き保存します。その advisor は、[`/model`](/docs/ja/model-config#setting-your-model)で[互換性のあるメインモデル](#choose-an-advisor-model)に切り替えた後にアクティブになります。59Claude Code は、組織の [`availableModels`](/docs/ja/model-config#restrict-model-selection)許可リストが除外した保存済み advisor を呼び出しません。advisor を使用するには、`/advisor` で許可されたモデルを選択してください。Claude Code は、現在のメインモデルがサポートしていない advisor を引き続き保存します。その advisor は、[`/model`](/docs/ja/model-config#setting-your-model)で[互換性のあるメインモデル](#choose-an-advisor-model)に切り替えた後にアクティブになります。

54 60 

92advisor はメインモデル以上の機能を持つ必要があります。各メインモデルで受け入れられる advisor は次のとおりです。98advisor はメインモデル以上の機能を持つ必要があります。各メインモデルで受け入れられる advisor は次のとおりです。

93 99 

94| メインモデル | 受け入れられる advisor | 注記 |100| メインモデル | 受け入れられる advisor | 注記 |

95| --------------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------- |101| --------------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------- |

96| Haiku 4.5 | Fable、Opus、Sonnet | Haiku は advisor を呼び出すことはできますが、advisor として機能することはできません |102| Haiku 4.5 | Fable、Opus、Sonnet | Haiku は advisor を呼び出すことはできますが、advisor として機能することはできません |

97| Sonnet 4.6 | Fable、Opus、Sonnet | |103| Sonnet 4.6 | Fable、Opus、Sonnet | |

98| Sonnet 5 | Fable、Opus、Sonnet 5 | Sonnet 4.6 advisor は拒否されます |104| Sonnet 5 | Fable、Opus、Sonnet 5 | Sonnet 4.6 advisor は拒否されます |

99| Opus 4.6 | Fable、Opus、Sonnet 5 | Sonnet 5 と Opus 4.6 は同等の機能として評価されるため、Opus 4.6 メインは Sonnet 5 advisor を受け入れます |105| Opus 4.6 | Fable、Opus、Sonnet 5 | Sonnet 5 と Opus 4.6 は同等の機能として評価されるため、Opus 4.6 メインは Sonnet 5 advisor を受け入れます |

100| Opus 4.7 以降 | Fable、Opus 4.7 以降 | Opus 4.7 以降の Opus モデルは同等の機能として評価されるため、どれでも他方を advisor として受け入れます。Opus 4.6 または Sonnet 5 advisor を持つ Opus 4.7 メインは拒否されます |106| Opus 4.7 以降 | Fable、Opus 4.7 以降 | Opus 4.7 以降の Opus モデルは同等の機能として評価されるため、どれでも他方を advisor として受け入れます。Opus 4.6 または Sonnet 5 advisor を持つ Opus 4.7 メインは拒否されます |

101| Fable 5.1 または Fable 5 | Fable 5.1、または同じ Fable バージョン | Opus または Sonnet advisor は拒否され、Fable 5.1 メインモデルの Fable 5 advisor も拒否されます |107| Fable 5.1 または Fable 5 | Fable 5.1 または Fable 5 | Opus または Sonnet advisor は拒否されます |

102 108 

103Fable 5.1 は Claude Code v2.1.257 以降が必要であり、Fable 5 は v2.1.170 以降が必要です。どちらも [Fable アクセス](/docs/ja/model-config#work-with-fable) が必要です。109Fable 5.1 は Claude Code v2.1.257 以降が必要です。どちらの Fable モデルも [Fable アクセス](/docs/ja/model-config#work-with-fable) が必要です。

104 110 

105advisor を `fable`、`opus`、または `sonnet` として設定します。これらのエイリアスは Claude Code の各モデルファミリーの組み込みデフォルトバージョンに解決され、新しい Claude Code リリースで進化します。`claude-opus-5` などの完全なモデル ID を渡すこともできます。111advisor を `fable`、`opus`、または `sonnet` として設定します。これらのエイリアスは Claude Code の各モデルファミリーの組み込みデフォルトバージョンに解決され、新しい Claude Code リリースで進化します。`claude-opus-5` などの完全なモデル ID を渡すこともできます。

106 112 

161 コスト167 コスト

162</h2>168</h2>

163 169 

164Claude が advisor を呼び出すと、advisor モデルが会話を読むため、各呼び出しはメインモデルの使用に加えて advisor モデルのレートでトークンを消費します。API 課金では、advisor トークンに対して advisor モデルの入力および出力レートで課金されます。サブスクリプションプランでは、advisor 使用量はプランの使用制限にカウントされます。ただし、Fable advisor は Fable 使用量が課金される計画では[使用クレジット](/docs/ja/model-config#fable-and-usage-credits)に課金されます。アカウントが使用クレジット同意を必要とする場合、Fable advisor は同意を与えるまで何も課金されません。Claude Code はそれまで[選択を適用しない](#fable-advisor-and-usage-credits)ためです。170Claude が advisor を呼び出すと、advisor モデルが会話を読むため、各呼び出しはメインモデルの使用に加えて advisor モデルのレートでトークンを消費します。これらの advisor トークンがどのように課金されるかは、お支払い方法によって異なります。

171 

172* **API 課金**: advisor トークンに対して advisor モデルの入力および出力レートで課金されます

173* **サブスクリプションプラン**: advisor 使用量はプランの使用制限にカウントされます。ただし、Fable advisor は Fable 使用量が課金される計画では[使用クレジット](/docs/ja/model-config#fable-and-usage-credits)に課金されます

174 

175アカウントが使用クレジット同意を必要とする場合、Fable advisor は同意を与えるまで何も課金されません。Claude Code はそれまで[選択を適用しない](#fable-advisor-and-usage-credits)ためです。

165 176 

166Claude は各ターンではなく決定ポイントで advisor を呼び出すため、より高速なメインモデルをより強力な advisor と組み合わせることは、通常、より強力なモデルを全体で実行するよりもコストが低くなります。advisor 使用量は [`/usage`](/docs/ja/costs#track-your-costs)で表示されるセッション合計にカウントされます。177Claude は各ターンではなく決定ポイントで advisor を呼び出すため、より高速なメインモデルをより強力な advisor と組み合わせることは、通常、より強力なモデルを全体で実行するよりもコストが低くなります。advisor 使用量は [`/usage`](/docs/ja/costs#track-your-costs)で表示されるセッション合計にカウントされます。

167 178 

189 advisor をオフにする200 advisor をオフにする

190</h2>201</h2>

191 202 

192advisor の使用を停止し、保存された `advisorModel` をクリアするには、`/advisor off` を実行するか、`/advisor` ピッカーで **No advisor** を選択します。203advisor の使用を停止するには、`/advisor off` を実行するか、`/advisor` ピッカーで **No advisor** を選択します。

193 204 

194```205```

195/advisor off206/advisor off

23<img src="https://mintcdn.com/claude-code/_xqph1dUOslCOwsj/images/agent-loop-diagram-dark.svg?fit=max&auto=format&n=_xqph1dUOslCOwsj&q=85&s=afe723c52a324d3c61fa72fb02432ab6" className="hidden dark:block" alt="エージェントループの図：プロンプトが agentic ループに入り、Claude が評価してツール呼び出しをリクエストするか最終回答を返すか、またはツール呼び出しの結果が別の評価にフィードバックされます" width="720" height="212" data-path="images/agent-loop-diagram-dark.svg" />23<img src="https://mintcdn.com/claude-code/_xqph1dUOslCOwsj/images/agent-loop-diagram-dark.svg?fit=max&auto=format&n=_xqph1dUOslCOwsj&q=85&s=afe723c52a324d3c61fa72fb02432ab6" className="hidden dark:block" alt="エージェントループの図：プロンプトが agentic ループに入り、Claude が評価してツール呼び出しをリクエストするか最終回答を返すか、またはツール呼び出しの結果が別の評価にフィードバックされます" width="720" height="212" data-path="images/agent-loop-diagram-dark.svg" />

24 24 

251. **プロンプトを受け取る。** Claude はプロンプト、システムプロンプト、ツール定義、および会話履歴とともにプロンプトを受け取ります。SDK はセッションメタデータを含むサブタイプ `"init"` の[`SystemMessage`](#message-types)を生成します。251. **プロンプトを受け取る。** Claude はプロンプト、システムプロンプト、ツール定義、および会話履歴とともにプロンプトを受け取ります。SDK はセッションメタデータを含むサブタイプ `"init"` の[`SystemMessage`](#message-types)を生成します。

262. **評価して応答する。** Claude は現在の状態を評価し、どのように進めるかを決定します。テキストで応答したり、1 つ以上のツール呼び出しをリクエストしたり、その両方を行ったりできます。SDK はテキストとツール呼び出しリクエストを含む[`AssistantMessage`](#message-types)を生成します。262. **評価して応答する。** Claude は現在の状態を評価し、どのように進めるかを決定します。テキストで応答したり、1 つ以上のツール呼び出しをリクエストしたり、その両方を行ったりできます。SDK はテキストブロックやツール呼び出しリクエストなどのコンテンツブロックごとに 1 つずつ、1 つ以上の[`AssistantMessage`](#message-types)オブジェクトを生成します。

273. **ツールを実行する。** SDK は要求された各ツールを実行し、結果を収集します。ツール結果の各セットは次の決定のために Claude にフィードバックされます。[hooks](/docs/ja/agent-sdk/hooks)を使用して、ツール呼び出しを実行前に傍受、変更、またはブロックできます。273. **ツールを実行する。** SDK は要求された各ツールを実行し、結果を収集します。ツール結果の各セットは次の決定のために Claude にフィードバックされます。[hooks](/docs/ja/agent-sdk/hooks)を使用して、ツール呼び出しを実行前に傍受、変更、またはブロックできます。

284. **繰り返す。** ステップ 2 と 3 がサイクルとして繰り返されます。各完全なサイクルは 1 ターンです。Claude はツール呼び出しと結果の処理を続け、ツール呼び出しのない応答を生成するまで続きます。284. **繰り返す。** ステップ 2 と 3 がサイクルとして繰り返されます。各完全なサイクルは 1 ターンです。Claude はツール呼び出しと結果の処理を続け、ツール呼び出しのない応答を生成するまで続きます。

295. **結果を返す。** SDK は最終的な[`AssistantMessage`](#message-types)（テキスト応答、ツール呼び出しなし）を生成し、その後に最終テキスト、トークン使用量、コスト、およびセッション ID を含む[`ResultMessage`](#message-types)を生成します。295. **結果を返す。** SDK は最終的な[`AssistantMessage`](#message-types)（テキスト応答、ツール呼び出しなし）を生成し、その後に最終テキスト、トークン使用量、コスト、およびセッション ID を含む[`ResultMessage`](#message-types)を生成します。

41まず、SDK はプロンプトを Claude に送信し、セッションメタデータを含む[`SystemMessage`](#message-types)を生成します。その後、ループが開始されます。41まず、SDK はプロンプトを Claude に送信し、セッションメタデータを含む[`SystemMessage`](#message-types)を生成します。その後、ループが開始されます。

42 42 

431. **ターン 1：** Claude は `Bash` を呼び出して `npm test` を実行します。SDK は[`AssistantMessage`](#message-types)とツール呼び出しを生成し、コマンドを実行し、出力（3 つの失敗）を含む[`UserMessage`](#message-types)を生成します。431. **ターン 1：** Claude は `Bash` を呼び出して `npm test` を実行します。SDK は[`AssistantMessage`](#message-types)とツール呼び出しを生成し、コマンドを実行し、出力（3 つの失敗）を含む[`UserMessage`](#message-types)を生成します。

442. **ターン 2：** Claude は `Read` を呼び出して `auth.ts` と `auth.test.ts` を読み取ります。SDK はファイルの内容を返し、`AssistantMessage` を生成します。442. **ターン 2：** Claude は `Read` を呼び出して `auth.ts` と `auth.test.ts` を読み取ります。SDK は各呼び出しに対して `AssistantMessage` を生成し、ファイルの内容を返します。

453. **ターン 3：** Claude は `Edit` を呼び出して `auth.ts` を修正し、`Bash` を呼び出して `npm test` を再実行します。3 つのテストすべてが成功します。SDK は `AssistantMessage` を生成します。453. **ターン 3：** Claude は `Edit` を呼び出して `auth.ts` を修正し、`Bash` を呼び出して `npm test` を再実行します。3 つのテストすべてが成功します。SDK は各呼び出しに対して `AssistantMessage` を生成します。

464. **最終ターン：** Claude はツール呼び出しのないテキストのみの応答を生成します。「認証バグを修正し、3 つのテストすべてが成功しました。」SDK はこのテキストを含む最終 `AssistantMessage` を生成し、その後、同じテキストとコストおよび使用量を含む[`ResultMessage`](#message-types)を生成します。464. **最終ターン：** Claude はツール呼び出しのないテキストのみの応答を生成します。「Fixed the auth bug, all three tests pass now.」SDK はこのテキストを含む最終 `AssistantMessage` を生成し、その後、同じテキストとコストおよび使用量を含む[`ResultMessage`](#message-types)を生成します。

47 47 

48これは 4 ターンでした。3 つはツール呼び出し、1 つは最終テキストのみの応答です。48これは 4 ターンでした。3 つはツール呼び出し、1 つは最終テキストのみの応答です。

49 49 

50`max_turns` / `maxTurns` でループをキャップできます。これはツール使用ターンのみをカウントします。たとえば、上記のループで `max_turns=2` は編集ステップの前に停止していたでしょう。`max_budget_usd` / `maxBudgetUsd` を使用して、支出しきい値に基づいてターンをキャップすることもできます。50`max_turns` / `maxTurns` でループをキャップできます。これはツール使用ターンのみをカウントします。たとえば、上記のループで `max_turns=2` は編集ステップの前に停止していたでしょう。`max_budget_usd` / `maxBudgetUsd` を使用して、支出しきい値に基づいてターンをキャップすることもできます。

51 51 

52制限がない場合、ループは Claude が独自に終了するまで実行されます。これは適切にスコープされたタスクには問題ありませんが、オープンエンドのプロンプト（「このコードベースを改善する」）では長時間実行される可能性があります。予算を設定することは、本番エージェントの良いデフォルトです。以下の[ターンと予算](#turns-and-budget)でオプションリファレンスを参照してください。52制限がない場合、ループは Claude が独自に終了するまで実行されます。これは適切にスコープされたタスクには問題ありませんが、オープンエンドのプロンプト（「improve this codebase」）では長時間実行される可能性があります。予算を設定することは、本番エージェントの良いデフォルトです。以下の[ターンと予算](#turns-and-budget)でオプションリファレンスを参照してください。

53 53 

54<h2 id="message-types">54<h2 id="message-types">

55 メッセージタイプ55 メッセージタイプ

65 * `"worker_shutting_down"`：ホストが終了しているか Remote Control が切断されたため、現在のターン後にループが終了します65 * `"worker_shutting_down"`：ホストが終了しているか Remote Control が切断されたため、現在のターン後にループが終了します

66 66 

67 TypeScript では、`"init"` 以外の各サブタイプは `SDKSystemMessage` のサブタイプではなく、[`SDKMessage` ユニオン](/docs/ja/agent-sdk/typescript#sdkmessage)内の独自のタイプです。67 TypeScript では、`"init"` 以外の各サブタイプは `SDKSystemMessage` のサブタイプではなく、[`SDKMessage` ユニオン](/docs/ja/agent-sdk/typescript#sdkmessage)内の独自のタイプです。

68* **`AssistantMessage`：** 最終テキストのみの応答を含む、各 Claude 応答の後に生成されます。そのターンからのテキストコンテンツブロックとツール呼び出しブロックを含みます。68* **`AssistantMessage`：** 最終テキストのみの応答を含む、Claude の各応答のコンテンツブロックごとに生成されます。各メッセージは、テキストやツール呼び出しなどの単一のコンテンツブロックを持ち、1 つの応答からのメッセージは同じメッセージ ID を共有します。

69* **`UserMessage`：** 各ツール実行後、Claude に送り返されるツール結果コンテンツとともに生成されます。ループ中盤でストリーミングするユーザー入力に対しても生成されます。69* **`UserMessage`：** 各ツール実行後、Claude に送り返されるツール結果コンテンツとともに生成されます。ループ中盤でストリーミングするユーザー入力に対しても生成されます。

70* **`StreamEvent`：** 部分メッセージが有効な場合のみ生成されます。生の API ストリーミングイベント（テキストデルタ、ツール入力チャンク）を含みます。[ストリーム応答](/docs/ja/agent-sdk/streaming-output)を参照してください。70* **`StreamEvent`：** 部分メッセージが有効な場合のみ生成されます。生の API ストリーミングイベント（テキストデルタ、ツール入力チャンク）を含みます。[ストリーム応答](/docs/ja/agent-sdk/streaming-output)を参照してください。

71* **`ResultMessage`：** エージェントループの終了をマークします。最終テキスト結果、トークン使用量、コスト、およびセッション ID を含みます。`subtype` フィールドをチェックして、タスクが成功したか制限に達したかを判断します。`prompt_suggestion` などの少数の末尾システムイベントはその後に到着する可能性があるため、結果で中断するのではなく、ストリームを完了まで反復処理します。[結果を処理する](#handle-the-result)を参照してください。71* **`ResultMessage`：** エージェントループの終了をマークします。最終テキスト結果、トークン使用量、コスト、およびセッション ID を含みます。`subtype` フィールドをチェックして、タスクが成功したか制限に達したかを判断します。`prompt_suggestion` などの少数の末尾システムイベントはその後に到着する可能性があるため、結果で中断するのではなく、ストリームを完了まで反復処理します。[結果を処理する](#handle-the-result)を参照してください。

91 <CodeGroup>91 <CodeGroup>

92 ```python Python theme={null}92 ```python Python theme={null}

93 import asyncio93 import asyncio

94 from claude_agent_sdk import query, AssistantMessage, ResultMessage94 from claude_agent_sdk import query, AssistantMessage, ResultMessage, TextBlock, ToolUseBlock

95 95 

96 96 

97 async def main():97 async def main():

98 try:98 try:

99 async for message in query(prompt="Summarize this project"):99 async for message in query(prompt="Summarize this project"):

100 if isinstance(message, AssistantMessage):100 if isinstance(message, AssistantMessage):

101 print(f"Turn completed: {len(message.content)} content blocks")101 # Each AssistantMessage carries one content block

102 for block in message.content:

103 if isinstance(block, TextBlock):

104 print(f"Claude: {block.text}")

105 elif isinstance(block, ToolUseBlock):

106 print(f"Tool call: {block.name}")

102 if isinstance(message, ResultMessage):107 if isinstance(message, ResultMessage):

103 if message.subtype == "success":108 if message.subtype == "success":

104 print(message.result)109 print(message.result)

120 try {125 try {

121 for await (const message of query({ prompt: "Summarize this project" })) {126 for await (const message of query({ prompt: "Summarize this project" })) {

122 if (message.type === "assistant") {127 if (message.type === "assistant") {

123 console.log(`Turn completed: ${message.message.content.length} content blocks`);128 // Each assistant message carries one content block

129 for (const block of message.message.content) {

130 if (block.type === "text") {

131 console.log(`Claude: ${block.text}`);

132 } else if (block.type === "tool_use") {

133 console.log(`Tool call: ${block.name}`);

134 }

135 }

124 }136 }

125 if (message.type === "result") {137 if (message.type === "result") {

126 if (message.subtype === "success") {138 if (message.subtype === "success") {

175 187 

176Claude はタスクに基づいてどのツールを呼び出すかを決定しますが、それらの呼び出しの実行を許可するかどうかを制御します。特定のツールを自動承認したり、他のツールを完全にブロックしたり、すべてに対して承認を要求したりできます。3 つのオプションが連携して、何が実行されるかを決定します。188Claude はタスクに基づいてどのツールを呼び出すかを決定しますが、それらの呼び出しの実行を許可するかどうかを制御します。特定のツールを自動承認したり、他のツールを完全にブロックしたり、すべてに対して承認を要求したりできます。3 つのオプションが連携して、何が実行されるかを決定します。

177 189 

178* **`allowed_tools` / `allowedTools`** リストされたツールを自動承認します。許可されたツールリストに `["Read", "Glob", "Grep"]` がある読み取り専用エージェントは、プロンプトなしでそれらのツールを実行します。リストされていないツールは引き続き利用可能ですが、権限が必要です。190* **`allowed_tools` / `allowedTools`** リストされたツールを自動承認します。許可されたツールリストに `["Read", "Glob", "Grep"]` がある読み取り専用エージェントは、プロンプトなしでそれらのツールを実行します。リストされていないツールは引き続き利用可能ですが、それらへの呼び出しで承認が必要な場合は、権限モードと `canUseTool` にフォールスルーします。

179* **`disallowed_tools` / `disallowedTools`** リストされたツールをブロックします。他の設定に関係なく。ツールが実行される前にルールがチェックされる順序については、[権限](/docs/ja/agent-sdk/permissions)を参照してください。191* **`disallowed_tools` / `disallowedTools`** リストされたツールをブロックします。他の設定に関係なく。ツールが実行される前にルールがチェックされる順序については、[権限](/docs/ja/agent-sdk/permissions)を参照してください。

180* **`permission_mode` / `permissionMode`** 許可または拒否ルールでカバーされていないツールに何が起こるかを制御します。SDK は有効なモードと許可および拒否ルールを固定順序で評価します。詳細については、[権限がどのように評価されるか](/docs/ja/agent-sdk/permissions#how-permissions-are-evaluated)を参照してください。利用可能なモードについては、[権限モード](#permission-mode)を参照してください。192* **`permission_mode` / `permissionMode`** 必要な人間の監視の量を制御します。SDK は有効なモードと許可および拒否ルールを固定順序で評価します。詳細については、[権限がどのように評価されるか](/docs/ja/agent-sdk/permissions#how-permissions-are-evaluated)を参照してください。利用可能なモードについては、[権限モード](#permission-mode)を参照してください。

181 193 

182`"Bash(npm *)"` のようなルールで個別のツールをスコープすることもできます。これにより、特定のコマンドのみを許可できます。完全なルール構文については、[権限](/docs/ja/agent-sdk/permissions)を参照してください。194`"Bash(npm *)"` のようなルールで個別のツールをスコープすることもできます。これにより、特定のコマンドのみを許可できます。完全なルール構文については、[権限](/docs/ja/agent-sdk/permissions)を参照してください。

183 195 

219`effort` オプションは Claude が適用する推論の量を制御します。低い努力レベルはターンあたりのトークンが少なく、コストが削減されます。すべてのモデルが努力パラメータをサポートしているわけではありません。どのモデルがサポートしているかについては、[努力](https://platform.claude.com/docs/ja/build-with-claude/effort)を参照してください。231`effort` オプションは Claude が適用する推論の量を制御します。低い努力レベルはターンあたりのトークンが少なく、コストが削減されます。すべてのモデルが努力パラメータをサポートしているわけではありません。どのモデルがサポートしているかについては、[努力](https://platform.claude.com/docs/ja/build-with-claude/effort)を参照してください。

220 232 

221| レベル | 動作 | 適している用途 |233| レベル | 動作 | 適している用途 |

222| :--------- | :---------- | :------------------------------------------------------------------------------- |234| :--------- | :---------- | :------------------------------------------------------------------------------ |

223| `"low"` | 最小限の推論、高速応答 | ファイル検索、ディレクトリのリスト |235| `"low"` | 最小限の推論、高速応答 | ファイル検索、ディレクトリのリスト |

224| `"medium"` | バランスの取れた推論 | ルーチン編集、標準タスク |236| `"medium"` | バランスの取れた推論 | ルーチン編集、標準タスク |

225| `"high"` | 徹底的な分析 | リファクタリング、デバッグ |237| `"high"` | 徹底的な分析 | リファクタリング、デバッグ |

226| `"xhigh"` | 拡張推論深度 | [サポートしているモデル](/docs/ja/model-config#adjust-effort-level)での コーディングと agentic coding タスク |238| `"xhigh"` | 拡張推論深度 | [サポートしているモデル](/docs/ja/model-config#adjust-effort-level)でのコーディングと agentic coding タスク |

227| `"max"` | 最大推論深度 | 深い分析が必要な複数ステップの問題 |239| `"max"` | 最大推論深度 | 深い分析が必要な複数ステップの問題 |

228 240 

229`effort` を設定しない場合、両方の SDK はパラメータを設定したままにして、モデルのデフォルト動作に委譲します。241`effort` を設定しない場合、両方の SDK はパラメータを未設定のままにして、モデルのデフォルト動作に委譲します。

230 242 

231<Note>243<Note>

232 `effort` は各応答内の推論深度のレイテンシとトークンコストをトレードオフします。[Extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)は、出力に `thinking` ブロックを生成する別の機能であり、[Python](/docs/ja/agent-sdk/python#thinkingconfig)または[TypeScript](/docs/ja/agent-sdk/typescript#thinkingconfig)の `ThinkingConfig` の `display` フィールドは、テキストを受け取るかどうかを制御します。これらは独立しています。`effort: "low"` を extended thinking 有効で設定することも、`effort: "max"` を有効にしないで設定することもできます。244 `effort` は各応答内の推論深度のレイテンシとトークンコストをトレードオフします。[Extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)は、出力に `thinking` ブロックを生成する別の機能であり、[Python](/docs/ja/agent-sdk/python#thinkingconfig)または[TypeScript](/docs/ja/agent-sdk/typescript#thinkingconfig)の `ThinkingConfig` の `display` フィールドは、テキストを受け取るかどうかを制御します。これらは独立しています。`effort: "low"` を extended thinking 有効で設定することも、`effort: "max"` を有効にしないで設定することもできます。

242 254 

243| モード | 動作 | ユースケース |255| モード | 動作 | ユースケース |

244| :-------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------- |256| :-------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------- |

245| `"default"` | 許可ルールでカバーされていないツールは `canUseTool` コールバックをトリガーします。コールバックがない場合は拒否 | カスタム承認コールバックを備えたインタラクティブアプリケーション |257| `"default"` | 許可ルールでカバーされていないツール呼び出しは `canUseTool` コールバックをトリガーします。コールバックがない場合は拒否 | カスタム承認コールバックを備えたインタラクティブアプリケーション |

246| `"acceptEdits"` | ファイル編集と一般的なファイルシステムコマンド（`mkdir`、`touch`、`mv`、`cp` など）を自動承認します。他の Bash コマンドはデフォルトルールに従います | Claude の編集を信頼し、プロトタイピング中や隔離されたディレクトリで作業する場合など、より高速な反復を望む |258| `"acceptEdits"` | ファイル編集と一般的なファイルシステムコマンド（`mkdir`、`touch`、`mv`、`cp` など）を自動承認します。他の Bash コマンドはデフォルトルールに従います | Claude の編集を信頼し、プロトタイピング中や隔離されたディレクトリで作業する場合など、より高速な反復を望む |

247| `"plan"` | Claude はソースファイルを編集せずに探索して計画を作成します。ファイル編集は自動承認されず、`canUseTool` コールバックを通じてプロンプトされます | Claude が変更を提案するが実行しないようにしたい場合、例えばコードレビュー中または変更を実行する前に承認する必要がある場合 |259| `"plan"` | Claude はソースファイルを編集せずに探索して計画を作成します。ファイル編集は自動承認されず、`canUseTool` コールバックを通じてプロンプトされます | Claude が変更を提案するが実行しないようにしたい場合、例えばコードレビュー中または変更を実行する前に承認する必要がある場合 |

248| `"dontAsk"` | プロンプトしません。[権限ルール](/docs/ja/settings-reference#permission-settings)によって事前承認されたツールが実行され、その他はすべて拒否されます。`AskUserQuestion`、組織が[`ask` に設定](/docs/ja/mcp#organization-controls-on-connector-tools)したコネクタツール、および[`requiresUserInteraction`](/docs/ja/mcp#require-approval-for-a-specific-tool)とマークされた MCP ツールは、許可していても拒否されます | ヘッドレスエージェント用に固定で明示的なツール表面を望み、`canUseTool` が存在しないことへの暗黙的な依存よりもハード拒否を優先する |260| `"dontAsk"` | プロンプトしません。[権限ルール](/docs/ja/settings-reference#permission-settings)によって事前承認されたツールが実行され、`default` モードで承認が不要な呼び出し（作業ディレクトリ内のファイル読み取りなど）も実行されます。それ以外のプロンプトが表示される呼び出しはすべて拒否されます。`AskUserQuestion`、組織が[`ask` に設定](/docs/ja/mcp#organization-controls-on-connector-tools)したコネクタツール、および[`requiresUserInteraction`](/docs/ja/mcp#require-approval-for-a-specific-tool)とマークされた MCP ツールは、許可していても拒否されます | ヘッドレスエージェント用に固定で明示的なツール表面を望み、`canUseTool` が存在しないことへの暗黙的な依存よりもハード拒否を優先する |

249| `"auto"` | モデル分類器を使用して権限プロンプトを承認または拒否します。利用可能性と動作については、[Auto mode](/docs/ja/permission-modes#eliminate-prompts-with-auto-mode)を参照してください | ツール使用に対する安全ガードレールを望む自律型エージェント |261| `"auto"` | モデル分類器を使用して権限プロンプトを承認または拒否します。利用可能性と動作については、[Auto mode](/docs/ja/permission-modes#eliminate-prompts-with-auto-mode)を参照してください | ツール使用に対する安全ガードレールを望む自律型エージェント |

250| `"bypassPermissions"` | 明示的な[`ask` ルール](/docs/ja/settings-reference#permission-settings)に一致するツール、組織が[`ask` に設定](/docs/ja/mcp#organization-controls-on-connector-tools)したコネクタツール、およびユーザーインタラクションが必要なツールを除き、尋ねずにすべての許可されたツールを実行します。[クロスセッションメッセージングセーフガード](/docs/ja/permission-modes#skip-all-checks-with-bypasspermissions-mode)は引き続き適用されます。権限がどのように評価されるかについては、[権限の評価方法](/docs/ja/agent-sdk/permissions#how-permissions-are-evaluated)を参照してください。TypeScript SDK では、`options` で `allowDangerouslySkipPermissions: true` も必要です。Unix でルートとして実行する場合は使用できません。エージェントのアクションが気にするシステムに影響を与えられない隔離環境でのみ使用します | CI、コンテナ、またはその他の隔離環境 |262| `"bypassPermissions"` | 明示的な[`ask` ルール](/docs/ja/settings-reference#permission-settings)に一致するツール、組織が[`ask` に設定](/docs/ja/mcp#organization-controls-on-connector-tools)したコネクタツール、およびユーザーインタラクションが必要なツールを除き、尋ねずにすべての許可されたツールを実行します。[クロスセッションメッセージングセーフガード](/docs/ja/permission-modes#skip-all-checks-with-bypasspermissions-mode)は引き続き適用されます。権限がどのように評価されるかについては、[権限の評価方法](/docs/ja/agent-sdk/permissions#how-permissions-are-evaluated)を参照してください。TypeScript SDK では、`options` で `allowDangerouslySkipPermissions: true` も必要です。Unix でルートとして実行する場合は使用できません。エージェントのアクションが気にするシステムに影響を与えられない隔離環境でのみ使用します | CI、コンテナ、またはその他の隔離環境 |

251 263 

506* **長時間または高コストのタスクを実行していますか？** 隔離された作業を[サブエージェント](/docs/ja/agent-sdk/subagents)にオフロードして、メインコンテキストをリーンに保ちます。518* **長時間または高コストのタスクを実行していますか？** 隔離された作業を[サブエージェント](/docs/ja/agent-sdk/subagents)にオフロードして、メインコンテキストをリーンに保ちます。

507* **サービスとしてデプロイしていますか？** コンテナおよびサーバーレスガイダンスについては[Agent SDK のホスティング](/docs/ja/agent-sdk/hosting)を参照し、セッションを独自のバックエンドに永続化するには[セッションストレージ](/docs/ja/agent-sdk/session-storage)を参照してください。519* **サービスとしてデプロイしていますか？** コンテナおよびサーバーレスガイダンスについては[Agent SDK のホスティング](/docs/ja/agent-sdk/hosting)を参照し、セッションを独自のバックエンドに永続化するには[セッションストレージ](/docs/ja/agent-sdk/session-storage)を参照してください。

508 520 

509agentic ループのより広い概念的な図（SDK 固有ではない）については、[Claude Code の仕組み](/docs/ja/how-claude-code-works)を参照してください。Claude Code でループを設計するための実践的なガイド（ターンベースループからゴールベースループおよびプロアクティブループまで）については、ブログの[ループエンジニアリング：ループの開始](/docs/ja/blog/getting-started-with-loops)を参照してください。521agentic ループのより広い概念的な図（SDK 固有ではない）については、[Claude Code の仕組み](/docs/ja/how-claude-code-works)を参照してください。Claude Code でループを設計するための実践的なガイド（ターンベースループからゴールベースループおよびプロアクティブループまで）については、ブログの[ループエンジニアリング：ループの開始](https://claude.com/blog/getting-started-with-loops)を参照してください。

338`tools` オプションと許可/禁止リストは、2 つのレイヤーに影響します。可用性はツールが Claude のコンテキストに表示されるかどうかを制御し、権限は Claude がツールを試みた後に呼び出しが承認されるかどうかを制御します。`tools` と単純名の `disallowedTools` エントリは可用性を変更します。`allowedTools` とスコープ付き `disallowedTools` ルールは権限を変更します。[タスク追跡ツール](/docs/ja/agent-sdk/todo-tracking#model-availability)の 1 つを `allowedTools` に名前を付けた場合、Claude Code もセッションをオプトインします。338`tools` オプションと許可/禁止リストは、2 つのレイヤーに影響します。可用性はツールが Claude のコンテキストに表示されるかどうかを制御し、権限は Claude がツールを試みた後に呼び出しが承認されるかどうかを制御します。`tools` と単純名の `disallowedTools` エントリは可用性を変更します。`allowedTools` とスコープ付き `disallowedTools` ルールは権限を変更します。[タスク追跡ツール](/docs/ja/agent-sdk/todo-tracking#model-availability)の 1 つを `allowedTools` に名前を付けた場合、Claude Code もセッションをオプトインします。

339 339 

340| オプション | レイヤー | 効果 |340| オプション | レイヤー | 効果 |

341| :------------------------ | :--- | :--------------------------------------------------------------------------------------------------------------------------------- |341| :------------------------ | :--- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

342| `tools: ["Read", "Grep"]` | 可用性 | リストされた組み込みツールのみが Claude のコンテキストに含まれます。リストされていない組み込みツールは削除されます。MCP ツールは影響を受けません。 |342| `tools: ["Read", "Grep"]` | 可用性 | リストされた組み込みツールのみが Claude のコンテキストに含まれます。リストされていない組み込みツールは削除されます。MCP ツールは影響を受けません。 |

343| `tools: []` | 可用性 | すべての組み込みツールが削除されます。Claude は MCP ツールのみを使用できます。 |343| `tools: []` | 可用性 | すべての組み込みツールが削除されます。Claude は MCP ツールのみを使用できます。 |

344| 許可されたツール | 権限 | リストされたツールは権限プロンプトなしで実行されます。その他のリストされていないツールは利用可能なままです。呼び出しは[権限フロー](/docs/ja/agent-sdk/permissions)を通じて行われます。 |344| 許可されたツール | 権限 | リストされたツールは権限プロンプトなしで実行されます。その他のリストされていないツールは利用可能なままです。呼び出しは[権限フロー](/docs/ja/agent-sdk/permissions)を通じて行われます。 |

345| 禁止されたツール | 両方 | `"Bash"` などの単純なツール名は、`tools` から省略するのと同じように、ツールを Claude のコンテキストから削除します。`"Bash(rm *)"` などのスコープ付きルールは、ツールをコンテキストに残し、一致する呼び出しのみを拒否します。 |345| 禁止されたツール | 両方 | `"Bash"` などの単純なツール名は、`tools` から省略するのと同じように、ツールを Claude のコンテキストから削除します。`"Bash(rm *)"` などのスコープ付きルールは、ツールをコンテキストに残し、[記述されたとおり](/docs/ja/permissions#bash-rule-limits)一致する呼び出しのみを拒否します。 |

346 346 

347組み込みツールを完全に削除するには、`tools` から省略するか、`disallowedTools`（Python: `disallowed_tools`）に単純名をリストします。どちらもツールをコンテキストから除外するため、Claude はそれを試みることはありません。スコープ付き `disallowedTools` ルールは一致する呼び出しをブロックしますが、ツールを表示したままにするため、Claude はそれを試みるターンを無駄にする可能性があります。評価順序の詳細については、[権限の設定](/docs/ja/agent-sdk/permissions)を参照してください。347組み込みツールを完全に削除するには、`tools` から省略するか、`disallowedTools`（Python: `disallowed_tools`）に単純名をリストします。どちらもツールをコンテキストから除外するため、Claude はそれを試みることはありません。スコープ付き `disallowedTools` ルールは一致する呼び出しをブロックしますが、ツールを表示したままにするため、Claude はそれを試みるターンを無駄にする可能性があります。評価順序の詳細については、[権限の設定](/docs/ja/agent-sdk/permissions)を参照してください。

348 348 

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

4 

5# 例

6 

7> 構築したいものに合致する完全で実行可能な Agent SDK プロジェクト、または Claude Cookbook のガイド付きレシピを見つけてください。

8 

9このページは、完全で実行可能な Agent SDK プロジェクトとガイド付き Claude Cookbook レシピへのルートを提供します。TypeScript アプリケーションは [`claude-agent-sdk-demos`](https://github.com/anthropics/claude-agent-sdk-demos) リポジトリに、Python レシピは [Claude Cookbook](https://platform.claude.com/cookbook) に存在します。

10 

11<h2 id="run-a-minimal-agent-first">

12 まず最小限のエージェントを実行する

13</h2>

14 

15SDK でまだ何も構築していない場合は、完全なアプリケーションの前に、以下のいずれかから始めてください。

16 

17* [Agent SDK クイックスタート](/docs/ja/agent-sdk/quickstart)：TypeScript または Python で最初に動作するエージェントを構築します。セットアップ手順が含まれています。エージェントはサンプルファイル内のバグを検出して修正します。

18 

19* [Hello World](https://github.com/anthropics/claude-agent-sdk-demos/tree/main/hello-world)：リポジトリコードから開始したい場合にクローンする最小限の TypeScript プロジェクト

20 

21<h2 id="explore-a-typescript-application">

22 TypeScript アプリケーションを探索する

23</h2>

24 

25[`claude-agent-sdk-demos`](https://github.com/anthropics/claude-agent-sdk-demos) の TypeScript アプリケーションは、メールクライアントからマルチエージェント研究システムまで、ローカル開発用のデモです。構築しているものの形状に合致するデモをクローンしてください。

26 

27<h2 id="work-through-a-python-recipe">

28 Python レシピを実行する

29</h2>

30 

31Claude Cookbook の Agent SDK シリーズは、各レシピが Python ノートブックである一連のレシピで、シンプルな研究エージェントから洗練されたマルチエージェントシステムへと進行します。各ノートブックは前のものに基づいており、新しい概念と機能を導入します。[ワンライナー研究エージェント](https://platform.claude.com/cookbook/claude-agent-sdk-00-the-one-liner-research-agent) から始めて、前に進んでください。

32 

33Claude 製品全体のレシピについては、完全な [Claude Cookbook](https://platform.claude.com/cookbook) を参照してください。

840 840 

841リモートサーバーのステータスは、`"connected"` を報告した後でも変わる可能性があります。セッション中に接続が切れると、Claude Code はサーバーを `"pending"` に戻して [再接続](/docs/ja/mcp#automatic-reconnection) します。その後、TypeScript で `mcpServerStatus()` を呼び出すか、Python で [`ClaudeSDKClient.get_mcp_status()`](/docs/ja/agent-sdk/python#methods) を呼び出すと、あなた側で設定変更がなくても、以前に接続されていたサーバーに対して `"pending"` を報告できます。841リモートサーバーのステータスは、`"connected"` を報告した後でも変わる可能性があります。セッション中に接続が切れると、Claude Code はサーバーを `"pending"` に戻して [再接続](/docs/ja/mcp#automatic-reconnection) します。その後、TypeScript で `mcpServerStatus()` を呼び出すか、Python で [`ClaudeSDKClient.get_mcp_status()`](/docs/ja/agent-sdk/python#methods) を呼び出すと、あなた側で設定変更がなくても、以前に接続されていたサーバーに対して `"pending"` を報告できます。

842 842 

8435 回の再接続試行が失敗した後、サーバーは `"failed"` を報告するか、再度認可が必要な場合は `"needs-auth"` を報告します。手動で再試行するには、TypeScript で [`reconnectMcpServer()`](/docs/ja/agent-sdk/python#methods) を呼び出すか、Python で [`ClaudeSDKClient.reconnect_mcp_server()`](/docs/ja/agent-sdk/python#methods) を呼び出してください。8435 回の再接続試行が失敗した後、サーバーは `"failed"` を報告するか、再度認可が必要な場合は `"needs-auth"` を報告します。手動で再試行するには、TypeScript で [`reconnectMcpServer()`](/docs/ja/agent-sdk/typescript#methods) を呼び出すか、Python で [`ClaudeSDKClient.reconnect_mcp_server()`](/docs/ja/agent-sdk/python#methods) を呼び出してください。

844 844 

845<h2 id="troubleshooting">845<h2 id="troubleshooting">

846 トラブルシューティング846 トラブルシューティング

924 ツール出力が最大許容トークン数を超える924 ツール出力が最大許容トークン数を超える

925</h3>925</h3>

926 926 

927SDK は Claude Code と同じ MCP 出力制限を適用します。ツール結果が 25,000 トークンより大きい場合、完全な出力はファイルに保存され、ツール結果はファイルパスを名前とするエラーメッセージに置き換えられるため、エージェントは出力を部分的に読み戻すことができます。[`MAX_MCP_OUTPUT_TOKENS`](/docs/ja/env-vars) 環境変数で制限を引き上げます。完全な動作については [MCP 出力制限と警告](/docs/ja/mcp#mcp-output-limits-and-warnings) を参照してください。これには、サーバーが `anthropic/maxResultSizeChars` アノテーションでツールごとの高い制限を宣言する方法も含まれます。927SDK は Claude Code と同じ MCP 出力制限を適用します。画像コンテンツのないツール結果が 25,000 トークンより大きい場合、Claude Code は出力をファイルに保存し、ツール結果をファイルパスを名前とするエラーメッセージに置き換えるため、エージェントは出力を部分的に読み戻すことができます。

928 

929[`MAX_MCP_OUTPUT_TOKENS`](/docs/ja/env-vars) 環境変数で制限を引き上げます。完全な動作については [MCP 出力制限と警告](/docs/ja/mcp#mcp-output-limits-and-warnings) を参照してください。これには、サーバーが `anthropic/maxResultSizeChars` アノテーションでツールごとの高い制限を宣言する方法も含まれます。

928 930 

929<h2 id="related-resources">931<h2 id="related-resources">

930 関連リソース932 関連リソース

44 エージェントの動作をカスタマイズする44 エージェントの動作をカスタマイズする

45</h2>45</h2>

46 46 

47出力スタイル、`append`、およびカスタムプロンプト文字列は、それぞれシステムプロンプトを直接変更します。CLAUDE.md は異なるパスを取ります。SDK がそれを読み込み、システムプロンプトではなくプロジェクトコンテキストとして会話に内容を注入するため、選択したシステムプロンプトに関係なく動作を形作ります。[Skills](/docs/ja/agent-sdk/skills)、[hooks](/docs/ja/agent-sdk/hooks)、および[permissions](/docs/ja/agent-sdk/permissions)もシステムプロンプト外で動作を形作り、独自のページで説明されています。47`append` とカスタムプロンプト文字列は、それぞれシステムプロンプトを直接変更します。また、出力スタイルは Claude Code が毎回の応答で Claude に与える命令を変更します。CLAUDE.md は異なるパスを取ります。SDK がそれを読み込み、システムプロンプトではなくプロジェクトコンテキストとして会話に内容を注入するため、選択したシステムプロンプトに関係なく動作を形作ります。[Skills](/docs/ja/agent-sdk/skills)、[hooks](/docs/ja/agent-sdk/hooks)、および[permissions](/docs/ja/agent-sdk/permissions)もシステムプロンプト外で動作を形作り、独自のページで説明されています。

48 48 

49<h3 id="claude-md-files-for-project-level-instructions">49<h3 id="claude-md-files-for-project-level-instructions">

50 プロジェクトレベルの命令用の CLAUDE.md ファイル50 プロジェクトレベルの命令用の CLAUDE.md ファイル

118 永続的な設定のための出力スタイル118 永続的な設定のための出力スタイル

119</h3>119</h3>

120 120 

121出力スタイルは Claude のシステムプロンプトを変更する保存された設定です。マークダウンファイルとして保存され、セッションとプロジェクト全体で再利用できます。121出力スタイルは、Claude のロール、トーン、および出力形式を変更する保存された命令セットです。マークダウンファイルとして保存され、セッションとプロジェクト全体で再利用できます。

122 122 

123<h4 id="create-an-output-style">123<h4 id="create-an-output-style">

124 出力スタイルを作成する124 出力スタイルを作成する

387* マーカーを複数回含める場合、最初のマーカーが分割であり、SDK は他のマーカーを削除します。387* マーカーを複数回含める場合、最初のマーカーが分割であり、SDK は他のマーカーを削除します。

388* マーカーを除外する場合、SDK はすべての文字列を 1 つのブロックに結合します。これは 1 つの文字列を渡すのと同じです。388* マーカーを除外する場合、SDK はすべての文字列を 1 つのブロックに結合します。これは 1 つの文字列を渡すのと同じです。

389 389 

390<h3 id="change-the-prompt-of-an-existing-session">

391 既存のセッションのプロンプトを変更する

392</h3>

393 

394デフォルトでは、Claude Code はセッションの最初のリクエストでシステムプロンプトを 1 回構築し、`append` テキストまたはカスタムプロンプトを含めて、セッションに記録します。セッションがコンパクト化されるまで、その後のすべてのリクエストは、`resume` または `continue` でセッションに戻った後でも、その記録されたプロンプトを使用します。その後の呼び出しで異なる `append` またはカスタムプロンプトを渡す場合、セッションがコンパクト化されるか、新しいセッションで効果が発生します。

395 

396[bare mode](/docs/ja/headless#start-faster-with-bare-mode)で Claude Code を起動する場合、`--bare` を `extraArgs` で渡すか、`CLAUDE_CODE_SIMPLE=1` を設定して、記録はオフのままです。ただし、`systemPrompt` のオブジェクト形式で `snapshot: true` を設定する場合を除きます。デフォルトで `append` またはカスタムプロンプトを記録するには、Claude Code v2.1.265 以降が必要です。これは TypeScript Agent SDK v0.3.265 からバンドルされています。Claude Code v2.1.268 より前では、[feature flags](/docs/ja/env-vars#features-that-need-feature-flag-fetching)を取得しないセッション（Amazon Bedrock、Google Cloud の Agent Platform、Microsoft Foundry を含む）は、すべてのリクエストでプロンプトを再構築し、`snapshot` は効果がありませんでした。

397 

398代わりにすべてのリクエストでプロンプトを再構築するには、TypeScript SDK の `systemPrompt` のオブジェクト形式で `snapshot: false` を設定します。`{ type: "preset", preset: "claude_code", append, snapshot: false }` または `{ type: "custom", prompt, snapshot: false }`。プロンプトの表現を反復処理する場合、または同じセッションを再開する呼び出し間で `append` を変更するアプリケーションの場合は、このフォームを使用します。`snapshot` フィールドには `@anthropic-ai/claude-agent-sdk` v0.3.257 以降が必要です。

399 

390<h2 id="compare-the-four-approaches">400<h2 id="compare-the-four-approaches">

391 4 つのアプローチすべての比較401 4 つのアプローチすべての比較

392</h2>402</h2>

934| `agents` | `dict[str, AgentDefinition] \| None` | `None` | プログラムで定義されたサブエージェント |934| `agents` | `dict[str, AgentDefinition] \| None` | `None` | プログラムで定義されたサブエージェント |

935| `plugins` | `list[SdkPluginConfig]` | `[]` | ローカルパスからカスタムプラグインを読み込みます。詳細については [プラグイン](/docs/ja/agent-sdk/plugins) を参照 |935| `plugins` | `list[SdkPluginConfig]` | `[]` | ローカルパスからカスタムプラグインを読み込みます。詳細については [プラグイン](/docs/ja/agent-sdk/plugins) を参照 |

936| `sandbox` | [`SandboxSettings`](#sandboxsettings) ` \| None` | `None` | プログラムでサンドボックス動作を設定します。詳細については [サンドボックス設定](#sandboxsettings) を参照 |936| `sandbox` | [`SandboxSettings`](#sandboxsettings) ` \| None` | `None` | プログラムでサンドボックス動作を設定します。詳細については [サンドボックス設定](#sandboxsettings) を参照 |

937| `setting_sources` | `list[SettingSource] \| None` | `None`（CLI デフォルト：すべてのソース） | 読み込むファイルシステム設定を制御します。`[]` を渡してユーザー、プロジェクト、ローカル設定を無効にします。管理ポリシー設定は常に読み込まれます。[Claude Code 機能を使用](/docs/ja/agent-sdk/claude-code-features#what-settingsources-does-not-control) を参照 |937| `setting_sources` | `list[SettingSource] \| None` | `None`（CLI デフォルト：すべてのソース） | 読み込むファイルシステム設定を制御します。`[]` を渡してユーザー、プロジェクト、ローカル設定を無効にします。管理ポリシー設定は常に読み込まれます。[適格な設定](/docs/ja/server-managed-settings#platform-availability) 上の組織認証情報でセッションが認証されるときに、サーバー管理設定が取得されます。[Claude Code 機能を使用](/docs/ja/agent-sdk/claude-code-features#what-settingsources-does-not-control) を参照 |

938| `skills` | `list[str] \| Literal["all"] \| None` | `None` | セッションで利用可能なスキル。すべての検出されたスキルを有効にするには `"all"` を渡すか、スキル名のリストを渡します。正確な名前のみを渡します。SDK は Claude Code プロセスを開始する前に、形式が正しくないワイルドカード形式の名前を `ValueError` で拒否します。このチェックには Python Agent SDK 0.2.129 以降が必要です。設定すると、SDK は `allowed_tools` に Skill ツールを自動的に追加します。`tools` も渡す場合は、そのリストに `"Skill"` を含めます。[スキル](/docs/ja/agent-sdk/skills) を参照 |938| `skills` | `list[str] \| Literal["all"] \| None` | `None` | セッションで利用可能なスキル。すべての検出されたスキルを有効にするには `"all"` を渡すか、スキル名のリストを渡します。正確な名前のみを渡します。SDK は Claude Code プロセスを開始する前に、形式が正しくないワイルドカード形式の名前を `ValueError` で拒否します。このチェックには Python Agent SDK 0.2.129 以降が必要です。設定すると、SDK は `allowed_tools` に Skill ツールを自動的に追加します。`tools` も渡す場合は、そのリストに `"Skill"` を含めます。[スキル](/docs/ja/agent-sdk/skills) を参照 |

939| `max_thinking_tokens` | `int \| None` | `None` | *非推奨* - 思考ブロックの最大トークン数。代わりに `thinking` を使用してください |939| `max_thinking_tokens` | `int \| None` | `None` | *非推奨* - 思考ブロックの最大トークン数。代わりに `thinking` を使用してください |

940| `thinking` | [`ThinkingConfig`](#thinkingconfig) ` \| None` | `None` | 拡張思考動作を制御します。`max_thinking_tokens` より優先されます |940| `thinking` | [`ThinkingConfig`](#thinkingconfig) ` \| None` | `None` | 拡張思考動作を制御します。`max_thinking_tokens` より優先されます |

1181| `maxTurns` | いいえ | エージェントが停止する前の最大 agentic ターン数 |1181| `maxTurns` | いいえ | エージェントが停止する前の最大 agentic ターン数 |

1182| `background` | いいえ | 呼び出されたときにこのエージェントをブロッキングされないバックグラウンドタスクとして実行します |1182| `background` | いいえ | 呼び出されたときにこのエージェントをブロッキングされないバックグラウンドタスクとして実行します |

1183| `effort` | いいえ | このエージェントの推論努力レベル。名前付きレベルまたは整数を受け入れます。[`EffortLevel`](#effortlevel) を参照 |1183| `effort` | いいえ | このエージェントの推論努力レベル。名前付きレベルまたは整数を受け入れます。[`EffortLevel`](#effortlevel) を参照 |

1184| `permissionMode` | いいえ | このエージェント内のツール実行のパーミッションモード。[`PermissionMode`](#permissionmode) を参照 |1184| `permissionMode` | いいえ | このエージェント内のツール実行のパーミッションモード。[サブエージェント継承ルール](/docs/ja/agent-sdk/permissions#available-modes) は、それが適用される場合を決定します。[`PermissionMode`](#permissionmode) を参照 |

1185 1185 

1186<Note>1186<Note>

1187 `AgentDefinition` フィールド名は `disallowedTools`、`permissionMode`、`maxTurns` などの camelCase を使用します。これらの名前は TypeScript SDK と共有される wire 形式に直接マップされます。これは `disallowed_tools` と `permission_mode` などの同等のトップレベルフィールドに Python snake\_case を使用する `ClaudeAgentOptions` とは異なります。`AgentDefinition` は dataclass であるため、snake\_case キーワードを渡すと構築時に `TypeError` が発生します。1187 `AgentDefinition` フィールド名は `disallowedTools`、`permissionMode`、`maxTurns` などの camelCase を使用します。これらの名前は TypeScript SDK と共有される wire 形式に直接マップされます。これは `disallowed_tools` と `permission_mode` などの同等のトップレベルフィールドに Python snake\_case を使用する `ClaudeAgentOptions` とは異なります。`AgentDefinition` は dataclass であるため、snake\_case キーワードを渡すと構築時に `TypeError` が発生します。

2885 2885 

2886バックグラウンドソースを実行し、各イベントを Claude に配信して、ポーリングなしで反応できるようにします。`command` はスクリプトを実行し、stdout 行ごとに 1 つのイベントを発行し、`ws` は WebSocket を開き、テキストフレームごとに 1 つのイベントを発行します。`command` または `ws` のいずれか 1 つを正確に指定してください。2886バックグラウンドソースを実行し、各イベントを Claude に配信して、ポーリングなしで反応できるようにします。`command` はスクリプトを実行し、stdout 行ごとに 1 つのイベントを発行し、`ws` は WebSocket を開き、テキストフレームごとに 1 つのイベントを発行します。`command` または `ws` のいずれか 1 つを正確に指定してください。

2887 2887 

2888Monitor がコマンドを実行する場合、Bash と同じパーミッションルールに従います。WebSocket ウォッチは別途承認を求めます。`ws` ソースには Claude Code v2.1.195 以降が必要です。動作とプロバイダーの可用性については、[Monitor ツールリファレンス](/docs/ja/tools-reference#monitor-tool) を参照してください。2888Monitor がコマンドを実行する場合、Bash と同じパーミッション規則に従います。WebSocket ウォッチは別途承認を求めます。`ws` ソースには Claude Code v2.1.195 以降が必要です。動作とプロバイダーの可用性については、[Monitor ツールリファレンス](/docs/ja/tools-reference#monitor-tool) を参照してください。

2889 2889 

2890**入力：**2890**入力：**

2891 2891 

3163**ツール名：** `TodoWrite`3163**ツール名：** `TodoWrite`

3164 3164 

3165<Note>3165<Note>

3166 Python Agent SDK 0.2.139 以降では、以下の制限が適用されます。

3167 

3168 The following tools are available by default only on Claude 3.x models, Opus 4 through 4.7, Sonnet 4 through 4.6, and Haiku 4.5. On every other model, including model IDs Claude Code doesn't recognize, they aren't available unless you opt in:3166 The following tools are available by default only on Claude 3.x models, Opus 4 through 4.7, Sonnet 4 through 4.6, and Haiku 4.5. On every other model, including model IDs Claude Code doesn't recognize, they aren't available unless you opt in:

3169 3167 

3170 * `TodoWrite`3168 * `TodoWrite`

3325 3323 

3326**ツール名：** `TaskOutput`。以前の名前 `BashOutput` はまだエイリアスとして受け入れられています。3324**ツール名：** `TaskOutput`。以前の名前 `BashOutput` はまだエイリアスとして受け入れられています。

3327 3325 

3328<Note>`TaskOutput` は非推奨です。タスクの出力ファイルパスで `Read` を使用することをお勧めします。以下のスキーマは、ツールを遭遇するフック と権限ハンドラーに対して有効なままです。</Note>3326<Note>`TaskOutput` は非推奨です。タスクの出力ファイルパスで `Read` を使用することをお勧めします。以下のスキーマは、ツールを遭遇するフックと権限ハンドラーに対して有効なままです。</Note>

3329 3327 

3330**入力：**3328**入力：**

3331 3329 

102 uuid: UUID;102 uuid: UUID;

103 session_id: string;103 session_id: string;

104 ttft_ms?: number; // メッセージ開始イベントにのみ存在する、最初のトークンまでの時間（ミリ秒）104 ttft_ms?: number; // メッセージ開始イベントにのみ存在する、最初のトークンまでの時間（ミリ秒）

105 user_message_uuid?: string;

105 };106 };

106 ```107 ```

107</CodeGroup>108</CodeGroup>

108 109 

109`parent_tool_use_id` フィールドは Python では常に `None`、TypeScript では `null` です。ストリームイベントはメインセッションのみに対して発行されます。サブエージェントからのトークンレベルのデルタは転送されません。出力をサブエージェントに属性付けするには、`parent_tool_use_id` を含む完全なメッセージを使用してください。[サブエージェント呼び出しの検出](/docs/ja/agent-sdk/subagents#detect-subagent-invocation)を参照してください。110`parent_tool_use_id` フィールドは Python では常に `None`、TypeScript では `null` です。ストリームイベントはメインセッションのみに対して発行されます。サブエージェントからのトークンレベルのデルタは転送されません。出力をサブエージェントに属性付けするには、`parent_tool_use_id` を含む完全なメッセージを使用してください。[サブエージェント呼び出しの検出](/docs/ja/agent-sdk/subagents#detect-subagent-invocation)を参照してください。

110 111 

111`event` フィールドには、[Claude API](https://platform.claude.com/docs/ja/build-with-claude/streaming#event-types) からの生のストリーミングイベントが含まれます。一般的なイベントタイプは以下の通りです：112Claude Code は、ターンの最初の非 ping ストリームイベントで `user_message_uuid` を設定し、ターンが応答しているメッセージが変わるときに再度設定します。これは [`user_message_uuid`](/docs/ja/agent-sdk/typescript#user_message_uuid) の条件下で行われます。Python の `StreamEvent` はこのフィールドを公開していません。

113 

114`event` フィールドには、[Claude API](https://platform.claude.com/docs/en/build-with-claude/streaming#event-types) からの生のストリーミングイベントが含まれます。一般的なイベントタイプは以下の通りです：

112 115 

113| イベントタイプ | 説明 |116| イベントタイプ | 説明 |

114| :-------------------- | :---------------------------- |117| :-------------------- | :---------------------------- |

123 メッセージフロー126 メッセージフロー

124</h2>127</h2>

125 128 

126部分メッセージが有効な場合、メッセージは以下の順序で受け取ります。129Claude Code は、空でない各コンテンツブロックが完了するたびに `AssistantMessage` を発行します。そのため、テキストブロックとツール呼び出しを含むレスポンスは 2 つの `AssistantMessage` オブジェクトを生成します。各メッセージは独自のコンテンツブロックのみを含み、両方とも同じメッセージ ID を共有します。これは TypeScript では `message.message.id` として、Python では `message.message_id` として読み取ります。部分メッセージが有効な場合、各 `AssistantMessage` はそのブロックの `content_block_stop` イベントの前に到着し、メッセージは以下の順序で受け取ります。

127 130 

128```text theme={null}131```text theme={null}

129StreamEvent (message_start)132StreamEvent (message_start)

130StreamEvent (content_block_start) - text block133StreamEvent (content_block_start) - text block

131StreamEvent (content_block_delta) - text chunks...134StreamEvent (content_block_delta) - text chunks...

135AssistantMessage - complete text block

132StreamEvent (content_block_stop)136StreamEvent (content_block_stop)

133StreamEvent (content_block_start) - tool_use block137StreamEvent (content_block_start) - tool_use block

134StreamEvent (content_block_delta) - tool input chunks...138StreamEvent (content_block_delta) - tool input chunks...

139AssistantMessage - complete tool_use block

135StreamEvent (content_block_stop)140StreamEvent (content_block_stop)

136StreamEvent (message_delta)141StreamEvent (message_delta)

137StreamEvent (message_stop)142StreamEvent (message_stop)

138AssistantMessage - complete message with all content

139... tool executes ...143... tool executes ...

140... more streaming events for next turn ...144... more streaming events for next turn ...

141ResultMessage - final result145ResultMessage - final result

142```146```

143 147 

144部分メッセージが有効でない場合、`StreamEvent` を除くすべてのメッセージタイプを受け取ります。一般的なタイプには `SystemMessage`（セッション初期化）、`AssistantMessage`（完全な応答）、`ResultMessage`（最終結果）、および会話履歴がコンパクト化されたときを示すコンパクト境界メッセージ（TypeScript では `SDKCompactBoundaryMessage`、Python では subtype `"compact_boundary"` の `SystemMessage`）が含まれます。148部分メッセージが有効でない場合、`StreamEvent` を除くすべてのメッセージタイプを受け取ります。一般的なタイプには `SystemMessage`（セッション初期化）、`AssistantMessage`（完全なコンテンツブロック）、`ResultMessage`（最終結果）、および会話履歴がコンパクト化されたときを示すコンパクト境界メッセージ（TypeScript では `SDKCompactBoundaryMessage`、Python では subtype `"compact_boundary"` の `SystemMessage`）が含まれます。

145 149 

146<h2 id="stream-tool-calls">150<h2 id="stream-tool-calls">

147 ツール呼び出しをストリーミングする151 ツール呼び出しをストリーミングする

6 6 

7> Agent SDK セッションで todo を追跡し、構造化されたツール呼び出しから Claude の進捗をアプリケーションでレンダリングします7> Agent SDK セッションで todo を追跡し、構造化されたツール呼び出しから Claude の進捗をアプリケーションでレンダリングします

8 8 

9[モデル利用可能性](#model-availability)に記載されているモデルでは、Claude は書かれた todo リストなしで複数ステップの作業を追跡し、Claude Code はデフォルトでセッションから[タスク追跡ツール](/docs/ja/tools-reference#task-tool-availability)を除外します。これらのモデルで Claude が複数ステップのタスクを処理するために、このページの内容は必要ありません。9Claude Code は、[モデル利用可能性](#model-availability)に記載されているモデルでのみデフォルトで[タスク追跡ツール](/docs/ja/tools-reference#task-tool-availability)を提供します。新しいモデルは書かれた todo リストなしで複数ステップの作業を追跡するため、これらのモデルでは Claude が複数ステップのタスクを処理するためにこのページの内容は必要ありません。

10 10 

11タスク追跡ツールを持つセッションでは、Claude は書かれた todo リストを保持し、作業を進めるにつれて各アイテムのステータスを更新します。メッセージストリーム内で各変更が構造化されたツール呼び出しとして表示されます。アプリケーションがこれらのツール呼び出しを読み取る場合にのみセッションをオプトインしてください。タスク活動をログするか、独自の進捗表示をレンダリングするかどうかに関わらず。11タスク追跡ツールを持つセッションでは、Claude は書かれた todo リストを保持し、作業を進めるにつれて各アイテムのステータスを更新します。メッセージストリーム内で各変更が構造化されたツール呼び出しとして表示されます。アプリケーションがこれらのツール呼び出しを読み取る場合にのみセッションをオプトインしてください。タスク活動をログするか、独自の進捗表示をレンダリングするかどうかに関わらず。

12 12 

15</h2>15</h2>

16 16 

17<Note>17<Note>

18 TypeScript Agent SDK 0.3.233 以降、または Python Agent SDK 0.2.139 以降では、以下の制限が適用されます。

19 

20 The following tools are available by default only on Claude 3.x models, Opus 4 through 4.7, Sonnet 4 through 4.6, and Haiku 4.5. On every other model, including model IDs Claude Code doesn't recognize, they aren't available unless you opt in:18 The following tools are available by default only on Claude 3.x models, Opus 4 through 4.7, Sonnet 4 through 4.6, and Haiku 4.5. On every other model, including model IDs Claude Code doesn't recognize, they aren't available unless you opt in:

21 19 

22 * `TodoWrite`20 * `TodoWrite`

30 This default set applies in Claude Code v2.1.268 and later, which the TypeScript Agent SDK bundles from v0.3.268.28 This default set applies in Claude Code v2.1.268 and later, which the TypeScript Agent SDK bundles from v0.3.268.

31</Note>29</Note>

32 30 

33記載されているモデルでは、セッションをオプトインしない限り、メッセージストリーム内でこれらのツールの `tool_use` ブロックは表示されません。Agent SDK は、バンドルされている Claude Code バイナリを通じてこれらのデフォルトを適用します。`pathToClaudeCodeExecutable`（TypeScript）または `cli_path`（Python）を独自の Claude Code インストールに指定する場合、そのインストールが提供するツールが、独自のデフォルトの下で取得されます。実行中のセッションで正確なセットを確認するには、[利用可能なツールを確認](/docs/ja/tools-reference#check-which-tools-are-available)してください。セッションをオプトインするには、以下のいずれかを実行してください：31デフォルトではツールを持たないモデルでは、セッションをオプトインしない限り、メッセージストリーム内でこれらのツールの `tool_use` ブロックは表示されません。Agent SDK は、バンドルされている Claude Code バイナリを通じてこれらのデフォルトを適用します。`pathToClaudeCodeExecutable`（TypeScript）または `cli_path`（Python）を独自の Claude Code インストールに指定する場合、そのインストールが提供するツールが、独自のデフォルトの下で取得されます。実行中のセッションで正確なセットを確認するには、[利用可能なツールを確認](/docs/ja/tools-reference#check-which-tools-are-available)してください。セッションをオプトインするには、以下のいずれかを実行してください：

34 32 

35* [`allowedTools`](/docs/ja/agent-sdk/permissions#allow-and-deny-rules)（TypeScript）または `allowed_tools`（Python）オプションでツールの 1 つに名前を付ける33* [`allowedTools`](/docs/ja/agent-sdk/permissions#allow-and-deny-rules)（TypeScript）または `allowed_tools`（Python）オプションでツールの 1 つに名前を付ける

36* `tools` オプションにツールをリストします。これはセッションの組み込みツールを、それが名前を付けるものに制限します。使用する他の組み込みツールと一緒に必要なツールを含めます34* `tools` オプションにツールをリストします。これはセッションの組み込みツールを、それが名前を付けるものに制限します。使用する他の組み込みツールと一緒に必要なツールを含めます

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

4 

5# Agent SDK のトラブルシューティング

6 

7> Agent SDK エラーを表示されたメッセージで修正します。TypeScript と Python SDK の各エラーについて、原因と対処方法を説明します。

8 

9このページのエントリは、表示されるエラーに対応しています。各エントリは原因と対処方法を示しています。

10 

11<h2 id="cli-startup">

12 CLI スタートアップ

13</h2>

14 

15<h3 id="clinotfounderror-claude-code-not-found">

16 CLINotFoundError: Claude Code not found

17</h3>

18 

19Python SDK は Claude Code CLI をサブプロセスとして起動します。`claude` 実行ファイルが見つからない場合、接続は `CLINotFoundError` で失敗します。

20 

21```

22Claude Code not found at: /your/configured/path

23```

24 

25メッセージには、`ClaudeAgentOptions(cli_path=...)` を設定して存在しないファイルを指している場合、設定されたパスが含まれます。`cli_path` がない場合、SDK は `PATH` と一般的なインストール場所を検索し、メッセージにはプラットフォーム用のインストール手順が含まれます。

26 

27修正するには：

28 

29* Claude Code がインストールされていない場合はインストールしてください。プラットフォーム用のコマンドについては、[Claude Code のインストール](/docs/ja/setup#install-claude-code)を参照してください。

30* `cli_path` を設定した場合は、ファイルが存在し、`claude` 実行ファイルであることを確認してください。

31* `PATH` 解決に依存している場合は、アプリケーションが実行される環境で `claude --version` が機能することを確認してください。IDE やサービスマネージャーなど、シェルの外から起動するプロセスは、多くの場合異なる `PATH` で実行されます。

32 

33TypeScript SDK は、バンドルされたプラットフォームパッケージと `pathToClaudeCodeExecutable` に設定されたパスで CLI を探します。表示されるメッセージに一致させてください：

34 

35* `Native CLI binary for <platform>-<arch> not found`：バンドルされたプラットフォームパッケージが見つかりません。最も一般的には、インストールがオプション依存関係をスキップしたためです。オプション依存関係をスキップせずに `@anthropic-ai/claude-agent-sdk` を再インストールするか、`pathToClaudeCodeExecutable` を[ネイティブインストール](/docs/ja/setup#install-claude-code)に指定してください。`bun build --compile` で構築された単一ファイル実行ファイルでは、同じメッセージが異なる原因と修正方法を持ちます。[単一実行ファイルへのコンパイル](/docs/ja/agent-sdk/typescript#compile-to-a-single-executable)を参照してください。

36* `Claude Code native binary not found at <path>` または `Claude Code executable not found at <path>. Is options.pathToClaudeCodeExecutable set?`：解決されたパスのファイルが見つからないか、プロセスがアクセスできません。ファイルがそのパスに存在し、プロセスがアクセスできることを確認してください。

37 

38<h3 id="cliconnectionerror-refusing-to-execute-batch-script">

39 CLIConnectionError: Refusing to execute batch script

40</h3>

41 

42Windows では、Python SDK が使用する CLI パスが `.bat` または `.cmd` バッチスクリプト（npm インストールが作成する `claude.cmd` シムを含む）の場合、接続は `CLIConnectionError` で失敗します。

43 

44```

45Refusing to execute batch script 'C:\\Users\\you\\AppData\\Roaming\\npm\\claude.cmd': Windows runs .bat/.cmd files via cmd.exe, which can execute commands injected through CLI arguments, and no reliable escaping for cmd.exe exists. Use a native claude executable instead: install Claude Code natively (irm https://claude.ai/install.ps1 | iex), point ClaudeAgentOptions(cli_path=...) at a claude.exe, or install the claude-agent-sdk wheel for a platform that bundles claude.exe (e.g. Windows x64).

46```

47 

48この拒否は意図的なセキュリティ強化であり、インストールが壊れているわけではありません。Windows はバッチスクリプトを `cmd.exe /c` 呼び出しに書き換えて実行し、`cmd.exe` は実行時にコマンドライン全体を再解析するため、引数値は注入されたコマンドを実行できます。

49 

50ほとんどの Windows インストールはこのエラーに到達しません。Windows x64 の `claude-agent-sdk` ホイールは `claude.exe` をバンドルしており、SDK はバンドルされた CLI を優先し、次に発見できるネイティブ `claude.exe` を優先し、その後バッチシムにフォールバックします。拒否は 2 つのケースで表示されます：

51 

52* `ClaudeAgentOptions(cli_path=...)` を `.bat` または `.cmd` ファイル（npm の `claude.cmd` シムなど）に設定した場合。

53* インストールにバンドルされたネイティブ `claude.exe` がない場合。たとえば、ARM64 Windows でのソースインストールで、`PATH` 上の唯一の `claude` が npm シムである場合。

54 

55修正するには、バッチスクリプトの代わりにネイティブ実行ファイルを SDK に提供してください：

56 

57* `ClaudeAgentOptions(cli_path=...)` を設定した場合は、`claude.exe` を指すか、オプションを削除してください。`cli_path` が設定されている間、SDK は検出をスキップするため、ネイティブインストールだけでは効果がありません。

58* PowerShell で Claude Code をネイティブにインストールしてください：`irm https://claude.ai/install.ps1 | iex`

59* x64 Windows では、`claude.exe` をバンドルする `claude-agent-sdk` ホイールをインストールしてください。

60 

61`claude-agent-sdk` 0.2.124 より前では、Python SDK はこのチェックなしで `cmd.exe` を通じてバッチスクリプトを生成していました。

62 

63<h3 id="cliconnectionerror-failed-to-start-claude-code">

64 CLIConnectionError: Failed to start Claude Code

65</h3>

66 

67SDK は解決されたパスでファイルを見つけましたが、起動できませんでした。Python はこれらの失敗を `CLIConnectionError` として発生させます。TypeScript はメッセージ反復を SDK クラスを持たないエラーで拒否します。以下の表は各メッセージを何を示しているかにマップします。表示されるメッセージに一致させてください：

68 

69| メッセージ | SDK | 意味 |

70| ----------------------------------------------------------------- | ---------- | ---------------------------------- |

71| `Failed to start Claude Code: <detail>` | Python | メッセージの残りはオペレーティングシステム自体のエラーです |

72| `Claude Code executable at <path> exists but failed to launch` | TypeScript | 設定されたパスのスクリプトは実行できません |

73| `Claude Code native binary at <path> exists but failed to launch` | TypeScript | バイナリは実行できません。libc の提案がメッセージに追加されます |

74| `Failed to spawn Claude Code process: <detail>` | TypeScript | その他の起動失敗 |

75 

76両方の SDK では、通常の原因は、テキストファイル、ディレクトリ、または実行権限のないファイルなど、実行できないものを指す解決されたパスです。ネイティブバイナリメッセージの libc 提案を 1 つの可能な原因として読んでください。

77 

78どちらの SDK でも修正するには：

79 

80* 設定されたパスが `claude` 実行ファイル自体を指し、ファイルに実行権限があることを確認してください。

81* カスタムパスが不要な場合は、Python で `cli_path` を削除するか、TypeScript で `pathToClaudeCodeExecutable` を削除して、SDK が独自に CLI を見つけるようにしてください。バンドルされたコピーを優先します。

82* 失敗しているバイナリがコンテナイメージ内の SDK のバンドルされたコピーの場合、イメージビルド中に SDK を再インストールして、バンドルされたバイナリがコンテナのプラットフォームと一致するようにするか、実行するアーキテクチャ用にイメージを再構築してください。通常の原因は、コンテナのアーキテクチャまたは libc と一致しないバイナリ、またはイメージビルド中に実行権限を失ったバイナリです。

83 

84<h3 id="cliconnectionerror-not-connected">

85 CLIConnectionError: Not connected

86</h3>

87 

88Python で `ClaudeSDKClient` メソッドを呼び出す前にクライアントが接続していない場合、または接続を切断した後に呼び出すと、`CLIConnectionError` がこのメッセージで発生します：

89 

90```

91Not connected. Call connect() first.

92```

93 

94メッセージが言うことをしてください。他のクライアントメソッドの前に `await client.connect()` を呼び出すか、`async with ClaudeSDKClient() as client:` でクライアントを開いてください。これは入口で接続します。

95 

96<h2 id="cli-process-exit">

97 CLI プロセス終了

98</h2>

99 

100このセクションのエントリは、アプリケーションがそれを使用している間に Claude Code プロセスが終了したことを意味します。表示されるエラーは SDK 言語と、CLI が終了する前にエラー結果を報告したかどうかによって異なります。

101 

102<h3 id="processerror-command-failed-with-exit-code">

103 ProcessError: Command failed with exit code

104</h3>

105 

106Python SDK は Claude Code プロセスが 0 以外のコードで終了すると `ProcessError` を発生させます：

107 

108```

109Command failed with exit code 1 (exit code: 1)

110Error output: Check stderr output for details

111```

112 

113メッセージは終了コードを 2 回述べ、`Error output` 行は固定テキストであり、プロセスの実際のエラー出力ではありません。同じ固定テキストが例外の `stderr` 属性を埋めます。例外の `exit_code` 属性がコードを持ちます。CLI が実際に stderr に書き込んだものをキャプチャするには、`ClaudeAgentOptions` で `stderr` コールバックを渡し、受け取ったものをログしてください。

114 

115単純な `ProcessError` は、CLI がエラー結果を報告せずに終了したことを意味します。CLI がエラー結果を報告した場合、SDK は代わりに [`ResultError`](/docs/ja/agent-sdk/python#resulterror) を発生させます。これは[Claude Code returned an error result](#claude-code-returned-an-error-result)で説明されています。`ResultError` は `ProcessError` をサブクラス化するため、`except ProcessError` は両方をキャッチします。異なる方法で処理するには、`except ResultError` 句を最初に配置してください。

116 

117`claude-agent-sdk` 0.2.140 より前では、Python SDK はエラー結果の終了を `ResultError` ではなく単純な `Exception` として発生させていました。

118 

119<h3 id="claude-code-process-exited-with-code-n">

120 Claude Code process exited with code N

121</h3>

122 

123IDE ラッパーもこのメッセージを出力し、[エラーリファレンス](/docs/ja/errors#claude-code-process-exited-with-code-n)は VS Code およびその他のランチャーをカバーしています。このエントリは TypeScript SDK コードが受け取るものをカバーしています。SDK は 0 以外の CLI 終了を単純な `Error` として表示し、`query()` のメッセージ上の `for await` ループを拒否します。キャッチする SDK エラークラスはないため、ループを `try`/`catch` でラップし、メッセージで一致させてください：

124 

125```

126Claude Code process exited with code 1. stderr: <tail of the CLI's stderr>

127```

128 

129CLI が stderr に書き込んだ場合、メッセージはそれのテールで終わります。完全なストリームをキャプチャするには、クエリオプションで `stderr` コールバックを渡してください。シグナルで強制終了されたプロセスは同じ形式で `Claude Code process terminated by signal <name>` を報告します。

130 

131<h3 id="claude-code-returned-an-error-result">

132 Claude Code returned an error result

133</h3>

134 

135両方の SDK は、CLI が終了する前にエラー結果を報告した場合、プロセス終了エラーをこのメッセージに置き換えます：

136 

137```

138Claude Code returned an error result: <the CLI's own error report>

139```

140 

141コロンの後のテキストは、何が間違ったかについての CLI の報告であるため、終了自体ではなくそこから始めてください。Python はこれを [`ResultError`](/docs/ja/agent-sdk/python#resulterror) として発生させます。その `data` 属性は完全なエラー結果を持ちます。TypeScript は同じメッセージ形式を持つ単純な `Error` でメッセージループを拒否します。

142 

143<h2 id="structured-outputs">

144 構造化出力

145</h2>

146 

147<h3 id="structured_output-is-none-but-the-result-says-success">

148 structured\_output は None ですが、結果は成功と言っています

149</h3>

150 

151結果メッセージは `subtype: "success"` で終わることができますが、Python では `structured_output` は `None` であり、TypeScript では `undefined` です。実行は完了しますが、検証された出力は存在しません。これに到達する 1 つの方法は、出力が満たすことができないスキーマです。たとえば、矛盾する長さの制約があります。実行は検証エラーなしで終了し、唯一の信号は欠落している `structured_output` です。

152 

153アプリケーションコードでこの結果を失敗として扱ってください。`structured_output` を使用する前に、`subtype` が `success` であり、`structured_output` が存在することの両方を確認してください。[エラーハンドリング](/docs/ja/agent-sdk/structured-outputs#error-handling)セクションは両方の SDK のこのパターンを示しています。

154 

155正しいと思われるスキーマで繰り返し発生する場合は、スキーマが満たされることを確認し、出力が検証されるまで単純化し、制約を 1 つずつ再導入してください。

156 

157<h2 id="report-a-new-issue">

158 新しい問題を報告する

159</h2>

160 

161エラーがここでカバーされていない場合は、オープンな問題を確認するか、SDK リポジトリに新しい問題を提出してください：[claude-agent-sdk-typescript](https://github.com/anthropics/claude-agent-sdk-typescript/issues) または [claude-agent-sdk-python](https://github.com/anthropics/claude-agent-sdk-python/issues)。完全なエラーテキストと SDK バージョンを含めてください。

12 12 

13確認質問については、Claude が質問とオプションを生成します。あなたの役割は、それらをユーザーに提示して、ユーザーの選択を返すことです。このフローに独自の質問を追加することはできません。ユーザーに何か尋ねる必要がある場合は、アプリケーションロジックで別途実行してください。13確認質問については、Claude が質問とオプションを生成します。あなたの役割は、それらをユーザーに提示して、ユーザーの選択を返すことです。このフローに独自の質問を追加することはできません。ユーザーに何か尋ねる必要がある場合は、アプリケーションロジックで別途実行してください。

14 14 

15コールバックは無期限に保留中のままにすることができます。実行はコールバックが返されるまで一時停止したままであり、SDK はクエリ自体がキャンセルされた場合にのみ待機をキャンセルします。ユーザーがプロセスが合理的に実行し続けることができるより長く応答するのに時間がかかる可能性がある場合、[`defer` フック決定](/docs/ja/hooks#defer-a-tool-call-for-later)を返します。これにより、プロセスを終了して、後で永続化されたセッションから再開できます。15コールバックは無期限に保留中のままにすることができます。実行はコールバックが返されるまで一時停止したままであり、SDK はクエリ自体がキャンセルされた場合にのみ待機をキャンセルします。ユーザーがプロセスが合理的に実行し続けることができるより長く応答するのに時間がかかる可能性がある場合、[`PreToolUse` フック](/docs/ja/agent-sdk/hooks)を登録して、[`defer` 決定](/docs/ja/hooks#defer-a-tool-call-for-later)を返します。これにより、プロセスを終了して、後で永続化されたセッションから再開できます。

16 16 

17このガイドでは、各タイプのリクエストを検出し、適切に応答する方法を示します。17このガイドでは、各タイプのリクエストを検出し、適切に応答する方法を示します。

18 18 

19<h2 id="detect-when-claude-needs-input">19<h2 id="detect-when-claude-needs-input">

20 Claude が入力を必要とする場合を検出する20 Claude が入力を必要とするタイミングを検出する

21</h2>21</h2>

22 22 

23クエリオプションで `canUseTool` コールバックを渡します。Claude がユーザー入力を必要とするたびにコールバックが発火し、ツール名と入力を引数として受け取ります。23クエリオプションで `canUseTool` コールバックを渡してください。このコールバックは Claude がユーザー入力を必要とするたびに発火し、ツール名と入力を引数として受け取ります。

24 24 

25<CodeGroup>25<CodeGroup>

26 ```python Python theme={null}26 ```python Python theme={null}

27 from claude_agent_sdk import ClaudeAgentOptions

28 

29 

27 async def handle_tool_request(tool_name, input_data, context):30 async def handle_tool_request(tool_name, input_data, context):

28 # ユーザーにプロンプトを表示して、許可または拒否を返す31 # ユーザーにプロンプトを表示して、許可または拒否を返す

29 ...32 ...

44 47 

45コールバックは 2 つのケースで発火します。48コールバックは 2 つのケースで発火します。

46 49 

471. **ツールが承認を必要とする場合**：Claude が [許可ルール](/docs/ja/agent-sdk/permissions)またはモードによって自動承認されていないツールを使用したい場合。`tool_name` でツール（例：`"Bash"`、`"Write"`）を確認します。501. **ツールが承認を必要とする場合**: Claude が [権限ルール](/docs/ja/agent-sdk/permissions) または権限モードで自動承認されていないツールを使用したいとき。`tool_name` でツール（例：`"Bash"`、`"Write"`）を確認してください。

482. **Claude が質問をする場合**：Claude が `AskUserQuestion` ツールを呼び出します。`tool_name == "AskUserQuestion"` をチェックして、異なる方法で処理します。`tools` 配列を指定する場合は、これが機能するように `AskUserQuestion` を含めます。詳細は [確認質問を処理する](#handle-clarifying-questions)を参照してください。512. **Claude が質問をする場合**: Claude が `AskUserQuestion` ツールを呼び出します。`tool_name == "AskUserQuestion"` をチェックして、異なる方法で処理してください。`tools` 配列を指定する場合は、これが機能するように `AskUserQuestion` を含めてください。詳細は [質問の明確化を処理する](#handle-clarifying-questions) を参照してください。

49 52 

50<Warning>53<Warning>

51 **コールバックは自動承認されたツールに対しては発火しません。** [許可評価フロー](/docs/ja/agent-sdk/permissions#how-permissions-are-evaluated)の前の段階での承認、許可ルール、または `acceptEdits` や `bypassPermissions` のようなモードは、`canUseTool` が参照される前に呼び出しを解決します。`allowed_tools` にツールをそのまま列挙する場合、そのツールに対する `canUseTool` チェックは、ask ルールまたは `plan` モードが呼び出しをプロンプトに戻さない限り実行されません。すべてのツール呼び出しに適用する必要があるロジックについては、[`PreToolUse` フック](/docs/ja/agent-sdk/hooks)を使用してください。このフックはフローの残りの部分の前に実行され、リクエストを許可、拒否、または変更できます。54 **コールバックは自動承認されたツールに対しては発火しません。** [権限評価フロー](/docs/ja/agent-sdk/permissions#how-permissions-are-evaluated) の前の段階での承認、許可ルール、または `acceptEdits` や `bypassPermissions` のようなモードは、`canUseTool` が参照される前に呼び出しを解決します。`allowed_tools` にツールをそのまま列挙した場合、そのツールの `canUseTool` チェックは、[評価フロー](/docs/ja/agent-sdk/permissions#how-permissions-are-evaluated) が呼び出しを質問ルールや `plan` モードなどのプロンプトに戻すルートを通るときのみ実行されます。すべてのツール呼び出しに適用する必要があるロジックの場合は、[`PreToolUse` フック](/docs/ja/agent-sdk/hooks) を使用してください。このフックはフローの残りの部分の前に実行され、リクエストを許可、拒否、または変更できます。

52 55 

53 `AskUserQuestion`、[`requiresUserInteraction`](/docs/ja/mcp#require-approval-for-a-specific-tool)とマークされた MCP ツール、および [組織が `ask` に設定したコネクタツール](/docs/ja/mcp#organization-controls-on-connector-tools)は、許可ルールが一致する場合でもコールバックに到達します。`dontAsk` モードではこれらの呼び出しは代わりに拒否され、コールバックは呼び出されません。56 許可ルールは [モードが自動承認しないアクション](/docs/ja/permission-modes#actions-no-mode-auto-approves) を事前承認しません。[権限がどのように評価されるか](/docs/ja/agent-sdk/permissions#how-permissions-are-evaluated) を参照して、どのアクションがコールバックに到達し、`dontAsk` モードと `auto` モードで何が起こるかを確認してください。

54</Warning>57</Warning>

55 58 

56また、[`PermissionRequest` フック](/docs/ja/agent-sdk/hooks#available-hooks)を使用して、Claude が承認を待っているときに外部通知（Slack、メール、プッシュ）を送信することもできます。59また、[`PermissionRequest` フック](/docs/ja/agent-sdk/hooks#available-hooks) を使用して、Claude が承認を待っているときに外部通知（Slack、メール、プッシュ）を送信することもできます。

57 60 

58<h2 id="handle-tool-approval-requests">61<h2 id="handle-tool-approval-requests">

59 ツール承認リクエストを処理する62 ツール承認リクエストを処理する

60</h2>63</h2>

61 64 

62クエリオプションで `canUseTool` コールバックを渡すと、Claude が自動承認されていないツールを使用したい場合に発火します。コールバックは 3 つの引数を受け取ります。65クエリオプションで `canUseTool` コールバックを渡すと、Claude が以前の許可フローで承認されていないツールを使用したい場合に発火します。`dontAsk` モードなどの一部の設定では、Claude Code はこれを呼び出しません。[許可がどのように評価されるか](/docs/ja/agent-sdk/permissions#how-permissions-are-evaluated)の最後のステップにそれらが記載されており、代わりに呼び出しに何が起こるかが説明されています。

66 

67コールバックは 3 つの引数を受け取ります。

63 68 

64| 引数 | 説明 |69| 引数 | 説明 |

65| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |70| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

220 225 

221拒否する場合、理由を説明するメッセージを提供します。Claude はこのメッセージを見て、アプローチを調整する可能性があります。226拒否する場合、理由を説明するメッセージを提供します。Claude はこのメッセージを見て、アプローチを調整する可能性があります。

222 227 

223<CodeGroup>

224 ```python Python theme={null}

225 from claude_agent_sdk.types import PermissionResultAllow, PermissionResultDeny

226 

227 # ツールの実行を許可する

228 return PermissionResultAllow(updated_input=input_data)

229 

230 # ツールをブロックする

231 return PermissionResultDeny(message="User rejected this action")

232 ```

233 

234 ```typescript TypeScript theme={null}

235 // ツールの実行を許可する

236 return { behavior: "allow", updatedInput: input };

237 

238 // ツールをブロックする

239 return { behavior: "deny", message: "User rejected this action" };

240 ```

241</CodeGroup>

242 

243許可または拒否を超えて、ツールの入力を変更したり、Claude がアプローチを調整するのに役立つコンテキストを提供したりできます。228許可または拒否を超えて、ツールの入力を変更したり、Claude がアプローチを調整するのに役立つコンテキストを提供したりできます。

244 229 

245* **承認**：ツールを Claude がリクエストしたとおりに実行させる230* **承認**：ツールを Claude がリクエストしたとおりに実行させる

249* **代替案を提案**：ブロックするが、ユーザーが望むものに向かって Claude をガイドする234* **代替案を提案**：ブロックするが、ユーザーが望むものに向かって Claude をガイドする

250* **完全にリダイレクト**：[ストリーミング入力](/docs/ja/agent-sdk/streaming-vs-single-mode)を使用して Claude に完全に新しい指示を送信する235* **完全にリダイレクト**：[ストリーミング入力](/docs/ja/agent-sdk/streaming-vs-single-mode)を使用して Claude に完全に新しい指示を送信する

251 236 

237次のスニペットの `ask_user` および `askUser` ヘルパーは、アプリケーション独自のプロンプト UI の代わりになります。

238 

252<Tabs>239<Tabs>

253 <Tab title="承認">240 <Tab title="承認">

254 ユーザーはアクションをそのまま承認します。コールバックから `input` をそのまま渡し、ツールは Claude がリクエストしたとおりに実行されます。241 ユーザーはアクションをそのまま承認します。コールバックから `input` をそのまま渡し、ツールは Claude がリクエストしたとおりに実行されます。

653 640 

654複数選択質問の場合、ラベルの配列を渡すか、`", "` で結合します。[自由テキスト入力をサポート](#support-free-text-input)に示されているような質問ごとの自由テキスト（例：「その他」オプション）の場合は、ユーザーのテキストを `answers[question]` に入力します。`response` は、ユーザーが質問カードを閉じて、特定の質問への回答ではない一般的な返信を入力できる UI の場合にのみ設定します。`response` が設定されている場合、Claude は質問ごとの回答リストではなく「ユーザーが応答しました：…」を受け取ります。641複数選択質問の場合、ラベルの配列を渡すか、`", "` で結合します。[自由テキスト入力をサポート](#support-free-text-input)に示されているような質問ごとの自由テキスト（例：「その他」オプション）の場合は、ユーザーのテキストを `answers[question]` に入力します。`response` は、ユーザーが質問カードを閉じて、特定の質問への回答ではない一般的な返信を入力できる UI の場合にのみ設定します。`response` が設定されている場合、Claude は質問ごとの回答リストではなく「ユーザーが応答しました：…」を受け取ります。

655 642 

656```json theme={null}643```jsonc theme={null}

657{644{

658 "questions": [645 "questions": [

659 // ...646 // ...

120 `tmux` には特定のオペレーティングシステムでの既知の制限があり、従来は macOS で最も効果的に動作します。iTerm2 で `tmux -CC` を使用することが、`tmux` への推奨エントリーポイントです。120 `tmux` には特定のオペレーティングシステムでの既知の制限があり、従来は macOS で最も効果的に動作します。iTerm2 で `tmux -CC` を使用することが、`tmux` への推奨エントリーポイントです。

121</Note>121</Note>

122 122 

123デフォルトは `"in-process"` です。v2.1.179 より前は、デフォルトは `"auto"` でした。そのため、以前に分割ペインを開いたアップグレードされたセッションは、モードを明示的に設定しない限り、1 つのターミナルに留まります。`"auto"` を設定して、既に tmux セッション内で実行している場合または使用しているターミナルが iTerm2 の場合は分割ペインを有効にし、それ以外の場合は in-process にフォールバックします。`"tmux"` 設定は分割ペインモードを有効にし、ターミナルに基づいて tmux または iTerm2 を使用するかどうかを自動検出します。123デフォルトは `"in-process"` です。v2.1.179 より前は、デフォルトは `"auto"` でした。そのため、以前に分割ペインを開いたアップグレードされたセッションは、モードを明示的に設定しない限り、1 つのターミナルに留まります。`"auto"` を設定して、既に tmux セッション内で実行している場合または使用しているターミナルが iTerm2 で `it2` CLI がインストールされている場合は分割ペインを有効にし、それ以外の場合は in-process にフォールバックします。`"tmux"` 設定は分割ペインモードを有効にし、ターミナルに基づいて tmux または iTerm2 を使用するかどうかを自動検出します。

124 124 

125v2.1.186 以降、`"iterm2"` を設定して iTerm2 ネイティブ分割ペインを明示的に使用してください。このモードは [`it2` CLI](https://github.com/mkusaka/it2) が必要で、`it2` が見つからない場合はインストールコマンド付きでエラーを表示します。`it2` をインストールするか tmux に切り替えるオプションを提供するセットアッププロンプトは、ターミナルが iTerm2 で tmux がフォールバックとして利用可能な場合、`"auto"` または `"tmux"` の下に表示されます。125v2.1.186 以降、`"iterm2"` を設定して iTerm2 ネイティブ分割ペインを明示的に使用してください。このモードは [`it2` CLI](https://github.com/mkusaka/it2) が必要で、`it2` が見つからない場合はインストールコマンド付きでエラーを表示します。`it2` をインストールするか tmux に切り替えるオプションを提供するセットアッププロンプトは、ターミナルが iTerm2 で tmux がフォールバックとして利用可能な場合、`"auto"` または `"tmux"` の下に表示されます。

126 126 

1633. [`CLAUDE_CODE_SUBAGENT_MODEL`](/docs/ja/model-config#environment-variables)。`inherit` 以外に設定されている場合。1633. [`CLAUDE_CODE_SUBAGENT_MODEL`](/docs/ja/model-config#environment-variables)。`inherit` 以外に設定されている場合。

1644. リーダーの現在のモデル。1644. リーダーの現在のモデル。

165 165 

166[`CLAUDE_CODE_SUBAGENT_MODEL_FORCE`](/docs/ja/sub-agents#run-every-subagent-on-one-model) はチームメンバーとサブエージェントの両方に適用されます。166[`CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1`](/docs/ja/sub-agents#run-every-subagent-on-one-model) を設定した場合、最初の 2 つのソースは適用されません。Claude Code は `CLAUDE_CODE_SUBAGENT_MODEL` が `inherit` 以外に設定されている場合はそこからすべてのチームメンバーのモデルを選択し、それ以外の場合はリーダーの現在のモデルから選択します。Claude Code v2.1.257 以降が必要です。

167 167 

168v2.1.251 より前は、`CLAUDE_CODE_SUBAGENT_MODEL` がこの順序で最初に来ていました。168v2.1.251 より前は、`CLAUDE_CODE_SUBAGENT_MODEL` がこの順序で最初に来ていました。

169 169 

252 Claude がエージェントチームを開始する方法252 Claude がエージェントチームを開始する方法

253</h3>253</h3>

254 254 

255チームを開始するには、Claude にチームメンバーをリクエストしてください。Claude は [Agent ツール](/docs/ja/tools-reference) を呼び出して [`name`](/docs/ja/sub-agents#subagent-names) を指定し、エージェントチームが有効になっている場合、Claude Code があなたに確認を求めないときにチームメンバーを起動します。Claude は通常の subagent にも独自に名前を付けるため、後でメッセージを送信でき、エージェントチームが有効になっている場合、名前付き subagent はチームメンバーとして起動するため、チームメンバーをリクエストしなくてもチームが形成される可能性があります。255チームを開始するには、Claude にチームメンバーをリクエストしてください。Claude は [Agent ツール](/docs/ja/tools-reference) を呼び出して [`name`](/docs/ja/sub-agents#subagent-names) を指定し、エージェントチームが有効になっている場合にチームメンバーを起動します。ただし、呼び出しが [fork](/docs/ja/sub-agents#fork-the-current-conversation) であるか、呼び出し自体で `isolation` を渡す場合は除きます。Claude Code があなたに確認を求めることはありません。

256 256 

257subagent の代わりに使用したい場合は、[エージェントチームをオフにしてください](#claude-spawns-teammates-instead-of-subagents)。257Claude は通常の subagent にも独自に名前を付けるため、後でメッセージを送信できます。これらの呼び出しは同じルールに従うため、チームメンバーをリクエストしなくてもチームが形成される可能性があります。subagent の代わりに使用したい場合は、[エージェントチームをオフにしてください](#claude-spawns-teammates-instead-of-subagents)。

258 258 

259<h3 id="architecture">259<h3 id="architecture">

260 アーキテクチャ260 アーキテクチャ

294 チームメンバーに subagent 定義を使用する294 チームメンバーに subagent 定義を使用する

295</h3>295</h3>

296 296 

297チームメンバーを生成するときに、任意の [subagent スコープ](/docs/ja/sub-agents#choose-the-subagent-scope)（プロジェクト、ユーザー、プラグイン、または CLI 定義）から [subagent](/docs/ja/sub-agents) タイプを参照できます。これにより、セキュリティレビュアーやテストランナーなどのロールを 1 回定義し、委任された subagent とエージェントチームチームメンバーの両方として再利用できます。297どちらの表示モードでもチームメンバーを生成するときに、プロジェクト、ユーザー、または管理対象の [subagent スコープ](/docs/ja/sub-agents#choose-the-subagent-scope) から [subagent](/docs/ja/sub-agents) タイプを参照できます。これにより、セキュリティレビュアーやテストランナーなどのロールを 1 回定義し、委任された subagent とエージェントチームチームメンバーの両方として再利用できます。

298 298 

299subagent 定義を使用するには、Claude にチームメンバーを生成するよう指示するときに名前で言及してください。299subagent 定義を使用するには、Claude にチームメンバーを生成するよう指示するときに名前で言及してください。

300 300 

314 権限314 権限

315</h3>315</h3>

316 316 

317チームメンバーはリーダーの権限設定で開始します。リーダーが `--dangerously-skip-permissions` で実行する場合、すべてのチームメンバーも同様に実行します。生成後、個別のチームメンバーモードを変更できますが、生成時にチームメンバーごとのモードを設定することはできません。317チームメンバーはリーダーの権限モードで開始します。ただし、[`dontAsk` モード](/docs/ja/permission-modes#allow-only-pre-approved-tools-with-dontask-mode) は継承しません。リーダーが `--dangerously-skip-permissions` で実行する場合、すべてのチームメンバーも同様に実行します。生成後、個別のチームメンバーの権限モードを変更できますが、生成時にチームメンバーごとの権限モードを設定することはできません。

318 318 

319チームメンバーの権限プロンプトはリーダーセッションに表示されるため、そこで自分で承認してください。[プラン承認](#have-teammates-plan-before-implementing) は設計された例外です。リーダーセッションはあなたへの別のプロンプトなしにチームメンバープラン承認を付与します。319チームメンバーの権限プロンプトはリーダーセッションに表示されるため、そこで自分で承認してください。[プラン承認](#have-teammates-plan-before-implementing) は設計された例外です。リーダーセッションはあなたへの別のプロンプトなしにチームメンバープラン承認を付与します。

320 320 

322 エージェント間のメッセージ322 エージェント間のメッセージ

323</h4>323</h4>

324 324 

3251 つのエージェントが `SendMessage` 経由で別のエージェントにメッセージを送信する場合、受信エージェントには、あなたからではなく別の Claude セッションから来たことが通知されます。チームメンバーは権限プロンプトを承認したり、あなたに代わって同意を提供したりすることはできません。また、アクションが拒否されたチームメンバーは、チェックをバイパスするために別のチームメンバーにそれをリレーすることはできません。[auto mode](/docs/ja/permission-modes#eliminate-prompts-with-auto-mode) では、別のエージェントからリレーされた承認クレームは、あなたからの確認ではなく、信頼できない入力として分類器によって扱われます。3251 つのエージェントが `SendMessage` 経由で別のエージェントにメッセージを送信する場合、受信エージェントには、あなたからではなく別の Claude セッションから来たことが通知されます。チームメンバーは権限プロンプトを承認したり、あなたに代わって同意を提供したりすることはできません。また、アクションが拒否されたチームメンバーは、チェックをバイパスするために別のチームメンバーにそれをリレーすることはできません。[チーム外の他の Claude Code セッション](/docs/ja/cross-session-messaging#how-a-session-treats-an-incoming-message) から到着するメッセージにも同じルールが適用されます。

326 326 

327[チーム外の他の Claude Code セッション](/docs/ja/cross-session-messaging#how-a-session-treats-an-incoming-message) から到着するメッセージにも同じルールが適用されます。327[auto モード](/docs/ja/permission-modes#eliminate-prompts-with-auto-mode) では、分類器はエージェント間のメッセージに 2 つのチェックを適用します。

328 

329* 別のエージェントからリレーされた承認クレームは、あなたからの確認ではなく、信頼できない入力として扱われます。

330* シャットダウンリクエストやプラン承認応答などの構造化プロトコルメッセージであるかどうかに関わらず、プレーンメッセージであるかどうかに関わらず、各メッセージを Claude Code が配信する前にレビューします。ブロックされたメッセージは受信者に到達することはありません。

328 331 

329<h3 id="context-and-communication">332<h3 id="context-and-communication">

330 コンテキストと通信333 コンテキストと通信

537 制限事項540 制限事項

538</h2>541</h2>

539 542 

540エージェントチームは実験的です。注意すべき現在の制限事項は以下の通りです。543Agent teams は実験的な機能です。現在の制限事項は以下の通りです。

541 544 

542* **In-process チームメンバーでのセッション再開なし**：`/resume` と `/rewind` は in-process チームメンバーを復元しません。セッションを再開した後、リーダーは存在しなくなったチームメンバーにメッセージを送信しようとする可能性があります。これが発生した場合は、リーダーに新しいチームメンバーを生成するよう指示してください。545* **インプロセス teammates でのセッション再開非対応**: `/resume` と `/rewind` はインプロセス teammates を復元しません。セッションを再開した後、lead が存在しなくなった teammates にメッセージを送ろうとする可能性があります。この場合、lead に新しい teammates をスポーンするよう指示してください。

543* **タスクステータスが遅延する可能性**：チームメンバーはタスクを完了としてマークできず、依存タスクをブロックすることがあります。タスクが立ち往生しているように見える場合は、作業が実際に完了しているかどうかを確認し、タスクステータスを手動で更新するか、リーダーにチームメンバーをナッジするよう指示してください。546* **タスク状態が遅延することがある**: teammates は時々タスク完了のマークに失敗し、これが依存タスクをブロックします。タスクが止まっているように見える場合、実際に作業が完了しているかどうかを確認し、タスク状態を手動で更新するか、lead に teammate に促すよう指示してください。

544* **シャットダウンが遅い可能性**：チームメンバーは現在のリクエストまたはツール呼び出しを完了してからシャットダウンし、時間がかかる可能性があります。547* **シャットダウンが遅い可能性がある**: teammates は現在のリクエストまたはツール呼び出しを完了してからシャットダウンするため、時間がかかる可能性があります。

545* **セッションあたり 1 つのチーム**：セッションは正確に 1 つのチームを持ち、そのセッションにスコープされています。追加の名前付きチームを作成したり、セッション間でチームを共有したりすることはできません。548* **セッションごとに 1 つのチーム**: セッションは正確に 1 つのチームを持ち、そのセッションにスコープされています。追加の名前付きチームを作成したり、セッション間でチームを共有したりすることはできません。

546* **ネストされたチームなし**：チームメンバーは独自のチームメンバーを生成できません。リーダーのみがチームを管理できます。549* **ネストされたチーム非対応**: teammates は独自の teammates をスポーンできません。lead のみがチームを管理できます。

547* **In-process チームメンバーからのバックグラウンドサブエージェントなし**：in-process チームメンバー自身のサブエージェントはフォアグラウンドで実行されます。チームメンバーの定義が `background: true` を設定するサブエージェントを生成する場合、Claude Code はエラーを返します。チームメンバーの `run_in_background: true` リクエストも失敗し、[Claude Code がフォアグラウンドまたはバックグラウンドを選択する方法](/docs/ja/sub-agents#run-subagents-in-foreground-or-background)で説明されているように、エラーが発生するか、フォアグラウンドで静かに実行されます。メイン会話から起動されたサブエージェントは、[バックグラウンドデフォルト](/docs/ja/sub-agents#run-subagents-in-foreground-or-background)に従います。550* **インプロセス teammates からのバックグラウンド subagents 非対応**: インプロセス teammate 自身の subagents はフォアグラウンドで実行されます。これは teammate のバックグラウンド作業が lead のプロセスより長く存続できないためです。Claude Code は、teammate が `background: true` を設定する定義を持つ subagent をスポーンする場合、エラーを返します。teammate の `run_in_background: true` リクエストも失敗し、[Claude Code がフォアグラウンドまたはバックグラウンドを選択する方法](/docs/ja/sub-agents#run-subagents-in-foreground-or-background)で説明されているようにエラーが発生するか、フォアグラウンドで静かに実行されます。メイン会話から起動された Subagents は[バックグラウンドデフォルト](/docs/ja/sub-agents#run-subagents-in-foreground-or-background)に従います。

548* **リーダーは固定**：メインセッションはその生涯のリーダーです。チームメンバーをリーダーに昇格させたり、リーダーシップを譲渡したりすることはできません。551* **Lead は固定**: メインセッションはその存続期間中、lead です。teammate を lead に昇格させたり、リーダーシップを譲渡したりすることはできません。

549* **権限は生成時に設定**：すべてのチームメンバーはリーダーの権限モードで開始します。生成後に個別のチームメンバーモードを変更できますが、生成時にチームメンバーごとのモードを設定することはできません。552* **権限はスポーン時に設定**: teammates は[権限](#permissions)の下で説明されている権限モードで開始します。スポーン後に個別の teammate の権限モードを変更できますが、スポーン時に teammate ごとの権限モードを設定することはできません。

550* **分割ペインには tmux または iTerm2 が必要**：デフォルトの in-process モードは任意のターミナルで動作します。分割ペインモードは VS Code の統合ターミナル、Windows Terminal、または Ghostty ではサポートされていません。553* **分割ペインは tmux または iTerm2 が必要**: デフォルトのインプロセスモードはすべてのターミナルで機能します。分割ペインモードは VS Code の統合ターミナル、Windows Terminal、または Ghostty ではサポートされていません。

551 554 

552<h2 id="next-steps">555<h2 id="next-steps">

553 次のステップ556 次のステップ

19 19 

20この作業をサポートする 3 つの追加ツールがありますが、エージェント自体を実行する方法ではありません。20この作業をサポートする 3 つの追加ツールがありますが、エージェント自体を実行する方法ではありません。

21 21 

22* [ワークツリー](/docs/ja/worktrees) は各セッションに個別の git チェックアウトを提供するため、並列セッションが同じファイルを編集することはありません。自分で実行するセッションに使用します。エージェントビューは、ディスパッチされた各セッションを自動的に独自のワークツリーに移動し、スポーンするサブエージェントも各々独自のワークツリーを取得できます。22* [ワークツリー](/docs/ja/worktrees) は各セッションに個別の git チェックアウトを提供するため、並列セッションが同じファイルを編集することはありません。自分で実行するセッションに使用します。エージェントビューからディスパッチされたセッションは、[ファイルを編集する前に独自のワークツリーに移動](/docs/ja/agent-view#how-file-edits-are-isolated) し、スポーンするサブエージェントも各々独自のワークツリーを取得できます。

23* [クロスセッションメッセージング](/docs/ja/cross-session-messaging) により、Claude はこのマシン上、別のマシン上、または [Claude Code on the web](/docs/ja/claude-code-on-the-web) 上の他の Claude Code セッションをリストして、メッセージを送信できます。自分で実行するセッションは、検出結果とステータスを相互に渡すことができます。23* [クロスセッションメッセージング](/docs/ja/cross-session-messaging) により、Claude はこのマシン上、別のマシン上、または [Claude Code on the web](/docs/ja/claude-code-on-the-web) 上の他の Claude Code セッションをリストして、メッセージを送信できます。自分で実行するセッションは、検出結果とステータスを相互に渡すことができます。

24* [`/batch`](/docs/ja/commands) は、1 つの大きな変更を 5 ～ 30 個のワークツリー分離サブエージェントに分割し、各エージェントがプルリクエストを開く [skill](/docs/ja/skills) です。これはサブエージェントとワークツリーのパッケージ化された使用法であり、別の調整スタイルではありません。24* [`/batch`](/docs/ja/commands) は、1 つの大きな変更を 5 ～ 30 個のワークツリー分離サブエージェントに分割し、各エージェントがプルリクエストを開く [skill](/docs/ja/skills) です。これはサブエージェントとワークツリーのパッケージ化された使用法であり、別の調整スタイルではありません。

25 25 

190 190 

191チェーンの各解決は 60 秒後にタイムアウトします。チェーン内のステップが停止した場合（例えば、受け取ることができない入力を待つ `credential_process` ヘルパー）、リクエストは [`AWS default-chain credential resolve timed out`](/docs/ja/errors#aws-default-chain-credential-resolve-timed-out) で失敗します。チェーンが正当に長い時間が必要なインタラクティブサインイン（`aws-vault` のようなラッパーを使用した MFA 付きブラウザベースの SSO など）を実行する場合、[`CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS`](/docs/ja/env-vars) でミリ秒単位で制限を引き上げてください。v2.1.207 より前では、停止した認証情報解決はリクエストを無期限に待機させていました。191チェーンの各解決は 60 秒後にタイムアウトします。チェーン内のステップが停止した場合（例えば、受け取ることができない入力を待つ `credential_process` ヘルパー）、リクエストは [`AWS default-chain credential resolve timed out`](/docs/ja/errors#aws-default-chain-credential-resolve-timed-out) で失敗します。チェーンが正当に長い時間が必要なインタラクティブサインイン（`aws-vault` のようなラッパーを使用した MFA 付きブラウザベースの SSO など）を実行する場合、[`CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS`](/docs/ja/env-vars) でミリ秒単位で制限を引き上げてください。v2.1.207 より前では、停止した認証情報解決はリクエストを無期限に待機させていました。

192 192 

193Amazon Bedrock API キーで認証する場合を除き、[セットアップウィザード](#sign-in-with-bedrock)は認証情報を検証する際に行う各 AWS 呼び出しに同じ制限を適用し、各モデルチェック前の認証情報ルックアップにも適用します。認証情報検証中に、制限を超えるチェックは [`Timed out after 60s waiting for AWS`](/docs/ja/errors#bedrock-setup-verification-timed-out-waiting-for-aws) で失敗します。

194 

193<h4 id="advanced-credential-configuration">195<h4 id="advanced-credential-configuration">

194 高度な認証情報設定196 高度な認証情報設定

195</h4>197</h4>

263 265 

264Claude Code で Amazon Bedrock を有効にする場合、以下の点に注意してください。266Claude Code で Amazon Bedrock を有効にする場合、以下の点に注意してください。

265 267 

266* v2.1.172 以降、AWS プロファイルのリージョンをオーバーライドする場合、またはプロファイルにリージョンがない場合にのみ `AWS_REGION` を設定する必要があります。Claude Code はこの順序でリージョンを解決します。268* `AWS_REGION` を設定する必要があるのは、AWS プロファイルのリージョンをオーバーライドする場合、またはプロファイルにリージョンがない場合のみです。Claude Code はこの順序でリージョンを解決します。

267 269 

268 * `AWS_REGION`270 * `AWS_REGION`

269 * `AWS_DEFAULT_REGION`271 * `AWS_DEFAULT_REGION`

274 276 

275 アクティブなプロファイルは、設定されている場合は `AWS_PROFILE`、そうでない場合は `default` です。`AWS_SHARED_CREDENTIALS_FILE` または `AWS_CONFIG_FILE` を設定して、デフォルト以外のファイルパスを指定してください。277 アクティブなプロファイルは、設定されている場合は `AWS_PROFILE`、そうでない場合は `default` です。`AWS_SHARED_CREDENTIALS_FILE` または `AWS_CONFIG_FILE` を設定して、デフォルト以外のファイルパスを指定してください。

276 278 

277 `/status` を実行して、解決されたリージョンを確認してください。リージョンが AWS 設定ファイルまたはデフォルトフォールバックから来た場合、Claude Code は `/status` 出力でソースも記載します。v2.1.171 以前では、Claude Code は AWS 設定ファイルを読み込まないため、`AWS_REGION` を明示的に設定してください。279 `/status` を実行して、解決されたリージョンを確認してください。リージョンが AWS 設定ファイルまたはデフォルトフォールバックから来た場合、Claude Code は `/status` 出力でソースも記載します。

278* Amazon Bedrock を使用する場合、認証は AWS 認証情報を通じて処理されるため、`/logout` コマンドは利用できません。280* Amazon Bedrock を使用する場合、認証は AWS 認証情報を通じて処理されるため、`/logout` コマンドは利用できません。

279* WebSearch ツールは Amazon Bedrock では利用できません。[WebSearch ツールの動作](/docs/ja/tools-reference#websearch-tool-behavior)を参照してください。281* WebSearch ツールは Amazon Bedrock では利用できません。[WebSearch ツールの動作](/docs/ja/tools-reference#websearch-tool-behavior)を参照してください。

280* `AWS_PROFILE` のような他のプロセスにリークしたくない環境変数に設定ファイルを使用できます。詳細については [Settings](/docs/ja/settings) を参照してください。282* `AWS_PROFILE` のような他のプロセスにリークしたくない環境変数に設定ファイルを使用できます。詳細については [Settings](/docs/ja/settings) を参照してください。

530export AWS_REGION=us-east-1532export AWS_REGION=us-east-1

531```533```

532 534 

533Claude Code は AWS リージョンからエンドポイント URL を構築します。v2.1.172 以降では、リージョンは [上記の Amazon Bedrock](#3-configure-claude-code) と同じ優先順位で解決されます。以前のバージョンは `AWS_REGION` のみを使用します。カスタムエンドポイントまたはゲートウェイの URL をオーバーライドするには、`ANTHROPIC_BEDROCK_MANTLE_BASE_URL` を設定します。535Claude Code は AWS リージョンからエンドポイント URL を構築します。リージョンは [上記の Amazon Bedrock](#3-configure-claude-code) と同じ優先順位で解決されます。カスタムエンドポイントまたはゲートウェイの URL をオーバーライドするには、`ANTHROPIC_BEDROCK_MANTLE_BASE_URL` を設定します。

534 536 

535Claude Code 内で `/status` を実行して確認します。Mantle がアクティブな場合、プロバイダー行は `Amazon Bedrock (Mantle)` を表示します。537Claude Code 内で `/status` を実行して確認します。Mantle がアクティブな場合、プロバイダー行は `Amazon Bedrock (Mantle)` を表示します。

536 538 

606 608 

607ネットワーク環境が自動ブラウザベースの SSO フローに干渉する場合は、`awsAuthRefresh` に依存する代わりに、Claude Code を開始する前に手動で `aws sso login` を使用してください。609ネットワーク環境が自動ブラウザベースの SSO フローに干渉する場合は、`awsAuthRefresh` に依存する代わりに、Claude Code を開始する前に手動で `aws sso login` を使用してください。

608 610 

611<h3 id="certificate-errors-behind-a-tls-inspecting-proxy">

612 TLS 検査プロキシの背後での証明書エラー

613</h3>

614 

615Claude Code は、[CA certificate store](/docs/ja/network-config#ca-certificate-store) 設定を AWS へのリクエストに適用します。これには以下が含まれます：

616 

617* モデル検出

618* トークンカウント

619* AWS 認証情報を解決する STS および SSO ロール認証情報呼び出し

620* [setup wizard](#sign-in-with-bedrock) の認証情報検証とモデルチェック

621 

622これらのリクエストについては、OS トラストストアまたは `NODE_EXTRA_CA_CERTS` バンドル内の企業ルート証明書には、Amazon Bedrock 固有のセットアップは必要ありません。

623 

624v2.1.260 より前では、Claude Code は設定されたプロキシを通過するリクエストにのみ CA 設定を適用し、直接接続では実行時のデフォルト証明書ストアのみを信頼していました。

625 

626v2.1.261 より前では、**Use credentials already in my environment** オプションを使用した setup wizard のモデルチェックの背後での認証情報ルックアップは、実行時のデフォルト証明書ストアのみを信頼していました。ルート証明書が OS ストアにのみある TLS 検査プロキシの背後では、影響を受けるリクエストは `unable to get local issuer certificate` で失敗するか、ウィザードはモデルを `unreachable` として表示していましたが、推論リクエストは成功していました。v2.1.261 以降に更新してください。

627 

609<h3 id="region-issues">628<h3 id="region-issues">

610 リージョンの問題629 リージョンの問題

611</h3>630</h3>

26* **リーダーボード**：Claude Code 使用量でランク付けされたトップコントリビューター26* **リーダーボード**：Claude Code 使用量でランク付けされたトップコントリビューター

27* **データエクスポート**：カスタムレポート用に貢献データを CSV としてダウンロード27* **データエクスポート**：カスタムレポート用に貢献データを CSV としてダウンロード

28 28 

29ユーザーごとのトークン数とコスト推定については、[OpenTelemetry エクスポート](/ja/monitoring-usage)を構成するか、組織の分析設定から[支出レポート](https://support.claude.com/en/articles/12883420-view-usage-analytics-for-team-and-enterprise-plans)をエクスポートしてください。これはユーザーごと、モデルごとのトークン使用量と推定使用クレジット支出を一覧表示します。29ユーザーごとのトークン数とコスト推定については、[OpenTelemetry エクスポート](/docs/ja/monitoring-usage)を構成するか、組織の分析設定から[支出レポート](https://support.claude.com/en/articles/12883420-view-usage-analytics-for-team-and-enterprise-plans)をエクスポートしてください。これはユーザーごと、モデルごとのトークン使用量と推定使用クレジット支出を一覧表示します。

30 30 

31<h3 id="enable-contribution-metrics">31<h3 id="enable-contribution-metrics">

32 貢献メトリクスを有効にする32 貢献メトリクスを有効にする

41分析設定を構成するには、オーナーロールが必要です。GitHub 管理者が GitHub アプリをインストールする必要があります。41分析設定を構成するには、オーナーロールが必要です。GitHub 管理者が GitHub アプリをインストールする必要があります。

42 42 

43<Warning>43<Warning>

44 [Zero Data Retention](/ja/zero-data-retention) が有効になっている組織では、貢献メトリクスは利用できません。分析ダッシュボードは使用メトリクスのみを表示します。44 [Zero Data Retention](/docs/ja/zero-data-retention) が有効になっている組織では、貢献メトリクスは利用できません。分析ダッシュボードは使用メトリクスのみを表示します。

45</Warning>45</Warning>

46 46 

47<Steps>47<Steps>

139 139 

140貢献メトリクスが有効になっている場合、Claude Code はマージされたプルリクエストを分析して、Claude Code 支援で記述されたコードを判定します。これは、Claude Code セッションアクティビティを各 PR のコードと照合することで行われます。140貢献メトリクスが有効になっている場合、Claude Code はマージされたプルリクエストを分析して、Claude Code 支援で記述されたコードを判定します。これは、Claude Code セッションアクティビティを各 PR のコードと照合することで行われます。

141 141 

142<h4 id="tagging-criteria">

143 タグ付け基準

144</h4>

145 

146PR は、Claude Code セッション中に記述された少なくとも 1 行のコードを含む場合、「with Claude Code」としてタグ付けされます。システムは保守的なマッチングを使用します。Claude Code の関与に高い信頼度がある場合のみ、支援されたコードとしてカウントされます。

147 

148<h4 id="attribution-process">142<h4 id="attribution-process">

149 属性プロセス143 属性プロセス

150</h4>144</h4>

267 関連リソース261 関連リソース

268</h2>262</h2>

269 263 

270* [OpenTelemetry での監視](/ja/monitoring-usage)：リアルタイムメトリクスとイベントを可観測性スタックにエクスポート264* [OpenTelemetry での監視](/docs/ja/monitoring-usage)：リアルタイムメトリクスとイベントを可観測性スタックにエクスポート

271* [コストを効果的に管理する](/ja/costs)：支出制限を設定し、トークン使用を最適化265* [コストを効果的に管理する](/docs/ja/costs)：支出制限を設定し、トークン使用を最適化

272* [権限](/ja/permissions)：ロールと権限を構成266* [権限](/docs/ja/permissions)：ロールと権限を構成

235 235 

236署名済みの [Claude apps gateway](/docs/ja/claude-apps-gateway) セッションはこのリストの外に位置します。これは Amazon Bedrock または Google Cloud の Agent Platform のようなプロバイダー選択であり、それらより優先されます。ゲートウェイセッションが存在する場合、CLI は `CLAUDE_CODE_USE_BEDROCK`、`CLAUDE_CODE_USE_VERTEX`、または `CLAUDE_CODE_USE_FOUNDRY` が設定されていても、ゲートウェイトークンで認証され、ベアラートークン、API キー、`apiKeyHelper`、およびプロファイルなどの上記の認証情報ソースは使用されません。236署名済みの [Claude apps gateway](/docs/ja/claude-apps-gateway) セッションはこのリストの外に位置します。これは Amazon Bedrock または Google Cloud の Agent Platform のようなプロバイダー選択であり、それらより優先されます。ゲートウェイセッションが存在する場合、CLI は `CLAUDE_CODE_USE_BEDROCK`、`CLAUDE_CODE_USE_VERTEX`、または `CLAUDE_CODE_USE_FOUNDRY` が設定されていても、ゲートウェイトークンで認証され、ベアラートークン、API キー、`apiKeyHelper`、およびプロファイルなどの上記の認証情報ソースは使用されません。

237 237 

238アクティブな Claude サブスクリプションがあり、環境に `ANTHROPIC_API_KEY` も設定されている場合、API キーは承認されると優先されます。キーが無効または期限切れの組織に属している場合、これは認証エラーを引き起こす可能性があります。`unset ANTHROPIC_API_KEY` を実行してサブスクリプションにフォールバックし、`/status` をチェックしてどの方法がアクティブであるかを確認します。`Login method` 行はサブスクリプションアカウントを表示し、API キーが使用中の場合は `API key` 行が表示されます。238マシンの [管理設定](/docs/ja/managed-settings)が [`forceLoginMethod`](/docs/ja/settings-reference#forceloginmethod) を `"gateway"` に設定するか、[`forceLoginGatewayUrl`](/docs/ja/settings-reference#forcelogingatewayurl) を設定し、`CLAUDE_CODE_USE_BEDROCK` または `CLAUDE_CODE_USE_VERTEX` などの変数を通じてクラウドプロバイダーを選択しない場合、セッションはゲートウェイサインインのみを使用します。Claude Code は他の認証情報ソースをスキップし、`/login` でサインインするよう求めます。残りの各認証情報で表示される内容については、[Administrator policy requires a Cloud gateway sign-in](/docs/ja/errors#administrator-policy-requires-a-cloud-gateway-sign-in) を参照してください。v2.1.261 より前、またはゲートウェイサインインのみを設定するマシンの v2.1.265 より前では、Claude Code はこれらのマシンで残りの保存されたログインを使用していました。

239 

240アクティブな Claude サブスクリプションがあり、環境に `ANTHROPIC_API_KEY` も設定されている場合、API キーは承認されると優先されます。キーが無効または期限切れの組織に属している場合、これは認証エラーを引き起こす可能性があります。

241 

242`unset ANTHROPIC_API_KEY` を実行してサブスクリプションにフォールバックし、`/status` をチェックしてどの方法がアクティブであるかを確認します。ログインと API キーの両方が設定されている場合、`/status` は使用中でない認証情報をマークします。

239 243 

240[Claude Code on the Web](/docs/ja/claude-code-on-the-web) は常にサブスクリプション認証情報を使用します。サンドボックス環境で `ANTHROPIC_API_KEY` または `ANTHROPIC_AUTH_TOKEN` を設定しても、サブスクリプション認証情報はオーバーライドされません。244[Claude Code on the Web](/docs/ja/claude-code-on-the-web) は常にサブスクリプション認証情報を使用します。サンドボックス環境で `ANTHROPIC_API_KEY` または `ANTHROPIC_AUTH_TOKEN` を設定しても、サブスクリプション認証情報はオーバーライドされません。

241 245 

36 36 

37<Info>v2.1.211 より前では、分類器は作業ブランチ、Claude が作成したブランチ、およびデフォルトブランチへの定期的なプッシュのみを許可していました。</Info>37<Info>v2.1.211 より前では、分類器は作業ブランチ、Claude が作成したブランチ、およびデフォルトブランチへの定期的なプッシュのみを許可していました。</Info>

38 38 

39すべてのプッシュまたはプルリクエストの前に人間によるチェックポイントが必要な場合は、権限ルールを追加してください。[以下のレシピ](#add-a-human-checkpoint)では、他のすべてのアクションに対してオートモードを有効に保ちます。39Claude のプッシュおよびプルリクエストコマンドの前に人間によるチェックポイントが必要な場合は、権限ルールを追加してください。[以下のレシピ](#add-a-human-checkpoint)では、他のすべてのアクションに対してオートモードを有効に保ちます。

40 40 

41<h3 id="add-a-human-checkpoint">41<h3 id="add-a-human-checkpoint">

42 人間によるチェックポイントを追加する42 人間によるチェックポイントを追加する

55}55}

56```56```

57 57 

58これらのルールは `git push` または `gh pr create` で始まるコマンドに一致します。Claude が別の方法で記述したプッシュ（例：`git -C <dir> push` または `git -c <key>=<value> push`）は、[ルールに一致しない](/docs/ja/permissions#bash-rule-limits)ため、チェックポイントされません。完全なコマンドテキストを検査するチェックポイントの場合は、[PreToolUse フック](/docs/ja/hooks#pretooluse)を追加してください。

59 

58境界がどの程度厳密である必要があるかに応じて、メカニズムを選択してください。60境界がどの程度厳密である必要があるかに応じて、メカニズムを選択してください。

59 61 

60| 境界 | メカニズム | オートモードでの動作 |62| 境界 | メカニズム | オートモードでの動作 |

61| :------------- | :-------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------- |63| :------------- | :-------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------- |

62| アクション前にプロンプト表示 | `permissions.ask` | 上記のレシピのようなコンテンツスコープのルールに対して常にプロンプトを表示します。分類器は一致するアクションを自動承認できません。 |64| アクション前にプロンプト表示 | `permissions.ask` | 上記のレシピのようなコンテンツスコープのルールに一致するコマンドに対して常にプロンプトを表示します。分類器は一致するアクションを自動承認できません。 |

63| アクションを実行しない | `permissions.deny` | 分類器が参照される前にブロックします。分類器もユーザーの意図も、これをオーバーライドできません。 |65| アクションを実行しない | `permissions.deny` | 分類器が参照される前にブロックします。分類器もユーザーの意図も、これをオーバーライドできません。 |

64| このセッション限定の境界 | 「レビューするまでプッシュしない」のように会話で述べる | 分類器は一致するアクションをブロックしますが、[コンテキストコンパクション](/docs/ja/costs#reduce-token-usage)がそのステートメントを含むメッセージを削除すると、境界が失われる可能性があります。永続的な保証のために ask ルールまたは deny ルールを使用してください。 |66| このセッション限定の境界 | 「レビューするまでプッシュしない」のように会話で述べる | 分類器は一致するアクションをブロックしますが、[コンテキストコンパクション](/docs/ja/costs#reduce-token-usage)がそのステートメントを含むメッセージを削除すると、境界が失われる可能性があります。永続的な保証のために ask ルールまたは deny ルールを使用してください。 |

65 67 

395 397 

396分類器がブロックした内容を確認するには、会話でツール呼び出しを見つけます。呼び出しが短縮されているか、`Ran 3 shell commands` のような概要行に折りたたまれている場合は、`Ctrl+O` を押して[トランスクリプトビューア](/docs/ja/interactive-mode#transcript-viewer)を開き、展開します。398分類器がブロックした内容を確認するには、会話でツール呼び出しを見つけます。呼び出しが短縮されているか、`Ran 3 shell commands` のような概要行に折りたたまれている場合は、`Ctrl+O` を押して[トランスクリプトビューア](/docs/ja/interactive-mode#transcript-viewer)を開き、展開します。

397 399 

398画面上の拒否を報告する他の 2 つの場所では、コマンドまたは URL が省略されています。入力ボックスの近くの通知（`bash denied by auto mode · Blocked by classifier · /permissions` など）はツールと理由を示し、**Recently denied** タブはシェルコマンドを Claude が記述した説明で一覧表示します。これらの拒否の正確な入力をプログラムで取得するには、[`PermissionDenied` フック](/docs/ja/hooks#permissiondenied)を追加します。これは `tool_input` として受け取ります。400画面上の拒否を報告する他の 2 つの場所では、コマンドまたは URL が省略されています。入力ボックスの近くの通知（`bash denied by auto mode · [Data Exfiltration] · /permissions` など）はツールと理由を示し、**Recently denied** タブはシェルコマンドを Claude が記述した説明で一覧表示します。これらの拒否の正確な入力をプログラムで取得するには、[`PermissionDenied` フック](/docs/ja/hooks#permissiondenied)を追加します。これは `tool_input` として受け取ります。

399 401 

400呼び出しの下のテキストは、修正すべきことがあるかどうかを示します。分類器自体の問題を報告するテキスト（`is temporarily unavailable` のようなモデルや分類器エラーなど）は、Claude Code が分類器からの最終判定なしに呼び出しをブロックしたことを意味します。詳細は[オートモードがアクションの安全性を判定できない](/docs/ja/errors#auto-mode-cannot-determine-the-safety-of-an-action)を参照してください。それ以外の場合、`Denied by auto mode classifier` と `Blocked by classifier` などの理由が記載された行は、分類器が呼び出しを安全でないと判定したことを意味するため、呼び出しが何に到達しようとしていたか、または何をしようとしていたかから修正を選択します。402呼び出しの下のテキストは、修正すべきことがあるかどうかを示します。分類器自体の問題を報告するテキスト（`is temporarily unavailable` のようなモデルや分類器エラーなど）は、Claude Code が分類器からの最終判定なしに呼び出しをブロックしたことを意味します。詳細は[オートモードがアクションの安全性を判定できない](/docs/ja/errors#auto-mode-cannot-determine-the-safety-of-an-action)を参照してください。それ以外の場合、`Denied by auto mode classifier` と `[Production Deploy]` または `Blocked by classifier` などの理由が記載された行は、分類器が呼び出しを安全でないと判定したことを意味するため、呼び出しが何に到達しようとしていたか、または何をしようとしていたかから修正を選択します。

401 403 

402* タスク全体を通じて Claude が必要とする宛先（パッケージレジストリ、内部ドメイン、リポジトリホストなど）：`autoMode.environment` に追加します。404* タスク全体を通じて Claude が必要とする宛先（パッケージレジストリ、内部ドメイン、リポジトリホストなど）：`autoMode.environment` に追加します。

403* これからレビューなしで実行したいコマンド：`allow` ルールを追加します。405* これからレビューなしで実行したいコマンド：`allow` ルールを追加します。

405 407 

406環境エントリまたは `allow` ルールは、`/permissions` ダイアログの[**Auto mode** タブ](#edit-rules-from-permissions)から追加できます。408環境エントリまたは `allow` ルールは、`/permissions` ダイアログの[**Auto mode** タブ](#edit-rules-from-permissions)から追加できます。

407 409 

408呼び出しに表示される理由は、Claude Code v2.1.208 以降のほとんどのセッションで固定テキスト `Blocked by classifier` です。分類器は各アクションを内部の重大度スケールでスコアリングするため、説明を記述しません。一部のセッションでは、v2.1.193 以降で短い説明を記述する分類器モデルを実行します。説明が表示される場合は、分類器が欠落していた宛先または意図についてのヒントとして扱います。Claude Code が分類器モデルを選択するため、表示される理由はユーザーが設定できるものではありません。410ほとんどのセッションでは、理由は分類器が一致したルールを角括弧で示します。例えば `[Data Exfiltration]` または `[Production Deploy]` のようにです。一部のセッションでは、短い説明を追加する分類器モデルを実行します。Claude Code が分類器モデルを選択するため、表示される形式はユーザーが設定できるものではありません。

409 411 

410<h3 id="fix-repeated-denials">412<h3 id="fix-repeated-denials">

411 繰り返される拒否を修正する413 繰り返される拒否を修正する

47 * `Marketplace "claude-plugins-official" not found`：`/plugin marketplace add anthropics/claude-plugins-official` でマーケットプレイスを追加してから、インストールを再試行してください。47 * `Marketplace "claude-plugins-official" not found`：`/plugin marketplace add anthropics/claude-plugins-official` でマーケットプレイスを追加してから、インストールを再試行してください。

48 * プラグインが[マーケットプレイスで見つかりません](/docs/ja/discover-plugins#install-plugins)：プラグイン名を確認してください。48 * プラグインが[マーケットプレイスで見つかりません](/docs/ja/discover-plugins#install-plugins)：プラグイン名を確認してください。

49 49 

50 インストールがインストールスコープを求めるとき、ユーザースコープオプションを選択して、プラグインがすべてのプロジェクト全体で利用可能になるようにしてください。インストール概要を確認してください。`Run /reload-plugins to activate.` と報告されている場合は、そのコマンドを実行してプラグインの設定コマンドをアクティブにしてください。50 インストールがインストールスコープを求めるとき、ユーザースコープオプションを選択して、プラグインがすべてのプロジェクト全体で利用可能になるようにしてください。インストール概要を確認してください。`Run /reload-plugins to activate.` と報告されている場合は、[プラグイン変更を再起動なしで適用する](/docs/ja/discover-plugins#apply-plugin-changes-without-restarting)を参照して、プラグインの設定コマンドを利用可能にしてください。

51 </Step>51 </Step>

52 52 

53 <Step title="トークンを設定する">53 <Step title="トークンを設定する">

125 * `Marketplace "claude-plugins-official" not found`：`/plugin marketplace add anthropics/claude-plugins-official` でマーケットプレイスを追加してから、インストールを再試行してください。125 * `Marketplace "claude-plugins-official" not found`：`/plugin marketplace add anthropics/claude-plugins-official` でマーケットプレイスを追加してから、インストールを再試行してください。

126 * プラグインが[マーケットプレイスで見つかりません](/docs/ja/discover-plugins#install-plugins)：プラグイン名を確認してください。126 * プラグインが[マーケットプレイスで見つかりません](/docs/ja/discover-plugins#install-plugins)：プラグイン名を確認してください。

127 127 

128 インストールがインストールスコープを求めるとき、ユーザースコープオプションを選択して、プラグインがすべてのプロジェクト全体で利用可能になるようにしてください。インストール概要を確認してください。`Run /reload-plugins to activate.` と報告されている場合は、そのコマンドを実行してプラグインの設定コマンドをアクティブにしてください。128 インストールがインストールスコープを求めるとき、ユーザースコープオプションを選択して、プラグインがすべてのプロジェクト全体で利用可能になるようにしてください。インストール概要を確認してください。`Run /reload-plugins to activate.` と報告されている場合は、[プラグイン変更を再起動なしで適用する](/docs/ja/discover-plugins#apply-plugin-changes-without-restarting)を参照して、プラグインの設定コマンドを利用可能にしてください。

129 </Step>129 </Step>

130 130 

131 <Step title="トークンを設定する">131 <Step title="トークンを設定する">

170 170 

171 イベントが到着しない場合、診断は `curl` が返したものに依存します：171 イベントが到着しない場合、診断は `curl` が返したものに依存します：

172 172 

173 * **`curl` は成功するが Claude に何も到着しない**：セッションで `/mcp` を実行してサーバーのステータスを確認します。`failed` ステータスは通常、サーバーファイルの依存関係またはインポートエラーを意味します。`~/.claude/debug/<session-id>.txt` のデバッグログで stderr トレースを確認してください。173 * **`curl` は成功するが Claude に何も到着しない**：セッションで `/mcp` を実行してサーバーのステータスを確認します。`failed` ステータスは通常、サーバーファイルの依存関係またはインポートエラーを意味します。stderr トレースを確認するには、`claude --debug --dangerously-load-development-channels server:webhook` で再開し、`~/.claude/debug/<session-id>.txt` のデバッグログを確認してください。

174 * **`curl` が「接続が拒否されました」で失敗**：ポートはまだバインドされていないか、以前の実行からの古いプロセスがそれを保持しています。`lsof -i :<port>` は何がリッスンしているかを示します。セッションを再開する前に古いプロセスを `kill` してください。174 * **`curl` が「接続が拒否されました」で失敗**：ポートはまだバインドされていないか、以前の実行からの古いプロセスがそれを保持しています。`lsof -i :<port>` は何がリッスンしているかを示します。セッションを再開する前に古いプロセスを `kill` してください。

175 </Step>175 </Step>

176</Steps>176</Steps>

12 チェックポイントの仕組み12 チェックポイントの仕組み

13</h2>13</h2>

14 14 

15Claude で作業する際、チェックポイント機能は各ユーザープロンプト前のコード状態を自動的にキャプチャします。15Claude で作業する際、チェックポイント機能は送信する各プロンプトがターンを開始する前のコード状態を自動的にキャプチャします。

16 16 

17<h3 id="automatic-tracking">17<h3 id="automatic-tracking">

18 自動追跡18 自動追跡

20 20 

21Claude Code は、ファイル編集ツールで行われたすべての変更を追跡します。21Claude Code は、ファイル編集ツールで行われたすべての変更を追跡します。

22 22 

23* ユーザープロンプトごとに新しいチェックポイントが作成されます23* 送信する各プロンプトがターンを開始するたびに新しいチェックポイントが作成されます

24* Claude Code はセッション内の最新 100 個のチェックポイントのファイルスナップショットを保持します。古いチェックポイントを破棄すると、残りのチェックポイントが参照しないスナップショットファイルが削除されます。ただし、各ファイルの最初のスナップショットは除外されます。これは VS Code 拡張機能がセッション diff のベースラインとして使用します。24* Claude Code はセッション内の最新 100 個のチェックポイントのファイルスナップショットを保持します。古いチェックポイントを破棄すると、残りのチェックポイントが参照しないスナップショットファイルが削除されます。ただし、各ファイルの最初のスナップショットは除外されます。これは VS Code 拡張機能がセッション diff のベースラインとして使用します。

25* チェックポイントはセッションと共に保存されるため、再開したセッションでも `/rewind` で戻ることができます25* チェックポイントはセッションと共に保存されるため、再開したセッションでも `/rewind` で戻ることができます

26* Claude Code は[保持期間スイープ](/docs/ja/claude-directory#cleaned-up-automatically)でセッションのファイルスナップショットを削除します。デフォルトではセッションが最後に保存されてから約 30 日後です。スナップショットが削除されたチェックポイントに巻き戻すと、[`No files were restored`](/docs/ja/errors#no-files-were-restored) エラーで失敗する可能性があります。スナップショットをより長く保持するには、[`cleanupPeriodDays`](/docs/ja/settings-reference#cleanupperioddays) を設定してください。26* Claude Code は[保持期間スイープ](/docs/ja/claude-directory#cleaned-up-automatically)でセッションのファイルスナップショットを削除します。デフォルトではセッションが最後に保存されてから約 30 日後です。スナップショットが削除されたチェックポイントに巻き戻すと、[`No files were restored`](/docs/ja/errors#no-files-were-restored) エラーで失敗する可能性があります。スナップショットをより長く保持するには、[`cleanupPeriodDays`](/docs/ja/settings-reference#cleanupperioddays) を設定してください。

35 プロンプト入力にテキストが含まれている場合、ダブル `Esc` はメニューを開く代わりにテキストをクリアします。クリアされたテキストは入力履歴に保存されるため、巻き戻しメニューを終了した後に `Up` キーを押して呼び出すことができます。35 プロンプト入力にテキストが含まれている場合、ダブル `Esc` はメニューを開く代わりにテキストをクリアします。クリアされたテキストは入力履歴に保存されるため、巻き戻しメニューを終了した後に `Up` キーを押して呼び出すことができます。

36</Note>36</Note>

37 37 

38巻き戻しメニューには、セッション中に送信した各プロンプトが表示されます。操作したいポイントを選択してから、アクションを選択します。38巻き戻しメニューには、セッション中に送信した各プロンプトが表示されます。ただし、[ターン中に送信されたメッセージ](#messages-sent-mid-turn-not-checkpointed)は除外されます。操作したいポイントを選択してから、アクションを選択します。

39 39 

40* **コードと会話を復元**: コードと会話の両方をそのポイントに戻します40* **コードと会話を復元**: コードと会話の両方をそのポイントに戻します

41* **会話を復元**: 現在のコードを保持しながら、そのメッセージに巻き戻します41* **会話を復元**: 現在のコードを保持しながら、そのメッセージに巻き戻します

110 110 

111チェックポイント機能は、現在のセッション内で編集されたファイルのみを追跡します。Claude Code の外部で手動で行ったファイルの変更や、他の同時セッションからのエディットは、通常キャプチャされません。ただし、現在のセッションと同じファイルを変更する場合は除きます。111チェックポイント機能は、現在のセッション内で編集されたファイルのみを追跡します。Claude Code の外部で手動で行ったファイルの変更や、他の同時セッションからのエディットは、通常キャプチャされません。ただし、現在のセッションと同じファイルを変更する場合は除きます。

112 112 

113<h3 id="messages-sent-mid-turn-not-checkpointed">

114 ターン中に送信されたメッセージはチェックポイントされません

115</h3>

116 

117[Claude が作業中にキューに入れたメッセージ](/docs/ja/interactive-mode#queue-messages-while-claude-works)が実行中のターン内に Claude に到達すると、新しいターンを開始する代わりにそのターンに参加します。メッセージは会話に表示されますが、Claude Code はそれのチェックポイントを作成せず、巻き戻しメニューにはリストされません。Claude Code が独自のターンとして送信するキューに入れたメッセージは、通常どおりチェックポイントを取得します。

118 

119そのようなメッセージを削除するか、メッセージの後に Claude が行った編集を取り消すには、ターンを開始したプロンプトに巻き戻します。これにより、メッセージが到達する前に Claude が行った作業を含む、ターン全体が巻き戻されます。

120 

113<h3 id="symlinked-and-hard-linked-paths-not-restored">121<h3 id="symlinked-and-hard-linked-paths-not-restored">

114 シンボリックリンクおよびハードリンクパスは復元されません122 シンボリックリンクおよびハードリンクパスは復元されません

115</h3>123</h3>

425これらの保証はすべての `/login` を通じてサインインしたセッションに適用されます。Claude Desktop が起動する埋め込みセッションは[Claude Desktop セッションにポリシーを配信する](#deliver-policy-to-claude-desktop-sessions)で説明されているようにポリシーを取得し、テレメトリの箇条書きはそれらのエクスポートがどこに行くかを示します。425これらの保証はすべての `/login` を通じてサインインしたセッションに適用されます。Claude Desktop が起動する埋め込みセッションは[Claude Desktop セッションにポリシーを配信する](#deliver-policy-to-claude-desktop-sessions)で説明されているようにポリシーを取得し、テレメトリの箇条書きはそれらのエクスポートがどこに行くかを示します。

426 426 

427* **モデルアクセス**：ポリシーが許可しないモデルのリクエストは 400 を返し、`/model` ピッカーはポリシーの `availableModels` 許可リストにフィルタリングされます。ポリシーで [`enforceAvailableModels: true`](/docs/ja/model-config#default-model-behavior) を設定して、Default オプションが Claude Code の組み込みデフォルトではなく `availableModels` 内のモデルに解決されるようにします。なしでは、Default は選択可能なままであり、そのモデルが許可されていない場合、リクエスト時に拒否されます。427* **モデルアクセス**：ポリシーが許可しないモデルのリクエストは 400 を返し、`/model` ピッカーはポリシーの `availableModels` 許可リストにフィルタリングされます。ポリシーで [`enforceAvailableModels: true`](/docs/ja/model-config#default-model-behavior) を設定して、Default オプションが Claude Code の組み込みデフォルトではなく `availableModels` 内のモデルに解決されるようにします。なしでは、Default は選択可能なままであり、そのモデルが許可されていない場合、リクエスト時に拒否されます。

428* **テレメトリ宛先**：`/login` を通じてサインインしたセッションでは、CLI はローカルに設定された `OTEL_EXPORTER_OTLP_ENDPOINT` に関係なく、OTLP/HTTP エクスポートをゲートウェイに送信し、ゲートウェイは [`telemetry.forward_to`](/docs/ja/claude-apps-gateway-config#telemetry) の宛先にそれらをリレーします。[Claude Desktop が起動する](#connect-claude-desktop)埋め込みセッションでは、CLI はエクスポートを設定された `OTEL_EXPORTER_OTLP_ENDPOINT` に送信します。CLI はそのエンドポイントがゲートウェイ自体を指す場合にのみ、ゲートウェイセッショントークンをそれらのエクスポートに添付します。信号に設定された宛先がない場合、ゲートウェイはそれを受け入れて破棄するため、既に Claude Code テレメトリを直接収集する場合は、コレクターを `forward_to` 宛先として追加します。428* **テレメトリ宛先**：`/login` を通じてサインインしたセッションでは、CLI はローカルに設定された `OTEL_EXPORTER_OTLP_ENDPOINT` に関係なく、OTLP/HTTP エクスポートをゲートウェイに送信します。ただし、ポリシーが[コレクターをエンドポイントとして指定](/docs/ja/claude-apps-gateway-config#export-directly-to-your-collector)する場合を除きます。ゲートウェイは [`telemetry.forward_to`](/docs/ja/claude-apps-gateway-config#telemetry) の宛先にそれらをリレーします。

429 * [Claude Desktop が起動する](#connect-claude-desktop)埋め込みセッションでは、CLI はエクスポートを設定された `OTEL_EXPORTER_OTLP_ENDPOINT` に送信します。CLI はそのエンドポイントがゲートウェイ自体を指す場合にのみ、ゲートウェイセッショントークンをそれらのエクスポートに添付します。

430 * 信号に設定された宛先がない場合、ゲートウェイはそれを受け入れて破棄します。

431 * 既に Claude Code テレメトリを直接収集する場合は、コレクターを `forward_to` 宛先として追加するか、ポリシーで指定してリレーをスキップします。

429* **認証情報**：ゲートウェイトークンはセッションの唯一の認証情報です。[Anthropic プロファイル](/docs/ja/authentication#anthropic-profiles-and-federation-credentials)および以前の claude.ai ログインはサインイン中は無視されるため、開発者は最初に claude.ai からログアウトする必要はありません。設定された `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN`、または `apiKeyHelper` 認証情報については、[Administrator policy requires a Cloud gateway sign-in](/docs/ja/errors#administrator-policy-requires-a-cloud-gateway-sign-in)を参照してください。432* **認証情報**：ゲートウェイトークンはセッションの唯一の認証情報です。[Anthropic プロファイル](/docs/ja/authentication#anthropic-profiles-and-federation-credentials)および以前の claude.ai ログインはサインイン中は無視されるため、開発者は最初に claude.ai からログアウトする必要はありません。設定された `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN`、または `apiKeyHelper` 認証情報については、[Administrator policy requires a Cloud gateway sign-in](/docs/ja/errors#administrator-policy-requires-a-cloud-gateway-sign-in)を参照してください。

430* **管理設定**：ロックされたキーはローカルでオーバーライドできません。CLI はポリシーを起動時に適用し、[次の起動時にのみ適用される変更](/docs/ja/server-managed-settings#fetch-and-caching-behavior)を除いて、毎時間のポーリングで変更を適用します。433* **管理設定**：ロックされたキーはローカルでオーバーライドできません。CLI はポリシーを起動時に適用し、[次の起動時にのみ適用される変更](/docs/ja/server-managed-settings#fetch-and-caching-behavior)を除いて、毎時間のポーリングで変更を適用します。

431* **ゲートウェイが到達不可能な状態での起動**：サインイン済みセッションは、設定なしで起動するのではなく、約 10 秒後に起動時にエラーで終了します。434* **ゲートウェイが到達不可能な状態での起動**：サインイン済みセッションは、設定なしで起動するのではなく、約 10 秒後に起動時にエラーで終了します。

456| ユーザーごとおよびグループごとの支出制限 | 利用可能 | [支出制限](/docs/ja/claude-apps-gateway-spend-limits)を参照してください |459| ユーザーごとおよびグループごとの支出制限 | 利用可能 | [支出制限](/docs/ja/claude-apps-gateway-spend-limits)を参照してください |

457| サーバー側ウェブ検索 | 利用不可 | CLI はゲートウェイがルーティングするアップストリームプロバイダーを見ることができないため、ウェブ検索サポートを検証できず、ゲートウェイセッションで WebSearch を無効化します |460| サーバー側ウェブ検索 | 利用不可 | CLI はゲートウェイがルーティングするアップストリームプロバイダーを見ることができないため、ウェブ検索サポートを検証できず、ゲートウェイセッションで WebSearch を無効化します |

458| [リモートコントロール](/docs/ja/remote-control) | 利用不可 | CLI は[ゲートウェイを指定するエラー](/docs/ja/errors#remote-control-requires-the-anthropic-api)を表示します |461| [リモートコントロール](/docs/ja/remote-control) | 利用不可 | CLI は[ゲートウェイを指定するエラー](/docs/ja/errors#remote-control-requires-the-anthropic-api)を表示します |

459| 標準プロンプトキャッシング | 利用可能 | ゲートウェイは `cache_control` ブレークポイントをすべてのアップストリームに転送し、CLI は[会話の途中で追加するシステムコンテキスト](/docs/ja/prompt-caching#where-the-cache-lives)をゲートウェイセッションでキャッシング用にマークします。これは他のすべてのプロバイダーと接続と同じです。 |462| [`/design-sync`](/docs/ja/commands#all-commands) と `/design-login` | 利用不可 | どちらも claude.ai が必要ですが、CLI はゲートウェイセッションで claude.ai に接続しないため、どちらのコマンドもそこに表示されません |

463| `/import` と `claude import` などの機能フラグ取得が必要な機能 | 利用不可 | CLI はゲートウェイセッションでフラグ取得をスキップします。[機能フラグ取得が必要な機能](/docs/ja/env-vars#features-that-need-feature-flag-fetching)は、それがオフにするものをリストします |

464| 標準プロンプトキャッシング | 利用可能 | ゲートウェイは `cache_control` ブレークポイントをすべてのアップストリームに転送します。[キャッシュが存在する場所](/docs/ja/prompt-caching#where-the-cache-lives)は、CLI がマークするブロック（会話の途中で追加するシステムコンテキストを含む）をカバーしています |

460| 1 時間キャッシュ TTL | 利用不可 | CLI はゲートウェイセッションで拡張キャッシュ TTL ベータを省略します。ゲートウェイがルーティングできるすべてのアップストリームが 1 時間 TTL をサポートしているわけではないため、ゲートウェイを通じたプロンプトキャッシングは 5 分 TTL を使用します。上記のベータヘッダーノートを参照してください |465| 1 時間キャッシュ TTL | 利用不可 | CLI はゲートウェイセッションで拡張キャッシュ TTL ベータを省略します。ゲートウェイがルーティングできるすべてのアップストリームが 1 時間 TTL をサポートしているわけではないため、ゲートウェイを通じたプロンプトキャッシングは 5 分 TTL を使用します。上記のベータヘッダーノートを参照してください |

461| オートモード | 利用可能 | [サードパーティプロバイダールール](/docs/ja/permission-modes#enable-auto-mode-on-bedrock-agent-platform-or-foundry)に従います。サードパーティプロバイダーで適格なモデルのみがそれを使用できます。v2.1.207 より前では、ゲートウェイセッションのオートモードは `CLAUDE_CODE_ENABLE_AUTO_MODE=1` を設定する必要があり、管理ポリシー `env` ブロック経由で配信可能でした |466| オートモード | 利用可能 | [サードパーティプロバイダールール](/docs/ja/permission-modes#enable-auto-mode-on-bedrock-agent-platform-or-foundry)に従います。サードパーティプロバイダーで適格なモデルのみがそれを使用できます。v2.1.207 より前では、ゲートウェイセッションのオートモードは `CLAUDE_CODE_ENABLE_AUTO_MODE=1` を設定する必要があり、管理ポリシー `env` ブロック経由で配信可能でした |

462| グローバルキャッシュスコープとトークン効率的なツールなどのファーストパーティのみの最適化 | 利用不可 | CLI はゲートウェイセッションでそれらを有効化しません。上記のベータヘッダーノートを参照してください |467| グローバルキャッシュスコープとトークン効率的なツールなどのファーストパーティのみの最適化 | 利用不可 | CLI はゲートウェイセッションでそれらを有効化しません。上記のベータヘッダーノートを参照してください |

62 62 

63ここのすべての本番トポロジーは、L7 プロキシ（Ingress、Cloud Run のフロントエンド、ALB など）をプレーン HTTP レプリカの前に配置します。[`listen.trusted_proxies`](/docs/ja/claude-apps-gateway-config#listen) をプロキシのソース範囲に設定して、ゲートウェイが `X-Forwarded-For` からクライアント IP を読み込みます。ゲートウェイは TCP ピアが信頼されている場合にのみヘッダーを尊重します。[Google Cloud](/docs/ja/claude-apps-gateway-on-gcp) と [AWS](/docs/ja/claude-apps-gateway-on-aws) の実装例には、トポロジーごとに具体的な値があります。信頼されたプロキシなしでは、すべてのリクエストはプロキシの IP から来ているように見え、IP ごとのレート制限を 1 つの共有バケットに折りたたみ、監査イベントにプロキシの IP を記録します。63ここのすべての本番トポロジーは、L7 プロキシ（Ingress、Cloud Run のフロントエンド、ALB など）をプレーン HTTP レプリカの前に配置します。[`listen.trusted_proxies`](/docs/ja/claude-apps-gateway-config#listen) をプロキシのソース範囲に設定して、ゲートウェイが `X-Forwarded-For` からクライアント IP を読み込みます。ゲートウェイは TCP ピアが信頼されている場合にのみヘッダーを尊重します。[Google Cloud](/docs/ja/claude-apps-gateway-on-gcp) と [AWS](/docs/ja/claude-apps-gateway-on-aws) の実装例には、トポロジーごとに具体的な値があります。信頼されたプロキシなしでは、すべてのリクエストはプロキシの IP から来ているように見え、IP ごとのレート制限を 1 つの共有バケットに折りたたみ、監査イベントにプロキシの IP を記録します。

64 64 

65ゲートウェイのデバイス認可とトークンエンドポイントへのリクエストをリダイレクトしないでください。Claude Code はこれらのリクエストでリダイレクトに従わないため、HTTP から HTTPS へのリダイレクトやホスト正規化の書き換えなどのリダイレクトルールは、サインインとトークン更新を破壊します。65ゲートウェイのデバイス認可とトークンエンドポイントへのリクエストをリダイレクトしないでください。例えば、HTTP から HTTPS へのリダイレクトやホスト正規化の書き換えなどです。Claude Code はこれらのリクエストでリダイレクトに従わないため、ingress ルールがそれらをリダイレクトするとサインインとトークン更新が破壊されます。

66 66 

67プロキシに、ゲートウェイのキープアライブ間隔より長いアイドルタイムアウトを与えます。これは上流に依存します：67プロキシに、ゲートウェイのキープアライブ間隔より長いアイドルタイムアウトを与えます。これは上流に依存します：

68 68 

120 ゲートウェイ URL を開発者マシンにプッシュする120 ゲートウェイ URL を開発者マシンにプッシュする

121</h3>121</h3>

122 122 

123ゲートウェイがサービスを提供したら、MDM を通じて、または OS ごとの `managed-settings.json` を直接書き込むことで、管理設定を通じて各開発者のマシンに `forceLoginMethod`、`forceLoginGatewayUrl`、および `parentSettingsBehavior: "merge"` をプッシュします。これなしでは、`/login` はゲートウェイオプションなしで標準アカウントピッカーを表示します。ファイルパスと Claude Desktop `bootstrapUrl` 相当については、[クライアント側の管理設定](/docs/ja/claude-apps-gateway-config#client-side-managed-settings) を参照してください。123ゲートウェイがサービスを提供したら、MDM を通じて、または OS ごとの `managed-settings.json` を直接書き込むことで、管理設定を通じて各開発者のマシンに `forceLoginMethod`、`forceLoginGatewayUrl`、および `parentSettingsBehavior: "merge"` をプッシュします。これなしでは、`/login` はゲートウェイオプションなしで標準アカウントピッカーを表示します。

124 

125キーをデプロイしたら、Claude Code はマシン上の残存する API キーまたは claude.ai ログインの使用を停止するため、サインイン指示と一緒にプッシュを計画します。[Administrator policy requires a Cloud gateway sign-in](/docs/ja/errors#administrator-policy-requires-a-cloud-gateway-sign-in) は開発者が見るメッセージについて説明しています。

126 

127各メカニズムがポリシーを保存する場所については [where each mechanism stores the policy](/docs/ja/managed-settings#where-each-mechanism-stores-the-policy) を参照し、Claude Desktop `bootstrapUrl` 相当については [Client-side managed settings](/docs/ja/claude-apps-gateway-config#client-side-managed-settings) を参照してください。

124 128 

125<h2 id="operations">129<h2 id="operations">

126 運用130 運用

136 140 

137* **監査イベント**：セキュリティ関連イベントごとの単一行 JSON。stderr をログアグリゲーターにパイプします。発行されるイベントには `config.load`、`session.mint`、`session.refresh`、`device.authorize`、`device.verify`、`device.callback`、`auth.denied`、`access.denied`、`inference`、`managed.serve`、`desktop_bootstrap.serve`、`desktop_bootstrap.denied`、`spend.blocked`、`admin.denied`、`admin.limit.upsert`、`admin.limit.delete` が含まれます。フィールドはイベントによって異なります：141* **監査イベント**：セキュリティ関連イベントごとの単一行 JSON。stderr をログアグリゲーターにパイプします。発行されるイベントには `config.load`、`session.mint`、`session.refresh`、`device.authorize`、`device.verify`、`device.callback`、`auth.denied`、`access.denied`、`inference`、`managed.serve`、`desktop_bootstrap.serve`、`desktop_bootstrap.denied`、`spend.blocked`、`admin.denied`、`admin.limit.upsert`、`admin.limit.delete` が含まれます。フィールドはイベントによって異なります：

138 * 成功した mint と refresh イベントは `sub`、`email`、`client_ip`、結果を含みます142 * 成功した mint と refresh イベントは `sub`、`email`、`client_ip`、結果を含みます

139 * `auth.denied` と `access.denied` は理由とクライアント IP を含み、`auth.denied` ではリクエストパスも含みます。拒否時にはユーザーアイデンティティが存在しないため143 * `auth.denied` と `access.denied` は理由とクライアント IP を含み、`auth.denied` ではリクエストパスも含みます。拒否時にはユーザーアイデンティティが存在しないため。2 つの `access.denied` 理由はイベントが何を含むかを変更します：

144 * `xff_unparseable`：イベントは読み込めなかった `X-Forwarded-For` エントリも含みます

145 * `client_ip_unknown`：イベントはクライアント IP を含みません。接続にピアアドレスがなく、`access_control` リストが設定されていたため

140 * `inference` は、どの上流がリクエストを提供したか、応答ステータスを記録します146 * `inference` は、どの上流がリクエストを提供したか、応答ステータスを記録します

141 * `desktop_bootstrap.denied` は、拒否された Claude Desktop ブートストラップフェッチを理由（`not_configured`、`policy_not_opted_in`、`no_policy_matched`）とユーザーのアイデンティティで記録します147 * `desktop_bootstrap.denied` は、拒否された Claude Desktop ブートストラップフェッチを理由（`not_configured`、`policy_not_opted_in`、`no_policy_matched`）とユーザーのアイデンティティで記録します

142 * `admin.denied` は、拒否された admin-API 認証試行をクライアント IP、メソッド、パス、理由で記録します。提示されたキーマテリアルなし：`x-api-key` が提示されたが設定されたキーと一致しなかった場合は `invalid_key`、`Authorization` ヘッダーのみが提示され、ゲートウェイセッションとして `admin.admin_groups` で検証されなかった場合は `bearer_rejected`、どちらのヘッダーも提示されなかった場合は `no_credentials`148 * `admin.denied` は、拒否された admin-API 認証試行をクライアント IP、メソッド、パス、理由で記録します。提示されたキーマテリアルなし：`x-api-key` が提示されたが設定されたキーと一致しなかった場合は `invalid_key`、`Authorization` ヘッダーのみが提示され、ゲートウェイセッションとして `admin.admin_groups` で検証されなかった場合は `bearer_rejected`、どちらのヘッダーも提示されなかった場合は `no_credentials`

265 トラブルシューティング271 トラブルシューティング

266</h2>272</h2>

267 273 

268質問とフィードバックについては、[Claude Code サポート](https://support.claude.com/en/collections/14445694-claude-code) を使用するか、[Claude Code GitHub リポジトリ](https://github.com/anthropics/claude-code/issues) で issue を開きます。問題を報告するときは、以下を含めます：274ご質問やフィードバックについては、[Claude Code サポート](https://support.claude.com/en/collections/14445694-claude-code)をご利用いただくか、[Claude Code GitHub リポジトリ](https://github.com/anthropics/claude-code/issues)で issue を開いてください。問題を報告する際は、以下の情報を含めてください。

269 275 

270* **ゲートウェイの問題**：関連するウィンドウのゲートウェイの stderr、シークレットが削除された `gateway.yaml`、ゲートウェイバージョン（`/` のランディングページに表示、`/managed/settings` の `x-cc-gateway-version` レスポンスヘッダー）、最近変更されたもの276* **Gateway の問題**: gateway の stderr（該当するウィンドウの）、`gateway.yaml`（シークレットは削除）、gateway のバージョン（ランディングページの `/` と `/managed/settings` の `x-cc-gateway-version` レスポンスヘッダーに表示）、および最近の変更内容

271* **ログイン問題**：開発者は `claude --debug-file ./claude-debug.txt` を実行し、再現し、そのファイルとゲートウェイの同じウィンドウの監査ログを送信します277* **ログイン問題**: 開発者が `claude --debug-file ./claude-debug.txt` を実行して再現し、そのファイルと同じウィンドウの gateway の監査ログを送信

272* **推論問題**：リクエストされたモデル、設定された上流、リクエストのゲートウェイ監査ログ。どの上流がそれを提供したか、応答ステータスを記録します278* **推論の問題**: リクエストされたモデル、設定されたアップストリーム、およびリクエストの gateway 監査ログ（どのアップストリームがそれを処理したか、およびレスポンスステータスを記録）

273 279 

274ゲートウェイの stderr には監査イベントストリームが含まれ、監査ログには開発者の ID が記録され、デバッグファイルには開発者のマシンからの hook と MCP サーバーの出力が記録されます。公開 issue に投稿する前に、これらを確認して秘密情報を削除してください。280gateway の stderr には監査イベントストリームが含まれ、監査ログには開発者の ID が記録され、デバッグファイルには開発者のマシンからの hook と MCP サーバーの出力が記録されます。公開 issue に投稿する前に、これらを確認して削除してください。

275 281 

276| 症状 | 原因 | 修正 |282| 症状 | 原因 | 修正方法 |

277| ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |283| -------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

278| 開発者の `/login` は標準アカウントピッカーを表示し、**Cloud gateway** 画面ではなく | 管理設定で `forceLoginMethod` または `forceLoginGatewayUrl` が設定されていない | [管理設定ファイル](/docs/ja/claude-apps-gateway#set-the-gateway-url) をデバイスにデプロイします。`/login` はそこからゲートウェイ URL を読み込みます |284| 開発者の `/login` が **Cloud gateway** 画面ではなく標準のアカウントピッカーを表示する | そのマシンのマネージド設定で `forceLoginMethod` または `forceLoginGatewayUrl` が設定されていない | [マネージド設定ファイル](/docs/ja/claude-apps-gateway#set-the-gateway-url)をデバイスにデプロイしてください。`/login` はそこから gateway URL を読み込みます |

279| Claude Desktop はブートストラップ設定を取得できなかったと報告 | `/user/bootstrap` は 404 を返しました：ユーザーと一致するポリシーが `desktop` キーを持たないか、ポリシーが一致しません。ゲートウェイの監査ログは各拒否を `desktop_bootstrap.denied` として理由とともに記録します。 | ユーザーと一致するポリシーに `desktop` ブロックを追加するか、`match: {}` ベースレイヤーに追加します。空の `desktop: {}` で十分です。[Claude Desktop オーバーレイ](/docs/ja/claude-apps-gateway-config#claude-desktop-overlay) を参照してください。 |285| 開発者のリクエストが `Not signed in to the Cloud gateway — run /login.` で失敗する | マシンのマネージド設定で `forceLoginMethod: "gateway"` または `forceLoginGatewayUrl` が設定されており、セッションに gateway サインインがない。残っている claude.ai ログインは要件を満たしていません。 | 開発者に `/login` を実行して gateway サインインを完了させてください。[Administrator policy requires a Cloud gateway sign-in](/docs/ja/errors#administrator-policy-requires-a-cloud-gateway-sign-in) も参照してください。 |

280| スタートアップは `Gateway login is configured in managed settings, but this Claude Code build does not include Cloud gateway support.` を表示 | インストールされた Claude Code ビルドはゲートウェイサポートより前 | 開発者に Claude Code を Cloud gateway サポートを含むリリースに更新させます |286| Claude Desktop がブートストラップ設定を取得できないと報告する | `/user/bootstrap` が 404 を返した: ユーザーに一致するポリシーが `desktop` キーを持たないか、ポリシーが一致しなかった。gateway の監査ログは各拒否を `desktop_bootstrap.denied` として理由とともに記録します。 | ユーザーに一致するポリシー、または `match: {}` ベースレイヤーに `desktop` ブロックを追加してください。空の `desktop: {}` で十分です。[Claude Desktop overlay](/docs/ja/claude-apps-gateway-config#claude-desktop-overlay) を参照してください。 |

281| CLI `/login`：`Gateway hosts must be on your organization's private network; <host> resolves to the public (or unrecognized) address <ip>` | ゲートウェイホスト名は少なくとも 1 つのパブリック IP アドレスに解決されます。Claude Code は各解決されたアドレスをチェックし、すべてがプライベートであることを要求します。一般的な原因は、1 つのファミリーがパブリックアドレスに解決するデュアルスタック名です。AWS 内部デュアルスタックロードバランサーを含み、パブリック範囲 AAAA アドレスを返します。 | ゲートウェイ名が開発者マシンでプライベートアドレスのみに解決されるようにします。デュアルスタック名の場合は、パブリック範囲レコードをドロップするか、個別の内部専用 DNS 名を提供します。[プライベートネットワーク前提条件](/docs/ja/claude-apps-gateway#prerequisites) を参照してください。 |287| スタートアップが `Gateway login is configured in managed settings, but this Claude Code build does not include Cloud gateway support.` を表示する | インストールされている Claude Code ビルドが gateway サポート前のバージョン | 開発者に Claude Code を Cloud gateway サポートを含むリリースに更新させてください |

282| CLI `/login`：`Gateway login would go through proxy <proxy>, which is not on a private network` | `HTTPS_PROXY` または `HTTP_PROXY` がゲートウェイホストに適用され、プロキシのホスト名がパブリックアドレスに解決されます。ホスト名がプライベートアドレスのみに解決するプロキシは許可され、このエラーをトリガーしません | ゲートウェイホストを開発者のマシンの `NO_PROXY` に追加して、接続が直接になるようにするか、ホスト名がプライベートアドレスに解決するプロキシを使用します。メッセージは追加する正確な `NO_PROXY` エントリを名前で指定します |288| スタートアップまたは `/login` がマネージド設定ロード時の 403 の後に `Claude Code may not be enabled for your organization` を報告する | gateway、またはその前にあるもの、が `/managed/settings` リクエストに 403 で応答した。gateway 自体の設定ルートは 403 で応答することはありません。ステータスは [`access_control`](/docs/ja/claude-apps-gateway-config#http-tuning) IP チェック、または gateway の前にあるプロキシまたは WAF から来ています。監査ログは IP チェック拒否を `access.denied` として理由とともに記録します。開発者はサインイン状態を保ちます。 | 失敗時の監査ログで `access.denied` を確認し、`access_control` リストまたはフロントエンドを修正してから、開発者に `claude` を再度起動させてください |

283| CLI `/login`：`Could not resolve the configured HTTP proxy` | `HTTPS_PROXY` または `HTTP_PROXY` のホスト名が開発者のマシンから解決されません。通常、企業ネットワークに接続していないため | 開発者にネットワークまたは VPN に接続させて再試行するか、プロキシ URL を修正します |289| CLI `/login`: `Gateway hosts must be on your organization's private network; <host> resolves to the public (or unrecognized) address <ip>` | gateway ホスト名が少なくとも 1 つのパブリック IP アドレスに解決される。Claude Code は各解決されたアドレスをチェックし、すべてがプライベートであることを要求します。一般的な原因は、1 つのファミリーがパブリックアドレスに解決されるデュアルスタック名です。AWS 内部デュアルスタックロードバランサーを含み、パブリック範囲の AAAA アドレスを返します。 | gateway 名が開発者マシン上でのみプライベートアドレスに解決されるようにしてください。デュアルスタック名の場合、パブリック範囲のレコードを削除するか、別の内部専用 DNS 名を提供してください。[プライベートネットワークの前提条件](/docs/ja/claude-apps-gateway#prerequisites)を参照してください。 |

284| CLI `/login`：`Could not resolve gateway host <host>` | マシンはゲートウェイの内部 DNS 名を解決できません。通常、企業ネットワークにないため | 開発者にネットワークまたは VPN に接続させ、`/login` を再試行します |290| CLI `/login`: `Gateway login would go through proxy <proxy>, which is not on a private network` | `HTTPS_PROXY` または `HTTP_PROXY` が gateway ホストに適用され、プロキシのホスト名がパブリックアドレスに解決される。ホストがプライベートアドレスのみに解決されるプロキシは許可され、このエラーをトリガーしません | 開発者のマシンの `NO_PROXY` に gateway ホストを追加して接続を直接にするか、ホスト名がプライベートアドレスに解決されるプロキシを使用してください。メッセージは追加する正確な `NO_PROXY` エントリを名前付けします |

285| ブートは `store.postgres_url` という名前の設定検証エラーで終了 | Postgres が設定されていません。ゲートウェイは Postgres が必要です | `store.postgres_url` を設定します。ローカル開発の場合は、使い捨てコンテナを使用します：`docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres`。 |291| CLI `/login`: `Could not resolve the configured HTTP proxy` | `HTTPS_PROXY` または `HTTP_PROXY` のホスト名が開発者のマシンから解決されない。通常、企業ネットワークに接続されていないため | 開発者にネットワークまたは VPN に接続させて再試行するか、プロキシ URL を修正してください |

286| ブートは終了：`requires the native binary` | Node の代わりにネイティブバイナリの下で実行 | [スタンドアロンインストール方法](/docs/ja/setup) の 1 つで Claude Code をインストールします |292| CLI `/login`: `Could not resolve gateway host <host>` | マシンが gateway の内部 DNS 名を解決できない。通常、企業ネットワーク上にないため | 開発者にネットワークまたは VPN に接続させてから、`/login` を再試行してください |

287| ブートは `config.load` の後の OIDC ディスカバリーエラーで終了 | `oidc.issuer` に到達不可、または TLS チェーンが信頼されていない | issuer がポッドから到達可能で `/.well-known/openid-configuration` を提供することを確認します。プライベート PKI の場合は `ca_cert_pem` を設定します。 ポッドが forward proxy を通じてのみ IdP に到達する場合は、[`oidc.use_proxy: true`](/docs/ja/claude-apps-gateway-config#idp-requests-through-a-forward-proxy) を設定します。v2.1.227 より前のバージョンでは、代わりに IdP の各エンドポイントへの直接ルートをポッドに提供します。 |293| ブート時に `store.postgres_url` という名前の設定検証エラーで終了する | Postgres が設定されていない。gateway は Postgres を必要とします | `store.postgres_url` を設定してください。ローカル開発の場合、使い捨てコンテナを使用してください: `docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres`。 |

288| ブートは Postgres パーミッションエラーで終了 | データベースロールがそのスキーマに対して DDL 権限を持たない | ロールにゲートウェイのスキーマに対する `CREATE` を付与して、ブート時にテーブルを作成および変更できるようにします |294| ブート時に終了: `requires the native binary` | Node の代わりにネイティブバイナリで実行されていない | Claude Code を [スタンドアロンインストール方法](/docs/ja/setup)のいずれかでインストールしてください |

289| `/oauth/callback` は「Sign-in could not be completed」を表示 | メールドメインが拒否されました。id\_token 検証が失敗しました。または `email_verified` が明示的に `false` です。ゲートウェイは常にオーバーライドなしで拒否します | `allowed_email_domains` を確認し、IdP が検証済み `email` クレームを返すことを確認します。`email_verified: false` の場合は、IdP 側の検証を修正します。IdP がメールを別のクレーム名の下で発行する場合は、`oidc.email_claim` を設定します。 |295| ブート時に `config.load` の後に OIDC ディスカバリーエラーで終了する | `oidc.issuer` に到達できない、または TLS チェーンが信頼されていない | 発行者がポッドから到達可能で、`/.well-known/openid-configuration` を提供していることを確認してください。プライベート PKI の場合は `ca_cert_pem` を設定してください。ポッドが IdP にフォワードプロキシ経由でのみ到達する場合、[`oidc.use_proxy: true`](/docs/ja/claude-apps-gateway-config#idp-requests-through-a-forward-proxy)を設定してください。v2.1.227 より前のバージョンでは、代わりに IdP の各エンドポイントへの直接ルートをポッドに提供してください。 |

290| ログ：`token exchange failed request_id=<id>: id_token missing email claim` | IdP はデフォルトで id\_token に `email` を含めていません。この拒否は `allowed_email_domains` が設定されている場合にのみ発火します。なしでは、欠落したメールはメールなしでセッションをミントします | IdP を設定して id\_token で `email` を発行します。Okta：カスタム認可サーバーの ID トークンクレームに `email` を追加します。Entra：アプリ登録でオプションクレームとして `email` を追加します。PingFederate：`email` を発行する OpenID Connect ポリシーを有効にします。IdP が userinfo エンドポイントから `email` を提供するが、id\_token に含めない場合（Okta org 認可サーバーなど）、`oidc.userinfo_fallback: true` を設定します。 |296| ブート時に Postgres パーミッションエラーで終了する | データベースロールがそのスキーマに対する DDL 権限を持たない | ロールに gateway のスキーマに対する `CREATE` を付与して、ブート時にテーブルを作成・変更できるようにしてください |

291| すべての Amazon Bedrock リクエストは 502 を返します。ログは `Could not load credentials from any providers` を表示 | EC2 では、IMDSv2 のデフォルトホップリミット 1 がコンテナ内からのインスタンスメタデータリクエストをブロックします。ブートと `/readyz` はクライアント構築時ではなく最初のリクエストで AWS SDK がインスタンス認証情報を解決するため、とにかく合格します | `aws ec2 modify-instance-metadata-options --instance-id <id> --http-put-response-hop-limit 2` でホップリミットを上げるか、起動テンプレートで設定します。変更はインスタンス上のすべてのコンテナに適用されます。利用可能な場合は ECS タスクロールを優先します。ECS コンテナ認証情報エンドポイントから認証情報を読み込み、変更を完全に回避するか、専用ゲートウェイインスタンスで変更を適用して露出を制限します。 |297| `/oauth/callback` が「Sign-in could not be completed」を表示する | メールドメインが拒否された、id\_token 検証が失敗した、または `email_verified` が明示的に `false` である。gateway は常にオーバーライドなしでこれを拒否します | `allowed_email_domains` を確認し、IdP が検証済みの `email` クレームを返していることを確認してください。`email_verified: false` の場合、IdP 側の検証を修正してください。IdP がメールを別のクレーム名で発行する場合、`oidc.email_claim` を設定してください。 |

292| IdP エラー：unknown or unsupported scope | IdP は認識しないスコープを拒否します | `oidc.scopes` を IdP が受け入れる正確なリストに設定します。`openid` を含める必要があります。デフォルトは `openid profile email offline_access` です。 |298| ログ: `token exchange failed request_id=<id>: id_token missing email claim` | IdP がデフォルトで id\_token に `email` を含めていない。この拒否は `allowed_email_domains` が設定されている場合にのみ発火します。設定されていない場合、メールがないとメールなしのセッションが作成されます | IdP を設定して id\_token に `email` を発行させてください。Okta: カスタム認可サーバーの ID トークンクレームに `email` を追加してください。Entra: アプリ登録でオプションクレームとして `email` を追加してください。PingFederate: `email` を発行する OpenID Connect ポリシーを有効にしてください。IdP が userinfo エンドポイントから `email` を提供するが id\_token に含めない場合（Okta org 認可サーバーなど）、`oidc.userinfo_fallback: true` を設定してください。 |

293| `oidc.scopes` を設定した後、セッションはサイレントに更新されません | `offline_access` がオーバーライドからドロップされました | IdP がサポートしている場合は `offline_access` を戻します。リフレッシュトークンなしでは、開発者は `session.ttl_hours` ごとにブラウザログインを再実行します。 |299| ログ: `refresh failed request_id=<id>: invalid_token (…) (at userinfo_no_id_token, …)`、および開発者が `Cloud gateway session expired` を `session.ttl_hours` ごとに見る | IdP がリフレッシュトークンを受け入れたが、それで id\_token を返さなかったため、gateway は IdP の userinfo エンドポイントにユーザーのクレームを求めました。IdP はそこでリフレッシュされたアクセストークンを拒否しました。gateway は `temporarily_unavailable` で応答するため、Claude Code はリフレッシュトークンを保持しますがセッションを更新できません。v2.1.260 より前の gateway バージョンは `(at …)` の詳細なしで同じ行をログします。 | [`oidc.scope_on_refresh: true`](/docs/ja/claude-apps-gateway-config#oidc)を設定してください。gateway v2.1.260 以降で利用可能です。リフレッシュリクエストが再び `openid` を要求するようにします。Okta などの一部の IdP は、要求された場合にのみリフレッシュ時に id\_token を返します。PingFederate では、代わりに **Applications > OAuth > OpenID Connect Policy Management** の下で **Return ID Token On Refresh Grant** を有効にしてください。キーは PingFederate の動作を変更しません。それでも省略する他の IdP の場合、userinfo エンドポイントがリフレッシュによって発行されたアクセストークンを受け入れるかどうかを確認してください。一時的な対応として、[`session.ttl_hours`](/docs/ja/claude-apps-gateway-config#session)を上げてください。[Identity provider setup](#identity-provider-setup) でプロビジョニング解除のトレードオフを参照してください。 |

294| ブラウザは「This request came from another site and was blocked」を表示 | クロスサイトフォーム POST。CSRF 保護としてブロックされました。埋め込みまたはプロキシされたページの場合は予想されます | 検証リンクを直接開きます |300| すべての Amazon Bedrock リクエストが 502 を返す。ログに `Could not load credentials from any providers` が表示される | EC2 では、IMDSv2 のデフォルトホップリミット 1 がコンテナ内からのインスタンスメタデータリクエストをブロックします。ブートと `/readyz` は AWS SDK がクライアント構築時ではなく最初のリクエストでインスタンス認証情報を解決するため、とにかく成功します | `aws ec2 modify-instance-metadata-options --instance-id <id> --http-put-response-hop-limit 2` でホップリミットを上げるか、起動テンプレートで設定してください。変更はインスタンス上のすべてのコンテナに適用されます。利用可能な場合は ECS タスクロールを優先してください。これは ECS コンテナ認証情報エンドポイントから認証情報を読み込み、変更を完全に回避します。または、変更を専用 gateway インスタンスに適用して露出を制限してください。 |

295| Chrome は「Refused to send form data … violates … Content Security Policy directive: form-action」で Approve ボタンをブロックしますが、同じページは Safari または Firefox で機能します | Chrome はリダイレクトチェーン全体に対して `form-action` を実装します。IdP はさらに、許可リストに登録されていない 2 番目のホストにリダイレクトします。 | リダイレクトチェーン内の各追加オリジンを `oidc.form_action_origins` に追加します。Approve ページで Chrome DevTools → Console を開いて、どのオリジンがブロックされたかを確認します。 |301| IdP エラー: unknown or unsupported scope | IdP が認識しないスコープを拒否する | `oidc.scopes` を IdP が受け入れるリストに正確に設定してください。`openid` を含める必要があります。デフォルトは `openid profile email offline_access` です。 |

296| サインインは IdP で完了しますが、コールバックは失敗します。Chrome で CSP エラーまたは Safari で「this sign-in link has expired」 | IdP は `response_mode=form_post` を通じてコードを返しました。これは `/oauth/callback` にクロスオリジン POST を通じて自動送信します。Chrome はそれを厳密な CSP の下でブロックします。Safari は送信を許可しますが、コールバックはクエリ文字列のみを読み込みます。 | IdP が `response_mode=query` を尊重することを確認します。ゲートウェイは明示的にリクエストするため、コールバックはプレーンリダイレクトです |302| `oidc.scopes` を設定した後、セッションが自動的に更新されない | `offline_access` がオーバーライドから削除された | IdP がサポートしている場合は `offline_access` を戻してください。リフレッシュトークンがない場合、開発者は `session.ttl_hours` ごとにブラウザログインを再実行します。 |

297| ログインはローカルで機能しますが、ALB の背後で失敗します | `public_url` が設定されていないため、IdP は内部 `http://` オリジンを `redirect_uri` として取得します | `listen.public_url` を外部 `https://` オリジンに設定し、`<public_url>/oauth/callback` を IdP に登録します |303| ブラウザが「This request came from another site and was blocked」を表示する | クロスサイトフォーム POST。CSRF 保護としてブロックされました。埋め込みまたはプロキシされたページでは予想されます | 検証リンクを直接開いてください |

298| 開発者は信頼プロンプトを繰り返し見ます | TLS 証明書はレプリカごと、またはリクエストごとにローテーションしています | ingress で安定した証明書を使用するか、TLS を 1 回終了し、レプリカをプレーン HTTP で内部で実行します |304| Chrome が「Refused to send form data … violates … Content Security Policy directive: form-action」で Approve ボタンをブロックするが、同じページが Safari または Firefox で機能する | Chrome はリダイレクトチェーン全体に対して `form-action` を適用します。IdP が許可リストに登録されていない 2 番目のホストにさらにリダイレクトします。 | リダイレクトチェーン内の各追加オリジンを `oidc.form_action_origins` に追加してください。Approve ページで Chrome DevTools → Console を開いて、どのオリジンがブロックされたかを確認してください。 |

299| CLI `/login`：「Could not verify the gateway's TLS certificate」または `SELF_SIGNED_CERT_IN_CHAIN` | ゲートウェイの TLS チェーンは、CLI ホストの信頼ストアにないプライベート CA によって署名されています | Claude Code はデフォルトでネイティブバイナリで OS 信頼ストアを読み込み、Node 22.15 以降で読み込みます。[`CLAUDE_CODE_CERT_STORE`](/docs/ja/network-config#ca-certificate-store) はこの動作を制御します。CA が OS 信頼ストアにインストールされている場合は、開発者が現在のランタイムにいることを確認します。そうでない場合は、起動する前に `NODE_EXTRA_CA_CERTS` を CA 証明書 PEM に設定します。最初の接続フィンガープリントプロンプトは引き続き適用されます。 |305| サインインが IdP で完了するがコールバックが失敗する。Chrome で CSP エラーまたは Safari で「this sign-in link has expired」が表示される | IdP が `response_mode=form_post` 経由でコードを返しました。これは POST 経由で `/oauth/callback` にクロスオリジンで自動送信します。Chrome はこれを厳密な CSP の下でブロックします。Safari は送信を許可しますがコールバックはクエリ文字列のみを読み込みます。 | IdP が `response_mode=query` を尊重していることを確認してください。gateway はコールバックがプレーンリダイレクトになるように明示的にこれをリクエストします |

300| CLI `/login` はブラウザサインインを完了し、セッションは `Cloud gateway sign-in was not completed` で終了し、TLS 証明書の不一致 | サインイン後の最初のリクエストで、ゲートウェイは Claude Code がピンした フィンガープリントと一致しない証明書を提示したため、Claude Code はゲートウェイ認証情報を保持しませんでした。通常の原因は、1 つのアドレスの背後にあるレプリカが異なる証明書を提供するか、ネットワークパス上の何かが TLS をインターセプトしています。 | ホスト名に対して 1 つの証明書を提供します。例えば、ingress で TLS を 1 回終了し、開発者に `/login` を再度実行させます。その証明書がピンされたものと異なる場合、Claude Code は [信頼プロンプト](/docs/ja/claude-apps-gateway#connect-developers) を警告とともに表示し、証明書が変更されたことを示します。 |306| ログインはローカルで機能するが ALB の背後では失敗する | `public_url` がまだローカルまたは内部の `http://` オリジンを名前付けしているため、IdP は間違った `redirect_uri` を取得します | `listen.public_url` を外部の `https://` オリジンに設定し、`<public_url>/oauth/callback` を IdP に登録してください |

301| CLI `/login` は `The gateway's TLS certificate changed during sign-in: it no longer matches the one you trusted` で停止 | サインインリクエストは、開発者が `/login` を開始したときに受け入れた証明書と一致しない証明書を提供するサーバーに到達しました：1 つのアドレスの背後にあるレプリカが異なる証明書を提供、パス上の TLS インターセプション、またはサインイン中の証明書ローテーション。 | ホスト名に対して 1 つの証明書を提供し、開発者にサインインを再度開始させ、[信頼プロンプト](/docs/ja/claude-apps-gateway#connect-developers) で新しい証明書を確認させます。 |307| 開発者が信頼プロンプトを繰り返し見る | TLS 証明書がレプリカごと、またはリクエストごとにローテーションしている | イングレスで安定した証明書を使用するか、TLS を 1 回終了して、レプリカをプレーン HTTP で内部的に実行してください |

302 308| CLI `/login`: 「Could not verify the gateway's TLS certificate」または `SELF_SIGNED_CERT_IN_CHAIN` | Gateway の TLS チェーンが CLI ホストの信頼ストアにないプライベート CA によって署名されている | Claude Code はネイティブバイナリ上でデフォルトで OS 信頼ストアを読み込み、Node 22.15 以降で読み込みます。[`CLAUDE_CODE_CERT_STORE`](/docs/ja/network-config#ca-certificate-store) がこの動作を制御します。CA が OS 信頼ストアにインストールされている場合、開発者が現在のランタイムを使用していることを確認してください。そうでない場合、起動前に `NODE_EXTRA_CA_CERTS` を CA 証明書 PEM に設定してください。最初の接続フィンガープリントプロンプトは引き続き適用されます。 |

303`Cloud gateway sign-in was not completed` メッセージはゲートウェイホスト名を名前で指定し、Claude Code が両方のフィンガープリントを持つ場合、ピンされたものと提示されたものの最初の 16 文字を指定します。309| CLI `/login` がブラウザサインインを完了してから、セッションが `Cloud gateway sign-in was not completed` と TLS 証明書の不一致で終了する | サインイン後の最初のリクエストで、gateway は Claude Code がピンした フィンガープリントと一致しない証明書を提示したため、Claude Code は gateway 認証情報を保持しませんでした。通常の原因は、1 つのアドレスの背後にあるレプリカが異なる証明書を提供するか、ネットワークパス上の何かが TLS をインターセプトしています。 | ホスト名に対して 1 つの証明書を提供してください。例えば、イングレスで TLS を 1 回終了してから、開発者に `/login` を再度実行させてください。その証明書がピンされたものと異なる場合、Claude Code は [信頼プロンプト](/docs/ja/claude-apps-gateway#connect-developers) を警告とともに表示します。証明書が変更されました。 |

304 310| CLI `/login` が `The gateway's TLS certificate changed during sign-in: it no longer matches the one you trusted` で停止する | サインインリクエストが、開発者が `/login` を開始したときに受け入れた証明書と一致しない証明書を提供するサーバーに到達しました: 1 つのアドレスの背後にあるレプリカが異なる証明書を提供する、パス上の TLS インターセプション、またはサインイン中の証明書ローテーション。 | ホスト名に対して 1 つの証明書を提供してから、開発者にサインインを再度開始させ、[信頼プロンプト](/docs/ja/claude-apps-gateway#connect-developers)で新しい証明書を確認させてください。 |

305Claude Code がゲートウェイサインイン後に `couldn't load your organization's managed settings` を報告する場合、Claude Code は理由を名前で指定し、その場で再起動し、会話を再開します。Claude Code が再起動できない場合（例えば、バックグラウンドセッション）、Claude Code はセッションを終了し、サインインを保持します。311 

312`Cloud gateway sign-in was not completed` メッセージは gateway ホスト名を名前付けします。Claude Code がピンされたフィンガープリントと提示されたフィンガープリントの両方を持つ場合、メッセージは各の最初の 16 文字も表示します。

313 

314Claude Code がゲートウェイサインイン後に `couldn't load your organization's managed settings` を報告する場合、Claude Code は理由を名前付けし、その場で再起動して、会話を再開します。Claude Code が再起動できない場合（例えば、バックグラウンドセッション）、Claude Code はセッションを終了し、サインインを保持します。

306 315 

307<h2 id="related">316<h2 id="related">

308 関連317 関連

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

4 

5# AWS に Claude apps gateway をデプロイする

6 

7> AWS で Claude apps gateway を実行する実装例：ECS Fargate または EKS、Amazon RDS for PostgreSQL、AWS Secrets Manager、および Amazon Bedrock への IAM ロール認証。

8 

9<Note>

10 このページは、AWS で Claude apps gateway を実行する 1 つの方法を説明しています。この設定は、サポートされている本番環境デプロイメントではなく、カスタマー管理インフラストラクチャの実装例です。各部分がどのように組み合わさるかを確認してから、自分の環境に適応させてください。プラットフォーム非依存の要件については、[デプロイメントガイド](/docs/ja/claude-apps-gateway-deploy)を参照してください。

11</Note>

12 

13この例では、Amazon Bedrock をモデルアップストリームとして使用し、[Amazon ECS](https://aws.amazon.com/ecs/) を [AWS Fargate](https://aws.amazon.com/fargate/) で実行するか、[Amazon EKS](https://aws.amazon.com/eks/) をコンピュートに使用して、AWS に Claude apps gateway をプロビジョニングします。[Okta](https://www.okta.com/) は例の ID プロバイダー（IdP）ですが、OpenID Connect（OIDC）準拠の任意の IdP が機能します。IdP ごとの詳細については、[ID プロバイダーのセットアップ](/docs/ja/claude-apps-gateway-deploy#identity-provider-setup)を参照してください。

14 

15<Note>

16 Bedrock は AWS 上の唯一の Claude アップストリームではありません。ゲートウェイは、Bedrock の代わりに、または Bedrock と並行して、AWS 認証と AWS Marketplace 課金を備えた Anthropic 運営の Claude API である Claude Platform on AWS もサポートしています。そのアップストリームエントリ、認証情報、および IAM 権限は、このページの Bedrock スコープのものとは異なります。[Claude Platform on AWS アップストリームリファレンス](/docs/ja/claude-apps-gateway-config#claude-platform-on-aws)は何が変わるかをカバーしており、このページの残りは変わらずに適用されます。

17</Note>

18 

19<h2 id="architecture">

20 アーキテクチャ

21</h2>

22 

23<Frame caption="例のアーキテクチャ。Amazon Bedrock をモデルアップストリームとして使用しています。Claude Platform on AWS アップストリームは同じ位置を占めます。">

24 <img src="https://mintcdn.com/claude-code/PHweeRmDUYEKff49/images/claude-gateway-aws-architecture.svg?fit=max&auto=format&n=PHweeRmDUYEKff49&q=85&s=8599cc34aa28522cde208ee831439bb4" alt="AWS 上の Claude apps gateway の図：Claude Code クライアントは HTTPS 経由でゲートウェイ（ECS Fargate または EKS）の前にある内部アプリケーションロードバランサーに接続し、プライベートサブネット内で Amazon RDS for PostgreSQL インスタンスと並行して実行されます。ゲートウェイは OIDC 経由でユーザーを企業 IdP に対してサインインさせ、AWS Secrets Manager からシークレットを読み取り、IAM ロールを使用してモデルリクエストを Amazon Bedrock に転送し、デプロイ時に Amazon ECR からイメージをプルします。" width="820" height="430" data-path="images/claude-gateway-aws-architecture.svg" />

25</Frame>

26 

27ゲートウェイは、開発者が IdP を通じてサインインするネットワーク上のプライベート HTTPS エンドポイントとして実行されます。Claude Code セッションは、ゲートウェイの IAM ロールを通じて Amazon Bedrock 上の Claude モデルに到達するため、モデル認証情報は開発者マシンに到達しません。参照設定は以下をプロビジョニングします：