platform-models-api-configure

为 AI 编码 Agent 设置 Salesforce Models API

Salesforce Models API（https://api.salesforce.com/ai/gpt/v1）使用签名的 OrgJWT 进行身份验证（通过 client_credentials 和 sfap_api 范围获取；参见 scripts/get-orgjwt.sh；不使用代理）。任何 Agent 的身份验证方式和基础 URL 都相同。之后各 Agent 与端点通信的方式则因 Agent 而异：Anthropic 客户端（Claude Code 和 Claude Agent SDK）通过 Bedrock 模式路由（使用步骤 3 中的环境变量），而其他 Agent（例如 Codex）使用各自的客户端配置，访问相同的端点和令牌——Bedrock 模式不适用于它们。

以下步骤是 Claude Code / Claude Agent SDK 的参考实现（Bedrock 模式 + JSON 设置文件 + API 密钥辅助程序）。对于非 Bedrock Agent，重用 OrgJWT 身份验证（步骤 1）和基础 URL，并在该 Agent 自己的配置位置应用等效的客户端设置，而不是设置 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）——参考 Agent 的设置路径
• 请求头——<FEAT> = x-client-feature-id（默认值为 ai-platform-models-connected-app）， <APP> = x-sfdc-app-context（默认值为 EinsteinGPT）。在步骤 2 的验证 curl 命令和 ANTHROPIC_CUSTOM_HEADERS 中使用。

步骤（参考实现）

适用于使用 JSON 设置 + API 密钥辅助程序的 Agent 的具体配置。任何 Agent 都可以原样重用 OrgJWT 身份验证、验证 curl 命令和基础 URL；请针对目标 Agent 调整设置文件位置和环境变量配置。

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. 告知管理员彻底重启 Agent（参考 Agent 为 claude）——设置和 API 密钥辅助程序仅在启动时加载。

记录为操作手册（用户要求编写文档，而非应用设置时）

如果用户希望将设置写成文档以供审核，而不是应用到其计算机上（例如“将其保存为 Markdown 操作手册”），请按顺序将以上全部内容写入指定文件（例如 models-api-setup-runbook.md），确保内容完整且独立： .orgjwt.env 的准确内容、chmod 600 + gitignore 说明、验证 curl 命令（附上“写入设置前必须返回 200”的说明）、包含步骤 3 中所有键的完整 settings.json 代码块，以及最后的“彻底重启 claude”步骤。不得遗漏 settings.json 中的九个键。

完成前验证

• 已创建 .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）。若不清除 → 使用错误或过期的 bearer token → 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 会用 AWS SigV4 覆盖 Authorization， OrgJWT 就无法传入。
• apiKeyHelper 必须以 bash <path> <credsfile> 的形式调用（避免退出码 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 用于路由；不需要 tenant-id 请求头。

诊断

错误	含义	首先检查
401	令牌不是有效的 OrgJWT	Connected App 的 sfap_api 作用域、是否启用了 client_credentials 流程、.orgjwt.env 中的 consumer key/secret；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__… 别名（参见支持的模型）