Codex 登录认证与初始化配置实战指南

Codex 是 OpenAI 开源的终端 AI 编程助手，安装后需要进行登录认证才能使用。Codex 提供了两种认证方式：ChatGPT 账户登录（推荐）和 API Key 登录。本文将全面讲解 Codex 的安装、登录流程、配置管理以及常见问题的排查方法。

安装 Codex CLI

在登录之前，首先需要将 Codex 安装到系统中。Codex 支持多种安装方式，适配不同操作系统。

macOS / Linux 一键安装

最快捷的方式是使用官方安装脚本：

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

安装脚本会自动检测系统架构，下载匹配的二进制文件并完成配置。如果遇到网络问题，可以强制使用 GitHub Releases 下载：

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

Windows 安装

在 PowerShell 中执行以下命令：

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

如需使用 GitHub Releases 源：

$env:CODEX_INSTALLER_USE_RELEASES_OPENAI_COM='false'; irm https://chatgpt.com/codex/install.ps1 | iex

包管理器安装

如果你使用 Node.js 生态，可以通过 npm 全局安装：

npm install -g @openai/codex

macOS 用户也可以使用 Homebrew：

brew install --cask codex

手动下载二进制文件

访问 GitHub Releases 页面，根据平台选择对应的压缩包：

• macOS Apple Silicon: codex-aarch64-apple-darwin.tar.gz
• macOS x86_64: codex-x86_64-apple-darwin.tar.gz
• Linux x86_64: codex-x86_64-unknown-linux-musl.tar.gz
• Linux arm64: codex-aarch64-unknown-linux-musl.tar.gz

解压后建议将可执行文件重命名为 codex，并移动到系统 PATH 中：

tar -xzf codex-x86_64-unknown-linux-musl.tar.gz
mv codex-x86_64-unknown-linux-musl /usr/local/bin/codex
chmod +x /usr/local/bin/codex

安装完成后，运行以下命令验证：

codex --version

如果显示出 Codex 的版本号，说明安装成功。

登录认证方式

Codex 支持两种认证方式。运行 codex 命令后，终端会提示选择登录方式。

方式一：ChatGPT 账户登录（推荐）

ChatGPT 账户登录是 OpenAI 推荐的方式，适用于拥有 ChatGPT Plus、Pro、Business、Edu 或 Enterprise 订阅的用户。这种方式的优势在于可以直接使用订阅中已包含的 Codex 配额，无需额外配置 API Key。

运行 codex 后，选择 Sign in with ChatGPT，Codex 会自动打开系统默认浏览器，跳转到 OpenAI 的 OAuth 授权页面：

如果你尚未在浏览器中登录 ChatGPT，会先进入登录页面

登录后，页面会展示 Codex CLI 请求的权限范围

确认授权后，浏览器会显示"授权成功"的提示

回到终端，Codex 会自动完成认证

认证成功后会生成一个刷新令牌（refresh token），存储在本地。后续启动时无需再次登录，令牌会在后台自动续期。

# 首次登录只需运行 codex，按提示操作
codex

如果你使用的是无浏览器环境（如远程服务器），Codex 会在终端中打印一个设备激活链接。复制该链接到任意有浏览器的设备上打开，完成授权后自动同步。

方式二：API Key 登录

如果你拥有 OpenAI API Key，也可以使用 API Key 进行认证。这种方式适合已经习惯 API 付费模式的开发者，或者无法使用 ChatGPT 账户的场景。

Codex 支持两种方式设置 API Key：

环境变量方式：

export OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

将上述命令添加到 shell 配置文件中（~/.bashrc、~/.zshrc 或 ~/.config/fish/config.fish），确保每次打开终端时自动生效。

配置文件方式：

Codex 的配置目录位于 ~/.codex/（Linux/macOS）或 %USERPROFILE%\.codex\（Windows）。你可以在该目录下创建或编辑配置文件来设置 API Key。

需要注意的是，使用 API Key 方式需要先在 OpenAI 平台充值，并且需要确保 API Key 具有访问 Codex 相关模型的权限。具体配置请参考 OpenAI 官方文档。

设置好 API Key 后运行：

codex

如果一切正常，会进入 Codex 的交互式界面。

配置文件详解

Codex 的配置文件主要位于 ~/.codex/ 目录下，了解这些文件的结构有助于排查问题和进行高级配置。

目录结构

运行 codex 完成首次登录后，配置目录会包含以下核心文件：

~/.codex/
├── credentials.json    # 认证令牌（ChatGPT 登录方式）
├── config.toml         # 用户级配置文件
├── state.json          # 会话状态数据
└── logs/               # 运行日志

• credentials.json：存储认证令牌，权限应设为仅用户可读（chmod 600）
• config.toml：个性化配置，可覆盖默认行为
• state.json：跨会话状态，如上次使用的模型、窗口位置等

检查登录状态

使用 codex status 命令可以查看当前的认证状态和基本信息：

codex status

输出示例：

Authenticated as: user@example.com
Plan: ChatGPT Plus
Model: gpt-4.1-codex

如果显示"Not authenticated"，说明需要重新登录。此时运行 codex login 即可。

项目级配置与全局配置

Codex 的配置分为两个层级：

| 层级 | 位置 | 作用范围 |
|------|------|----------|
| 全局配置 | ~/.codex/config.toml | 所有项目 |
| 项目配置 | <project>/.codex/config.toml | 当前项目优先 |

