AWS Emulator 是什么、怎么装?让 Claude Code / Codex 在本地测 AWS 应用(1.0.322 实测)

AWS Emulator 是 AWS 官方 2026 年 11 月 12 日(北京时间)正式发布的本地 AWS 模拟器,没有额外服务费、源码开放,不需要 AWS 账号,覆盖 200 多个服务。本文在 Debian 13 上实测 1.0.322:安装命令、AWS CLI 指向本地 endpoint 建 S3 桶和 DynamoDB 表、常见报错,以及让 Claude Code、Codex、Cursor 对着模拟器写代码跑测试的接法。

9 分钟阅读
AWS Emulator 是什么、怎么装?让 Claude Code / Codex 在本地测 AWS 应用(1.0.322 实测)

AWS Emulator 是 AWS 官方出的本地 AWS 模拟器。它在你自己的电脑上起一个 HTTPS endpoint,AWS CLI、AWS SDK 和编程 Agent 用跟云上一样的 API 调它,不需要 AWS 账号,也不会创建真实的云资源。据 AWS 官方博客,它于 2026 年 11 月 11 日(美国时间)正式发布(GA),对应北京时间 11 月 12 日凌晨约 2 点。

2026 年 11 月 13 日(北京时间,UTC+8),我们在一台 Debian 13 x86_64 机器上装了当时 LTS 通道的 AWS Emulator 1.0.322,用 AWS CLI 2.40.1 建了 S3 桶、DynamoDB 表、SQS 队列和 Lambda 函数,再让 Claude Code 2.1.319 和 Codex CLI 0.167.0 各自对着模拟器写代码、跑测试。下面的命令、耗时和输出都来自这次实际运行。

创建 API Key →

先看结论

问题答案
AWS Emulator 是什么?AWS 官方的本地 AWS API 模拟器,用 Rust 实现,没有图形界面。据 AWS 官方,基于 400 多个 API 模型,覆盖 200 多个 AWS 服务。
收费吗?需要 AWS 账号吗?据 AWS 官方,没有额外服务费,也不需要 AWS 账号;源码在 GitHub,采用 CC0 公共领域协议。
怎么装?Linux 装 RPM 或 Debian 包;macOS 和 Windows 用官方文档里的 Dockerfile 自己构建镜像(官方不提供现成镜像);Rust 项目还可以用嵌入模式。
怎么用?运行 aws-emulator,默认监听 https://127.0.0.1:9297;设置几个环境变量,让 AWS CLI 和 SDK 指向它,业务代码不用改。
实测结果下载加安装约 6 秒,启动后约 0.3 秒健康检查就返回 ok,S3、DynamoDB、SQS、Lambda 都跑通。Claude Code 用约 32 秒、Codex 用约 81 秒完成同一个「S3 + DynamoDB + pytest」任务,两边测试都是 2 passed。
最需要注意的一点它不按 AWS 的方式评估 IAM 策略,也只模拟单账号、单区域。权限和安全相关的逻辑,最终还要在真实 AWS 上测。

AWS Emulator 是什么

据 AWS 官方博客,AWS Emulator 启动时会自己生成一套凭证、一个 config 文件和一张证书,写到 ~/.aws/emulator/9297/。你把 SDK 的环境变量指过去,请求就发到本机,而不是 AWS。它按 AWS SDK 用的同一批 API 模型实现,所以返回的数据和错误跟云上同样的格式。

它主打的使用场景是编程 Agent。据 @AWSNewsroom,AWS Emulator 的每一行代码都由运行在 Amazon Bedrock AgentCore 上的自主 AI Agent 写成,几百个 Agent 分成三组,分别负责写测试、实现功能和审查。据 AWS 的 Swami Sivasubramanian 在 All Things Distributed 的客座文章,Agent 先写「保真度测试」(fidelity test),并让测试在真实 AWS 上通过,再去实现模拟器,直到模拟器也通过同一个测试。AWS CTO @Werner 称,它完全由 Agent 编写和测试,为 200 多个 AWS 服务提供了接近真实运行环境的测试环境。

