奇 奇连 AI
学习路线图课程工具计算器企业服务关于加入会员

让 Claude Code 走 Amazon Bedrock：环境变量、区域与凭证怎么对

2026-08-18

很多团队不是不想直接用 Anthropic 的 API，而是走不通：公司只允许模型流量留在自己的 AWS 账号里，账单要并进 AWS 的成本中心，访问控制要落在 IAM 上。Claude Code 官方文档里有一页专门讲这条路——code.claude.com/docs/en/amazon-bedrock。这篇就沿着那一页，把环境变量名、区域是怎么解出来的、凭证有哪几种给法、IAM 要开哪些动作，一条条对清楚。

先说清楚这篇的性质：Claude Code 是闭源商业产品，我们没有源码，也没有在任何环境里跑过下面这些配置。文中每一条都能在官方文档那一页里检索到，超出文档的部分一律标注「官方文档没有说明这一点」。

一、前置条件：AWS 那边要先备齐的四项

官方文档的 Prerequisites 一节列了四项：

  • 一个已启用 Amazon Bedrock 访问的 AWS 账号
  • 在 Amazon Bedrock 里拿到目标 Claude 模型的访问权
  • 安装并配置好 AWS CLI——文档标注为可选，只在你没有别的方式拿凭证时才需要
  • 合适的 IAM 权限

第二项容易被跳过。文档写明：第一次调用 Anthropic 模型之前，必须先提交 use case 表单，每个 AWS 账号做一次。做法是打开 Amazon Bedrock 控制台，从 Model catalog 里选一个 Anthropic 模型，把表单填完；文档写「提交后立即授予访问权」。

如果你们用 AWS Organizations，文档给了一条省事的路：在管理账号上调用 PutUseCaseForModelAccess API 提交一次，该调用需要 bedrock:PutUseCaseForModelAccess 这个 IAM 权限，批准会自动扩展到子账号。

还有一件事得提前有心理准备：这一页多处标注「Requires Claude Code v2.1.xxx or later」。下面凡有版本门槛我都照实写——同一个变量在旧版本上的行为可能完全不同，照着新文档配、跑在旧版本上，症状会很奇怪。

二、两条路：向导，还是手动写变量

走向导

文档写明：运行 claude，在登录提示里选 3rd-party platform，再选 Amazon Bedrock。如果你已经登录、看到的是聊天提示符，那就输入 /setup-bedrock 打开向导。

这里有个反直觉的点，文档自己点破了：/setup-bedrock 这条命令在 Bedrock 配置好之前不会出现在命令菜单里，但手打进去是有效的。

向导会问你用哪种方式认证 AWS：从 ~/.aws 目录里探测到的 AWS profile、一个 Amazon Bedrock API key、access key 加 secret，或者环境里已有的凭证。文档写明向导会取到你的区域、核实你的账号能调用哪些 Claude 模型，并允许你把模型钉住（pin）。结果写进用户 settings 文件的 env 块——文档写的是 ~/.claude/settings.json，当设置了 CLAUDE_CONFIG_DIR 时写到 $CLAUDE_CONFIG_DIR/settings.json。之后任何时候再跑 /setup-bedrock 都能重开向导改凭证、区域或模型钉法。

手动写变量

文档说手动这条路是给 CI 和脚本化的企业铺开用的。开关变量只有一个：

# Enable Bedrock integration
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1  # optional if your AWS profile already sets a region

三、区域到底从哪来：四级解析顺序

这一段是本篇最值得抄下来的部分。文档写明，自 v2.1.172 起，只有在你要覆盖 AWS profile 里的区域、或者 profile 根本没设区域时，才需要设 AWS_REGION。解析顺序是：

  1. AWS_REGION
  2. AWS_DEFAULT_REGION
  3. 当前活动 AWS profile 上的 region——先读 AWS shared credentials 文件，再读 shared config 文件，与 AWS SDK 的优先级一致
  4. us-east-1

