在实际开发环境里使用 Codex 的第一步往往不是写提示词而是把命令行工具安装好、把账号登录好、把模型配置好。很多人在这一阶段就会遇到command not found、unable to locate the codex cli binary、浏览器授权失败、模型不支持等各种报错。这篇文章会按照“理解原理 - 环境检查 - 安装 - 注册登录 - 运行验证 - 排错 - 配置建议 - 接入兼容模型”的顺序把 Codex 安装注册全流程拆开讲清楚。这篇教程适合刚接触 Codex CLI 的开发者也适合已经运行过 Codex 但被登录和配置问题卡住的人。完成阅读后你可以在自己的电脑上从零安装 Codex完成账号登录跑通一次真实的“让 Codex 修改项目代码”的流程并且知道遇到常见报错时该从哪里排查。1. 先理解 Codex 安装注册到底在装什么、注册什么1.1 Codex CLI 是什么Codex CLI 是 OpenAI 推出的命令行编程助手。它把大模型能力搬到了终端里你可以让它在当前项目目录中阅读代码、生成文件、执行命令、修改代码并在执行前请求你的批准。它并不是一个只能在网页里聊天的工具而是可以真正参与工程开发的命令行应用。现在常说的“安装 Codex”通常指安装三个层面的内容CLI 程序即你在终端里运行的codex命令。认证信息用于证明你是一个被允许调用模型服务的用户通常通过 OpenAI 账号或 API Key 完成。模型配置告诉 CLI 应该调用哪个模型服务、使用哪个接口格式、读取哪个环境变量里的密钥。所以“安装到注册”并不是一个动作而是一条链路。任何一个环节断了后面的使用都会失败。1.2 安装和注册为什么会出问题安装阶段的问题主要出现在环境差异上。Codex CLI 需要 Node.js 环境需要合适的操作系统和 CPU 架构需要 PATH 环境变量配置正确。注册阶段的问题则主要出现在认证方式上浏览器授权没有弹出来、API Key 没有权限、网络无法访问认证服务等。理解了这条链路后你在排查时就不会只盯着“命令执行失败”这一层而是会去检查CLI 是否真的装好了登录凭证是否真的生效模型是否真的可用下面从环境检查开始一步步走完整个过程。2. 安装前环境检查三条命令确认你可以开始2.1 检查操作系统和 CPU 架构Codex CLI 支持主流操作系统但不同安装方式对平台要求不一样。在安装前先确认你使用的是 Linux、macOS 还是 Windows。Linux 和 macOS 用户直接在终端执行uname -m常见输出x86_64Intel 或 AMD 64 位架构。arm64Apple Silicon 或 ARM 64 位架构。Windows 用户建议优先使用 WSL 2 安装这样可以获得和 Linux 类似的终端体验。如果你坚持在 Windows 原生环境使用要注意 npm 全局安装路径和 PATH 配置与 Linux 不同后面的command not found概率会更高。检查完成后把架构记录下来。后面从 GitHub Releases 下载二进制版本时要根据架构选择对应的压缩包。2.2 检查 Node.js、npm 和 Git使用 npm 方式安装 Codex CLI 时Node.js 是必须的。终端执行node -v npm -v git --version如果提示command not found说明对应软件没有安装或者没有加入 PATH。Node.js 版本建议使用当前主流稳定版本。如果版本过低npm 安装时可能报语法错误或引擎不匹配。升级 Node.js 的常见做法是使用 nvmcurl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash安装完成后重新打开终端再执行nvm install --lts node -vGit 不是 Codex 运行的必要条件但如果要在已有 Git 仓库中让 Codex 修改代码它需要借助 Git 来生成 diff、跟踪文件变化所以建议提前装好。2.3 安装前检查清单在开始安装之前先把下面这张表格过一遍检查项检查命令预期结果不满足时的处理操作系统uname -aLinux 或 macOSWindows 建议 WSL更换安装方式或启用 WSLCPU 架构uname -mx86_64 或 arm64下载时选择对应架构Node.jsnode -v返回版本号用 nvm 安装 LTS 版本npmnpm -v返回版本号随 Node.js 一起安装Gitgit --version返回版本号按系统包管理器安装网络连通curl -I https://openai.com返回 HTTP 响应头先解决网络访问问题这里的网络检查只验证基本连通性。实际调用 Codex 服务时还需要确保当前网络可以正常访问 OpenAI 服务这一步请在你的网络环境下合规配置。3. 安装 Codex CLInpm、Homebrew、二进制三种方式都走一遍3.1 方式一使用 npm 全局安装npm 是最常见的安装方式。执行npm install -g openai/codex这里使用了-g参数表示全局安装。安装完成后codex命令会被放到 npm 的全局 bin 目录中。如果你在安装时遇到权限错误通常是因为 npm 的全局目录在当前用户没有写入权限。不建议直接使用sudo npm install -g更稳妥的做法是重新配置 npm 的全局目录mkdir -p ~/.npm-global npm config set prefix ~/.npm-global然后把下面的内容加入~/.bashrc或~/.zshrcexport PATH~/.npm-global/bin:$PATH保存后执行source ~/.bashrc在 Windows 的 WSL 中路径配置逻辑类似。3.2 方式二使用 Homebrew 安装macOS 用户如果已经安装了 Homebrew可以直接执行brew install codexHomebrew 的优点是安装路径统一升级时用brew upgrade codex即可。但要注意Homebrew 仓库中的包版本可能没有 npm 发布的新。如果你的项目依赖 Codex 的最新功能建议先对比两个来源的版本。验证 Homebrew 安装路径which codex brew list codex如果提示找不到包说明本地 Homebrew 的仓库需要更新brew update3.3 方式三从 GitHub Releases 下载二进制如果要绕开 Node.js 环境可以直接下载编译好的二进制。打开 Codex 的 GitHub Releases 页面在最新版本的 Assets 里选择对应操作系统和架构的压缩包。下载后解压并把可执行文件移动到 PATH 目录tar -xzf codex-*.tar.gz mv codex /usr/local/bin/注意这里只是示例实际文件名要以 Releases 页面展示的为准。下载前确认架构是 arm64 还是 x86_64选错了会提示Exec format error或无法执行。3.4 验证安装结果无论使用哪种方式安装完成后执行codex --version如果输出类似codex version x.x.x说明 CLI 已经安装成功。再看一下可执行文件位置which codex这个路径很重要。后面如果使用 ChatGPT 桌面版或其他客户端可能要求你填写 Codex CLI 的路径。4. 登录注册从 codex login 到 OAuth 和 API Key4.1 登录前的账号准备Codex CLI 需要你有一个可用的 OpenAI 账号。如果你还没有账号需要先到 OpenAI 官网找到注册入口用邮箱完成注册并按页面提示完成验证。这里的“注册”指的是 OpenAI 账号注册不是 Codex 单独再注册一遍。Codex 本身是 OpenAI 服务的一部分登录 Codex CLI 时使用的是同一个账号体系。需要注意账号的可用权限、地区、计费方式会影响后续模型调用。不同账号可能看到不同的可用模型列表。如果登录后提示模型不受支持先回到账号权限上检查。4.2 使用 codex login 完成浏览器授权在终端执行codex login正常情况下终端会输出一个授权链接和一个一次性验证码并尝试打开默认浏览器。浏览器弹出后登录你的 OpenAI 账号并允许 Codex CLI 访问权限。授权完成后浏览器会显示成功页面此时可以回到终端继续操作。如果浏览器没有自动弹出不要急着关闭终端。手动复制终端里输出的 URL粘贴到任意浏览器中打开完成授权后回到终端CLI 会检测到登录状态。登录成功后Codex 会在用户目录下生成认证信息。常见位置是~/.codex/auth.json这个文件保存了令牌信息不要提交到 Git 仓库也不要发给别人。4.3 使用 API Key 登录除了浏览器 OAuthCodex CLI 也支持使用 API Key。先确认你的账号有可用 API Key然后在终端设置环境变量export OPENAI_API_KEY你的API Key如果当前版本的 Codex CLI 支持--api-key参数也可以直接执行codex login --api-key 你的API Key需要注意API Key 是敏感信息。不要在团队聊天里粘贴不要写进项目中。推荐放到~/.bashrc、~/.zshrc或密钥管理工具中并设置好文件权限。4.4 登录状态验证登录完成后不要直接开始写代码。先确认当前登录身份是否生效。执行codex login status如果你的版本没有这个子命令可以查看~/.codex/目录下是否存在认证文件或者直接启动codex看是否可以进入交互界面。如果启动后提示未登录或 401说明认证信息没有写入正确位置需要重新登录。5. 运行最小示例确认聊天和改文件链路都通5.1 先跑一个最小对话进入一个空目录mkdir ~/codex-demo cd ~/codex-demo codex启动后Codex 会进入交互模式。你可以在提示符后输入写一个 Python 猜数字小游戏Codex 会生成代码并展示执行计划。如果它提出运行命令或修改文件你需要根据提示批准或拒绝。这一步的意义不是看代码生成多好而是确认“CLI 已安装 - 登录已生效 - 模型可调用”这条链路是通的。如果在这里报模型错误后面项目中的使用也会报同样的错误。5.2 在项目目录里让 Codex 修改文件Codex 的典型用途不是写单个文件而是在已有项目里分析代码、修改文件、补充测试。新建一个简单的项目mkdir ~/codex-project cd ~/codex-project git init echo # Demo Project README.md然后启动codex输入读取 README.md补充一段“环境要求”说明包括 Node.js 20 和 npm。Codex 会读取文件、生成修改方案并展示 diff。你确认后它会写入文件。完成后用命令验证cat README.md git diffgit diff可以清楚看到 Codex 对文件的改动。这也是为什么前面建议先把目录初始化为 Git 仓库。如果你的版本提供了exec子命令也可以在非交互模式下完成简单任务codex exec 统计当前目录下所有 Go 文件的行数具体子命令名称和参数以你安装版本的codex --help输出为准。5.3 验证结果和日志运行到这一步如果一切都正常说明安装注册已经全部打通。你还可以检查 Codex 的日志目录了解它执行了哪些请求、调用了哪个模型。常见日志位置~/.codex/log/日志文件会按会话或时间拆分。排错时如果只靠报错信息判断不了问题打开日志看模型请求和响应状态是最直接的。6. 安装注册阶段的高频报错排查现象、原因、解决6.1 codex: command not found现象执行codex --version提示codex: command not found。常见原因npm 全局 bin 目录没有加入 PATH。全局安装失败只是最后一部分日志没有看清楚。使用 Homebrew 安装时 brew 的 bin 目录没在 PATH 中。排查方式npm ls -g --depth0查看 openai/codex 是否出现在全局包列表中。如果出现了说明包已安装问题出在 PATH。再执行npm bin -g这会输出全局可执行文件目录。检查这个目录是否在 PATH 中echo $PATH处理建议把该目录加入 shell 配置文件然后重新打开终端。6.2 unable to locate the codex cli binary现象在 ChatGPT 桌面应用或某个 Codex 客户端中启动任务时提示无法定位 Codex CLI 二进制文件并给出codex_cli_path相关提示。常见原因客户端是单独安装的界面真正执行命令的却是 CLI。客户端找不到codex可执行文件的路径。排查方式先在终端确认codex的完整路径which codex然后把这个路径配置到客户端的设置项中。很多客户端读取CODEX_CLI_PATH环境变量你可以按下面的方式设置macOS / Linuxexport CODEX_CLI_PATH$(which codex)Windowssetx CODEX_CLI_PATH C:\path\to\codex.exe注意Windows 的setx设置的是用户环境变量需要重新打开终端或客户端才能生效。如果你的客户端支持codex_cli_path配置项也可以直接写在配置文件中。6.3 codex login 后浏览器不弹出或跳转失败现象执行codex login后终端停在等待状态浏览器没有自动打开或者打开后页面报错。常见原因当前环境没有默认浏览器。终端环境无法自动启动浏览器。浏览器安全策略拦截了授权页面。网络无法正常访问认证服务。处理建议不要关闭终端手动复制终端中输出的完整 URL 到浏览器访问。如果无法访问授权页先解决网络连通问题。如果浏览器能打开但授权后没有跳转回到终端查看是否出现Login successful之类的提示。如果仍然失败删除旧的认证信息后重试rm -rf ~/.codex/auth.json codex login6.4 模型不受支持现象启动 Codex 或调用接口时出现类似the gpt-5.6-sol model is not supported when using codex with a...的报错。常见原因你配置的模型名称在当前账号下不可用。第三方模型提供商支持的白名单里没有这个模型。Codex 版本内部维护的模型列表比较旧。排查方式codex --help查看当前版本的帮助信息里是否列出了可用模型。再检查配置文件cat ~/.codex/config.toml看model字段是否填写了不存在的模型名。处理建议把模型改成账号实际可用的模型或者升级 Codex 到最新版本。如果你接入了第三方模型服务需要到模型提供商的文档确认模型名。6.5 网络链路异常类报错现象调用 Codex 时报错信息中包含cc switch local ... failed while handling codex endpoint /responses最终表现为请求没有返回结果。常见原因本机网络链路异常请求没有到达模型服务。常见影响因素包括网络出网状态、本地防火墙、DNS 解析、证书信任配置。排查方式先用curl -I https://api.openai.com检查基础网络连通性。查看 Codex 日志中请求的完整错误码。检查系统时间是否准确证书验证依赖系统时间。处理建议在合规网络环境下重试确认系统时间同步必要时重新安装或信任本地证书。这一类报错通常不是 Codex 配置文件的问题而是本地到远端服务的网络链路问题。6.6 安装注册排错清单问题现象可能原因检查动作处理建议command not foundPATH 错误或未安装which codex、npm ls -g修正 PATH重装客户端找不到 CLI未配置 CLI 路径which codex设置CODEX_CLI_PATH浏览器不弹授权页默认浏览器异常手动复制 URL手动打开授权链接模型不支持模型名不可用查看帮助和配置修改模型名或升级版本网络链路报错本地出网异常curl -IAPI 地址检查网络和证书7. 生产环境与日常使用的配置建议7.1 配置文件、环境变量和密钥管理Codex CLI 的配置默认位于~/.codex/config.toml这个文件可以配置模型、模型提供商、日志级别等参数。下面是一个最小配置示例model gpt-5 model_provider openai [model_providers.openai] name OpenAI base_url https://api.openai.com/v1 env_key OPENAI_API_KEY wire_api responses注意这里写的是可参考的配置结构实际模型名和环境变量要以你账号可用的服务和版本支持为准。如果只是本地常规使用Codex 的默认配置通常已经足够不需要手动创建这个文件。生产环境使用 Codex 时最关键的是不要硬编码密钥。建议把 API Key 放在环境变量或密钥管理服务中Codex 通过env_key字段读取。7.2 目录权限和提交安全Codex 会在用户目录下写入认证文件、日志、会话历史。这些内容可能包含提示词、文件内容摘要和令牌信息。建议不要把~/.codex/auth.json提交到 Git。不要把包含 API Key 的环境变量打印到日志中。如果使用共享机器设置~/.codex目录权限为当前用户可读写。chmod 700 ~/.codex chmod 600 ~/.codex/auth.json7.3 日常使用的最佳实践在项目目录中使用 Codex 前先初始化 Git便于查看 Codex 造成的改动。复杂的修改任务先让 Codex 输出计划确认后再执行。不要让 Codex 自动执行高危命令尤其是删除文件、重置数据库、推送远端等操作。不同项目可以单独维护配置文件通过CODEX_HOME或命令行参数指定。CODEX_HOME~/.codex-project-a codex这样可以在不同项目间隔离模型、日志和会话数据。8. 扩展把 Codex 接到 OpenAI 兼容模型DeepSeek 示例8.1 为什么要配第三方模型Codex CLI 本身支持通过模型提供商配置调用 OpenAI 兼容接口。这样可以在不更换 CLI 的情况下把模型指向其他兼容服务。比如 DeepSeek 提供了一个 OpenAI 兼容的 API 端点就可以通过 Codex 的model_providers配置接入。这种做法的好处是复用了 Codex 的终端交互和文件修改能力同时使用不同的模型服务。前提是你有对应服务的 API Key并且确认该服务支持 Codex 需要的接口格式。8.2 配置 OpenAI 兼容模型提供商打开配置文件vim ~/.codex/config.toml添加一个模型提供商model deepseek-chat model_provider deepseek [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY wire_api chat然后设置环境变量export DEEPSEEK_API_KEY你的DeepSeek API Key再启动 Codexcodex如果配置正确Codex 会通过 DeepSeek 的 OpenAI 兼容接口完成对话和代码任务。强调一点不同模型的接口能力、上下文长度、工具调用支持都不一样。第三方协议兼容不等于所有功能都能在 Codex 中原样工作。如果遇到功能异常优先查看该模型服务是否支持工具调用和响应用responses协议。8.3 扩展时的回归验证接入第三方模型后不要直接进项目改代码。先在空目录跑一次最小对话再测试一次文件修改确认功能链路稳定。这样可以避免把模型服务问题误认为是 Codex 配置问题。如果需要切回 OpenAI 官方模型把配置中的model、model_provider和base_url改回默认值即可或者直接删除自定义的model_providers配置。8.4 扩展方向学习 Codex 配置文件中的model_providers完整字段理解base_url、env_key、wire_api的作用。尝试在 CI 流水线中使用codex exec完成自动化代码修改但要在沙箱或临时分支中执行。结合 Git diff 和 Codex 的日志建立一套“AI 修改代码前的审查流程”。如果你维护团队规范可以统一成员本地的config.toml模板提升团队复现效率。从安装到注册再到跑通一次真实任务Codex 的使用链路并不复杂但每一个环节都有对应的环境依赖。安装前先做好系统检查登录时理解认证方式报错时按“CLI 是否安装 - 认证是否生效 - 模型是否可用 - 网络是否连通”的顺序排查大部分问题都能快速定位。
