Codex新手保姆级教程：新手从安装到跑通第一个项目实用指南

平时做技术实践时，很多问题不是概念不会，而是细节没串起来。拿“Codex新手保姆级教程：新手从安装到跑通第一个项目”来说，它看着像小点，放到项目里常会牵出环境、配置、兼容性和维护成本。下面按实际采用顺序，把思路、关键写法和容易踩坑的地方讲清楚，便于大家直接对照操作。

Codex介绍

从实现思路看，Codex 是 OpenAI 于 2025 年推出的 AI 编程智能体，到 2026 年已成为开发者圈子里最热门的生产力工具之一。

从实现思路看，它和我们日常采用的聊天机器人有着本质区别，不只是轻松问答对话，还能直接读取本地项目文件、编辑文档与代码、执行系统命令、操控各类软件，同时兼容联网检索信息、网上查资料这些工作，它都能包揽，还能持续跟进长期复杂任务、自动完成一系列操作。

在这个场景下，不少人会把它和 Claude Code 作对比，两者能力上相近，但 Codex 搭配了完整的可视化界面，操作一目了然，更适合新手小白用户采用。

1. 安装Codex

一切的前提，是先要把 Codex 安装到你的本地电脑。

当然还有一个前提：如果采用官方账号直接登录，需提前准备好网络环境和 ChatGPT 账号，这个大家只能自己去想办法解决了（如果是 AI 进化社的成员，之前有教程专门讲过）。此外，Codex 也兼容借助 API Key（接口密钥） 的方式接入采用。

基本流程是：

1. 打开官方入口。
2. 下载 Windows 或 Mac 版 Codex 桌面 App。
3. 按提示安装。
4. 打开 Codex。
5. 在这个场景下，用 ChatGPT / OpenAI 账号登录，或设置大模型 API Key 接入。

具体操作：

1、下载安装包
在这个场景下，我们能够直接去 OpenAI 的 Codex 官网下载安装，访问：[（链接已移除）](（链接已移除）)，Mac 和 Windows 都有，我就用 Mac 做个演示，点击下载安装。

2、安装到本地
下载好 .dmg 安装包后，双击打开，把 Codex 拖到应用程序（Applications）中。

在这个场景下，首次启动时，macOS 可能提示「无法验证开发者」，进入「系统设置 → 隐私与安全性」，点击「仍要打开」。安装这件事本身不复杂，最重要的是别乱下载，建议只从 OpenAI 官方入口下载。

3、登录与接入 Codex
在这个场景下，打开 Codex，直接用 ChatGPT 账号登录，也能够采用其他方式采用 Codex，比如 API Key。

在这个场景下，若你只是初步体验，优先用账号登录，不用一上来就折腾复杂设置。免费账号能不能用，要看当时官方开放策略和额度。长期采用的话，通常建议至少准备 Plus 或更高套餐，或者直接接入 API 按量采用——因为 Codex 一旦进入项目、读文件、改文件、跑长任务，Token 消耗还是比较大的。

1.1 补充方案：Codex 接入大模型 API 教程（官方接口 vs 国内托管中转）

实际处理时，很多朋友在用账号登录跑项目时，常会遇到两个痛点：一是 Plus 账号有固定时间窗口的额度限制，代码库一大就容易触发限流；二是终端环境下的网络代理不够稳定，跑长任务中途容易断连。

这时候，借助 API Key 落到代码里，接入就是一种很实用的替代方案。在 Codex 中接入 API 主要有两种路径，大家能够根据自己的条件按需选择：

方式一：OpenAI 官方 API 原生接入

落到代码里，若你手里本身有海外，且本地网络环境很稳定，能够直接走官方 API 通道：

1. 拿到官方密钥：登录 OpenAI 开发者平台（[platform.openai.com/api-keys](（链接已移除）)），绑定海外支付方式同时充值后，新建一个以 sk- 开头的 API Key。
2. 在 Codex 中设置：

• 桌面端操作：在 Codex 登录界面或设置中选择「采用 API Key（Use API Key）」，直接粘贴你的官方 sk-... 密钥即可（官方默认端点无需修改 Base URL）。
• 命令行验证（可选）：如果后续配合终端采用，也能够将密钥写入环境变量 OPENAI_API_KEY，执行 printenv OPENAI_API_KEY | codex login --with-api-key 完成绑定。

方式二：国内托管中转站接入（以 4SAPI 为例）

理解这一步时，对于大多数没有海外、或者不想折腾终端全局代理的国内开发者来说，也能够借助兼容 OpenAI 协议的国内 API 托管中转站（比如 4SAPI）来接入 Codex。

设置步骤：

