OpenAI Codex 在 Amazon Bedrock 上的部署指南

开发者越来越多地将 Codex 与 Amazon Bedrock 结合使用，以探索不熟悉的代码、进行修改并处理重复性的工程工作。对于平台团队而言，挑战在于如何在不额外构建一套模型访问、身份和运维体系的情况下提供这些工具。

Codex 可以使用 Amazon Bedrock 对受支持的 OpenAI 模型进行推理。在本文中，我们将展示如何将这条路径融入贵组织已在使用的 AWS 身份、AWS Identity and Access Management (IAM)、区域和可观测性实践。Codex 仍在开发者工作站上运行。主要的设计选择在于其模型请求如何到达 Amazon Bedrock，以及贵组织在何处应用策略和运维控制。

我们从一个规模小、权限最小化的试点开始，并逐一梳理在扩大访问范围之前需要关注的关键检查项。示例使用 GPT-5.6 Sol。在开始试点之前，请查阅 Amazon Bedrock 中按 AWS 区域支持的模型，以确认 Sol、Terra 或 Luna 在您计划使用的 AWS 区域和推理路径中可用。

推荐的默认方案：从 Native AWS Access 开始，进行规模小、权限最小化的试点。当您希望获得 AWS 托管的网关基础设施用于路由或 Amazon Bedrock Guardrails 时，请选择 AgentCore Gateway（Amazon Bedrock AgentCore 的一项能力）。当平台团队希望在请求路径中强制执行控制时，请选择 LLM Gateway。自定义集成是 LLM Gateway 模式的高级版本，而非快速入门方案。

这些示例来自开源的 Guidance for Codex on AWS 仓库。其中包含 Native AWS Access、AgentCore Gateway、ECS 上的 LiteLLM、Portkey、AWS Distro for OpenTelemetry (ADOT) 的快速入门，以及本文后面使用的 Amazon CloudWatch 设置。请选择与您的架构相匹配的快速入门，将其用于试点，并根据您的环境进行调整。

选择您的推广路径

身份验证只是企业推广的一部分。需要确定谁可以使用该服务，以及哪些模型和区域获得批准。还要定义配置存放的位置、收集哪些遥测数据、如何分配用量，以及允许使用哪些技能或 Model Context Protocol (MCP) 服务器。下表将这些需求映射到访问路径和负责团队。

选择能够提供您当前所需控制能力的访问路径。满足需求的最直接路径通常运维开销最低。

决策规则

1. 当 AWS 身份和 IAM 控制足以满足试点需求时，Native AWS Access 是通常的起点。
2. Amazon Bedrock AgentCore 是一个用于大规模构建、连接和优化智能体的平台，支持任意框架或模型。在该平台中，AgentCore Gateway 适合希望获得 AWS 托管网关基础设施用于路由、Amazon Bedrock Guardrails 或相关控制的团队。
3. 大型语言模型 (LLM) Gateway 适合已经运营网关或希望在请求路径中强制执行控制的组织。构建自定义网关是此选项的高级版本。

下图比较了三种推广路径中身份、路由、策略、遥测和运维归属所在的位置。

图 1：在每种场景中，Codex 都在开发者工作站上运行。Native AWS Access 使用 AWS IAM Identity Center，配置好的 AgentCore Gateway 可以应用托管路由和 Guardrails，配置好的 LLM Gateway 可以应用请求路径控制

Native AWS Access

如果 Native AWS Access 适合该试点，仓库中的 Native AWS Access 快速入门 提供了完整流程和支持文件。以下简要演练重点介绍操作顺序和最重要的检查项。

使用你的员工身份提供商进行登录

员工继续通过他们已经在使用的身份提供商登录。在本示例中，Okta 通过安全断言标记语言（SAML）处理身份验证，并通过跨域身份管理系统（SCIM）将用户和组预配到 IAM Identity Center。随后，IAM Identity Center 签发 Codex 使用的临时 AWS 凭证。身份提供商不在 Codex 中配置。

