通过 AWS Bedrock 使用 Claude Code 完全指南

为什么选择 Bedrock？

Claude Code 是 Anthropic 官方发布的 AI 编码助手，支持 CLI、VS Code 和 JetBrains 等多种形态。默认情况下它连接 Anthropic 的直接 API，但企业用户往往需要更高的安全性、合规性和统一管理能力——这正是 AWS Bedrock 的价值所在。

通过 Bedrock 使用 Claude Code 的核心优势：

维度	Anthropic 直接 API	AWS Bedrock
数据驻留	Anthropic 基础设施	数据不出 AWS
训练数据	不用于训练（需协议）	明确不用于训练
认证管理	API Key	IAM / SSO 集中管理
网络隔离	不支持	VPC PrivateLink
合规认证	单独协商	SOC2、HIPAA、GDPR、ISO 27001
企业折扣	单独协商	可叠加 AWS EDP
审计	有限	CloudTrail 完整审计
模型可用性	最新模型最先可用	可能延迟数天至数周

第一部分：快速配置指南

按照下面的流程图，5 步完成 Bedrock + Claude Code 的配置：

1. 安装 Claude Code

# npm 安装（推荐）
npm install -g @anthropic-ai/claude-code

# 或 Homebrew (macOS)
brew install claude-code

2. 配置 AWS 凭证

根据你的使用场景选择合适的认证方式：

个人开发 — Access Key

aws configure
# 输入 Access Key ID 和 Secret Access Key

团队协作 — AWS SSO / Identity Center

aws configure sso
# 按提示完成 SSO 配置
aws sso login --profile your-sso-profile
export AWS_PROFILE=your-sso-profile

云端环境 — IAM Role（推荐）

在 EC2、ECS、Lambda 等环境中，通过 Instance Profile / Task Role 自动获取凭证，无需额外配置。

跨账户 — AssumeRole

export ANTHROPIC_BEDROCK_ROLE_ARN=arn:aws:iam::TARGET_ACCOUNT:role/bedrock-access-role

3. 设置环境变量

# 必须：启用 Bedrock 模式
export CLAUDE_CODE_USE_BEDROCK=1

# 必须：指定 AWS 区域
export AWS_REGION=us-east-1

# 可选：自定义 Bedrock 端点（VPC Endpoint 场景）
export BEDROCK_ENDPOINT_URL=https://your-custom-endpoint

# 可选：指定模型版本
export ANTHROPIC_MODEL=us.anthropic.claude-sonnet-4-20250514-v1:0

推荐：将以上变量添加到 ~/.zshrc 或 ~/.bashrc 中持久化。

4. 启用 Bedrock 模型访问

在 AWS 控制台中：Amazon Bedrock → Model access → 勾选所需的 Claude 模型 → Request access

5. 验证连接

claude        # 启动 Claude Code
/doctor       # 检查连接状态

所需 IAM 权限

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": [
      "bedrock:InvokeModel",
      "bedrock:InvokeModelWithResponseStream"
    ],
    "Resource": "arn:aws:bedrock:*::foundation-model/anthropic.*"
  }]
}

支持的模型

模型	Bedrock Model ID	适用场景
Claude Opus 4	`us.anthropic.claude-opus-4-20250514-v1:0`	最强推理，复杂架构
Claude Sonnet 4	`us.anthropic.claude-sonnet-4-20250514-v1:0`	性价比最佳，日常开发
Claude Haiku 3.5	`us.anthropic.claude-haiku-3-5-20241022-v1:0`	快速响应，轻量任务

提示：模型 ID 中的 us. 前缀表示跨区域推理（Cross-Region Inference），AWS 推荐使用此方式，可自动路由到有容量的区域，减少限流。

第二部分：企业级部署架构

下图展示了企业环境中 Bedrock + Claude Code 的完整架构：

企业级 Bedrock + Claude Code 架构图：开发者工作站、认证层、AWS云端三层架构

