platform-models-api-configure

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Salesforce Models API setup for an AI coding agent

为AI编码Agent配置Salesforce Models API

The Salesforce Models API (

https://api.salesforce.com/ai/gpt/v1

) is authenticated with a signed OrgJWT (obtained via

client_credentials

with the

sfap_api

scope — see

scripts/get-orgjwt.sh

; no proxy). That auth and the base URL are the same for any agent. How each agent then talks to the endpoint is agent-specific: Anthropic clients (Claude Code and the Claude Agent SDK) route through Bedrock mode (the env vars in Step 3), whereas other agents (e.g. Codex) use their own client config against the same endpoint and token — Bedrock mode does not apply to them.

The steps below are the Claude Code / Claude Agent SDK reference implementation (Bedrock mode + a JSON settings file + an API-key helper). For a non-Bedrock agent, reuse the OrgJWT auth (Step 1) and the base URL, and apply the equivalent client settings in that agent's own config location instead of the Bedrock env vars.

Bundled scripts are in

scripts/

. Path placeholders below:

<SKILL>

= the absolute path to this skill's own directory (the folder containing this

SKILL.md

; resolve it from the skill path in context).

<ABS>

= the absolute path to the user's project root. Always emit fully resolved absolute paths — the API-key helper runs from an undefined working directory, so relative paths break it.

Salesforce Models API（

https://api.salesforce.com/ai/gpt/v1

）通过签名的OrgJWT进行认证（通过带有

sfap_api

权限范围的

client_credentials

获取——详见

scripts/get-orgjwt.sh

；无需代理）。该认证方式和基础URL对所有Agent都适用。不同Agent与端点通信的方式则因Agent而异：Anthropic客户端（Claude Code和Claude Agent SDK）通过Bedrock模式（步骤3中的环境变量）进行路由，而其他Agent（如Codex）则使用自身的客户端配置对接相同的端点和令牌——Bedrock模式不适用于这些Agent。

以下步骤是Claude Code/Claude Agent SDK的参考实现（Bedrock模式 + JSON配置文件 + API密钥助手）。对于非Bedrock模式的Agent，请复用OrgJWT认证（步骤1）和基础URL，并在该Agent自身的配置位置应用等效的客户端设置，而非使用Bedrock环境变量。

配套脚本位于

scripts/

目录下。以下路径占位符说明：

<SKILL>

= 本技能自身目录的绝对路径（包含此

SKILL.md

的文件夹；根据上下文的技能路径解析）。

<ABS>

= 用户项目根目录的绝对路径。请始终输出完全解析的绝对路径——API密钥助手的运行工作目录不确定，因此相对路径会导致运行失败。

Prerequisite

前置条件

A connected app in the org with the sfap_api
OAuth scope and the client_credentials flow enabled (consumer key/secret + a run-as user). Setup steps: https://developer.salesforce.com/docs/ai/agentforce/guide/access-models-api-with-rest.html

curl

jq

installed.

组织中已创建Connected App，且具备**

sfap_api

OAuth权限范围，并启用了client_credentials**流程（包含消费者密钥/密钥对 + 运行用户）。设置步骤：https://developer.salesforce.com/docs/ai/agentforce/guide/access-models-api-with-rest.html 已安装

curl

jq

工具。

Inputs to collect

需要收集的输入信息

SF_INSTANCE_URL

— org My Domain, e.g.

https://acme.my.salesforce.com

```
SF_CLIENT_ID
```
,
```
SF_CLIENT_SECRET
```
— connected-app consumer key/secret
Models API base URL:
```
https://api.salesforce.com/ai/gpt/v1
```
Model: a fully qualified
```
sfdc_ai__…
```
name, e.g.
```
sfdc_ai__DefaultBedrockAnthropicClaude46Sonnet
```
(full list: https://developer.salesforce.com/docs/ai/agentforce/guide/supported-models.html)
Scope: project (
```
<cwd>/.claude/settings.json
```
, default) or user (
```
~/.claude/settings.json
```
) — reference-agent settings paths

Headers —

<FEAT>

x-client-feature-id

(default

ai-platform-models-connected-app

<APP>

x-sfdc-app-context

(default

EinsteinGPT

). Used in the Step 2 verify curl and in

ANTHROPIC_CUSTOM_HEADERS

SF_INSTANCE_URL

— 组织My Domain，例如

https://acme.my.salesforce.com

```
SF_CLIENT_ID
```
,
```
SF_CLIENT_SECRET
```
— Connected App的消费者密钥/密钥对
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

中。

Steps (reference implementation)

步骤（参考实现）

Concrete values for a JSON-settings + API-key-helper agent. Reuse the OrgJWT auth, verify curl, and base URL verbatim for any agent; adapt the settings-file location and env-var wiring to the target agent.

Write

<project>/.claude/.orgjwt.env

(chmod 600), gitignore it:

ini

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

Verify — must return

before writing settings:

bash

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"}]}'

Write

.claude/settings.json

(merge into existing; keep other keys):

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>"
  }
}

Use absolute paths in

apiKeyHelper

. (

<FEAT>

<APP>

defaults are in "Inputs to collect" above.)

Tell the admin to fully restart the agent (
```
claude
```
for the reference agent) — settings and the API-key helper load at startup only.

适用于JSON配置 + API密钥助手类型Agent的具体配置值。对于任何Agent，请直接复用OrgJWT认证、验证curl命令和基础URL；根据目标Agent调整配置文件位置和环境变量设置。

创建

<project>/.claude/.orgjwt.env

文件（设置权限为chmod 600），并添加至git忽略列表：

ini

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