发布后讨论度不低。据 X 公开数据,截至 11 月 13 日凌晨(北京时间),@AWSNewsroom 的发布帖约 11.1 万次浏览、705 次点赞、206 次转发;@awsdevelopers 的发布帖约 7.8 万次浏览、1203 次点赞、758 次收藏。GitHub 仓库 aws/aws-emulator 同期约 4400 星。

时间线

时间(北京时间)事件
11 月 11 日1.0.322 发布(aws-emulator -v 显示的发布日期是 2026.11.10)
11 月 12 日 约 02:00AWS 官方博客、Werner 和 AWS 官方账号同时宣布 GA
11 月 13 日 00:16我们从 LTS/latest 下载到的仍是 1.0.322;同一时间 GitHub Releases 上出现了 v1.0.336

AWS Emulator 发版很频繁。官方 skill 也要求始终用最新版,所以你装的时候版本号大概率比我们新。

安装 AWS Emulator

官方给了四条路径(据 Getting started 文档):让 AI 编程 Agent 帮你装、Linux 包、Docker、Rust 嵌入模式。

Linux:RPM 或 Debian 包

bash
# Debian / Ubuntu(x86_64)
curl -fsSLo aws-emulator.deb https://downloads.aws.com/aws-emulator/packages/aws-emulator/LTS/latest/aws-emulator_amd64.deb
sudo apt-get install -y ./aws-emulator.deb

# Amazon Linux / Fedora / RHEL(x86_64)
sudo dnf install -y https://downloads.aws.com/aws-emulator/packages/aws-emulator/LTS/latest/aws-emulator-x86_64.rpm

# 确认版本
aws-emulator -v

ARM 机器把文件名换成 aws-emulator_arm64.deb 或 aws-emulator-aarch64.rpm。包会装到 /opt/aws-emulator/,并把 aws-emulator 命令放进 /usr/bin/。

我们实测的输出:

text
Version: 1.0.322
Release date: 2026.11.10
Commit: 7753983c6e495ec3612695b1336bf4936fc7b7fd

deb 包大约 171 MB,下载用了 1.7 秒,下载加 apt-get install 总共约 6 秒。官方文档还给了 GPG 校验步骤:包旁边有同名的 .sig 文件,导入 https://downloads.aws.com/keys/gpg/current.asc 后,指纹应为 98BC F336 A3BE 53B7 34E9 67C5 2E5B F49B D940 F624。我们按步骤校验,结果是 Good signature from "SSM Publishing <ssm-publishing@amazon.com>"。

macOS / Windows:用 Dockerfile 自己构建

据 Docker 文档,官方不发布现成镜像,需要用下面这个 Dockerfile 自己构建。Apple 芯片把 x86_64.rpm 换成 aarch64.rpm:

dockerfile
FROM public.ecr.aws/amazonlinux/amazonlinux:2023-minimal
ADD https://downloads.aws.com/aws-emulator/packages/aws-emulator/LTS/latest/aws-emulator-x86_64.rpm /tmp/aws-emulator.rpm
RUN rpm -i /tmp/aws-emulator.rpm && rm /tmp/aws-emulator.rpm \
 && mkdir -p /home/emulator && chown 1000 /home/emulator
USER 1000
ENV HOME=/home/emulator
EXPOSE 9297
ENTRYPOINT ["aws-emulator", "-b", "0.0.0.0"]
bash
docker build -t aws-emulator .
mkdir -p ~/.aws/emulator
PORT=9297
docker run --rm --memory=2g --memory-swap=2g -p 127.0.0.1:$PORT:$PORT \
  -e HOME="$HOME" -v "$HOME/.aws/emulator:$HOME/.aws/emulator" \
  aws-emulator -p $PORT

端口映射要写 -p 127.0.0.1:9297:9297,不要写 -p 9297:9297,否则局域网里的其他机器也能访问。这台测试机没有 Docker,Docker 这条路径我们只照官方文档整理,没有跑。

启动并让 AWS CLI 指向它

