Codex CLI 安装与登录教程：进入仓库、常用命令与排错

Codex CLI 的上手顺序是安装、确认版本、登录、进入仓库、执行小任务。 安装成功只代表本机能运行客户端，不能证明账号有权限、API 有余额或网关兼容。本篇只讲终端操作；完整任务流程见 Codex 使用教程。

文档核对日期：2026 年 10 月 24 日。本文基于 OpenAI CLI 官方文档及 认证说明整理，没有逐一实测所有系统。

如需自定义 API 入口，可到 api.clawsocket.com 核对协议与配置文档。当前支持的模型、路径、配额、价格、限制，以 api.clawsocket.com 控制台当前显示为准；请按 网关配置专文操作，避免把第三方 Key 用进官方账号登录步骤。

1. 选择与你的系统匹配的安装方式

官方安装页有操作系统和包管理器选项。安装前确认当前终端运行的是 macOS、Linux、Windows 原生，还是 WSL；WSL 中安装的程序与 Windows 原生程序不是同一份环境。

macOS / Linux 当前官方页面展示的独立安装方式是：

npm i -g @openai/codex

这条命令会下载并运行官方安装脚本，应先核对来源。企业设备按组织的软件安装规则处理。Windows 用户请在 官方安装页切换 Windows 选项，或按当前 WSL 官方说明选择环境，不要直接照抄上面的 shell 命令。

安装后运行：

codex --version
codex --help

版本输出和帮助正常，才进入登录步骤。本文不固定版本号；升级时使用同一安装渠道，避免留下多份可执行文件。

2. 确认运行的是哪一份 Codex

在 macOS / Linux / WSL 中：

command -v codex

Windows PowerShell 中：

Get-Command codex

如果提示找不到命令，先检查安装是否完成、安装目录是否在 PATH 中，再重新打开终端。若安装后版本仍旧，检查是否存在旧包管理器版本或别名。不要用删除整个配置目录的方式解决 PATH 问题，那会混淆安装和身份状态。

3. 选择认证路线

用 ChatGPT 账号登录

codex --login

CLI 会打开浏览器完成 ChatGPT 登录。登录后运行 codex 进入会话。不同版本的登录提示可能有差异，遇到选项变化时以 codex --help 和当前终端提示为准。

用 API Key 认证

如果使用 API 项目计费，先在当前 shell 设置 OPENAI_API_KEY，再按 CLI 当前提示选择 API Key 认证。不要把真实 Key 写进命令、截图、AGENTS.md 或 Git 文件。API Key 计费和 ChatGPT 订阅是两条独立路线，费用说明见 Codex 费用教程。

自动化或企业访问令牌

OpenAI 当前文档还提供 CODEX_ACCESS_TOKEN 和 codex login --with-access-token 的访问令牌路线，适合明确配置了 Codex 访问令牌的自动化场景。令牌应放在 CI 密钥存储中，不要把它当作普通 API Key，也不要把令牌提交到仓库。

第三方网关使用独立 provider 与环境变量，见 config.toml 配置，不要把第三方 Key 用进官方账号登录流程。

4. 从正确的项目目录启动

cd /path/to/your/project
git rev-parse --show-toplevel
git status --short
codex

/path/to/your/project 要换成真实目录。先保存自己的工作，再创建任务分支。第一个提示词可以用：

请只读分析当前仓库。列出项目入口、构建命令、测试命令，
以及会影响本次工作的 AGENTS.md 路径。
不要改文件、安装依赖或访问外部服务。

如果找不到构建命令，就继续补上下文；不要让它虚构一个 npm test。长期规则写法见 AGENTS.md 教程。

5. 先认识这几个会话命令

以下命令可在当前官方 CLI 文档和 命令参考核对，实际可用项以已安装版本的帮助为准。

命令	用途	什么时候检查
/status（若当前版本提供）	查看当前会话状态	以 /? 或 codex --help 确认
/model（若当前版本提供）	选择模型和推理设置	以当前会话菜单为准
/review（若当前版本提供）	发起代码审查	仍需人工检查与项目测试
codex exec	在脚本或自动化中执行任务	先用测试仓库验证权限与输出