验证配置——在写入配置文件前，必须返回

状态码：

bash

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"}]}'

写入

.claude/settings.json

文件（与现有内容合并；保留其他键）：

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>

的默认值见上方“需要收集的输入信息”部分。）

告知管理员完全重启Agent（参考Agent使用
```
claude
```
命令）——配置文件和API密钥助手仅在启动时加载。

Capturing as a runbook (when asked to document, not apply)

整理为运行手册（当用户要求文档记录而非直接应用时）

If the user wants the setup written up for review instead of applied to their machine (e.g. "save it as a Markdown runbook"), write all of the above into the requested file (e.g.

models-api-setup-runbook.md

), in order and self-contained: the exact

.orgjwt.env

contents, the

chmod 600

+ gitignore note, the verification curl (with the "must be

before writing settings" note), the full

settings.json

block with every key from Step 3, and the final "fully restart

claude

" step. Don't omit any of the nine

settings.json

keys.

如果用户希望将配置步骤整理为文档供审核，而非直接应用到机器上（例如“保存为Markdown运行手册”），请将上述所有内容按顺序写入请求的文件（例如

models-api-setup-runbook.md

），内容需独立完整：包括

.orgjwt.env

的准确内容、

chmod 600

及git忽略的说明、验证curl命令（附带“写入配置文件前必须返回

状态码”的说明）、步骤3中的完整

settings.json

代码块，以及最后“完全重启

claude

”的步骤。请勿省略

settings.json

中的9个键。

Verify before finishing

完成前的验证项

```
.claude/.orgjwt.env
```
created,
```
chmod 600
```
, and gitignored
Verification curl returned HTTP
```
200
```
before
```
settings.json
```
was written
```
ANTHROPIC_AUTH_TOKEN
```
set to
```
""
```
in
```
settings.json
```
```
CLAUDE_CODE_USE_BEDROCK
```
set to
```
"1"
```
```
CLAUDE_CODE_SKIP_BEDROCK_AUTH
```
set to
```
"1"
```

ANTHROPIC_BEDROCK_BASE_URL

is exactly

https://api.salesforce.com/ai/gpt/v1

(no trailing slash/path)

model

ANTHROPIC_DEFAULT_MODEL

, and

ANTHROPIC_SMALL_FAST_MODEL

all use the fully qualified

sfdc_ai__…

alias

ANTHROPIC_CUSTOM_HEADERS

contains

x-client-feature-id

and

x-sfdc-app-context

apiKeyHelper

uses absolute paths (

bash <SKILL>/scripts/get-orgjwt.sh <ABS>/.claude/.orgjwt.env

)

User told to fully restart
```
claude
```

已创建
```
.claude/.orgjwt.env
```
文件，设置了
```
chmod 600
```
权限，并添加至git忽略列表
验证curl命令在写入
```
settings.json
```
前返回了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
```

Must be exact (each prevents a specific failure)

必须严格执行（每项可避免特定故障）

```
"ANTHROPIC_AUTH_TOKEN": ""
```
— clears any global token that would otherwise outrank
```
apiKeyHelper
```
(precedence:
```
ANTHROPIC_AUTH_TOKEN
```
>
```
ANTHROPIC_API_KEY
```
```
apiKeyHelper
```
). Without it → wrong/old bearer → 401/404.
```
CLAUDE_CODE_USE_BEDROCK=1
```
— activates the Bedrock API client; without it Claude Code uses the standard Anthropic API protocol and ignores
```
ANTHROPIC_BEDROCK_BASE_URL
```
entirely, so every call bypasses the Models API.
```
CLAUDE_CODE_SKIP_BEDROCK_AUTH=1
```
— else Claude Code overwrites
```
Authorization
```
with AWS SigV4 and the OrgJWT never lands.
```
apiKeyHelper
```
must be invoked as
```
bash <path> <credsfile>
```
(avoids exit-126).
Model must be a fully qualified
```
sfdc_ai__…
```
name (see supported models).
Auth is the OrgJWT from
```
client_credentials
```
(a signed JWT, 2 dots, scope
```
sfap_api
```
) — NOT
```
sf org display
```
(unsigned session token → 404).
```
sf
```
CLI has no client_credentials command; the helper calls
```
/services/oauth2/token
```
.
Only
```
ANTHROPIC_BEDROCK_BASE_URL
```
routes; no tenant-id header needed.

```
"ANTHROPIC_AUTH_TOKEN": ""
```
— 清除任何全局令牌，否则该令牌优先级会高于
```
apiKeyHelper
```
（优先级顺序：
```
ANTHROPIC_AUTH_TOKEN
```
>
```
ANTHROPIC_API_KEY
```
>
```
apiKeyHelper
```
）。若不设置此值→使用错误/旧的Bearer令牌→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>
```
的形式调用（避免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请求头。

Diagnose

故障诊断

Error	Meaning	Check first
`401`	Token is not a valid OrgJWT	Connected App `sfap_api` scope, `client_credentials` flow enabled, consumer key/secret in `.orgjwt.env` ; `ANTHROPIC_AUTH_TOKEN` not cleared to `""`
`404`	Token valid but model/env/org not routable	Fully qualified `sfdc_ai__…` model alias, `ANTHROPIC_BEDROCK_BASE_URL` exactly `https://api.salesforce.com/ai/gpt/v1` , org entitled for the Models API, `ANTHROPIC_AUTH_TOKEN` cleared
`model not available`	Non-alias model id	Replace with a fully qualified `sfdc_ai__…` alias (see supported models)

错误	含义	优先检查项
`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__…` 别名（详见支持的模型列表）