1. 拿到中转 Key 与接口地址：在 4SAPI 后台注册同时新建一个令牌（同样是 sk- 开头的格式），同时复制平台提供的接口转发地址（Base URL，通常以 /v1 结尾）。
2. 修改 Codex 接口设置：
   理解这一步时，打开电脑本地用户目录下的 Codex 全局设置文件 ~/.codex/config.toml（如果没有该文件可手动新建），填入中转站的服务地址与密钥环境变量：

# 方案 A：直接将内置 OpenAI 通道指向中转地址
openai_base_url = "https://www.4sapi.org/v1"

或者设置为独立的自定义服务商（便于随时切换多模型）：

# 方案 B：自定义服务商配置
model = "gpt-5.3-codex"
model_provider = "4sapi"
[model_providers.4sapi]
name = "4SAPI Gateway"
base_url = "https://www.4sapi.org/v1"
env_key = "OPENAI_API_KEY"

3. 填入密钥生效：将从 4SAPI 拿到的 Key 填入 ~/.codex/.env 文件（格式为 OPENAI_API_KEY=sk-你的密钥）或在客户端设置中粘贴保存，重启 Codex 即可正常调用。

客观对比：为什么不少开发者会用国内托管中转站（如 4SAPI）？
这里轻松提一嘴这种方案的核心优势，便于大家根据自身情况做取舍：

• 国内网络直连更稳：API 请求直接走国内高可用节点转发，不需为终端或桌面端单独设置复杂的 TUN 模式代理，跑长流程代码重构时不容易因网络抖动中断。
• 省去海外支付与封号烦恼：不需办理海外双币卡，兼容国内常用支付方式按需充值；同时避免了官方账号因环境变动被风控导致整月订阅费打水漂。
• 按量计费 + 多模型聚合：不受 Plus 账号“每 5 小时/每周”的固定次数限制，用多少算多少；而且同一套接口协议下通常聚合了 OpenAI、Claude 等多种主流编程模型，切换起来更省心。

2. 先别急着提问、干活

结合项目来看，若你只把 Codex 当成 ChatGPT 的另一个入口，那它确实就是一个聊天框。

从实现思路看，但 Codex 真正厉害的地方，不是“回答问题”，而是“能直接进入项目文件，扮演你的工作助手帮你做事”。

比如，它能够做这些事：

• 读取你指定的本地文件。
• 修改项目里的文档和代码。
• 运行终端命令。
• 打开网页查资料。
• 借助插件处理文档、表格、PPT。
• 用 Skills 按固定流程完成任务。
• 借助 MCP 连接外部工具。
• 在 IDE 或云端继续处理项目。

对于新手来讲，要先建立一个重要的意识：不要一上来就用“Codex 直接开发项目”，而是要先学会了解它。

2.1 Codex 不同采用方式

在这个场景下，Codex 能够在多个入口采用，比如 桌面 App、CLI、Web/Cloud、IDE extension 等。具体入口和按钮名称会实时更新，以自己当前看到的界面为准。

小白先看这张表就够了：

从实现思路看，建议先把桌面 App 这条路跑通，后面去 VS Code、Cloud、GitHub 都会顺很多。

2.2 了解 Codex 基本组成

理解这一步时，打开 Codex 桌面 App，进来后，我们先带大家更快认识一下各个区域。

中间这一大块，就是我们平时的工作区，左侧栏包含两个主要入口：Chat（对话） 和 Project（项目）。

• 对话（Chat）：适合不需绑定到特定文件夹的任务，与 ChatGPT 网页端对话体验基本一致，适合处理日常的、一次性的问答和轻松任务。每个对话相互独立，不共享工作目录。
• 项目（Project）：项目才是 Codex 真正的主战场，适合需操作本地文件的任务，比如生成代码、编写文档、制作 PPT、完成报告。选一个本地文件夹作为项目目录，Codex 就会以这个文件夹为工作区间，所有生成的文件都会自动存进去。一个项目里能够开多个对话，每个对话是一条独立的任务线，它们共享同一个文件夹里的文件，但记录互相隔离。借助项目便于统一管理多个子任务。

我们能够在左侧项目这边点击加号新建文件夹，或者采用一个现有的。

从实现思路看，Codex 桌面 App 的对话框与 ChatGPT 网页端类似，但额外提供了以下功能：

• 添加上下文：能够附加文件、截图或其他参考内容。
• 选择模型：在不同模型之间切换。
• 选择工作目录：指定 Codex 在哪个本地文件夹下执行任务。
• 计划模式（Plan Mode）：只规划不动手，先帮你把方案理清楚，你确认了再开始做。每个稍微复杂一点的项目，我都建议你先用这个模式过一遍。
• 本地模式：分为本地 / 工作树 / 云端，决定文件改在哪里。

然后在对话框左下角有三档权限选择：