先决条件

1. 将每位试点用户添加到员工身份系统中的专用组，并将该组预配到 IAM Identity Center。将分配范围限制在试点内。
2. 选择一个 Amazon Bedrock 区域和一个试点身份可用的 OpenAI 模型，如果所选 API 需要，还要选择一个推理配置文件。针对所选账户、区域和推理路径，分别检查 Sol、Terra 和 Luna。
3. 仅授予 Codex 使用的 Amazon Bedrock 模型推理权限、任何直接验证命令以及选定的可观测性目标。
4. 准备一个非生产仓库，并指定一名回滚负责人。

配置

该试点有三项检查。首先，使用为 AWS 命令行界面（AWS CLI）配置的 IAM Identity Center 配置文件登录，并直接调用 Amazon Bedrock Runtime。接下来，将 Codex 指向已批准的模型。最后，运行一个安全的 Codex 任务。直接调用可隔离 AWS 访问问题。最后一步确认 Codex 配置。

第 1 步：登录并验证 Amazon Bedrock Runtime 访问权限。

aws sso login --profile codex-bedrock
export AWS_PROFILE=codex-bedrock
aws bedrock-runtime converse
--model-id us.openai.gpt-5.6-sol
--messages '[{"role":"user","content":[{"text":"Reply with OK"}]}]'
--region us-east-2

此命令会创建一个短期 AWS 会话，并检查该配置文件能否在所选区域中调用所选模型。如果失败，请在配置 Codex 之前解决配置文件、区域、模型或推理配置文件访问权限或 IAM 权限问题。

第 2 步：配置 Codex 提供商。

# ~/.codex/config.toml (or managed user configuration)
model_provider = "amazon-bedrock"
model = "openai.gpt-5.6-sol"

[model_providers.amazon-bedrock.aws]
profile = "codex-bedrock"
region = "us-east-2"

model 值是 Codex 模型 ID。profile 选择 AWS IAM Identity Center 会话，region 告诉 Codex 使用哪个 AWS 区域。将这些设置保留在用户级或托管配置中，以便仓库无法更改提供商。

验证试点并确认回滚

在添加用户之前，确保试点能够访问已批准的模型、生成预期记录，并且可以干净地禁用。

1. 身份：aws sts get-caller-identity 返回预期的 IAM Identity Center 代入角色会话。
2. 模型访问：试点配置文件通过为测试选择的 API 和区域调用已批准的模型。
3. Codex 访问：用户在一个非生产仓库中完成一项安全的只读任务，并且预期的请求路径证据可用。
4. 证据与回滚：身份、调用、审计和可选遥测记录均已存在。移除配置或 IAM Identity Center 分配，按照你的流程处理任何活动会话或等待其过期，并验证新的调用会被拒绝。

观看 Native AWS Access 演练

该演练展示了完整的试点流程：员工登录、直接验证 Amazon Bedrock Runtime、配置 Codex 提供商以及执行一项安全测试任务。

图 2：Native AWS Access 演练，涵盖员工登录、Amazon Bedrock Runtime 验证、Codex 提供商配置以及一项安全试点任务

使用该视频来核实检查的顺序以及需要收集的证据，然后再添加更多试点用户。

运行双用户身份隔离检查

测试身份隔离需要两个用户。单个用户只能证明登录可用。第二个用户用于测试归属是否保持区分。让两个试点用户分别登录并运行相同的无害任务。他们假定角色的会话和审计记录，以及配置后的遥测记录，都应保持区分。

下图展示了独立的试点身份应如何在使用同一获批的 Codex 和 Amazon Bedrock 路径时，产生独立的 AWS 会话、请求证据和可选遥测。

图 3：使用可信身份注册来实现归属。本地收集器只有在作为受管注册流程的一部分进行部署和配置时，才能添加获批的身份上下文

请求路径控制的网关路径