第一个终端启动模拟器(-t off 关闭默认开启的匿名遥测):

bash
aws-emulator -t off

日志是 JSON 行格式,其中一行会给出 endpoint、config、证书路径:

text
"endpoint_url":"https://127.0.0.1:9297","health_check_url":"https://127.0.0.1:9297/__admin/health","config_file":"/home/box/.aws/emulator/9297/config","ca_file":"/home/box/.aws/emulator/9297/ca.pem"

第二个终端设置环境变量。这一组来自 AWS 官方博客,注意最后一行要清掉真实 AWS 凭证:

bash
export AWS_ENDPOINT_URL=https://127.0.0.1:9297
export AWS_SHARED_CREDENTIALS_FILE=~/.aws/emulator/9297/emulator_credentials
export AWS_CONFIG_FILE=~/.aws/emulator/9297/config
export AWS_EC2_METADATA_DISABLED=true
export AWS_DISABLE_HOST_PREFIX_INJECTION=true
export AWS_REGION=us-east-1
export AWS_DEFAULT_REGION=us-east-1
unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN AWS_PROFILE

先确认连的是模拟器:

bash
curl --cacert ~/.aws/emulator/9297/ca.pem https://127.0.0.1:9297/__admin/health
aws sts get-caller-identity

我们这次启动后约 0.27 秒,健康检查就返回 ok。get-caller-identity 返回的账号是模拟器固定的 000000000000,ARN 是 arn:aws:iam::000000000000:user/emulator。看到这个账号,就说明请求没有发到真实 AWS。模拟器空跑时常驻内存约 283 MB。

实测:S3、DynamoDB、SQS、Lambda

bash
aws s3 mb s3://aicodewith-emu-demo
echo "hello from the emulator" > hello.txt
aws s3 cp hello.txt s3://aicodewith-emu-demo/
aws s3 ls s3://aicodewith-emu-demo/

aws dynamodb create-table --table-name notes \
  --attribute-definitions AttributeName=id,AttributeType=S \
  --key-schema AttributeName=id,KeyType=HASH --billing-mode PAY_PER_REQUEST
aws dynamodb wait table-exists --table-name notes
aws dynamodb put-item --table-name notes --item '{"id":{"S":"n1"},"msg":{"S":"hello"}}'
aws dynamodb get-item --table-name notes --key '{"id":{"S":"n1"}}'
操作结果单条命令耗时
s3 mb / s3 cp / s3 lsmake_bucket: aicodewith-emu-demo,上传 24 字节,列表能看到 hello.txt约 0.55–0.6 秒
dynamodb create-table返回状态 CREATING约 0.5 秒
建表后马上 put-itemResourceNotFoundException: Requested resource not found约 0.5 秒
wait table-exists 之后再 put-item / get-item写入成功,读回 {"id":"n1","msg":"hello"}约 0.5 秒
sqs create-queue / send-message / receive-message收到刚发的消息体 "hi"约 0.5 秒
lambda create-function(Python 3.13)+ invokeStatusCode: 200,函数返回 {"ok": true, "echo": {"a": 1}}约 0.6 秒

单条命令 0.5 秒左右,大部分是 AWS CLI 自己的启动时间,模拟器的响应很快。

有两个现象值得注意,它们都跟真实 AWS 的行为一致:

  • DynamoDB 刚建的表不能马上写。 建表后状态是 CREATING,立刻 put-item 会报 ResourceNotFoundException。先 aws dynamodb wait table-exists,或在代码里用 waiter,再写入。Agent 写的测试最容易在这里翻车。
  • Lambda 会检查角色的信任策略。 我们第一次用一个 Statement 为空的角色建函数,报 The role defined for the function cannot be assumed by Lambda。信任策略里加上 lambda.amazonaws.com 的 sts:AssumeRole 后,函数才建成功。

让 Claude Code、Codex、Cursor 对着模拟器干活

方式一:装官方 aws-emulator skill

