Claude Codeのnetwork secretsでAPIキーをVMに置かずに使う手順

Claude Codeのクラウド環境でAPIキーをClaudeに使わせつつ、キー自体は見せたくないときは、環境の「Network secrets」に登録します。登録したキーはAnthropicのエージェントプロキシが、指定したホスト宛のリクエストに後から付けます。キーはVMの中に置かれないので、環境変数やファイルとして読まれることがありません。

環境変数に入れた値は、その環境を使う全員とClaudeが読めます。ここに本番APIのキーを置くか、network secretsに置くかで、漏れ方の前提が変わります。

network secretsは環境変数と何が違うのか

network secretとは、クラウド環境に保存するAPIキーやトークンのことです。同じ環境のどのセッションからでも、Claudeがキーを見ずにそのAPIを呼べます。リクエストがセッションのVMを出た後で、エージェントプロキシがキーを付け足す仕組みです。

環境変数は逆の性質を持ちます。セッションは環境の値を通常の環境変数として読み込み、Claudeが実行するコマンドはそれを読めます。環境を使う人なら誰でも値を読めます。

ルーチン(定期実行)で使うAPIキーも同じ考え方です。Anthropic管理の環境では、実行中にClaudeが呼ぶAPI向けのキーは環境変数でなくnetwork secretsに置く、と書かれています。

追加できる条件とロール別の可否

network secretsはPro、Max、Team、Enterpriseの各プランで使えます。ただし、追加できるかどうかはプランだけでは決まりません。次の4つが揃う必要があります。

• 環境の種類: Anthropic管理のクラウド環境で、すでに作成済みのもの。自前ホスト環境にはnetwork secretsがありません
• APIへの到達性: リクエストはAnthropicのネットワークから出るため、そのAPIがインターネットから接続を受け付けること
• 暗号鍵: 組織が顧客管理の暗号鍵(CMEK)を使っている場合、network secretsは保存できません
• ロール: 下の表のとおり、プランと組織管理者ロールの有無で決まります

ロールの扱いはPro、Max、Teamと、Enterpriseで分かれます。TeamとEnterpriseでは、Ownerがclaude.aiの組織管理者ロールを持ち、Adminは持ちません。この差が画面に出ます。

Enterpriseで管理者ロールがないと、「Network secrets」の行は一覧を開くだけで、「Only an organization admin can add or delete network secrets」という注記が出ます。この場合はOwnerに共有環境へ追加してもらい、そこでセッションを動かす形になります。共有環境のダイアログには、管理者ロールのない人には「Network secrets」の節自体が出ません。

共有環境の作り方と権限の分担は、クラウド環境の組織共有の設定で扱っています。

通常のフォームでsecretを追加する

追加は1件ずつです。ホストや値を変えたいときは、削除して入れ直します。

フォームの入力欄は3つです。

• Name: secretの名前。例は Internal billing API
• Allowed websites: APIのホスト。例は api.example.com。先頭の *. で全サブドメインに一致します
• Custom headers: キーを載せるヘッダー1行。初期値は名前が Authorization、接頭辞が Bearer です。Valueにキーを貼ります

X-Api-Key のように接頭辞なしで値だけ受け取るAPIなら、ヘッダー名を書き換え、接頭辞を空にします。Bearer以外の認証方式は、Secret typeで別の種類を選びます。選べる種類の一覧は、Slack連携のClaude Tagがconnectionsで使うものと同じです。

Teamで管理者ロールがないときの短いフォーム

Teamプランで組織管理者ロールがない人の「Add secret」は、1件につき1ホストだけを受け付ける短いフォームになります。

• Host: secretを付ける1つのホスト。*. のワイルドカードは使えません
• Name: 任意のラベル
• Secret type: ヘッダーで渡すキーなら「Token」、そうでなければ「Username and password」

サブドメインが複数あるAPIに使いたいなら、ホストの数だけsecretを分けるか、Ownerに通常のフォームで足してもらいます。

動作確認はcurlで足りる

保存したら、同じ環境で新しいセッションを始めて、Claudeに curl でAPIを呼ばせます。次のような依頼で確かめられます。

api.example.com の /v1/status を curl で叩いて、
HTTP ステータスと本文を見せて。ヘッダーは自分で付けなくていい。