项目级配置会覆盖全局配置的同名选项。这种设计允许不同的项目使用不同的模型或行为设置。

例如，在某个 Go 项目中，你可以在 .codex/config.toml 中指定：

[model]
default = "gpt-4.1-codex"

[execution]
auto_approve = false
sandbox = true

这样该项目就有了独立的执行策略，不影响其他项目。

账户管理与多账户切换

登出当前账户

运行 codex logout 会清除本地的认证令牌，下次运行 codex 时需要重新登录：

codex logout

登出后 ~/.codex/credentials.json 中的令牌会被清除，但其他配置文件会保留。

切换账户

Codex 目前不直接支持多账户并存，但可以通过环境变量重定向配置目录来实现账户隔离：

# 使用 ChatGPT 个人账户
CODEX_HOME="$HOME/.codex-personal" codex

# 使用 API Key 工作账户
CODEX_HOME="$HOME/.codex-work" OPENAI_API_KEY="sk-work-xxxx" codex

通过 CODEX_HOME 环境变量，你可以为不同场景创建独立的配置目录。建议配合 shell alias 使用：

alias codex-personal='CODEX_HOME="$HOME/.codex-personal" codex'
alias codex-work='CODEX_HOME="$HOME/.codex-work" codex'

令牌安全存储

Codex 的认证令牌在本地以加密形式存储。对于 ChatGPT 登录方式，Codex 使用系统的钥匙串（macOS Keychain、Linux Secret Service API、Windows Credential Manager）来保护令牌。

你可以通过以下命令验证令牌的安全性：

# macOS - 查看 Codex 在钥匙串中的条目
security find-generic-password -s "codex"

# Linux - 查看 Secret Service 中的条目（需要 libsecret）
secret-tool search application codex

网络与代理配置

在某些网络环境下（如企业内网或使用代理的场景），Codex 可能无法直接连接 OpenAI 的 API 服务器。

配置 HTTP 代理

Codex CLI 遵循标准的 HTTP_PROXY 和 HTTPS_PROXY 环境变量：

export HTTP_PROXY="http://127.0.0.1:7890"
export HTTPS_PROXY="http://127.0.0.1:7890"

# 然后正常运行 codex
codex

配置 SOCKS 代理

如果使用 SOCKS5 代理：

export ALL_PROXY="socks5://127.0.0.1:1080"
codex

测试网络连通性

在登录之前，可以先用 curl 测试到 OpenAI API 的连接：

# 测试 API 连通性
curl -I https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

如果返回 HTTP 200，说明网络连接正常。返回 403 说明 API Key 有效但无权限；返回 401 说明 API Key 无效。

常见问题排查

问题一：codex 命令找不到

症状：终端提示 command not found: codex

解决方案：

检查 Codex 是否安装到系统的 PATH 中：which codex

如果通过 Homebrew 安装，确认 Homebrew 的 bin 目录在 PATH 中

手动添加安装目录到 PATH：export PATH="$PATH:/usr/local/bin"

问题二：浏览器未自动打开

症状：运行 codex 选择 ChatGPT 登录后，浏览器没有弹出登录页面

解决方案：

Codex 会在终端打印一个蓝色的设备激活链接，类似 https://chatgpt.com/auth/device?code=XXXX-XXXX

手动复制该链接到浏览器中打开

如果链接也没有打印，可以尝试设置 BROWSER 环境变量指定浏览器路径：

export BROWSER="/usr/bin/google-chrome"
codex

问题三：登录后提示 "Not authenticated"

症状：浏览器显示授权成功，但终端仍然提示未认证

解决方案：

检查 ~/.codex/credentials.json 是否存在且可读

尝试重新登录：codex logout && codex login

如果使用 WSL2，确保文件系统权限正常

检查系统时间是否正确（令牌验证依赖时间同步）

问题四：API Key 方式提示配额不足

症状：使用 API Key 登录后，首次对话提示 "insufficient_quota"

解决方案：

前往 OpenAI Platform Billing 检查账户余额

确认 API Key 具有访问 codex 相关模型的权限

考虑切换到 ChatGPT 账户登录方式，使用订阅中包含的配额

问题五：代理环境下登录超时

症状：设置代理后，登录过程卡住或超时

解决方案：

确认代理端口正确且代理服务正在运行

尝试同时设置 HTTP_PROXY 和 ALL_PROXY

Codex 登录过程中会使用 OAuth 回调，确保代理不会拦截本地回环地址：

export NO_PROXY="localhost,127.0.0.1,::1"

总结

Codex 的登录认证虽然流程简洁，但涉及多种场景（桌面环境、无头服务器、代理网络、多账户）时，了解底层机制能帮你快速解决问题。核心要点回顾：

ChatGPT 账户登录是首选：无需额外付费，配置最简单

API Key 登录适合高级用户：需要自行管理配额和权限

CODEX_HOME 环境变量可以实现多账户隔离

配置文件位于 ~/.codex/，排查问题时优先检查该目录

网络代理通过标准环境变量配置，Codex 会自动读取

掌握了登录初始化流程后，你可以进一步探索 Codex 的 AGENTS.md 项目配置、Sandbox 安全模式、exec 非交互模式等高级功能，让 AI 编程助手真正融入你的日常工作流。