当你需要 AWS 托管的网关基础设施来实现集中路由或 Amazon Bedrock Guardrails 时，AgentCore Gateway 是一个选项。如果你的组织已经运行 LLM Gateway，或希望在请求路径中强制执行控制，请改用该网关。在向试点用户开放之前，先验证所选网关。

LLM Gateway：在试点前进行验证

1. 检查网关是否接受 Codex 请求格式。
2. 使用网关团队定义的登录或令牌流程。
3. 在邀请试点用户之前，测试模型路由、监控、故障处理和回滚。

自定义企业集成

自定义企业集成是 LLM Gateway 模式中涉及面最广的形式。只有当原生 AWS 访问、AgentCore Gateway 和现有网关都无法满足特定需求时，才应考虑它。其结果是需要设计、保护、测试、支持和运营的另一个服务，因此平台工程和安全团队需要从一开始就负责它。

观测、治理和分配成本

Codex OpenTelemetry、Amazon Bedrock 服务记录、AWS 身份记录和账单数据回答的是不同的问题。Codex OpenTelemetry 描述客户端活动。启用后，Amazon Bedrock 服务指标和模型调用日志显示服务端活动。AWS 身份记录和 AWS 成本与使用报告（CUR）提供身份和计费使用证据。针对你部署的路径将它们关联起来，并且不要将 token 量作为成本报告呈现。

定义 Codex 可能通过所选模型路径发送的代码、提示、文件和工具输出。排除机密和受限数据，除非组织已批准该数据流。要求开发人员在合并前审查和测试生成的更改。遥测并不能确立正确性或安全性。

来自 Codex 的 OpenTelemetry 指标

为实现可观测性，本文使用仓库中监控与运营指南里的 ADOT 收集器配置和 CloudWatch 仪表板。将该配置部署到每台受管试点设备，然后运行一个安全的 Codex 任务。

仓库提供了配置文件。按照其部署说明安装获批的 ADOT 收集器并配置其 AWS 身份验证。

# ~/.codex/config.toml or managed user configuration
[otel]
environment = "pilot"
log_user_prompt = false
metrics_exporter = { "otlp-http" = { endpoint = "http://127.0.0.1:4318/v1/metrics", protocol = "binary" } }

验证仓库路径：运行一个安全的 Codex 任务，并确认预期的运营指标出现在受管 CloudWatch 仪表板上。

Amazon CloudWatch 仪表盘与证据

Guidance for Codex on AWS 仓库中的 Amazon CloudWatch Coding Agent Insights 托管仪表盘展示了通过 ADOT 收集的 Codex 运营指标。使用它来了解客户端活动，并在需要归属或成本证据时单独使用 AWS 身份、审计和账单记录。

观看 Codex OTel 和 CloudWatch 演练

该演练展示了如何查询 Codex OpenTelemetry 指标，并确认预期的 token 和请求数据出现在 Amazon CloudWatch 中。

图 4：Amazon CloudWatch 仪表盘中显示的 Codex OpenTelemetry 指标

该示例验证了 Amazon CloudWatch Query Studio 中的别名指标结果，并展示了仪表盘如何呈现 Codex 客户端活动。

标准化团队行为

在基础设施路径正常工作后，转向开发者体验。仓库指南、托管插件、钩子和经批准的 MCP 服务器可以使推广保持一致，而无需每个团队自行组装配置。

插件

组织拥有的插件是分发共享技能、钩子和经批准的 MCP 集成的实用方式。为每个插件指定所有者和版本，在发布前审查变更，并仅通过经批准的来源发布。与试点小组一起测试更新，并保留文档化的移除路径。

插件可能包含 MCP 服务器配置，但这并不意味着所有捆绑的工具都已获批准。仅允许组织已审查的服务器和工具，并在需要时要求用户确认。

钩子

钩子可以在 hooks.json 中声明，也可以直接在配置中声明。保持文档化的事件大小写，并通过经批准的端点工具部署组织拥有的策略命令。

[[hooks.PreToolUse]]
matcher = "^Bash$"