据 AI 编程 Agent 入门文档,AWS CLI 2.35.0 及以上可以一条命令装官方 skill。装好后可以直接对 Agent 说「Install AWS Emulator and point my project at it」:

bash
aws agent-toolkit add-skill --skill-name aws-emulator --region us-east-1

这条命令会安装到本机检测到的所有 Agent,不需要 AWS 账号。我们用 AWS CLI 2.40.1 实测,每次 0.6 秒左右,检测到哪个 Agent 就写到哪个目录:

  • Claude Code:~/.claude/skills/aws-emulator/
  • Codex:~/.agents/skills/aws-emulator/
  • Cursor:~/.cursor/skills/aws-emulator/

注意:执行这条命令前,不要在当前 shell 里设置 AWS_ENDPOINT_URL。我们第一次就是在已经指向模拟器的终端里执行的,报了 UnknownService ... GetLatestSkillVersion,因为下载 skill 的请求也被发到了模拟器。换一个干净的终端就好了。

skill 本身只有文档,没有脚本。内容包括 Linux、Docker、Rust 嵌入模式的安装步骤,SDK 连接方法,一张报错对照表,以及「我的项目能不能在模拟器上跑」的兼容性检查流程。Skill 的通用机制见《Agent Skills 怎么用》。

方式二:环境变量写好,直接给 Agent 派活

Claude Code、Codex、Cursor 的 Agent 都是在终端里执行命令的,所以最省事的办法是:在启动 Agent 的那个终端里,先把上一节的环境变量设好。Agent 跑的 aws 命令、boto3 测试会自动连到模拟器,即使 Agent 写错了,也不会碰到真实账号。Cursor 的终端同样认这些环境变量;我们这次在 Cursor 里只装了 skill,没有用 Cursor 跑任务。

我们给 Claude Code 和 Codex 发了同一个任务。项目是一个空的 Python 仓库,.venv 里预装了 boto3 1.44.1 和 pytest 9.2.0:

text
The shell already points the AWS CLI and SDKs at a local AWS Emulator (AWS_ENDPOINT_URL=https://127.0.0.1:9297); never use a real AWS account.
1. Write notes.py with save_note(bucket, table, note_id, text): put the text in S3 at notes/<note_id>.txt and put an item {id, s3_key} in the DynamoDB table; and get_note(bucket, table, note_id) that returns the text by reading the item and then the S3 object.
2. Write tests/test_notes.py with pytest: create a uniquely named bucket and table (string key "id", PAY_PER_REQUEST, wait until the table exists) against the emulator, then test save/get round trip and that get_note of a missing id raises KeyError.
3. Run .venv/bin/pytest -q until it passes, then verify with the aws CLI that the object and item exist. Finish with a 3-line summary.
客户端模型墙钟耗时结果
Claude Code 2.1.319(claude -p)claude-opus-5-5约 32.3 秒,5 轮写出 notes.py 和 tests/test_notes.py,2 passed;用 aws CLI 确认对象 notes/n1.txt 和对应条目都在
Codex CLI 0.167.0(codex exec)gpt-6.1-sol约 80.9 秒写出 notes.py、tests/test_notes.py,另加了 pytest.ini;2 passed in 3.36s,再用脚本确认对象和条目都在

两边都自己用了 get_waiter("table_exists"),没有踩到上面「建表后马上写」的坑。之后我们在 Claude Code 的目录里自己重跑 .venv/bin/pytest -q,结果还是 2 passed in 3.24s;aws s3 ls 能看到两边测试建的 notes-test-* 桶。Agent 的自述可以参考,但最终要以你自己重跑测试的结果为准。

这次是用非交互方式跑的:Claude Code 加了 --permission-mode bypassPermissions,Codex 加了 --dangerously-bypass-approvals-and-sandbox。这只适合一次性的测试目录。在真实仓库里,建议用 hooks 拦住危险命令,见《Claude Code / Codex / Cursor Agent Hooks 配置》。想在一个界面里同时调 Claude Code 和 Codex,可以看《T3 Code 接入 Claude Code 和 Codex》。

Claude Code / Codex 接 AICodeWith API Key

上面的测试里,两个客户端都接的是 AICodeWith API Key。不想用官方订阅登录的话,把两个 CLI 的全局配置写好即可。

Claude Code 写 ~/.claude/settings.json(完整说明见《Claude Code 第三方 API 配置》):

json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.aicodewith.ai",
    "ANTHROPIC_AUTH_TOKEN": "你的 AICodeWith API Key"
  }
}

