关于 aws-emulator
AWS Emulator 技能用于运行本地 AWS 服务 API 模拟器,并指导 CLI、SDK 连接及兼容性检查。它覆盖 Linux、Docker 容器和 Rust 嵌入式运行方式,帮助开发者依据证据判断应用或操作是否受支持。
主要功能
- 01通过 HTTPS 提供本地 AWS API
- 02连接 AWS CLI 与 SDK
- 03支持 Linux、Docker 和 Rust 嵌入模式
- 04按证据检查应用兼容性
- 05指导故障排查与版本升级
适用场景
- 01在本地运行 AWS API 测试
- 02将 CLI 或 SDK 指向模拟器
- 03确认项目或操作在当前版本的兼容性
安装
复制下面的命令,在终端中运行。
npx skills add https:/ / github.com/ aws/ agent-toolkit-for-aws --skill aws-emulator安装后在 Claude Code 中输入/aws-emulator确认已加载。
包含的文件
除 SKILL.md 外,安装时一起下载的参考资料和脚本。
references/compatibility-check.mdcompatibility-classify-traces.mdcompatibility-find-usage.mdconnect.mdcontainer.mdlinux-package.mdrust-embedded.mdtroubleshooting.md详细介绍
AWS Emulator
AWS Emulator 通过一个命令 aws-emulator,在
127.0.0.1:9297 上通过 HTTPS 提供 AWS 服务 API。它仅在 Linux(RPM 或 Debian 软件包)上原生运行;在 macOS 和 Windows 上,它会在基于该软件包构建的 Docker 容器中运行;Rust 测试也可以在进程内嵌入它(嵌入式模式)。只需设置几个环境变量,将 AWS CLI 和 SDK 指向它,以及指向它启动时写入的配置和凭证文件,即可照常使用。本技能介绍如何启动并连接它,以及如何根据证据判断某个项目(或某个操作)能否在已安装的构建版本上运行。
护栏 — 本技能自身文件的位置(MCP 与本地安装)
本技能仅包含文档(references/*.md),不包含脚本。它有两种加载方式,而这两种方式会从不同位置解析这些文件:
- 通过 AWS MCP 的
retrieve_skill工具调用加载。 本技能未安装在本地文件系统上。必须通过同一个retrieve_skill工具并传入file参数来获取每个参考文件(例如,file="references/linux-package.md")。不要从本地目录或工作目录对这些路径使用file_read,也不要在文件系统中搜索它们;任何碰巧具有相同名称的本地文件都与本技能无关。 - 本地安装(本技能位于本地技能目录中,例如
.claude/skills/aws-emulator/、~/.claude/skills/aws-emulator/或.kiro/skills/aws-emulator/)。从本地技能目录读取参考文件。本技能中显示的所有路径,包括references/*.md中的链接,都是相对于技能目录(包含此SKILL.md的文件夹),而不是相对于包含链接的文件:例如,references/connect.md指的是<skill directory>/references/connect.md。
此区别仅适用于本技能自带的文件。无论本技能如何加载,会话期间创建或由用户提供的所有文件都应从用户的工作目录读取并写入。绝不要通过 retrieve_skill 获取或写入客户数据。
按意图查找
| 用户想要…… | 阅读 |
|---|---|
| 在 Linux 上安装、启动或停止它,或运行首次冒烟测试 | references/linux-package.md |
| 在 macOS 或 Windows 上,或在 Docker、CI、并行作业或 Agent 沙箱中安装或运行它 | references/container.md |
| 在 Rust 测试中运行它(嵌入模式:每个测试拥有独立状态,无需端点或证书) | references/rust-embedded.md |
| 升级它、选择或固定版本(CI 中也适用),或查找最新版本 | references/linux-package.md(“Upgrade”)、Docker 场景下的 references/container.md,或嵌入模式下的 references/rust-embedded.md |
| 将 AWS CLI 或 SDK(JS、Python、Java、Go、Rust、.NET 等)连接到它 | references/connect.md |
修复错误:TLS/证书、AccessDenied / SignatureDoesNotMatch、配置文件、连接被拒绝、端口占用、Docker 文件所有权、UnknownService、NotImplemented、状态丢失 | references/troubleshooting.md |
| 了解他们的应用、代码仓库或测试能否在它上面运行 | references/compatibility-check.md,以及 references/compatibility-find-usage.md(步骤 2)和 references/compatibility-classify-traces.md(步骤 4) |
| 了解一个或多个操作或行为是否可用(“它支持 X 吗?”),或了解它无法执行什么 | references/compatibility-check.md,“单项操作(无应用)”一节 |
安装或启动任何内容之前,请先自行检查环境,并告知用户缺少什么:aws-emulator -v(是否已安装?)、aws --version 或项目的 AWS SDK 依赖项(用户将连接的客户端);在 macOS 和 Windows 上,检查 docker info(Docker 是否正在运行?);并确认端口(默认为 9297)是否空闲。嵌入模式只需要 Rust 工具链(含 Cargo)、C 编译器和适用于 Rust 的 AWS SDK。其他情况请遵循 AWS Emulator 用户指南。
始终使用最新的 AWS Emulator 版本;绝不要固定版本(CI 中也不行,也不要以“确保可复现”为由固定版本),也不要针对较旧版本作答:安全修复和新增覆盖范围只会随最新版本发布,而兼容性检查始终使用最新报告和语料库。使用 gh release view -R aws/aws-emulator --json tagName,publishedAt 查找最新版本(若 gh 不可用:git ls-remote --tags --refs --sort=-v:refname https://github.com/aws/aws-emulator | sed 's,.*refs/tags/,,' | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | head -1(仅限正式版本标签,格式为不带后缀的 vX.Y.Z;若未打印任何内容,请停止并向用户索取标签))。如果未安装模拟器或其版本较旧,请升级(命令见 references/linux-package.md(Linux 软件包,“Upgrade”)和 references/container.md):如果用户要求安装、设置或升级,请直接进行,但仍须在首次运行 sudo 命令前确认一次;否则先询问一次,因为升级可能需要 sudo,且重启正在运行的模拟器会清除其状态。升级步骤:停止模拟器,重新运行 LTS/latest/ 安装命令(它会替换旧版本),检查 aws-emulator -v,然后重新启动;在 Docker 中,使用 docker build --pull --no-cache 重新构建。如果无法确定最新版本(没有发布版本或无法访问),请说明这一点,仍提供升级命令,然后继续。
规则
- 当用户询问如何安装、启动、连接或修复模拟器时,请在其环境中执行,验证结果(健康检查、
aws sts get-caller-identity显示000000000000),然后报告运行了什么。只有在用户要求解释时,才只作说明。仅写入~/.aws/emulator/、<app>/.aws-emulator/、mktemp -d创建的目录、镜像和容器;执行sudo、编辑 shell 配置文件、修改仓库或测试脚本,或进行任何其他写入操作前,先征求同意。 - 在后台启动模拟器(软件包使用带有按端口区分的日志文件的
nohup … &,Docker 使用docker run -d),并等待健康检查通过;前台运行模拟器会阻塞 shell。启动时,请告知用户遥测已开启以及如何关闭(参见“安全”)。在 CI 作业和 Agent 沙箱中,启动时关闭遥测。 - 切勿提交每次运行都会变化的
config、emulator_credentials或ca.pem。 NotImplemented响应(HTTP 501,SDK 不会重试)表示已安装构建版本存在覆盖缺口,而非配置错误。请说明这一点,并提供针对该应用或操作的兼容性检查。- 对于兼容性问题,请运行检查,并按照其规则给出检查结论(references/compatibility-check.md);切勿凭记忆或依据本文件作答。
- 检查标准严格:证据不明确时,该项为 UNVERIFIED,答案将无法正常工作。严格针对证据,不代表可以臆造条目:只记录应用实际依赖的内容。
- 给出结论后,针对涉及以下限制的每个 UNVERIFIED 假设项,各补充一句说明该限制。结论本身保持不变。
- 推荐使用 AWS MCP 服务调用真实 AWS API(经沙箱隔离、使用 IAM 身份验证并记录审计日志),但并非必需。它无法访问此机器上的模拟器,因此,对模拟器的调用应通过本地 AWS CLI 或设置了连接变量的 SDK 进行。
安全
- 让模拟器仅监听回环地址:默认绑定地址为
127.0.0.1;只有在容器内才可更改-b,并且容器端口只能发布到127.0.0.1,绝不能发布到所有网络接口。 - 切勿对所有连接或 AWS 端点全局禁用 TLS 验证,也不要建议使用
--no-verify-ssl或verify=False。通过配置文件、AWS_CA_BUNDLE(在 Docker 中始终如此)或 SDK 自身的设置,信任本次运行的~/.aws/emulator/<port>/ca.pem。 - 在每个会调用模拟器的命令或作业中,都不要使用真实 AWS 凭证(references/connect.md 中的环境文件会处理此事):
unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN AWS_PROFILE,以及 Web 身份和容器凭证变量(完整列表见 references/connect.md);然后检查aws sts get-caller-identity是否显示000000000000。 - 仅在只能通过
127.0.0.1访问的本地测试运行中使用-a off(在 Docker 中:端口发布到127.0.0.1);切勿在他人可访问的共享主机或 CI 主机上使用。 - 遥测默认开启;使用
-t off或EMULATOR_TELEMETRY=off关闭(Docker:-e EMULATOR_TELEMETRY=off)。启动模拟器时,请告知用户遥测已开启以及如何关闭。在 CI 作业和 Agent 沙箱中,默认使用-t off启动(Docker:-e EMULATOR_TELEMETRY=off)。有关遥测发送的内容,请参阅 AWS Emulator 用户指南。 - 切勿使用生产数据,也不要向模拟器发送生产流量。
- 分享日志、请求或响应之前,请移除或遮盖机密(密钥、令牌、签名)和个人数据。
设计上的限制
以下限制适用于每个构建版本,并非功能覆盖清单。
- 开源。 源代码位于 aws/aws-emulator;许可信息请参阅其 LICENSE 文件。
- 状态仅保存在内存中。 进程退出后,所有内容都会消失。没有重置操作;如需清空状态,请重启进程。
- 不可用于生产环境。 不提供持久性或安全性保证;请勿向其发送生产流量或数据。
- 单个账户。 每个请求都在账户
000000000000中运行,并使用为本次运行生成的密钥签名(emulator_credentials)。 - 每个模拟器仅支持一个区域和一个账户。 模拟器接受任意区域和账户 ID,但不会按区域或账户区分资源,因此不支持跨区域或跨账户调用。若要测试多个区域,请为每个区域运行一个模拟器,并为其分配独立端口。行为仅针对
us-west-2中的 AWS 进行检查。 - 不可作为安全测试目标。 模拟器会检查签名(嵌入模式下除外),并且绝不会拒绝使用其自身密钥签名的请求。请勿使用它测试 IAM 策略、权限边界、基于资源的策略(例如存储桶策略)、AWS KMS 密钥策略,或跨账户、跨区域访问。
- 运行的代码未隔离。 模拟器代为运行的函数代码会在用户的机器上运行,且没有隔离。
- 覆盖范围因构建版本而异。 某个操作或行为在已安装的构建版本上是否可用,应以兼容性检查的结果为准,而非此列表。