キーが効いていれば、APIはキー付きのリクエストとして応答します。一方で、キーはセッションの環境変数にもファイルにも現れません。この2点がそろえば、後付けが機能しています。

一覧のsecretに「Not sent」の印が付いているときは、その下の注記に理由と対処が書かれています。対象ホストが重なるのに完全一致ではない2つのsecretには印が付かず、エージェントプロキシはそのうち片方しか送りません。重なる設定を作らないのが安全です。

どのリクエストにsecretが付くか

エージェントプロキシは、リクエストのホストが登録したホストに一致したときにsecretを付けます。このとき、環境の「Network access」が通さないホストにも到達できます。ネットワークのレベルが「None」でも、secretの対象ホストへは出られます。

つまりsecretの対象ホストは、許可ドメインの一覧とは別の通り道です。許可ドメインの考え方は、クラウド環境のネットワークアクセス設定にあります。secretは、環境を使う全セッションに、誰が始めたかを問わず、削除するまで適用されます。

ただし、次のリクエストにはsecretが付きません。

• GitHub: 別のGitHubプロキシが認証するため、GitHub用にsecretは要りません
• Anthropic APIと公開パッケージレジストリ: api.anthropic.com、registry.npmjs.org、jsr.io、npm.jsr.io、pypi.org、files.pythonhosted.org、index.crates.io、proxy.golang.org
• セットアップスクリプトのリクエスト: Claude Codeがエージェントプロキシに接続するのは、セットアップスクリプトの実行後だからです
• Claude Codeのテレメトリー送信: コマンドではなくClaude Code自身が送るため、プロキシを通りません

最後の例外は見落としやすい箇所です。OpenTelemetryのコレクターにトークンが必要なとき、環境変数に置くと読まれてしまいます。network secretsに置いても付かないため、サーバー管理設定でエクスポート全体を設定する、という別の道になります。

向く場面と向かない場面

network secretsが効くのは、Claudeに呼ばせたい社内APIや外部SaaSのAPIが、キー1つで認証できる場合です。キーの値をClaudeのコンテキストに出したくない場合にも向きます。

向かないのは、次のような場面です。

• セットアップスクリプトの中で、プライベートなレジストリから依存関係を取る
• 自前ホスト環境で動かしている
• 組織が顧客管理の暗号鍵を使っている

セットアップスクリプトのリクエストにはsecretが付きません。スクリプトで認証が必要なら、環境変数など別の渡し方になり、その値は環境を使う人に見えます。この点は、Claude Codeのクラウド環境の仕組みと併せて確かめると、どの層で何が起きるかを追いやすくなります。

ローカルでシークレットをClaudeに読ませずに扱う方法は、SOPSのシークレットを読ませない境界の切り方にあります。こちらはクラウドでなく手元のファイルが対象です。

よくあるつまずき

「Network secrets」の行が出ない、または追加ボタンがない

プランと組織管理者ロールの組み合わせが原因のことが大半です。Enterpriseでロールがなければボタンが出ず、共有環境の画面には節自体がありません。Ownerに追加を頼み、共有環境で動かします。

自前ホスト環境に登録したい

自前ホスト環境にはnetwork secretsがありません。Anthropic管理のクラウド環境だけが対象です。

暗号鍵を使う組織で保存できない

顧客管理の暗号鍵を使う組織では、network secretsを保存できません。この条件はロールや環境を変えても動かないので、別の方法でキーを渡す設計になります。

値を変えたい

編集機能はなく、削除してから、ホストと値を入れ直します。値は保存後に再表示できないため、元のキーは別の場所で管理しておく必要があります。

GitHubのトークンを入れたつもりが効かない

GitHubへの通信はsecretでなく専用のプロキシが認証します。GitHub向けにsecretは付かず、入れる必要もありません。

まとめ

APIキーをClaudeに使わせるなら、環境変数よりnetwork secretsのほうが、キーが読まれる範囲を狭められます。代わりに、対象ホストの指定、ロールの条件、付かない例外の把握が必要です。自前ホスト環境と顧客管理の暗号鍵の組織は対象外なので、先にこの2点を確かめてから設計に入ると手戻りが減ります。