Codex 安装与配置文档

本文档用于在当前机器上安装、配置和验证 Codex CLI（终端中的 Codex 编码代理）。内容偏向 Linux / macOS 开发环境，适合个人工作站或远程开发机。

1. 目标说明

完成后，你应当具备以下能力：

安装并运行 codex 命令行工具

完成 OpenAI API 凭证配置

在终端内启动 Codex 会话

了解常见目录、权限和配置方式

能够排查最常见的启动与认证问题

2. 前置条件

建议先确认以下环境：

已安装 Node.js

已安装 npm 或 pnpm

已安装 git

已具备可用的 OpenAI API Key

Shell 环境为 bash、zsh 或兼容 shell

2.1 Node.js 与 npm 版本要求

由于 Codex CLI 通过 Node.js 生态分发，建议优先使用较新的 LTS 版本，以减少安装和运行时兼容性问题。

推荐版本如下：

Node.js：更推荐 20.x LTS 或 22.x LTS

npm：建议 9.x 及以上

pnpm：如使用，可采用当前稳定版

兼容性建议：

如果你的 Node.js 低于 18，建议先升级后再安装 Codex CLI

如果你的 npm 版本过旧，可能出现依赖解析、全局安装或执行入口异常

在团队环境中，尽量统一使用同一大版本的 Node.js，避免行为差异

可用以下命令检查版本：

如果你尚未安装 Node.js，推荐使用版本管理工具统一安装，例如：

nvm

fnm

asdf

例如使用 nvm 安装 Node.js 20：

如需更稳妥，可在项目或个人环境中固定默认版本：

2.2 建议的最小工具版本基线

为了减少兼容性问题，建议至少满足以下基线：

Node.js >= 18

npm >= 9

git >= 2.30（建议）

上述基线更偏向“稳定可用”的经验要求，而不是强制标准。实际以 Codex CLI 发布说明和官方文档为准。

可先执行：

如果系统提示命令不存在，请先安装对应工具。

3. 安装方式

说明：不同版本的 Codex CLI 发布方式可能调整。实际安装时，优先以官方仓库或官方文档为准。

方式一：使用 npm 全局安装

安装完成后验证：

如果提示找不到 codex，通常是全局 npm bin 目录未加入 PATH。

可通过以下命令查看全局 bin 目录：

然后将对应目录加入 shell 配置，例如 ~/.bashrc：

更新后执行：

方式二：使用 npx 临时执行

如果不希望全局安装，也可以直接运行：

这种方式适合快速试用，但每次启动可能稍慢。

4. API Key 配置

Codex CLI 通常依赖 OpenAI API 凭证运行。最常见的配置方式是环境变量。

当前目录下 ~/.codex/config.toml

将以下内容追加到 ~/.codex/config.toml

修改密钥 ~/.codex/auth.json

{
  "auth_mode": "apikey",
  "OPENAI_API_KEY": "sk-XXXXXXXXXXXXXXXXXXXXXXXX"
}

5. 推荐目录与本地配置

Codex 在本地通常会用到用户目录下的一些配置或数据目录。常见约定如下：

~/.codex/：Codex 用户级配置与记忆目录

~/.codex/memories/：记忆或持久化上下文

~/.agents/：本地代理扩展、技能或插件相关目录（如环境支持）

建议提前创建基础目录：

如果后续需要团队共享规范，可以在项目根目录放置：

AGENTS.md：给代理的仓库级工作说明

CLAUDE.md / README.md：面向人类和其他工具的辅助说明

6. 启动方法

在任意项目目录中进入后，直接运行：

启动后，通常可以：

直接输入自然语言任务

让 Codex 读取、修改当前目录下代码

在沙箱权限允许范围内执行命令

配合 AGENTS.md 约束代码风格和工作流程

7. 当前机器推荐配置

结合当前这台机器的使用方式，建议采用以下配置策略：

Shell 环境

如果你当前使用 bash，将配置写入：

建议加入：

安全建议

不要把以下内容提交到 Git：

API Key

私有代理地址中的认证信息

本地 token 缓存文件

含个人隐私的 memories 内容

建议在全局 .gitignore 或仓库 .gitignore 中忽略：

.env
.env.*
.codex/

注意：如果某些项目需要共享 .codex 内的非敏感模板，请按需细化忽略规则，不要一刀切覆盖团队约定。

8. 验证安装是否成功

1）确认命令存在

2）确认环境变量已生效

正常情况下应输出非空内容；不要在公共场合展示完整 Key。

3）启动交互会话

进入后尝试输入：

请帮我查看当前目录结构

如果能正常响应，说明基础安装和认证通常已经可用。

9. 常见问题排查

问题一：`codex: command not found`

原因通常是：

未安装成功

全局 npm bin 不在 PATH

shell 配置未重新加载

可依次检查：

问题二：认证失败 / Key 无效

检查：

OPENAI_API_KEY 是否已设置

Key 是否复制错误

是否混入多余空格或引号

所用网关是否需要 OPENAI_BASE_URL

问题三：网络访问失败

可能原因：

本机无法访问 OpenAI 接口

公司网络限制

代理配置缺失

自定义网关地址错误

可检查网络代理环境变量，例如：

问题四：权限不足

如果 Codex 在某些目录无法写入，通常与：

当前用户权限不足

沙箱策略限制写入范围

目标目录归属不正确

可先检查：

10. 推荐最佳实践

使用单独的 API Key，避免与生产服务混用

在用户级 shell 配置中保存密钥，不要写入仓库

在项目根目录维护 AGENTS.md，明确代码规范与执行约束

先在测试仓库试运行，再接入正式项目

升级前记录当前版本，便于回滚

升级可使用：

Codex安装配置教程

Codex 安装与配置文档#

1. 目标说明#

2. 前置条件#

2.1 Node.js 与 npm 版本要求#

2.2 建议的最小工具版本基线#

3. 安装方式#

方式一：使用 npm 全局安装#

方式二：使用 npx 临时执行#

4. API Key 配置#

当前目录下 ~/.codex/config.toml#

5. 推荐目录与本地配置#

6. 启动方法#

7. 当前机器推荐配置#

Shell 环境#

安全建议#

8. 验证安装是否成功#

1）确认命令存在#

2）确认环境变量已生效#

3）启动交互会话#

9. 常见问题排查#

问题一：codex: command not found#

问题二：认证失败 / Key 无效#

问题三：网络访问失败#

问题四：权限不足#

10. 推荐最佳实践#