「活动 profile」的定义是：设了 AWS_PROFILE 就用它，否则用 default。如果你的凭证文件和配置文件不在默认位置，用 AWS_SHARED_CREDENTIALS_FILE 和 AWS_CONFIG_FILE 指过去。

文档还给了一个自查动作：运行 /status 看解析出来的区域；当区域来自 AWS 配置文件或那个兜底值时，/status 会额外标出来源。另外文档明确写了一条版本边界：v2.1.171 及更早的版本不读 AWS 配置文件，那种情况下必须显式设 AWS_REGION。

还有一个只影响小/快模型的区域覆盖变量：

# Optional: Override the AWS region for the small/fast model (Bedrock and Mantle).
# On Bedrock, has no effect without ANTHROPIC_DEFAULT_HAIKU_MODEL
# or the deprecated ANTHROPIC_SMALL_FAST_MODEL set.
export ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION=us-west-2

注意这段注释里两件事：一是它在 Bedrock 上不设 ANTHROPIC_DEFAULT_HAIKU_MODEL 就没有效果，二是 ANTHROPIC_SMALL_FAST_MODEL 被文档明确标为 deprecated。

区域还决定了推理配置文件前缀

区域不只是端点，它还决定 Claude Code 把内置默认模型解析成哪个跨区域推理配置文件（cross-region inference profile）。文档给了一张对照表：

AWS regionPrefix
us-gov-* (AWS GovCloud)us-gov.
us-*us.
eu-*eu.
ap-*apac.
All other regionsglobal.

想改这个偏好，用 ANTHROPIC_BEDROCK_REGION_PREFIX，文档列出的合法值是 us、eu、apac、jp、au、global，并写明需要 v2.1.224 或更高版本。

文档特意强调：这个前缀是偏好，不是保证。 当 Claude Code 能列出你账号里的推理配置文件时，它按「带偏好前缀的配置文件 → 任意匹配的配置文件 → 带偏好前缀的内置模型 ID」的顺序解析；而当它无法在你账号里做配置文件发现（profile discovery）时，它直接套用前缀、这一步不做可用性检查，此时账号里若没启用该前缀的配置文件，请求会以 400 报错。另有两种情况变量会被忽略：GovCloud 区域始终用 us-gov.（文档自述这是唯一能在 GovCloud 分区内路由的前缀），以及设了非法值时回落到按区域推导的前缀。

四、凭证：五种给法，以及一个缓存机制

文档写明 Claude Code 使用 AWS 默认凭证链（default AWS SDK credential chain），并列出五个选项：

# Option A
aws configure

# Option B: 环境变量（access key）
export AWS_ACCESS_KEY_ID=your-access-key-id
export AWS_SECRET_ACCESS_KEY=your-secret-access-key
export AWS_SESSION_TOKEN=your-session-token

# Option C: 环境变量（SSO profile）
aws sso login --profile=your-profile-name
export AWS_PROFILE=your-profile-name

# Option D: AWS 管理控制台凭证
aws login

# Option E: Amazon Bedrock API key
export AWS_BEARER_TOKEN_BEDROCK=your-bedrock-api-key

以上为按官方文档中的参数语义组合的示例，未经实测，以官方文档与 --help 的实际输出为准；占位值请替换成你自己的。

Option C 下面藏着一条容易踩的坑，文档写得很直白：Claude Code 向 profile 的 sso_region 所指的 IAM Identity Center 区域请求角色凭证，这个区域不需要和你跑 Amazon Bedrock 的区域一致；而在 v2.1.207 这个版本上，Amazon Bedrock 的区域会覆盖 sso_region，导致 IAM Identity Center 实例在另一个区域的 profile 认证失败，报 Session token not found or invalid。