架构要点

开发者工作站层

Claude Code CLI 或 IDE 扩展作为入口
MCP Servers 在本地运行，提供工具扩展能力
CLAUDE.md 和 Hooks 执行团队规范

认证层

AWS SSO / IAM Identity Center 集中管理身份
IAM Roles 实施最小权限原则
支持跨账户 AssumeRole 访问

AWS 云端层

VPC Endpoint (PrivateLink) 确保流量不经过公网
CloudWatch 实时监控调用量和延迟
CloudTrail 审计所有 API 调用
AWS Budgets 设置成本预警
SCP (Service Control Policies) 限制组织级访问

网络隔离配置

# 创建 Bedrock VPC Endpoint
aws ec2 create-vpc-endpoint \
  --vpc-id vpc-xxx \
  --service-name com.amazonaws.us-east-1.bedrock-runtime \
  --vpc-endpoint-type Interface \
  --subnet-ids subnet-xxx \
  --security-group-ids sg-xxx \
  --private-dns-enabled

成本管理策略

策略	方法	效果
模型选择	日常用 Sonnet，复杂任务用 Opus	降低 50-70% 成本
跨区域推理	使用 `us.` 前缀模型 ID	减少限流，提高可用性
Prompt Caching	Bedrock 支持 Claude prompt caching	重复性工作降低 ~90% 输入成本
监控	CloudWatch + Cost Explorer + Budgets	及时发现异常用量

第三部分：六大扩展机制

Claude Code 不仅是一个编码助手，更是一个可深度定制的平台。以下六大机制让你可以将它打造成专属的开发工具：

Claude Code 六大扩展机制：MCP、Skills、CLAUDE.md、Hooks、SDK、Memory

1. MCP Servers — 连接外部工具

MCP (Model Context Protocol) 是 Anthropic 开发的开放协议，让 Claude Code 能连接任意外部工具和数据源。

项目级配置 (.claude/settings.json)：

{
  "mcpServers": {
    "database": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-postgres"],
      "env": { "DATABASE_URL": "postgresql://..." }
    },
    "browser": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-playwright"]
    }
  }
}

常见 MCP Server 用途：

数据库：直接在对话中查询和修改 PostgreSQL、MySQL
浏览器自动化：Playwright 驱动的 QA 测试
项目管理：连接 Notion、Linear、Jira
自定义 API：封装内部 API 为 MCP 工具

创建自定义 MCP Server（TypeScript）：

import { McpServer } from "@anthropic-ai/mcp-sdk";

const server = new McpServer({ name: "my-tool", version: "1.0.0" });

server.tool("search_docs", "搜索内部文档", {
  query: { type: "string", description: "搜索关键词" },
}, async ({ query }) => {
  const results = await searchInternalDocs(query);
  return { content: [{ type: "text", text: JSON.stringify(results) }] };
});

server.run();

2. Skills — 自定义 Slash Commands

Skills 是可复用的提示模板，通过 /skill-name 调用。存储在 ~/.claude/skills/ 或项目的 .claude/skills/ 目录。

创建示例：

~/.claude/skills/deploy/
└── SKILL.md

---
name: deploy
description: 一键部署到生产环境
trigger: /deploy
---

# /deploy

执行以下部署流程：
1. 运行所有测试
2. 构建生产版本
3. 推送到远程仓库
4. 创建 PR 并请求审查

使用时只需输入 /deploy 即可触发完整流程。

3. CLAUDE.md — 项目指令系统

CLAUDE.md 是给 Claude Code 的持久化指令文件，支持三级层次：

级别	路径	作用域
全局	`~/.claude/CLAUDE.md`	所有项目
项目	`./CLAUDE.md`	当前项目
子目录	`./src/CLAUDE.md`	特定目录

典型内容：

# CLAUDE.md

## 技术栈
Next.js 14 (App Router) + TypeScript + Tailwind CSS

