Codex新手入门教程：安装配置与API接入避坑指南

Codex介绍

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

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

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

1. 安装Codex

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

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

基本流程是：

打开官方入口。
下载 Windows 或 Mac 版 Codex 桌面 App。
按提示安装。
打开 Codex。
用 ChatGPT / OpenAI 账号登录，或配置大模型 API Key 接入。

具体操作：

1、下载安装包 我们可以直接去 OpenAI 的 Codex 官网下载安装，访问：[https://openai.com/zh-Hans-CN/codex/](https://openai.com/zh-Hans-CN/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 通道：

获取官方密钥：登录 OpenAI 开发者平台（[platform.openai.com/api-keys](https://platform.openai.com/api-keys)），绑定海外支付方式并充值后，创建一个以 sk- 开头的 API Key。
在 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。

配置步骤：

获取中转 Key 与接口地址：在 4SAPI 后台注册并创建一个令牌（同样是 sk- 开头的格式），同时复制平台提供的接口转发地址（Base URL，通常以 /v1 结尾）。
修改 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"

填入密钥生效：将从 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 等。具体入口和按钮名称会实时更新，以自己当前看到的界面为准。

小白先看这张表就够了：

使用方式	解释	适合谁	小白建议
Codex 桌面App	装在电脑上的 Codex 工作台	想管理本地项目的人	主推，从这里开始
Codex Web / Cloud	在网页或云端委托任务	想让任务离开本地持续跑的人	后面再学
Codex CLI	命令行里的 Codex	会终端的人	小白先不用
IDE / VS Code 扩展	在代码编辑器里用 Codex	写代码、改网页、改项目的人	有项目后再用
GitHub 里的 Codex	在代码仓库里委托任务	管 GitHub 仓库的人	后期再学

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

2.2 了解 Codex 基本组成

打开 Codex 桌面 App，进来后，我们先带大家快速认识一下各个区域。

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

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

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

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

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

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

默认权限（最安全、最保守）：一般主要是能读取工作区内所有文件，但是修改文件、执行终端命令、联网全部需要你手动点击确认。简单来说，就是动个啥都需要你审批。适合新手刚上手、不熟悉 Codex 时，或者对于一些陌生/重要/线上代码修改时。
自动审查（日常开发首选）：在默认权限基础上，内置自动风险判断，低风险操作自动放行，比如改普通代码、加注释、安装依赖、跑测试 / 构建。高风险操作仍会弹框确认，比如删除文件、rm -rf、提权等。适合日常开发，碰到有风险的操作会拦一下。小事自动过，大事问你，新手最推荐。
完全访问权限（最高权限、风险最大）：简单来说，可创建 / 修改 / 删除任何项目文件，无确认、无拦截、直接执行所有操作，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 的配置分为两个层级：全局级（影响所有项目）和项目级（仅影响当前文件夹）。建议先配置全局规则作为底线，再为特定项目补充专属要求。

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

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

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

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

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

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

然后记忆的两个功能，我推荐都可以在「设置 → 个性化」中打开。

针对于我们打开的具体项目，可以在项目根目录下创建一个 AGENTS.md 文件，Codex 在开始工作之前会先读取它的内容：

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

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

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

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

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

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

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

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

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

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

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

7、自动化先别急

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

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

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

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

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

名词	小白理解	什么时候用
Plugin 插件	给 Codex 装能力包	做表格、PPT、文档、浏览器操作
Skill 技能	工作流说明书	固定写作流程、项目规范、测评流程
MCP	外部工具通道	连接更专业的本地或远程工具

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

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

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

接下来，我们重点介绍一下 Codex 里的 Skills 和 Plugins。在 Codex 里，都是从左侧「插件（Plugins）」这个 tab 点进去，然后顶部就有 tab 可以切换插件和技能。

3.1 Skill 是什么、怎么用？

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

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