[[hooks.PreToolUse.hooks]]
type = "command"
command = "/usr/local/bin/company-pre-tool-policy"
timeout = 30

在能解决特定需求的地方使用 PreToolUse、PostToolUse 或 SessionStart。在更广泛部署之前，测试允许、拒绝、超时和端点断开时的行为。

MCP

MCP 服务器将 Codex 连接到另一个系统，因此每个服务器都会形成独立的信任边界。将访问权限限制在需要它的用户和工具范围内，通过经批准的 OAuth 或密钥流程管理凭据，并要求对会更改外部系统的工具进行确认。请勿将 MCP 凭据放入模型提供商配置中。

分阶段推广

下图定义了从准备阶段推进到试点、扩展和组织范围标准化所需的范围与证据。

图 5：从受控试点开始，在验证访问路径和运营证据后进行扩展，并在运营模式得到验证后标准化推广

管理员启动检查清单

1. 在变更记录中记录所选路径、负责团队、区域和模型。
2. 将试点身份限制在所需权限范围内，并记录已发放凭据或令牌的处理方式。
3. 运行一项非生产测试，涵盖登录、模型可用性以及一项安全的 Codex 任务。
4. 检查已部署版本的遥测和审计输出，而不是假设示例可原样适用。
5. 在成本报告中将会计金额与估算金额分开。
6. 演练恢复：移除配置或分配，通过经批准的流程处理任何活动会话或等待其过期，并验证新的调用会被拒绝。

清理

当试点结束或必须禁用访问时，移除不再需要的推广资源。

从受管设备中移除 Codex 模型提供商和遥测配置。移除 IAM Identity Center 试点分配或网关访问权限，撤销试点令牌和密钥，并按照经批准的流程处理活动会话。卸载或禁用 ADOT 收集器，如果试点 CloudWatch 仪表板和告警未与其他工作负载共享，则将其删除。通过确认新的模型调用会被拒绝且已停用的遥测资源不再接收新数据来验证清理结果。

配置边界

将模型提供商、凭据和组织遥测设置保留在用户级或受管配置中。项目本地的 .codex/config.toml 是仓库范围的配置：应将其作为代码进行审查，但不要将其视为企业强制边界。AGENTS.md 适用于持久性的仓库指导，例如测试命令和编码约定，但它也不是强制边界。

结论与后续步骤

Codex 可以使用 Amazon Bedrock 对受支持的 OpenAI 模型进行推理。从满足需求的最简单访问路径开始，通过小规模试点验证身份和模型路径，仅在网关或客户端控制能解决特定需求时才添加它们。

AgentCore Gateway 提供 AWS 托管网关选项，用于路由或 Amazon Bedrock Guardrails。当平台团队希望在请求路径中强制执行控制时，选择 LLM Gateway。仅当可用路径无法满足已记录的需求时，才构建自定义集成。

分阶段扩展，并利用每个阶段的证据来决定下一步行动。AWS 仓库中 Codex 的指南包含本文所使用的维护配置和验证流程。

关于作者

Shivi Bhatia

Shivi Bhatia 是 AWS 全球专家组织（Worldwide Specialist Organization）中负责 Amazon Bedrock 的高级解决方案架构师。他与企业客户合作，专注于生成式 AI、智能体系统、生产推理以及 AI/ML 架构。他的专业兴趣包括多智能体编排、推理优化、模型评估、可观测性以及安全的企业 AI 采用。

Sebastien Couturier

Sebastien Couturier 是 AWS 的高级 GenAI 专家解决方案架构师，与企业客户和合作伙伴密切合作，专注于 GenAI、智能体 AI 和开发者工具。

Sriharsha M S

Sriharsha M S 是 Amazon Web Services 战略专家团队的首席 Gen AI 专家解决方案架构师。他与正在利用 AI/ML 解决复杂业务问题的战略 AWS 客户合作。他为基础模型科学和大规模智能体 AI 应用提供技术指导和设计建议。他的专业领域涵盖应用硬件加速器、架构、大数据、分析和机器学习。