## 编码规范
- 使用函数式组件 + hooks
- 文件命名 kebab-case
- 每个新功能必须有测试

## 禁止操作
- 不允许直接 push 到 main
- 不允许 force push
- 不允许删除测试文件

4. Hooks — 生命周期事件

Hooks 在 Claude Code 的特定事件触发自定义 Shell 命令：

{
  "hooks": {
    "on_tool_call": [{
      "tool": "Write",
      "command": "echo '文件写入: $FILE_PATH' >> /tmp/claude-audit.log"
    }],
    "on_prompt_submit": [{
      "command": "security-check.sh"
    }]
  }
}

Hook 类型：

on_prompt_submit — 用户提交前（可用于安全检查）
on_tool_call — 工具调用前（可用于审计、拦截）
on_tool_result — 工具返回后（可用于自动格式化）
on_response — 响应生成后（可用于通知）

5. SDK (Headless 模式) — 自动化集成

将 Claude Code 嵌入 CI/CD 和其他自动化流程：

# 非交互式执行
claude -p "修复 src/ 下所有 TypeScript 错误" --output-format json

GitHub Actions 集成示例：

name: AI Code Review
on: [pull_request]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789:role/github-bedrock
          aws-region: us-east-1
      - run: npm install -g @anthropic-ai/claude-code
      - run: claude -p "Review this PR and provide feedback" --output-format json
        env:
          CLAUDE_CODE_USE_BEDROCK: "1"

6. Memory 系统 — 跨会话记忆

Claude Code 支持基于文件的持久化记忆，存储在 ~/.claude/projects/<project>/memory/：

user — 用户角色和偏好
feedback — 工作方式反馈
project — 项目上下文信息
reference — 外部资源指针

随着使用，Claude Code 会自动积累对你和项目的理解，使后续对话越来越高效。

第四部分：常见问题排查

"Could not connect to Bedrock"

检查清单：

CLAUDE_CODE_USE_BEDROCK=1 已设置
AWS 凭证有效：aws sts get-caller-identity
Model Access 已在 Bedrock 控制台启用
区域支持所需模型
IAM 权限包含 bedrock:InvokeModel*

限流 (ThrottlingException)

使用跨区域推理（us. 前缀模型 ID）
在 Service Quotas 控制台申请配额增加
考虑 Provisioned Throughput（预留容量）

延迟较高

选择最近的 AWS 区域
使用跨区域推理自动路由
用 Sonnet/Haiku 替代 Opus（如任务允许）
优化上下文长度，使用 /compact 压缩对话

模型不可用 (AccessDeniedException)

在 Bedrock 控制台 → Model Access 启用模型
部分模型（如 Opus）可能需要额外申请
确认所选区域是否提供该模型

第五部分：最佳实践总结

安全

最小权限：IAM 策略只授权需要的模型和区域
网络隔离：生产环境使用 VPC Endpoint
审计日志：启用 CloudTrail 跟踪所有 Bedrock 调用
Hooks 策略：通过 Hooks 拦截危险操作

效率

模型匹配任务：日常编码用 Sonnet，复杂架构用 Opus，简单修改用 Haiku
CLAUDE.md 先行：新项目先创建 CLAUDE.md，让 AI 了解项目规范
善用 MCP：连接常用工具，减少上下文切换
Skills 复用：将重复流程封装为 Skill

团队协作

共享 CLAUDE.md：纳入版本控制，统一团队 AI 行为
统一 MCP 配置：在项目 .claude/settings.json 中共享工具配置
AWS SSO 集中管理：避免 API Key 分散管理的安全风险
成本监控：通过 AWS Budgets 和 Cost Explorer 按团队追踪用量

本文综合了 Anthropic 官方文档、AWS 解决方案指南及社区实践经验。Claude Code 和 AWS Bedrock 均在快速迭代中，建议参考官方文档获取最新配置细节。

通过 AWS Bedrock 使用 Claude Code 完全指南：配置、扩展与企业部署