Codex 安装与国内使用教程：新手也能快速上手

发布于 2026年7月21日更新于 2026年7月22日作者：Codex 中文指南

第一次接触 Codex，不需要先学会复杂的 AI 概念。只要完成“安装客户端、配置账号或 API、打开一个项目、发送第一个任务”四步，就能开始使用。需要自定义 API 的读者可以访问 API 中转站：https://apibest.org 获取 API Key，API 基础地址是 https://apibest.org/v1。

第三方 API 说明

APIBest 不是 OpenAI 官方服务。可用模型、价格、额度、数据处理和协议兼容性以 APIBest 实际页面为准。公司代码、客户数据和生产配置是否允许发送给第三方服务，应先确认所在组织的安全要求。

一、Codex 能帮你做什么

Codex 是面向软件开发的编码代理。与普通聊天工具相比，它不只是给出代码片段，还可以在获得授权后：

• 阅读当前项目的目录和代码。
• 修改文件并展示差异。
• 运行测试、构建和格式化命令。
• 查找 Bug、补充测试和审查代码。
• 根据项目中的 README.md、AGENTS.md 等规则完成多步任务。

Codex 可以通过桌面应用、命令行或 IDE 扩展使用。新手如果不熟悉终端，可以先从桌面应用开始；经常写代码的用户通常更适合 CLI 或 IDE 扩展。

二、选择适合自己的安装方式

使用入口	适合谁	特点
Codex 桌面应用	希望使用图形界面的新手	安装直观，方便管理项目和任务
Codex CLI	经常在终端中开发的用户	启动快，适合直接操作本地仓库
Codex IDE 扩展	长期使用 VS Code、Cursor 或 Windsurf 的用户	可以结合编辑器中的文件和选区工作

三者可以同时安装。CLI 和 IDE 扩展通常共用本机的登录状态与 ~/.codex/config.toml，因此不需要为每个入口重复配置。

三、安装 Codex 桌面应用

访问 OpenAI 官方页面：

下载 Codex 官方桌面应用

在页面中选择 macOS 或 Windows 版本。官方可能随版本调整安装包、系统要求和下载方式，因此不建议收藏具体安装文件地址，也不要使用来源不明的第三方重打包程序。

安装完成后：

1. 启动应用。
2. 在登录页面不要点击账号登录或“使用 ChatGPT 登录”。
3. 点击 “使用其他方式”（英文界面为 Sign in another way）。
4. 选择 API Key 登录，输入你的 API Key，然后点击继续。
5. 进入 Codex 后添加一个本地 Git 项目。
6. 确认当前路径、分支和未提交改动。
7. 先发送只读任务，确认项目识别正常。

使用 APIBest 时还需要配置 API 地址

“使用其他方式”只负责切换到 API Key 登录。使用 APIBest 的读者仍需按下文配置 model_provider、https://apibest.org/v1 和 APIBEST_API_KEY；仅在登录框中输入 Key 不会自动切换 API 中转地址。

macOS 第一次打开可能显示系统安全确认；Windows 可能显示发布者或安装权限提示。确认文件来自 OpenAI 官方页面后，再按正常系统流程继续，不要为了安装关闭操作系统安全保护。

四、安装 Codex CLI

1. 安装 Node.js

通过 npm 安装 CLI 需要 Node.js。建议安装当前 LTS 版本，然后检查：

node -v
npm -v

两条命令都能输出版本号即可继续。

2. 安装 Codex

在 macOS、Linux、Windows PowerShell 或 WSL2 中运行：

npm install -g @openai/codex

验证安装：

codex --version

进入项目并启动：

cd /你的项目路径
codex

3. Windows 用户如何选择环境

如果项目和开发工具都安装在 Windows 中，就在 PowerShell 中安装 Codex；如果项目主要放在 WSL2 中，就在 WSL2 内安装 Node.js、Git 和 Codex。不要混用 Windows 与 WSL 的 Node.js 和项目路径。

4. 更新到最新版本

npm install -g @openai/codex@latest
codex --version

如果安装后提示找不到 codex，先重开终端，再用 npm prefix -g 检查 npm 全局目录是否已加入 PATH。

五、国内使用 Codex 的接入方式

安装成功只代表 Codex 可以在本机运行，还需要选择模型服务。常见方式有两类：

1. 使用 OpenAI 当前支持的 ChatGPT 登录或 OpenAI Platform API Key。
2. 配置支持 Codex 协议的 OpenAI-compatible 第三方 API。

本文提供 APIBest 配置示例：

• API 中转站：https://apibest.org
• API 地址：https://apibest.org/v1
• 示例模型：gpt-5.6-sol

第三方 API 可以完成普通聊天，不代表一定能完整运行 Codex。Codex 还需要 Responses API、流式事件、工具调用和工具结果回传，配置后必须实际测试。

六、配置 APIBest 自定义 API

第一步：创建 API Key

访问 APIBest，注册账号并在控制台创建 API Key。密钥不要发给他人，也不要放入公开仓库。

第二步：设置环境变量

macOS、Linux 或 WSL2：

export APIBEST_API_KEY="你的 API Key"