/review 或其他会话命令是否存在，以当前版本的帮助输出为准；任何命令都不能替代实际构建、测试和人工审查。

6. 报错按层排查

现象	先确认	下一步
command not found	安装目录与 PATH	核对可执行文件位置，重开终端
浏览器登录完成但终端没恢复	登录发生在哪台机器、哪个环境	对照官方认证文档的远程环境选项
显示错误账号或权益	重新运行 codex --login	确认账号后按需重新登录
找不到文件	当前目录、项目根目录	在正确仓库重新开始
操作被拒绝	权限、沙箱与组织策略	说明需要的操作范围后再调整
网关 401 / 404 / 流式中断	Key、Base URL、协议	按网关专文逐项验证

远程 SSH、容器和 WSL 的 localhost 与本机浏览器可能不在同一个环境。遇到登录回调问题，不要优先关闭防火墙；先确认官方支持的认证方式、回调所在环境和组织网络规则。

日志只分享与错误相关的片段，先去掉 token、认证头和敏感路径。不要公开 ~/.codex/auth.json；官方认证文档明确提醒该文件可能包含敏感认证信息。

7. 完成一次可验收的修改

登录和只读分析正常后，选择一个已有问题，提供复现、文件范围和检查命令。完成后运行 git diff --check，阅读差异，并执行项目自身的检查。成功标准是你能解释改动、复现结果有变化，而且清楚哪些内容没有验证。

下一步可读 使用教程的任务模板与回滚流程、项目规则与 API 网关排错。

FAQ：Codex CLI 安装与登录

codex: command not found 怎么处理？

先确认安装命令是否在当前环境完成，再用 command -v codex（macOS、Linux、WSL）或 Get-Command codex（PowerShell）检查 PATH。若能找到多个路径，优先确认当前执行的是哪一份；不要先删除整个配置目录，因为 PATH 问题和登录状态是两件事。修正 PATH 后重新打开终端，再运行 codex --version 和 codex --help。

浏览器登录成功，但 CLI 仍然显示未登录怎么办？

确认浏览器和 CLI 是否运行在同一台机器、同一个用户和同一个环境。远程 SSH、容器和 WSL 可能没有共享本机的回调或认证状态。回到 CLI 运行 codex --login，记录它实际使用的环境；如果仍不一致，再按官方认证文档的远程环境方式重新登录。不要把认证文件复制到项目仓库或公开发送。

ChatGPT 登录和 API Key 认证应该选哪个？

需要使用 ChatGPT 账号或工作区权益时，运行 codex --login；需要按 API 项目计费时，在环境变量中提供 OPENAI_API_KEY，再按当前 CLI 的提示选择 API Key 认证。API Key 路线按 API 计费，和 ChatGPT 订阅不是同一个余额。第三方 provider 还要按 provider 的环境变量和配置文件方式处理，不能把第三方 Key 当成官方登录凭证。

CLI 进入了错误的仓库，怎样避免误改文件？

启动前执行 pwd、git rev-parse --show-toplevel 和 git status --short，确认绝对路径、仓库根目录和现有未提交改动。第一次提示词明确要求只读分析，列出将要读取的文件和构建命令。路径确认前不要授权批量修改或运行会产生外部副作用的命令。

为什么文本回答正常，但工具调用或流式输出失败？

文本返回只验证了认证和最小路由。工具调用还需要正确传递工具定义、参数、工具结果和后续对话；流式调用还需要客户端能收到完整事件并正常结束。若使用自定义网关，按 Responses 兼容性排错逐级验证，不要根据一次短文本请求就判断完全兼容。

如何安全分享 CLI 报错？

保留客户端版本、操作系统、错误码、时间、脱敏后的 request ID 和执行到哪一步；删除 API Key、认证头、认证缓存内容、仓库私密路径、客户代码和完整请求体。~/.codex 下的认证文件不要上传到 issue、聊天或截图中。