Codex 写 ~/.codex/config.toml(下载安装见《Codex 下载》,字段含义见《Codex config.toml 配置指南》):

toml
model_provider = "aicodewith"
model = "gpt-6.1-sol"

[model_providers.aicodewith]
name = "aicodewith"
base_url = "https://api.aicodewith.ai/chatgpt/v1"
wire_api = "responses"
experimental_bearer_token = "你的 AICodeWith API Key"

写完先单独验证一次:claude -p "Reply with exactly: pong" 和 codex exec --skip-git-repo-check "Reply with exactly: pong"。这次两条都返回 pong,Claude Code 用时约 4.3 秒,Codex 约 4.8 秒。

注意两套凭证别混:AICodeWith Key 只给 Agent 调模型用;AWS 那边用的是模拟器每次启动生成的 EMULATOR... 开头的临时密钥,跟模型 Key 没关系。

创建 API Key →

放进 CI

据官方文档,模拟器的状态只存在内存里,/__admin/health 是专门给脚本和容器等待就绪用的。下面是一个 GitHub Actions 示例,安装和启动命令就是我们上面在 Debian 上跑的那几条:

yaml
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install and start AWS Emulator
        run: |
          curl -fsSLo aws-emulator.deb https://downloads.aws.com/aws-emulator/packages/aws-emulator/LTS/latest/aws-emulator_amd64.deb
          sudo apt-get install -y ./aws-emulator.deb
          aws-emulator -t off &
          until curl -sf --cacert ~/.aws/emulator/9297/ca.pem https://127.0.0.1:9297/__admin/health; do sleep 0.2; done
      - name: Run tests against the emulator
        run: |
          export AWS_ENDPOINT_URL=https://127.0.0.1:9297
          export AWS_SHARED_CREDENTIALS_FILE=~/.aws/emulator/9297/emulator_credentials
          export AWS_CONFIG_FILE=~/.aws/emulator/9297/config
          export AWS_EC2_METADATA_DISABLED=true AWS_DISABLE_HOST_PREFIX_INJECTION=true
          export AWS_REGION=us-east-1 AWS_DEFAULT_REGION=us-east-1
          pytest -q

CI 任务的环境变量里不要放真实 AWS 凭证,这也是官方的建议。

局限:哪些事它做不了

据 AWS 官方博客和 Fidelity 文档:

  • 不评估 IAM 策略。 在 AWS 上会被拒绝的请求,在模拟器里可能成功。所以别拿它测安全性。
  • 只模拟单账号、单区域。 没有跨账号、跨区域的行为。
  • 还没实现的操作返回 HTTP 501(`NotImplemented`)。 测试会直接失败,不会悄悄通过。
  • 保真度因服务而异。 控制面 API(建、查、删资源)最接近 AWS;数据面 API,以及 CloudFormation、Terraform、CDK 这类 IaC 工具的支持,各服务差别比较大。每个版本各服务的保真度分数发在 GitHub Releases 上,测试集公开在 aws-emulator-evaluation-suite 仓库。
  • 重启就清空。 我们停掉再启动后,之前建的桶和表都没了,emulator_credentials 里的 Access Key 也从 EMULATORC3... 换成了 EMULATOR1D...。所以每次重启后要重新读凭证文件。

常见报错与解法

