Codex

Codex 是 OpenAI 提供的编程智能体。你可以在终端中使用 Codex CLI，也可以在桌面 App 中管理项目和任务。通过配置自定义模型提供商，Codex 可以使用 AGTCloud 的 OpenAI Responses 兼容入口。

不同模型对工具调用、推理、多智能体和上下文长度的支持范围可能不同。请选择当前 API Key 可见且支持 Responses 协议的模型。

准备工作

开始前，请确认你已经：

准备好终端环境和需要打开的本地项目；
注册并登录 AGTCloud；
在 API Keys 页面创建令牌；
从模型广场复制当前令牌可用且支持 Responses 协议的模型 ID。

安装 Codex

选择与当前环境对应的安装方式。

curl -fsSL https://chatgpt.com/codex/install.sh | sh

安装完成后，重新打开终端并检查版本：

codex --version

配置 API Key

Codex 会从自定义 Provider 指定的环境变量读取 API Key。本教程使用独立的 AGTCLOUD_API_KEY，避免与 OpenAI 或其他平台的 Key 混用。

临时配置

以下配置只在当前终端会话中生效。

export AGTCLOUD_API_KEY="your-api-key"

持久配置

希望每次打开终端都自动生效时，可以把变量写入 shell 配置文件或 Windows 用户环境变量。

编辑 ~/.zshrc 并加入：

export AGTCLOUD_API_KEY="your-api-key"

保存后加载配置：

source ~/.zshrc

不要把 API Key 写入 config.toml

config.toml 只保存环境变量名称。API Key 会以明文形式保存在本机环境配置中，请只在个人受信设备上使用这种方式。

配置 AGTCloud Provider

Codex 的用户级配置位于 ~/.codex/config.toml。如果文件已经存在，请先备份，然后将 AGTCloud Provider 合并到现有配置中，不要直接覆盖其他设置。

mkdir -p ~/.codex

if [[ -f ~/.codex/config.toml ]]; then
    cp ~/.codex/config.toml ~/.codex/config.toml.backup
fi

在 ~/.codex/config.toml 中加入：

model_provider = "agtcloud"
model = "MODEL_ID"

[model_providers.agtcloud]
name = "AGTCloud"
base_url = "https://api.agtcloud.cn/v1"
env_key = "AGTCLOUD_API_KEY"
wire_api = "responses"

配置项	作用
`model_provider`	将默认模型提供商切换为 AGTCloud
`model`	指定 Codex 使用的模型 ID
`base_url`	将 Responses 请求发送到本页显示的 AGTCloud API 地址
`env_key`	指定保存 API Key 的环境变量名
`wire_api`	指定使用 OpenAI Responses 协议

Provider 必须放在用户级配置中

项目内的 .codex/config.toml 可以保存项目设置，但不能覆盖 model_provider 和 model_providers。请将上述 Provider 配置放在用户目录的 ~/.codex/config.toml 中。

选择模型

MODEL_ID 是需要替换的占位符，不是真实模型名称。请从模型广场复制当前 API Key 可用且支持 Responses 协议的模型 ID，再替换 config.toml 中的 MODEL_ID。

进入 Codex CLI 后可以使用 /model 查看或切换模型。自定义 Provider 下的可选范围取决于 Codex 版本和当前 API Key；如果目标模型没有出现，请直接更新 config.toml 中的 model。

使用 Codex CLI

进入项目目录

cd /path/to/your/project

启动 Codex

codex

检查当前配置

在 Codex 中执行：

/status

确认当前 Provider、模型和配置文件符合预期。Base URL 应为本页显示的 /v1 API 地址，不应出现重复的 /v1/v1。

发起只读测试

在包含 README.md 的测试项目中输入：

请读取 README.md，并用三点概括这个项目的用途。不要修改任何文件。

正常返回内容说明基础连接已经建立。本步会产生正常的 API 用量。

使用 Codex App

重新启动 App

保存 ~/.codex/config.toml 和环境变量后，完全退出 Codex App，然后重新打开。

打开本地项目

在桌面 App 中切换到 Codex，然后选择一个不含敏感代码的测试项目。

检查模型并验证

确认当前模型与 config.toml 一致，然后使用与 CLI 相同的 README 只读任务进行验证。

App 的环境变量加载取决于版本和启动方式

Codex App 会复用 Codex 的本地配置，但桌面应用对 shell 环境变量的加载方式可能随版本和操作系统变化。如果 CLI 可用但 App 无法读取 API Key，请先完全重启 App，再检查用户级配置和环境变量。

常见问题

现象	优先检查	处理方式
找不到 `codex` 命令	安装结果和 `PATH`	重新打开终端，运行 `codex --version`，必要时重新执行官方安装命令
API Key 未加载	`AGTCLOUD_API_KEY` 是否在当前进程中生效	重新打开终端或 App，再次加载用户环境配置
Provider 配置未生效	是否误写到项目级 `.codex/config.toml`	将 `model_provider` 和 `model_providers` 移到 `~/.codex/config.toml`
请求路径出现 `/v1/v1`	`base_url` 是否被额外拼接	直接使用本页显示的 `https://api.agtcloud.cn/v1`
返回 `401`	API Key 和环境变量	使用有效 API Key，并确认 `env_key` 名称一致
返回 `403`	令牌权限、模型权限和账户状态	在控制台检查令牌及模型可用范围
返回 `404`	Base URL、Responses 入口和模型 ID	核对 `base_url`，并重新复制当前 Key 可用的模型 ID
模型不存在或不可用	模型可见性和 Responses 协议支持	从模型广场复制完整 ID，选择当前 Key 可调用的模型
CLI 正常但 App 未读取配置	App 版本、配置路径和环境变量	完全重启 App；先以 CLI 验证同一份用户级配置
部分高级能力不可用	目标模型能力和当前适配范围	先使用基础只读任务验证；高级能力以实际调用结果为准

遇到无法定位的问题时，请记录请求时间、API Base URL、模型 ID、HTTP 状态和脱敏错误信息，然后查看错误与排障。不要提交完整 API Key。

安全建议

为 Codex 单独创建 API Key，便于管理权限和停用凭证。
不要把真实 Key 写入 config.toml、代码、仓库、截图、日志或共享脚本。
在共享设备或团队环境中，优先使用操作系统凭证管理或组织统一的密钥分发方案。
API Key 疑似泄露时，立即在控制台禁用或删除，然后创建新 Key。

下一步可以阅读 API Key、Base URL 与认证、OpenAI Responses 和错误与排障。

本页目录