1. 默认权限（最安全、最保守）：一般主要是能读取工作区内所有文件，但是修改文件、执行终端命令、联网全部需你手动点击确认。轻松来说，就是动个啥都需你审批。适合新手刚上手、不熟悉 Codex 时，或者对于一些陌生/重要/线上代码修改时。
2. 自动审查（日常开发首选）：在默认权限基础上，内置自动风险判断，低风险操作自动放行，比如改普通代码、加注释、安装依赖、跑测试 / 构建。高风险操作仍会弹框确认，比如删除文件、rm -rf、提权等。适合日常开发，碰到有风险的操作会拦一下。小事自动过，大事问你，新手最建议。
3. 完全访问权限（最高权限、风险最大）：轻松来说，可新建 / 修改 / 删除任何项目文件，无确认、无拦截、直接执行所有操作，AI 全权代理，全程不打扰，风险自担。几乎无安全限制，误操作可能导致文件丢失 / 项目损坏，一般适合那些高度信任的个人练习项目。

当然，用着用着，你可能会好奇自己还剩多少额度。
点左下角的设置，找到剩余额度落到代码里，，就能看到你 5 小时内还剩多少、这周还剩多少、啥时候刷新。（注：如果你在赶项目时经常把 5 小时或周额度跑满，就能够参考前文 1.1 节的方法，切到 OpenAI 官方 API 或 4SAPI 这类按量中转接口继续跑，避免开发节奏被打断。）

2.3 先做几个基础设置

从实现思路看，到这里，先别急着让它改文件，先做设置。Codex 的设置会随着版本变化，但小白能够先关注这几类设置。你不需把每个按钮都研究透，先把最影响采用体验和安全边界的地方搞清楚。

1、常规设置：将跟进行为改为“引导”

结合项目来看，跟进行为改成引导，这样在中途你想修改的时候就能够直接插入，而不是必须等着当前任务做完才能进行新一轮的对话。

2、常规设置：发送方式改为“组合键发送”

开启按组合键发送的开关选项（默认为 Enter 发送）。
因为你后面写项目需求时，经常会写很长：

• 项目目标
• 输出格式
• 不要做什么
• 目录结构
• 验证方式

落到代码里，若写一半按回车就发出去了，Codex 可能会拿着半截需求开始干活。（别问我是怎么知道的，我吃了很多次亏才想起来要设置一下）

3、先建项目目录

结合项目来看，若你是小白，很容易犯一个错误：什么都没设置好，就直接让它干活。结果就是文件到处飞。

先说结论：新手第一次用 Codex，最该先设置的不是模型，而是项目文件夹。这一步是全文最重要的地方。

从实现思路看，新手用 Codex，第一件事不是装插件，而是建立项目根目录。你能够建一个这样的文件夹：

~/codex-projects

实际处理时，这个目录以后专门放 Codex 项目。不要把项目直接放在桌面、下载目录、个人知识库目录等乱七八糟的位置。

在这个场景下，为什么？因为 Codex 会读文件、写文件、生成中间数据、跑脚本。比如，如果你把项目塞进日常知识库，它可能把一堆日志、设置、代码、缓存都放进去，知识库就被污染了。

实际处理时，所以先建一个干净的项目根目录。有了项目根目录，每个新项目再建一个独立文件夹，比如：

~/codex-projects/project1
~/codex-projects/project2
~/codex-projects/project3

4、设置 AGENTS.md

下面，设置 AGENTS.md，也就是你给 Codex 设置的家法规矩。

落到代码里，对于 Codex 而言，我们每开启一个新的对话窗口，它都会进入一个全新的上下文。它不记得之前发生了什么，对于整个项目的记忆都是空白的。所以 Codex 提供了记忆系统来解决这样的问题：AGENTS.md 就是给 Codex 这类编码 Agent 看的项目说明文件，它能够描述项目结构、开发命令、测试要求、代码风格和协作边界。

AGENTS.md 的设置分为两个层级：全局级（影响所有项目）和项目级实际处理时，（仅影响当前文件夹）。建议先设置全局规则作为底线，再为特定项目补充专属要求。

如果想要全局生效，有以下两种方式：

1. 落到代码里，在系统的全局 Codex 文件夹（~/.codex/）里面找到 AGENTS.md，它是你为 Codex 提供的全局通用规则。
2. 实际处理时，在 Codex 桌面 App 里面打开设置，找到“个性化”，在其中填写“自定义指令”。这里面设置的就是全局的 AGENTS.md 文件。

在这个场景下，设置全局文件后，对于所有的项目都会生效。设好之后，不管你以后开多少个新对话，它都会记得。比如，你能够添加如下所示自定义指令：

请默认用中文回答。
如果涉及代码或命令，请先用大白话解释目的，再给具体操作。
如果要修改文件、运行命令、访问外部账号，请先告诉我风险。
如果我的需求信息不完整，请先问我缺什么，不要直接编。