Windows PowerShell：

$env:APIBEST_API_KEY="你的 API Key"

以上命令只对当前终端有效。需要长期使用时，可以通过个人 shell 配置或 Windows 用户环境变量保存，但不要写入项目的 .env 示例、README 或其他可能提交的文件。

第三步：创建 Codex 配置文件

用户级配置文件位置：

~/.codex/config.toml

Windows PowerShell 中对应：

$HOME\.codex\config.toml

写入：

model = "gpt-5.6-sol"
model_provider = "apibest"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[model_providers.apibest]
name = "APIBest"
base_url = "https://apibest.org/v1"
env_key = "APIBEST_API_KEY"
wire_api = "responses"

配置含义：

字段	作用
model	APIBest 控制台实际提供的模型 ID
model_provider	选择 apibest 自定义提供商
base_url	API 基础地址，保留 /v1
env_key	保存密钥的环境变量名称，而不是密钥值
wire_api	使用 Codex 工具工作流所需的 Responses API
approval_policy	高权限操作出现时请求用户确认
sandbox_mode	默认只允许在当前工作区写文件

不要直接粘贴真实密钥

env_key = "APIBEST_API_KEY" 中填写的是变量名。不要把这一行改成真实 API Key，也不要把密钥写进项目级 .codex/config.toml。

七、十分钟完成第一次 Codex 任务

1. 准备测试项目

建议选择一个体积小、没有生产密钥、未提交改动较少的 Git 项目。进入项目后先执行：

git status
codex

2. 让 Codex 只读项目

输入：

阅读 README 和主要配置文件，告诉我项目使用什么技术栈，以及如何安装依赖、运行测试和启动项目。不要修改文件，也不要安装依赖。

如果 Codex 能正确说明目录和命令，证明基础连接和文件读取已正常。

3. 尝试一个小改动

输入：

找到项目中最简单的工具函数，为它补充一个边界条件测试。沿用现有测试风格，只修改相关测试文件，完成后运行对应测试并汇报结果。

完成后不要只看总结，要检查：

• 修改的文件是否正确。
• 是否改动了任务之外的内容。
• 测试命令是否真的执行。
• 测试结果是否通过。

八、新手最实用的提示词写法

一个清楚的任务通常包含目标、范围、限制和验证方式：

修复注册表单重复提交的问题。只修改表单组件和相关测试，不改变后端接口；完成后运行对应单元测试，并说明根因、改动和测试结果。

常用模板：

了解陌生项目

阅读项目结构和主要配置文件，解释核心模块、启动方式和测试命令。先不要修改代码。

修复问题

先复现并定位这个错误的根因，然后做最小范围修复，补充回归测试并运行相关测试。不要顺手重构无关代码。

审查代码

审查当前分支的改动，重点查找功能错误、安全风险、兼容性问题和缺失测试。按严重程度列出发现，不要修改文件。

九、权限设置怎么选

新手建议保留：

approval_policy = "on-request"
sandbox_mode = "workspace-write"

这套配置允许 Codex 在当前项目中工作，涉及更高权限时会请求确认。批准之前要看清：

• 命令会不会删除或覆盖文件。
• 路径是否属于当前项目。
• 是否要安装软件或访问外部网络。
• 是否可能上传源码、日志或密钥。

十、常见问题

API 返回 401 或 403

检查 API Key 是否有效、APIBEST_API_KEY 是否存在，以及 Codex 是否从设置变量的同一个终端启动。env_key 的拼写必须与环境变量完全一致。

提示模型不存在

模型 ID 必须以 APIBest 控制台显示为准。本文中的 gpt-5.6-sol 是示例，账号实际可见范围可能不同。

能回答问题但不能读取文件

先检查 Codex 的本地工作区权限。如果权限正常，仍然没有工具调用，则需要确认第三方 API 是否完整兼容 Responses 流式协议和工具调用。

修改配置后没有生效

确认文件是用户主目录下的 ~/.codex/config.toml，检查 TOML 引号和表名，然后完全退出 Codex 并新建任务。

请求超时或中断

先换成小项目和短任务，排除上下文过大。再检查网络、服务端负载、额度和限流，不要在不确定是否已经计费时无限重试。

更多排查方法见 Codex 自定义 API 常见错误与排查。

十一、下一步学什么

熟悉基本操作后，可以继续了解：

• Codex CLI 常用命令与高效工作流
• Codex config.toml 配置指南
• Codex 高质量提示词
• Codex 沙箱、权限与命令审批
• 使用 APIBest 为 Codex 配置自定义 API

总结

新手使用 Codex 的最短路径是：从官方页面安装桌面应用，或者运行 npm install -g @openai/codex 安装 CLI；然后选择官方登录或通过 https://apibest.org 配置自定义 API；最后用一个只读任务和一个小型测试任务验证完整工作流。

不要一开始就开放所有权限，也不要直接让 Codex 处理生产项目。先学会检查 Git 差异、命令和测试结果，再逐步把它用于更复杂的开发工作。

参考资料

• OpenAI Codex 官方页面
• Codex 认证文档
• Codex 自定义模型提供商文档
• Codex 配置参考