凭证解析还有缓存：文档写明解析出的凭证会留在内存里复用到临近过期，API 返回凭证错误则清掉缓存（需要 v2.1.207 或更高版本）。想每次请求都重新解析，设 CLAUDE_CODE_SKIP_AWS_CRED_CACHE=1。文档同时说明：这套缓存覆盖上面除 Amazon Bedrock API key 之外的所有凭证方式，因为 API key 根本不走凭证链。

链条里某一步卡住时（文档举的例子是一个在等待它收不到的输入的 credential_process 助手），请求以 AWS default-chain credential resolve timed out 失败；确有需要更久的交互式登录时，用 CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS 以毫秒为单位调高。v2.1.207 之前，卡住的凭证解析会让请求无限等待。

自动刷新的两个设置项，触发条件不一样

文档把 awsAuthRefresh 和 awsCredentialExport 的差别写得很清楚，这两个是 settings 文件里的键，不是环境变量：

  • awsAuthRefresh：只在 Claude Code 判定凭证已过期时才跑（依据本地时间戳，或 API 返回凭证错误），然后带刷新后的凭证重试。命令输出会显示给用户，但不支持交互式输入。
  • awsCredentialExport：在会话启动时和每次凭证重载时都跑，即使凭证链里的凭证仍然有效。文档说这个用在 Bedrock 账号需要跨账号凭证、和默认凭证链解析出来的不是同一套的场景。它的输出被静默捕获，不展示给用户，且必须输出指定格式的 JSON（顶层 Credentials，内含 AccessKeyId、SecretAccessKey、SessionToken、Expiration）。

文档给的示例配置是这样的：

{
  "awsAuthRefresh": "aws sso login --profile myprofile",
  "env": {
    "AWS_PROFILE": "myprofile"
  }
}

两条版本差异值得记：自 v2.1.181 起也接受 aws configure export-credentials --format process 的扁平输出（同样的键放在顶层而非嵌在 Credentials 下）；只配 awsCredentialExport 而不配 awsAuthRefresh 时，Claude Code 直接用导出的凭证、启动时不再解析默认凭证链，需要 v2.1.206 或更高版本。

五、Windows 与类 Unix：文档只给了 bash 写法

必须实话实说：官方文档这一页的示例一律是 bash 的 export，没有给 PowerShell 或 CMD 的对应写法——怎么在 Windows 上设环境变量是操作系统层面的通用知识，不是这个产品文档的内容，这篇不代它写。

但文档给了一条跨平台都成立、也更适合团队的做法：把这些值放进 settings 文件的 env 块。原文的措辞是，像 AWS_PROFILE 这种你不想泄漏给其它进程的环境变量，可以用 settings 文件来设，向导本身也正是这么落盘的。文件位置文档写的是 ~/.claude/settings.json，或设了 CLAUDE_CONFIG_DIR 时的 $CLAUDE_CONFIG_DIR/settings.json；至于 Windows 上 ~ 具体展开到哪个目录，官方文档没有说明这一点。

六、IAM：要开哪些动作

文档直接给了一份策略。这里只摘动作名，完整 JSON 请以官方文档为准：

SidAction
AllowModelAndInferenceProfileAccessbedrock:InvokeModel、bedrock:InvokeModelWithResponseStream、bedrock:ListInferenceProfiles、bedrock:GetInferenceProfile
AllowMarketplaceSubscriptionaws-marketplace:ViewSubscriptions、aws-marketplace:Subscribe（带 aws:CalledViaLast 等于 bedrock.amazonaws.com 的条件）

