让编程 Agent 在本机 AWS Emulator 里测云代码

让 Claude Code、Kiro 这类编程 Agent 改 AWS 相关代码,麻烦在验证:要么连真账号,怕它建错资源、删错数据;要么每次部署到区域再看结果,来回都要等部署。AWS 11 月 11 日(美国时间)正式发布的 AWS Emulator 给了第三条路:在本机起一个 HTTPS 端点,CLI、SDK 和 Agent 照常调用 AWS API,资源只存在内存里。这篇按官方文档讲怎么装、怎么让 Agent 接上、怎么判断哪些测试结果可信。
它给 Agent 补上的是一个安全的试错场
AWS Emulator 是装在本机的 AWS API 模拟器,没有图形界面,不需要 AWS 账号,也没有额外服务费,只有真正部署到 AWS 时才为资源付费。它用 Rust 实现,按 GitHub 上 AWS API 模型仓库里的模型生成,SDK 用的也是这些模型,所以请求和报错的格式与云上一致。没实现的操作直接返回 HTTP 501,测试会马上失败,不会悄悄给出假结果。
源码以 CC0-1.0 发布在 GitHub(vendor/ 目录为 Apache-2.0),截至 2026-11-13 约 5,427 星,最新版本 v1.0.338 发布于北京时间 11 月 13 日清晨。仓库不接受 PR,问题走 Issues。代码怎么由 Agent 写出来的,见站内快讯 AWS Emulator:代码全由 Agent 写。
| 验证方式 | 每轮耗时 | 误操作代价 | 能测 IAM 吗 |
|---|---|---|---|
| 直接连真实 AWS 账号 | 取决于部署 | 真实资源与费用 | 能 |
| 部署到测试区域再看 | 要等部署 | 测试账号里的资源 | 能 |
| 本机 AWS Emulator | 不用部署 | 重启即清空 | 不能 |
前置条件
- Linux(x86_64 或 aarch64,RPM / Debian 包),或任何能跑 Docker 的系统(macOS、Windows 用 Docker)。
- AWS CLI。要用 Agent Skill 的话,版本需 2.35.0 或以上(
aws --version查看)。 - 一个支持 Skill 的编程 Agent,比如 Claude Code、Kiro 或 Cursor。
第一步:装好并启动模拟器
Linux 上装官方包。下面是 AWS 博客里 Amazon Linux 2023 的命令,Debian 系用文档里的 .deb 包:
PKG=https://downloads.aws.com/aws-emulator/packages/aws-emulator/LTS/latest
sudo dnf install -y $PKG/aws-emulator-x86_64.rpm
aws-emulator -v
aws-emulator
macOS 和 Windows 没有现成镜像,要用文档里的短 Dockerfile 自己构建(Apple 芯片把包名换成 aws-emulator-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
启动后它在 127.0.0.1:9297 提供 HTTPS,并把本次生成的凭据、配置和证书写到 ~/.aws/emulator/9297/。
第二步:把 shell 指向模拟器,并清掉真凭据
另开一个终端,设置下面这组变量(官方博客原样),最后一行把可能带来真实凭据的变量全部 unset:
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
账号应该是 000000000000,访问密钥 ID 以 EMULATOR 开头。模拟器每次启动都会换一套密钥,用别的密钥签名的请求会被拒绝。看到别的账号号码,就说明这个 shell 还在连真账号,先别让 Agent 动手。
判断 Agent 有没有连对,就看 get-caller-identity 返回的是不是 000000000000。
第三步:装 Skill,让 Agent 自己接上
AWS 给编程 Agent 准备了一个 aws-emulator Skill,下面这条命令会给 AWS CLI 在本机找到的所有 Agent(Kiro、Cursor、Claude Code 等)都装上:
aws agent-toolkit add-skill --skill-name aws-emulator --region us-east-1
装好后可以直接对 Agent 说「Install AWS Emulator and point my project at it」。按文档,这个 Skill 会按系统选 Linux 包或 Docker 安装、启动模拟器、给 CLI 或 SDK 配好指向,并处理连接、证书和签名报错;要跑 sudo 或改 shell 配置文件这类写到工作目录之外的操作前,它会先问你。
环境变量已经在当前 shell 里设好的话,也可以不装 Skill,直接把任务交给 Agent。AWS 博客里的例子是让 Kiro 建一张 DynamoDB 表、写一条数据再读回:
aws dynamodb create-table --table-name kiro-demo \
--attribute-definitions AttributeName=id,AttributeType=S \
--key-schema AttributeName=id,KeyType=HASH \
--billing-mode PAY_PER_REQUEST
aws dynamodb put-item --table-name kiro-demo \
--item '{"id": {"S": "item-1"}, "msg": {"S": "hello from kiro"}}'
aws dynamodb get-item --table-name kiro-demo --key '{"id": {"S": "item-1"}}'
给 Agent 的提示词里最好写清三条约束:只用当前 shell 的环境变量;动手前先跑 aws sts get-caller-identity 并确认账号是 000000000000;遇到 501 就报告是哪个操作没实现,不要改成连真实区域。
第四步:先查哪些调用能靠模拟器
保真度按服务差别很大。AWS 用「保真测试」衡量:一段用 SDK 跑的工作流,状态码、响应体、错误码和错误信息,以及产生的资源和数据都和真实 AWS 一致才算通过。每次发版按服务公布 k/n 通过数,测试集放在 GitHub 的 aws-emulator-evaluation-suite 仓库,没通过的也在。
可以直接问装了 Skill 的 Agent:「Will my app in this repo work on AWS Emulator?」它会找出项目依赖的 AWS 操作,对照保真测试和分数,告诉你哪些能信、哪些可能和云上不一样;发现差异时还能起草 issue,发之前先给你看。自己查就四步:列出工作流调用的操作 → 在 manifest.jsonl 里找对应的保真测试 → 到发布页看你所用版本的分数 → 没有测试覆盖的操作,同一段测试在模拟器和真实 AWS 上各跑一遍对比。
常见坑
- 拿它测权限:模拟器不按 AWS 的方式评估 IAM 策略和基于资源的策略,云上会被拒的请求在本地可能成功。安全配置一定要在真实 AWS 上测。
- Docker 端口写成
-p 9297:9297:这会把模拟器开放给整个局域网,要写-p 127.0.0.1:9297:9297。换端口时,宿主机端口、容器端口和模拟器的-p三处要一起改,不然多个容器会互相覆盖凭据文件。 - 以为资源会保留:资源只在内存里,Ctrl+C 停掉或容器超出 2 GiB 内存限制(退出码 137)就全部清空。Agent 的测试脚本要能从零建起。
- 跨账号、跨区域场景:每个实例只模拟单账号,没有跨账号和跨区域行为,这类逻辑要另外测。
- Java SDK 连不上:部分 SDK 要额外信任模拟器证书,Java 需要配置 trust store。
- 遥测:默认会发匿名使用和错误数据。关掉用
aws-emulator --telemetry off,或先export EMULATOR_TELEMETRY=off,也可以在~/.aws/emulator/config.toml里写[telemetry]enabled = false。
完成标准
/__admin/health有响应,aws sts get-caller-identity返回000000000000。- Agent 在模拟器里完成一次「建资源 → 写入 → 读回」,全程没有用到真实凭据。
- 项目里用到的 AWS 操作,已经按保真分数分成「可靠模拟器验证」和「上线前必须在真实 AWS 测」两类。
- IAM 和跨账号相关逻辑,列进了上线前的真实环境测试清单。
最后
挑项目里一个只用 S3 或 DynamoDB 的测试,先按第二步配好变量,让 Agent 在模拟器里把它跑通,再决定要不要把整套测试搬过来。