报错 / 现象原因解法
AccessDenied: Sign the request with the emulator credentials用了别的密钥签名,比如环境变量里残留的真实 AWS Key(我们实测用假 Key 时出现)unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN AWS_PROFILE,并把 AWS_SHARED_CREDENTIALS_FILE 指向本次运行的 emulator_credentials
ResourceNotFoundException,刚建完 DynamoDB 表表还在 CREATING(我们实测遇到)aws dynamodb wait table-exists,或在代码里用 waiter
UnknownService: could not resolve a target service把不是发给模拟器的请求发给了它,比如在设了 AWS_ENDPOINT_URL 的终端里装 skill(我们实测遇到)换一个没设 AWS_ENDPOINT_URL 的终端执行
SSL: CERTIFICATE_VERIFY_FAILED客户端不信任本次运行的 ca.pem设 AWS_CONFIG_FILE;Node 设 NODE_EXTRA_CA_CERTS,Java 用 truststore.p12;不要关闭证书校验
sts get-caller-identity 显示真实账号这条命令没带 AWS_ENDPOINT_URL,请求发到了 AWS在设好环境变量的终端或脚本里执行
Address already in use端口被占用换端口,比如 aws-emulator -p 9300,环境变量里的端口也跟着改
NotImplemented / HTTP 501当前版本还没实现这个操作先升级到最新版,再去 Releases 查该服务的保真度分数

FAQ

AWS Emulator 和真实 AWS 的 API 一样吗?

据 AWS 官方,它是按 AWS SDK 使用的同一批 Smithy API 模型实现的,请求和错误的格式跟 AWS 相同。至于行为对不对,要看各服务的保真度分数。我们这次遇到的 DynamoDB CREATING 状态和 Lambda 信任策略检查,都跟 AWS 一致。

macOS 能直接装吗?

不能直接装,要用 Docker。官方只发布 Linux 包,macOS 和 Windows 需要用官方 Dockerfile 自己构建镜像。

能拿它跑生产或者测安全吗?

不能。官方明确说它只用于构建和测试,不评估 IAM 策略,也不适合生产负载。

Agent 会不会不小心改到我的真实 AWS 资源?

只要启动 Agent 的终端里设了 AWS_ENDPOINT_URL,并 unset 了真实凭证,请求就只会发到本机。模拟器也只接受用它自己生成的 EMULATOR... 密钥签名的请求。动手前先跑一次 aws sts get-caller-identity,确认返回的账号是 000000000000。

Claude Code、Codex、Cursor 哪个更适合?

三者都能用:都能装官方 skill,也都能直接继承终端里的环境变量。这次同一个任务,Claude Code 和 Codex 都一次跑通了。选哪个,按你平时的习惯来。

创建 API Key →

资料

相关文章

UI SDK 是什么、怎么用?Vercel + shadcn 给 Agent 的行为库,在 Claude Code / Codex / Cursor 里安装与实测(0.1.0-beta.1)

UI SDK 是什么、怎么用?Vercel + shadcn 给 Agent 的行为库,在 Claude Code / Codex / Cursor 里安装与实测(0.1.0-beta.1)

UI SDK 是 Vercel 在 2026 年 11 月 12 日发布的、给 Agent 用的行为(behaviors)库,版本 0.1.0-beta.1。行为写在与框架无关的 @ui-sdk/core 里,再由 React、Vue、Svelte、Solid 和 Web Components 适配器渲染。本文按官方文档整理它是什么、怎么安装、怎么给 Claude Code / Codex / Cursor 装 skill,并记录我们在测试机上的真实命令、耗时和输出。

T3 Code 是什么、怎么装?接入 Claude Code 和 Codex、配置第三方 API Key 与常见报错(0.1.9 实测)

T3 Code 是什么、怎么装?接入 Claude Code 和 Codex、配置第三方 API Key 与常见报错(0.1.9 实测)

T3 Code 是 pingdotgg 开源的编码 Agent 控制台,本身不带模型,调用你机器上已装好的 Claude Code、Codex、Cursor 等 CLI。本文在 Linux 上实测 T3 Code 0.1.9:讲清安装命令,Claude Code 和 Codex 先各自接上 AICodeWith API Key、再由 T3 Code 调用的配置方法,用 t3 thread 命令行跑通两端的过程,以及我们实际遇到的报错和解法。