Codex 使用教程：国内开发者从安装、登录到第一个任务

这篇 Codex 使用教程只讲一条最稳路径：国内开发者先确认 Node.js 和 npm，再安装官方 @openai/codex CLI，完成 codex login，最后用“只读分析 → README 小改动 → 看 diff → 跑检查”的方式完成第一个任务。不要第一天就让 Codex 改支付、登录、数据库或生产配置。

截至 2026-06-24，本地通过 npm registry 验证：@openai/codex 包提供 codex 命令，要求 Node.js >=16；codex --help 显示常用命令包括 exec、review、login、mcp、plugin、app、apply、resume 和 cloud。所以这篇文章里的命令以当前 CLI 帮助为准，而不是网上旧截图。

直接答案 国内开发者第一次用 Codex，不要从复杂配置开始。先安装 CLI，登录账号，用 demo repo 或 README 文件跑一个低风险任务。能看到 diff、能跑检查、能人工 review，才算真正入门。

关键要点

Codex 使用教程的第一步是环境检查，不是立刻改真实项目。

安装入口用官方 npm 包 @openai/codex，命令是 codex。

登录用 codex login，状态检查用 codex login status。

第一个任务先用 read-only，第二个任务再用 workspace-write。

国内开发者要特别注意账号、密钥、GitHub 授权和项目权限边界。

Codex 使用教程适合谁？

这篇 Codex 使用教程适合三类人：已经会一点命令行、想把 Codex 接到本地项目里的独立开发者；正在国内使用 ChatGPT Plus / Pro、想确认 Codex 入口和 CLI 是否能跑通的人；以及准备让 Codex 帮自己改博客、落地页、脚本或小功能的人。

如果你只是想确认账号和入口能不能用，可以先读 Codex 国内怎么用？账号、订阅、入口和安全检查清单。如果你已经能看到 Codex，但不知道第一条任务怎么发，继续看本文就够。

这篇文章不讲三件事：

1. 不讲网络环境规避类操作。
2. 不保证任何账号、任何地区、任何时间都有相同入口。
3. 不建议把陌生环境、共享 runner 或临时机器当作登录环境。

功能入口、计划权益和地区可用性，以 OpenAI 官方说明和你账号里的实际显示为准。

本节结论：这是一篇面向国内开发者的最小闭环教程。目标不是一次学完 Codex 全部功能，而是先把安装、登录和第一个可审查任务跑通。

第一步：安装前先检查什么？

Codex 使用教程的第一步，是确认你当前机器有 Node.js 和 npm。不要一上来复制安装命令；先知道自己的环境是否满足 CLI 要求。

在终端里执行：

node -v
npm -v
npm view @openai/codex version bin engines

你要确认三件事：

1. node 能输出版本号。
2. npm 能正常访问 registry。
3. @openai/codex 的 bin 里包含 codex，engines 满足你的 Node 版本。

本文验证时，npm view @openai/codex version bin engines --json 返回版本 0.142.0，bin.codex 指向 bin/codex.js，engines.node 为 >=16。以后版本可能变化，所以你应该以自己执行的命令输出为准。

如果你的电脑没有 Node.js，先安装 Node LTS；如果你用的是公司电脑或远程服务器，先确认你有权限安装全局 npm 包。国内开发者常见的问题不是 Codex 本身，而是 npm registry、系统权限和登录环境不清楚。

本节结论：先检查 Node、npm 和 @openai/codex 包信息。环境没确认前，不要把后续问题误判成 Codex 不能用。

第二步：怎么安装 Codex CLI？

环境确认后，再安装 Codex CLI。推荐先用官方包安装最新版：

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

如果你不想全局安装，也可以先临时查看帮助：

npx -y @openai/codex --help

codex --help 应该能看到类似这些命令：

codex exec      非交互执行任务
codex review    非交互代码审查
codex login     管理登录
codex logout    移除本地登录凭据
codex mcp       管理 MCP servers
codex plugin    管理插件
codex apply     应用 Codex 生成的 diff
codex resume    恢复之前的会话

如果你执行后提示 command not found: codex，优先检查 npm 全局安装前缀和当前命令路径：

npm prefix -g
npm config get prefix
command -v codex

macOS / Linux 常见解决方式是把全局前缀下的 bin 目录加入 shell 配置，例如 Homebrew Node 常见是 /opt/homebrew/bin。但不要为了省事直接用 sudo npm install -g；权限混乱之后，后面升级和卸载都会变麻烦。

本节结论：安装命令用 npm install -g @openai/codex@latest，安装后用 codex --version 和 codex --help 验证。能看到帮助，不等于已经登录。

第三步：Codex 登录怎么做？

Codex 使用教程里最容易漏掉的一步，是登录状态检查。安装完成后执行：

codex login

