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编码代理的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对任何代理都是通用的。不同代理与端点通信的方式则因代理而异：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密钥助手的工作目录未定义，因此相对路径会导致运行失败。

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
```
— 连接应用的消费者密钥/密码
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

中。

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密钥助手代理的具体配置值。对于任何代理，请直接复用OrgJWT认证、验证curl命令和基础URL；根据目标代理调整设置文件位置和环境变量配置。

写入

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

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

告知管理员完全重启代理（参考代理为
```
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忽略列表
在写入
```
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
```

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	连接应用的 `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__…` 别名（详见支持的模型列表）