零基础照着做：把 Codex 跑起来，并变成你的开发搭档

Codex 是什么

Codex 是 OpenAI 的编码智能体。它不只是回答问题，还能在你授权的范围内读取文件、修改代码、运行命令、做代码审查、整理资料、生成报告，并把结果留在你当前项目里。

对新手来说，最重要的理解是：Codex 不是一次性问答工具，更像一个需要上下文、规则和验收标准的队友。你给它的目标越清楚，它能检查自己工作的机会越多，结果就越稳定。

选择入口：App、CLI、IDE、Web

Codex 现在有多个使用入口。你不需要全部掌握，先选一个最贴近你当前工作的入口即可。

准备 3 样东西

安装与登录

如果你使用 Codex App，下载并安装 Windows 或 macOS 版本，打开后登录 ChatGPT 账号，选择一个项目文件夹，然后发送第一条消息。App 适合新手，因为它把线程、文件改动、审查面板和自动化放在同一个地方。

如果你使用 CLI，官方文档给出的 npm 安装方式如下：

npm i -g @openai/codex
codex

Windows 用户可以在 PowerShell 中原生运行 Codex；如果你需要 Linux 原生工具链，也可以用 WSL2。第一次运行时按提示用 ChatGPT 账号或 API Key 登录。

第一条成功任务

学 Codex 的第一步不是背命令，而是跑通一个完整闭环：描述目标，让它读项目，让它做最小修改，让它验证，再让它汇报结果。

这条消息之所以适合新手，是因为它包含了目标、上下文探索、具体产物、验收动作和交付说明。你能清楚看见 Codex 是否真的做完了。

截图课程：从打开 Codex 到交付结果

你发来的长截图适合沉淀成一个完整课程：它不是单点功能说明，而是一条从进入 Codex、选择环境、连接仓库、发起任务、查看执行日志、处理结果到复盘修正的实操路线。下面先把截图内容整理为文字版课程，后续可以把每一步替换成你的高清截图和录屏。

Codex 国内站使用教程

你补充的截图里出现了国内访问入口、控制台、模型配置、用量面板和任务执行页面。它可以作为一节面向中文学员的“国内站上手课”：先帮学员理解入口和风险，再带他们完成登录、配置、发起任务和查看结果。

用 CC-Switch 接入

新手建议：先做小任务

帮我修改首页文案
帮我整理 README
帮我加一个英文版页面
帮我修复样式问题
帮我把项目推送到 GitHub

把需求说清楚：四件套

官方最佳实践把高质量任务提示拆成四个部分：目标、上下文、约束、完成标准。你不必每次都写长提示，但复杂任务最好按这个结构写。

目标：把登录页表单改成两列布局，并保持移动端单列。
上下文：相关文件是 src/pages/Login.tsx 和 src/styles/login.css。
约束：不要引入新 UI 库，沿用现有颜色和间距变量。
完成标准：运行 npm test，打开页面检查 390px 和 1440px 两个视口。

先计划再动手

任务越复杂，越应该让 Codex 先计划。计划不是拖慢速度，而是让它先读上下文、暴露假设、拆解风险，再开始改文件。Codex 的官方最佳实践也建议在复杂、模糊、难描述的任务上使用 Plan mode 或先要求它采访你。

请先不要写代码。先阅读相关文件，给我一个 5 步以内的实现计划。
计划里标出你需要确认的问题、可能影响的文件、准备运行的验证命令。
我确认后你再开始实现。

验证与审查

Codex 的质量来自闭环。不要只让它“写完”，要让它“证明写完”。证明可以是测试、lint、类型检查、截图、构建日志、手动复现步骤，或者 diff 审查。

完成后请：
1. 运行项目里最相关的测试或检查命令。
2. 如果是页面改动，启动本地服务并用浏览器截图检查。
3. 最后按“改动 / 验证 / 风险”三段总结。

线程、工作树与并行

Codex 里的 thread 可以理解为一个工作会话。一个线程适合处理一个连贯任务。长任务可以继续追问，也可以在上下文太长时压缩；不同方向的任务可以 fork 或新开线程。

并行是 Codex 的强项，但不要让两个线程同时改同一批文件。对真实项目，建议用 Git 分支或工作树隔离改动。Codex App 内置工作树支持，适合同时推进多个互不冲突的尝试。

AGENTS.md：把重复要求写成规则

如果你每次都要提醒 Codex “先读项目、不要乱加依赖、修改后跑测试”，那就应该写进 AGENTS.md。官方文档把它描述为给 Codex 的项目级自定义说明：Codex 在开始工作前会读取这些文件，并按目录层级组合指令。

