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 各自对着模拟器写代码、跑测试。下面的命令、耗时和输出都来自这次实际运行。
先看结论
| 问题 | 答案 |
|---|---|
| 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:00 | AWS 官方博客、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 包
# 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/。
我们实测的输出:
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:
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"]
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 关闭默认开启的匿名遥测):
aws-emulator -t off
日志是 JSON 行格式,其中一行会给出 endpoint、config、证书路径:
"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 凭证:
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
先确认连的是模拟器:
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
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 ls | make_bucket: aicodewith-emu-demo,上传 24 字节,列表能看到 hello.txt | 约 0.55–0.6 秒 |
| dynamodb create-table | 返回状态 CREATING | 约 0.5 秒 |
| 建表后马上 put-item | ResourceNotFoundException: 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)+ invoke | StatusCode: 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」:
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:
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 配置》):
{
"env": {
"ANTHROPIC_BASE_URL": "https://api.aicodewith.ai",
"ANTHROPIC_AUTH_TOKEN": "你的 AICodeWith API Key"
}
}
Codex 写 ~/.codex/config.toml(下载安装见《Codex 下载》,字段含义见《Codex config.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 没关系。
放进 CI
据官方文档,模拟器的状态只存在内存里,/__admin/health 是专门给脚本和容器等待就绪用的。下面是一个 GitHub Actions 示例,安装和启动命令就是我们上面在 Debian 上跑的那几条:
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 都一次跑通了。选哪个,按你平时的习惯来。



