platform-models-api-configure

AI コーディングエージェント向け Salesforce Models API のセットアップ

Salesforce Models API（https://api.salesforce.com/ai/gpt/v1）は、署名付きの OrgJWT（client_credentials と sfap_api スコープを使用して取得。scripts/get-orgjwt.sh を参照。プロキシは不要）で認証します。この認証方式とベース URL は、すべてのエージェントで共通です。エンドポイントへの接続方法はエージェントごとに異なります。Anthropic クライアント（Claude Code と Claude Agent SDK）は Bedrock モード（ステップ 3 の環境変数）を経由しますが、その他のエージェント（例：Codex）は同じエンドポイントとトークンに対して各自のクライアント設定を使用します。Bedrock モードは適用されません。

以下の手順は、Claude Code／Claude Agent SDK のリファレンス実装（Bedrock モード＋JSON 設定ファイル＋API キーヘルパー）です。Bedrock を使用しないエージェントでは、OrgJWT 認証（ステップ 1）とベース URL を再利用し、Bedrock の環境変数の代わりに、そのエージェント固有の設定場所で同等のクライアント設定を適用してください。

同梱スクリプトは scripts/ にあります。以下のパスのプレースホルダー：<SKILL> ＝このスキル自体のディレクトリへの絶対パス（コンテキスト内のスキルパスから解決する、SKILL.md を含むフォルダー）。<ABS> ＝ユーザーのプロジェクトルートへの絶対パス。必ず解決済みの絶対パスを出力してください。API キーヘルパーは未定義の作業ディレクトリから実行されるため、相対パスでは動作しません。

前提条件

組織内に、sfap_api OAuth スコープがあり、client_credentials フローが有効な接続アプリが必要です（コンシューマーキー／シークレット＋実行ユーザー）。 セットアップ手順：https://developer.salesforce.com/docs/ai/agentforce/guide/access-models-api-with-rest.html curl と jq がインストールされていること。

収集する入力情報

• SF_INSTANCE_URL — 組織の My Domain。例：https://acme.my.salesforce.com
• SF_CLIENT_ID、SF_CLIENT_SECRET — 接続アプリのコンシューマーキー／シークレット
• Models API のベース URL：https://api.salesforce.com/ai/gpt/v1
• モデル：完全修飾された sfdc_ai__… 形式の名前。例： sfdc_ai__DefaultBedrockAnthropicClaude46Sonnet （全リスト：https://developer.salesforce.com/docs/ai/agentforce/guide/supported-models.html）
• スコープ：プロジェクト（<cwd>/.claude/settings.json、デフォルト）またはユーザー（~/.claude/settings.json）— リファレンスエージェントの設定パス
• ヘッダー — <FEAT> ＝ x-client-feature-id（デフォルト：ai-platform-models-connected-app）、 <APP> ＝ x-sfdc-app-context（デフォルト：EinsteinGPT）。ステップ 2 の検証用 curl と ANTHROPIC_CUSTOM_HEADERS で使用します。

手順（リファレンス実装）

JSON 設定＋API キーヘルパーを使用するエージェント向けの具体的な値です。任意のエージェントで OrgJWT 認証、検証用 curl、ベース URL をそのまま再利用し、設定ファイルの場所と環境変数の接続方法は対象エージェントに合わせてください。

1. <project>/.claude/.orgjwt.env を書き込み（chmod 600）、gitignore に追加します：

   SF_INSTANCE_URL="..."
   SF_CLIENT_ID="..."
   SF_CLIENT_SECRET="..."
   

2. 検証します。設定を書き込む前に 200 が返る必要があります：

   TOKEN=$(bash <SKILL>/scripts/get-orgjwt.sh <ABS>/.claude/.orgjwt.env)
   curl -s -o /dev/null -w '%{http_code}\n' \
     <MODELS_API_URL>/model/<MODEL>/invoke-with-response-stream \
     -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
     -H 'x-client-feature-id: <FEAT>' -H 'x-sfdc-app-context: <APP>' \
     --data '{"anthropic_version":"bedrock-2023-05-31","max_tokens":16,"messages":[{"role":"user","content":"hi"}]}'
   

3. .claude/settings.json を書き込みます（既存の内容にマージし、他のキーは保持します）：

   {
     "apiKeyHelper": "bash <SKILL>/scripts/get-orgjwt.sh <ABS>/.claude/.orgjwt.env",
     "model": "<MODEL>",
     "env": {
       "ANTHROPIC_AUTH_TOKEN": "",
       "CLAUDE_CODE_USE_BEDROCK": "1",
       "CLAUDE_CODE_SKIP_BEDROCK_AUTH": "1",
       "ANTHROPIC_BEDROCK_BASE_URL": "<MODELS_API_URL>",
       "ANTHROPIC_SMALL_FAST_MODEL": "<MODEL>",
       "ANTHROPIC_DEFAULT_MODEL": "<MODEL>",
       "ANTHROPIC_CUSTOM_HEADERS": "x-client-feature-id: <FEAT>\nx-sfdc-app-context: <APP>"
     }
   }
   

   apiKeyHelper には絶対パスを使用してください。（<FEAT>／<APP> のデフォルト値は、上記の「収集する入力情報」に記載されています。）