如果你使用 API Key 登录，可以查看当前 CLI 支持的登录选项：

codex login --help

本文验证时，codex login --help 显示支持：

codex login status
codex login --with-api-key
codex login --with-access-token
codex login --device-auth

普通用户优先走 codex login 的交互式登录流程。如果必须用 API Key，CLI 帮助里的示例是从 stdin 读取，例如 printenv OPENAI_API_KEY | codex login --with-api-key。登录后检查状态：

codex login status

这里要特别注意安全边界：

1. 只在自己控制的本地电脑或可信开发机上登录。
2. 不要在陌生云主机、共享 runner、临时 PR 环境里登录。
3. 不要把 OPENAI_API_KEY、access token、登录缓存或配置文件提交到 Git。
4. 给 Codex 授权 GitHub 时，先用 demo repo，不要第一天连核心私有仓库。

如果你卡在 ChatGPT Plus / Pro 订阅或支付，可以先看 ChatGPT Plus 充值和 ChatGPT Pro 说明。但要分清楚：订阅正常只是前置条件，Codex CLI 能否登录和任务能否跑通，还要看账号状态、入口权限和本机环境。

本节结论：安装后先 codex login，再 codex login status。国内开发者最该保护的是账号和项目权限，不要为了跑通教程把密钥交给不可信环境。

第四步：第一个任务为什么必须只读？

第一个 Codex 任务，不应该是“帮我重构项目”或“帮我修所有 bug”。正确做法是先让它只读项目，证明它理解项目结构、启动命令和风险边界。

进入一个低风险项目目录，然后执行：

codex -C . -s read-only "请先阅读这个项目的 README、package.json 和主要入口文件。只做分析，不要修改文件。请告诉我：1. 项目是做什么的；2. 本地怎么启动；3. 测试或检查命令是什么；4. 你建议我下一步做哪 3 个小任务。"

如果你更喜欢非交互式执行，可以用：

codex exec -C . -s read-only "请只读分析当前项目，不要修改文件。输出项目用途、启动命令、测试命令、风险点和下一步建议。"

这一步只看 Codex 的理解能力，不追求产出代码。合格答案应该包含：

1. 它读到了哪些关键文件。
2. 它是否说清楚项目用途。
3. 它是否找到了 install / dev / test / lint / build 命令。
4. 它是否主动说明不确定信息。
5. 它有没有越权尝试改文件或安装依赖。

如果第一个只读任务说不清楚项目，你就不要进入写入模式。先补 README、补项目说明，或者换一个更小的 demo repo。

本节结论：第一个任务必须只读。你要先验证 Codex 会不会读项目、懂不懂边界，再决定是否让它修改文件。

第五步：第一次让 Codex 改文件，改哪里最安全？

第一次写入任务，优先改 README、文案、注释或一个不会影响业务逻辑的小 UI 文案。不要让 Codex 一上来动登录、支付、数据库、密钥、管理员后台或生产部署配置。

先建分支：

git status
git checkout -b codex-first-task

再给 Codex 一个很窄的任务：

codex -C . -s workspace-write "请修复 README 里本地启动步骤不清楚的问题。只允许修改 README.md，不要改代码，不要新增依赖。改完后输出：1. 改了什么；2. 为什么这样改；3. 我应该运行什么命令验证。"

改完之后，不要急着提交。先看 diff：

git diff

再运行项目已有检查命令，例如：

npm test
npm run build

如果只是文档改动，没有测试命令，也至少做人工检查：确认没有误删段落、没有引入密钥、没有把临时路径写进公开文档。

更稳的验收顺序是：

1. git status 看它改了哪些文件
2. git diff 看每一行改动
3. 运行最小检查命令
4. 人工确认内容没有偏题
5. 再 commit 或开 PR

如果你要把 Codex 用到真实产品页、SEO 页面或支付相关页面，建议继续看 Codex 编程必备 Skill：独立开发者最该先做的 10 个工作流，先把验收标准沉淀下来。

本节结论：第一次写入只改一个低风险文件，最好是 README。能看懂 diff、能运行检查、能回滚，才进入更复杂任务。

国内开发者常见卡点怎么排查？

国内开发者用 Codex，常见卡点通常不是一个问题，而是账号、环境、权限和任务边界混在一起。你可以按下面顺序排查。

卡点	先看什么	不要急着做什么
`codex` 命令不存在	npm 全局 bin、PATH、安装是否成功	不要反复 sudo 安装
登录失败	`codex login --help`、账号状态、浏览器登录流程	不要把 token 贴进陌生环境
看不到入口	ChatGPT 计划、Codex web/app/CLI 入口是否开放	不要认定充值就等于功能永久可见
项目读不懂	README、package.json、启动命令是否清楚	不要让它直接大改代码
改动不可控	sandbox、分支、任务范围是否太宽	不要跳过 `git diff`
测试失败	先保存日志，再让 Codex 分析根因	不要让它无限循环乱改