AGENTS.md 编写的模板格式建议（或者直接让 AI 帮你生成）：

# AGENTS.md
 
## 项目概览
- 项目类型：
- 主要语言：
- 关键目录：
 
## 常用命令
- 安装依赖：`...`
- 本地开发：`...`
- 运行测试：`...`
- 类型检查：`...`
- 格式化：`...`
 
## 代码规范
- 遵循现有代码风格。
- 不做无关重构。
- 新增功能必须补充或更新测试。
 
## 安全边界
- 不读取或提交 `.env`、密钥和私有凭据。
- 不执行删除生产数据的命令。
- 修改数据库迁移前先说明影响。
 
## 交付要求
- 说明改动文件。
- 说明验证命令和结果。
- 说明未验证项和剩余风险。

随后记忆的两个功能，我建议都能够在「设置 → 个性化」中打开。

从实现思路看，针对于我们打开的具体项目，能够在项目根目录下新建一个 AGENTS.md 文件，Codex 在开始工作之前会先读取它的内容：

1. 在项目根目录的 AGENTS.md 文件里面写入项目说明内容。
2. 回到 Codex 对话窗口问它：“这是一个什么样的项目？”

在这个场景下，你会发现 Codex 会自动读取 AGENTS.md 文件，把里面的内容带入到新的对话作为上下文。当然，在当前项目根目录下新建的 AGENTS.md 只对当前文件夹生效，同时不是全局生效的。

5、权限：不要一上来 ALL IN

落到代码里，Codex 会请求权限，比如读文件、改文件、运行命令、访问网页、连接账号。新手最容易犯的错误是：看到确认按钮就点。不要这样。

实际处理时，第一次采用，建议只给当前项目文件夹权限。如果看不懂权限请求，就直接问 Codex：

请用小白能懂的话解释：你现在请求的权限会访问什么？为什么这个任务需要它？有没有更低风险的做法？

落到代码里，看到权限确认就点，这是最危险的习惯。不懂就问它解释。另外，很多新手一上来就给了 Codex 完全访问权限，结果它误删了重要文件或把代码改得面目全非。建议始终从“默认权限”或“自动审查”开始，熟悉它的行为模式后再逐步放开。

6、模型和推理强度：先默认，复杂任务再提高

小白不需一上来研究每个模型。建议：

• 普通问答 / 轻松脚本：默认模型即可。
• 复杂项目 / 跨文件重构：用更强模型或更高推理强度。（如果你是借助前面提到的 4SAPI 等中转服务或官方 API 接入的，也能够在设置文件里按需切换不同梯队的模型，平时跑小任务用轻量模型省钱，遇到硬骨头再切高阶推理模型。）

一句话：小任务别浪费额度，大任务别省过头。

7、自动化先别急

Codex 有一个听起来很诱人的功能：自动化。比如你能够用它：

• 每天自动总结
• 每周自动检查
• 定时抓资料
• 到点继续写文章
• 自动化测试

在这个场景下，但新手别急，先把手动流程跑通，再自动化。如果你手动都没说清楚“输入是什么、输出到哪里、失败怎么办”，自动化只会把混乱定时重复一遍。只有当一个工作流已经足够稳定、而且会重复发生时，才需考虑把它交给自动化来处理。

3. Codex进阶功能：插件、技能、MCP

理解这一步时，小白最容易把 Plugin、Skill、MCP 混在一起，先别纠结技术定义，看这张表：

你刚开始不需全懂，记住一个顺序：

先用 Codex 桌面 App 自带能力
→ 不够再装插件
→ 重复任务沉淀成 Skill
→ 特殊工具再考虑 MCP

不要一上来装一堆插件、技能。

从实现思路看，下面，我们重点介绍一下 Codex 里的 Skills 和 Plugins。在 Codex 里，都是从左侧「插件（Plugins）」这个 tab 点进去，随后顶部就有 tab 能够切换插件和技能。

3.1 Skill 是什么、怎么用？

落到代码里，Skill（技能）这个东西，字面意思，就是给 Agent 用的技能包。能够理解为一份让 Codex 稳定执行重复任务的操作手册或者工作流说明书。

实际处理时，比如你每次写技术文章、做代码审查或者生成周报，都有一套固定的步骤和格式要求。如果每次都在对话框里重新敲一遍提示词，既麻烦又容易漏掉细节。这时候把它写成一份 Skill，以后只需在对话框里借助指令唤醒这个技能，Codex 就会严格按照说明书里的步骤一步步帮你执行完毕。

从实现思路看，总的来说，Codex适合结合实际项目边做边理解。先抓住核心思路，再逐步补上细节和边界处理，最后效果会更稳定，也更容易复用。