# AGENTS.md

## 项目说明
- 这是一个中文教程站，主要入口是 index.html。
- 页面风格参考文档站：左侧目录，中间正文，右侧页内目录。

## 工作要求
- 修改前先说明会改哪些文件。
- 新增内容要保持中文表达清楚，不要堆术语。
- 页面改动后必须用浏览器检查桌面和移动端布局。

## 完成标准
- 文件能直接打开。
- 没有明显文字溢出、重叠或空白异常。
- 最终回复包含改动和验证结果。

可以有全局 ~/.codex/AGENTS.md，也可以有项目根目录的 AGENTS.md，还可以在子目录里放更具体的规则。越靠近当前目录的说明越具体，通常优先级越高。

config.toml 与权限

config.toml 用来保存 Codex 的持久配置，例如模型、推理强度、沙箱、审批策略、MCP 服务器和配置 profile。个人默认配置通常放在 ~/.codex/config.toml，可信项目可以使用 .codex/config.toml。

# ~/.codex/config.toml
model = "gpt-5.3-codex"
reasoning_effort = "medium"

[profiles.safe]
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[profiles.fast-local]
approval_policy = "never"
sandbox_mode = "workspace-write"

MCP：把外部工具接进来

MCP 是 Model Context Protocol，用来把外部工具和上下文接给 Codex。例如文档检索、浏览器、Figma、内部系统、数据库只读查询等。官方文档说明，Codex 在 CLI 和 IDE extension 中支持 MCP server。

适合使用 MCP 的场景：上下文在仓库外、信息经常变化、你希望 Codex 调工具而不是靠复制粘贴、或者团队需要可复用集成。

# 例：通过 CLI 添加一个文档检索 MCP server
codex mcp add context7 -- npx -y @upstash/context7-mcp

# 在 Codex TUI 中查看活跃 MCP
/mcp

Skills 与插件：把稳定流程封装起来

如果一个流程你反复使用，比如 PR 审查、故障排查、发布说明、数据报告，就可以把它做成 Skill。Skill 通常包含一个 SKILL.md，描述什么时候使用、怎么做、需要哪些脚本或模板。

初版 Skill 不要追求覆盖所有情况。先围绕 2 到 3 个真实任务写清楚输入、步骤和输出，跑顺后再扩展。团队共享时，可以把 Skill 打包进插件。

自动化：让稳定任务定期运行

当一个工作流已经稳定，可以用 Codex App 的 Automations 定时运行，例如每周总结提交、每天检查 CI 失败、定期草拟发布说明、扫描潜在 bug、生成站会摘要。

提示词模板

让 Codex 解释项目

请先阅读当前项目结构和关键文件，然后用中文说明：
1. 这个项目是做什么的。
2. 主要入口文件在哪里。
3. 本地运行、构建、测试命令分别是什么。
4. 新手继续开发时最需要注意的 3 件事。

让 Codex 修 bug

现象：描述 bug 如何出现。
复现：列出具体步骤和输入。
期望：说明正确行为。
约束：请先定位根因，不要大范围重构。
完成：修复后运行相关测试，并说明为什么这个修复覆盖了复现路径。

让 Codex 做教程内容

请基于官方文档和当前项目内容，整理一篇中文教程。
要求：
- 先给目录，再写正文。
- 每一节都要有“做什么、为什么、怎么验证”。
- 把不确定或会随时间变化的信息标注为“以官方页面为准”。
- 最后列出资料来源链接。

常见问题

我不会写代码，可以用 Codex 吗？

可以，但要从小任务开始。让 Codex 解释文件、生成简单页面、整理表格、写教程，比一上来让它重构大型系统更合适。

Codex 会不会乱改我的文件？

本地工作时它会在当前项目和权限范围内行动。新手应该使用练习目录、版本控制、默认审批和沙箱设置；在最终接受改动前查看 diff。

什么时候用 Cloud，什么时候用 Local？

本地适合你要立刻看文件、运行本机工具、检查页面的任务。Cloud 适合委托后台任务、并行尝试、从 GitHub 仓库开 PR 的任务。

教程里要不要写模型价格和限额？

可以写入口和查询方法，但具体价格、限额、包含计划变化很快，页面中应提示以官方定价页和帮助中心为准。

调研来源

这一版内容优先整合官方资料，再补充开源仓库信息。后续你加入自己的实操经验时，可以把“官方事实”和“个人经验”分开标注。