Resource 段覆盖 inference-profile/*、application-inference-profile/*、foundation-model/* 三类 ARN，文档说要更严格可以收窄到具体的推理配置文件 ARN。

bedrock:GetInferenceProfile 这一项文档解释得很具体：它让 Claude Code 把应用推理配置文件 ARN 解析回背后的基础模型，从而选对请求形态。缺这项权限时请求仍会成功（文档写明会用另一种形态重试一次自动恢复），但每个新模型多一次往返；这最常见于 AWS_BEARER_TOKEN_BEDROCK 部署，因为这类令牌的策略通常比完整 IAM 角色窄。

七、边界：这些地方文档明说了不行

这一节不能跳过，否则配好之后你会以为是自己配错了。

  • WebSearch 工具在 Amazon Bedrock 上不可用。 文档一句话写死，并指向工具参考页的 WebSearch 行为说明。
  • /logout 命令在 Amazon Bedrock 下不可用，因为认证走的是 AWS 凭证。
  • Claude Code 使用 Amazon Bedrock 的 Invoke API，不支持 Converse API。
  • 提示缓存不一定在所有 Amazon Bedrock 区域可用。 文档写：如果缓存 token 计数一直是零，去查 Amazon Bedrock 文档里支持的模型、区域与限制。
  • 遇到「on-demand throughput isn’t supported」报错时，文档给的处置是把模型指定为推理配置文件 ID。
  • 报错以 Bedrock streaming response has content-type 开头，说明中间的网关或代理改写了流式响应。文档写明 Amazon Bedrock 以 application/vnd.amazon.eventstream 返回二进制事件流，正解是让网关原样透传响应体和 Content-Type。
  • /context 里工具组 token 全是 0：文档写这是 v2.1.196 之前的问题，升级即可。

最后提醒一个走错门的常见情况：文档里另有一页叫 Claude Platform on AWS（code.claude.com/docs/en/claude-platform-on-aws），那是「用 AWS 认证访问 Anthropic 自营 API」，开关是 CLAUDE_CODE_USE_ANTHROPIC_AWS=1，还必须设 ANTHROPIC_AWS_WORKSPACE_ID。那一页写明：Amazon Bedrock 和 Microsoft Foundry 在 provider 路由中优先级更高，想走那条路得先取消设置 CLAUDE_CODE_USE_BEDROCK 和 CLAUDE_CODE_USE_FOUNDRY。两条路的变量名很像，配串了症状很迷惑。

八、怎么验证配对了

文档给出的验证动作有这么几个，按从粗到细排：

  1. /status——看解析出来的区域，以及区域的来源标注。这是确认变量到底有没有生效最直接的一步。
  2. aws bedrock list-inference-profiles --region your-region——文档在「Region issues」一节把它作为检查模型可用性的命令给出。
  3. 如果开关变量看起来没生效，文档在排查另一个同类变量时给出的判断是变量没到进程里：确认它在你启动 claude 的那个 shell 里导出了，或者干脆写进 settings 文件的 env 块。环境变量没传进去，是这类配置最常见的失败方式。

还有一个与「配对了没有」相关但容易误判的机制：启动时的模型检查。文档写明 Claude Code 启动时会验证它打算用的模型在你账号里可访问；钉住的版本比当前默认旧、而你的账号能调更新版本时，它会提示你更新钉法，接受会把新模型 ID 写进用户 settings 文件并重启；没钉模型而默认模型不可用时，它会为当前会话回落并显示提示，这个回落不会被持久化。也就是说，某次会话跑通了，不代表下次还落在同一个模型上——要固定下来，文档给的路只有把版本钉住。

本文依据 Claude Code 官方文档（code.claude.com/docs）于 2026-08-17 的公开内容整理。 该产品闭源，本文只复述官方文档写明的机制，不推断其内部实现； 我们没有对文中涉及的功能做过实测，因此不涉及界面外观、操作手感与运行速度的任何描述。 该产品迭代频繁，文中涉及的命令、配置项与默认值随版本变动，请以官方文档最新内容为准。 本文不涉及价格、额度与限流的具体数值，相关信息请以官方定价与用量说明页为准。

安全与合规相关做法请结合自身环境评估，本文不构成安全方案建议。

想系统学会用 AI？报名体系课或加入会员，照着学、照着用。

浏览课程 加入会员