最实用的排查链路：

安装问题 → node/npm/codex --help
登录问题 → codex login / codex login status
入口问题 → 账号计划 + Codex app/web/CLI 实际显示
项目问题 → 只读任务 + README/package.json
交付问题 → git diff + test/build + 人工 review

如果你还没有明确项目规则，可以继续看 Codex 怎么配置？从 AGENTS.md、MCP 到 Skills 的 2026 入门指南。配置不是越多越好，先让最小任务稳定跑通，再把规则写进项目。

本节结论：国内场景下，排查要分层。先确认命令能跑、账号能登录、入口能打开、项目能读懂，再谈复杂配置。

Codex 使用教程的推荐工作流是什么？

最推荐的 Codex 使用工作流，是把 Codex 当成会执行任务的临时工程师，而不是把它当成自动许愿机。你给它的任务越像工单，结果越稳定。

每次任务都按这个模板写：

背景：这个项目是做什么的，当前要解决什么问题。
目标：这次只完成哪一个结果。
范围：允许修改哪些文件，不允许改哪些文件。
验证：改完后必须运行什么命令，或者给出什么截图/日志。
输出：总结改动、风险、未验证事项和下一步。

一个可复制的任务示例：

请修复博客文章页移动端表格横向溢出的问题。

范围：
- 只允许改 components/blog/BlogContent.tsx 和对应测试。
- 不要改文章内容，不要改支付、后台、数据库代码。

验证：
- 运行 npm test -- __tests__/BlogContent.test.tsx
- 如果有页面预览，请说明截图或 DOM 证据。

输出：
- 改了什么
- 为什么这样改
- 还有什么没有验证

这个模板比一句“帮我优化项目”强很多，因为它给了 Codex 明确边界，也方便你用 diff 和测试验收。

本节结论：稳定使用 Codex 的关键不是神奇 prompt，而是任务卡、权限边界和验收命令。

常见问题

Codex 使用教程第一步是装 CLI 还是开 Plus？

如果你已经有可用账号，第一步是检查 Node.js、npm 和 @openai/codex CLI；如果你连账号和订阅都没有，先解决账号/订阅问题。两件事不要混在一起：Plus / Pro 是计划状态，CLI 安装和登录是本机环境。

国内开发者必须用 Codex CLI 吗？

不是。Codex 可能有 web、app、IDE extension、CLI 等入口。CLI 适合开发者在本地项目里做可审查任务；如果你只是确认账号能不能用，web 或 app 更直观。真正重要的是权限边界和验收，不是入口本身。

第一个任务能不能直接让 Codex 写功能？

不建议。第一条任务先只读，第二条任务再改 README 或低风险文案。你需要先确认 Codex 能读懂项目、能遵守边界、能输出可审查结果，再让它处理真实功能。

Codex 登录时可以用 API Key 吗？

codex login --help 显示 CLI 支持 --with-api-key 和 --with-access-token 等选项，但普通用户优先走交互式 codex login。如果必须用 API Key，只在可信机器上通过环境变量或 stdin 传入，不要写进仓库或聊天记录。

Codex 生成的代码可以直接合并吗？

不可以。Codex 生成的代码必须经过 git diff、测试/构建、人工 review；网站页面还要看真实渲染、SEO 元信息、schema、sitemap 和截图。AI 执行，人判断。

结论：先跑通一个小闭环，再放大任务

这篇 Codex 使用教程的核心只有一句话：国内开发者不要第一天追求“全自动开发”，先跑通安装、登录、只读分析、低风险修改、diff、测试和人工 review 这一条小闭环。

最小顺序如下：

1. node -v / npm -v
2. npm view @openai/codex version bin engines
3. npm install -g @openai/codex@latest
4. codex --version / codex --help
5. codex login / codex login status
6. codex -C . -s read-only 做只读项目分析
7. codex -C . -s workspace-write 只改 README
8. git diff + npm test / npm run build
9. 人工 review 后再提交 PR

如果你已经跑通第一条任务，下一步可以继续看 Codex 怎么调用 Claude Code CLI？claudcode 别名、登录与只读审查教程，把 Claude Code 当第二双眼睛做代码审查；如果你还在选套餐，可以看 ChatGPT Pro 5x / 20x 是什么意思？Codex 额度和 Plus 怎么选。

参考来源

OpenAI Developers，Codex 页面：https://developers.openai.com/codex ，retrieved 2026-06-24。
npm registry，本地命令 npm view @openai/codex version bin engines --json，retrieved 2026-06-24。
Codex CLI，本地命令 npx -y @openai/codex --help、npx -y @openai/codex login --help、npx -y @openai/codex exec --help，retrieved 2026-06-24。