4. エージェント（リファレンスエージェントの場合は claude）を完全に再起動するよう管理者に伝えてください。設定と API キーヘルパーは起動時にのみ読み込まれます。

ランブックとして記録する場合（適用ではなく、ドキュメント化を求められた場合）

ユーザーがセットアップを自分のマシンに適用するのではなく、レビュー用に文書化するよう求めている場合（例：「Markdown のランブックとして保存」）、上記の内容をすべて、指定されたファイル（例：models-api-setup-runbook.md）に順番どおり、単独で読める形で書き込んでください。.orgjwt.env の正確な内容、chmod 600 と gitignore に関する注意、検証用 curl（「設定を書き込む前に 200 が必要」という注記付き）、ステップ 3 の全キーを含む完全な settings.json ブロック、最後の「claude を完全に再起動する」手順を記載してください。settings.json の 9 つのキーを一つも省略しないでください。

終了前の確認

• .claude/.orgjwt.env を作成し、chmod 600 を設定して、Git の追跡対象から除外した
• settings.json を書き込む前に、検証用の curl が HTTP 200 を返した
• settings.json で ANTHROPIC_AUTH_TOKEN を "" に設定した
• CLAUDE_CODE_USE_BEDROCK を "1" に設定した
• CLAUDE_CODE_SKIP_BEDROCK_AUTH を "1" に設定した
• ANTHROPIC_BEDROCK_BASE_URL が正確に https://api.salesforce.com/ai/gpt/v1 になっている（末尾のスラッシュやパスなし）
• model、ANTHROPIC_DEFAULT_MODEL、ANTHROPIC_SMALL_FAST_MODEL のすべてで、完全修飾された sfdc_ai__… エイリアスを使用している
• ANTHROPIC_CUSTOM_HEADERS に x-client-feature-id と x-sfdc-app-context が含まれている
• apiKeyHelper で絶対パスを使用している（bash <SKILL>/scripts/get-orgjwt.sh <ABS>/.claude/.orgjwt.env）
• claude を完全に再起動するようユーザーに伝えた

正確に設定する必要がある項目（それぞれ特定の問題を防ぎます）

• "ANTHROPIC_AUTH_TOKEN": "" — apiKeyHelper より優先されるグローバルトークンをクリアします（優先順位：ANTHROPIC_AUTH_TOKEN > ANTHROPIC_API_KEY

  apiKeyHelper）。設定しない場合 → 誤った、または古いベアラートークンが使われ、401/404 が発生します。

• CLAUDE_CODE_USE_BEDROCK=1 — Bedrock API クライアントを有効にします。設定しない場合、Claude Code は標準の Anthropic API プロトコルを使用し、ANTHROPIC_BEDROCK_BASE_URL を完全に無視するため、すべての呼び出しが Models API を迂回します。
• CLAUDE_CODE_SKIP_BEDROCK_AUTH=1 — 設定しない場合、Claude Code が Authorization を AWS SigV4 で上書きし、OrgJWT が渡されません。
• apiKeyHelper は bash <path> <credsfile> として実行する必要があります（exit-126 を回避します）。
• モデルには完全修飾された sfdc_ai__… 名を指定する必要があります（対応モデルを参照）。
• 認証には client_credentials の OrgJWT（署名済み JWT、ドット 2 つ、スコープ sfap_api）を使用します。sf org display は使用しないでください（未署名のセッショントークンのため、404 になります）。sf CLI には client_credentials コマンドがありません。ヘルパーは /services/oauth2/token を呼び出します。
• ルーティングに使用されるのは ANTHROPIC_BEDROCK_BASE_URL のみです。テナント ID ヘッダーは不要です。

診断

エラー	意味	最初に確認する項目
401	トークンが有効な OrgJWT ではありません	Connected App の sfap_api スコープ、client_credentials フローの有効化、.orgjwt.env 内のコンシューマーキー／シークレット、ANTHROPIC_AUTH_TOKEN が "" にクリアされていないこと
404	トークンは有効ですが、モデル／環境／組織をルーティングできません	完全修飾された sfdc_ai__… モデルエイリアス、ANTHROPIC_BEDROCK_BASE_URL が正確に https://api.salesforce.com/ai/gpt/v1 であること、組織が Models API の利用資格を持つこと、ANTHROPIC_AUTH_TOKEN がクリアされていること
model not available	エイリアスではないモデル ID です	完全修飾された sfdc_ai__… エイリアスに置き換えてください（対応モデルを参照）