Codex保姆级入门教程,6000字长文带你轻松掌握编程奥秘

一、名字来源

Codex这个名称来源于拉丁文“codex”，意为“卷轴”或“书籍”。在古代，人们将文字记录在羊皮纸或纸草卷轴上，这些卷轴被称为codex。随着时间的推移，这个词汇逐渐演变为指代任何形式的书籍或文献。在现代，Codex这个名字被用来命名一种创新的社区治理模式，寓意着通过书籍和知识的力量来推动社区的发展和进步。

二、历史

Codex社区治理模式的历史可以追溯到20世纪初。当时，随着城市化进程的加快，传统的社区管理模式已经无法满足日益增长的社会需求。在这样的背景下，一些社会学家和城市规划师开始探索新的社区治理模式，Codex模式便是其中之一。经过几十年的发展，Codex模式逐渐成熟，并在全球范围内得到推广和应用。

三、地理位置与区划

Codex社区通常位于城市中心或交通便利的地区。这些社区在行政区划上可能属于不同的区域，但它们共同的特点是具有相对独立的社区治理结构。Codex社区往往以街道、小区或街区为单位，形成一个个相对封闭的社区单元。

四、人口与民族构成

Codex社区的人口构成多样，包括不同年龄、职业、民族和宗教背景的居民。这种多元化的构成有助于促进社区内部的交流和融合，同时也为社区治理提供了丰富的资源和视角。

五、社区治理与服务创新

Codex社区治理模式强调居民参与、民主决策和社区服务创新。以下是几个关键点,
1. "居民参与",Codex社区鼓励居民积极参与社区事务，通过定期举办居民大会、座谈会等形式，让居民对社区治理提出意见和建议。 2. "民主决策",社区治理决策过程遵循民主原则，通过投票、表决等方式，确保居民的利益得到充分体现。 3. "服务创新",Codex社区注重服务创新，通过引入新技术、新模式，提升社区服务质量，满足居民多样化的需求。

六、文化与周边环境

Codex社区的文化特色鲜明，与周边环境相互交融。以下是一些具体表现,
1. "文化活动",Codex社区定期举办各类文化活动，如音乐会、戏剧表演、艺术展览等，丰富居民的精神文化生活。 2. "社区公园",社区内设有公园、绿地等公共空间，

相关内容：

大家好，我是程序员小灰。

如今的AI编程领域，可谓是百家争鸣，Cursor、Trae、ClaudeCode、Codex......全球各大AI巨头都在AI编程这个赛道展开激烈的竞争。

前几天小灰发布了一篇 Claude Code 的入门教程，反响还不错，也有许多朋友在后台留言，询问我们能不能发布一篇关于 Codex 的教程。

没问题，安排上！

今天小灰就来给大家系统性讲解 Codex 这款AI编程工具，聊一聊 Codex 到底能不能打，普通人怎么安装、怎么上手、怎么少踩坑。

文章较长，建议大家先收藏、不迷路。

一、为什么 Codex 值得考虑 ？

Claude Code 好用吗？当然很好用。

然而用过 Claude Code 的朋友都知道，它有两个让人尴尬的特点：

1. 免费额度较少：用着用着就要你充钱，而且还死贵。

2. 封号风险：Anthropic 官方频繁封号，这一点最为致命。

因为以上的这些问题，小灰的粉丝群里经常有人问：”OpenAI 有没有类似的AI编程工具呢？”

答案是“有”，而且稳定性比 Claude Code 要好得多，不但编码能力强，而且还能接入 GitHub，这款产品就是 Codex。

二、什么是 Codex ？

Codex 是 OpenAI 官方出品的 AI 编码工具，能理解你的需求，帮你写代码、跑命令、调 Bug。

Codex 具有四种运行模式，覆盖你能想到的大部分使用场景：

• • CLI（命令行），在终端里跑，适合命令行党，主打一个黑框里掌控全局。
• • App（桌面应用），有图形界面，支持 macOS 和 Windows，适合不想跟终端互相折磨的人。
• • Web（网页版），打开浏览器就能用，不用装任何东西。出差用别人电脑、临时改个代码，随开随用。
• • IDE 插件，支持 VS Code、Cursor、Windsurf。写代码的时候直接在编辑器里调用，不用切窗口，不用复制粘贴，代码上下文自动带过去。

四种运行模式怎么选？

终端党用 CLI，鼠标党用 App，临时救火用 Web，天天写代码用 IDE 插件。

这四种模式没有优劣之分，大家哪种模式用着顺手，就可以优先选用哪种模式。

三、Codex 的最新版本

如果你只是把 Codex 理解成"OpenAI 版 Claude Code"，那现在这个理解有点窄了。

2026年以来，Codex 已经不只是一个命令行编码助手，而是逐步构建为一套"AI 干活系统"。

按官方 Changelog 看，2026 年 4 月 Codex 最核心的变化就三个：

1. Codex App 26.415（2026-04-16 更新）

桌面端从“聊天式编码工具”升级成更完整的 AI 工作台，开始支持内置浏览器、任务侧边栏、GitHub PR 处理、artifact viewer、Memories、多终端、多窗口，以及 Windows 托盘的适配。

2. 模型版本 GPT-5.5（2026-04-23 更新）

GPT-5.5 开始进入 Codex，重点提升复杂实现、重构、调试、测试和验证这类重任务的能力。也就是说，Codex 不只是能写小脚本，而是更适合接真实项目里的复杂任务。

3. Codex CLI 0.128.0（2026-04-30 更新）

CLI 加入可持久化的 /goal 工作流，可以把一个长期目标创建、暂停、恢复和清理；同时新增 codex update，权限、沙箱和插件能力也更细。

从上面的迭代可以看出，对于现在的 Codex，不要只问"它会不会写代码"，更准确的问题是，它能不能接住你工作流里那些重复、复杂、跨文件、需要验证的任务。

不过这篇是入门教程，不会把每个高级功能都展开，你先知道它们存在就行，真用到的时候再按场景深入。

四、Codex 适合什么样的场景？

下面的五种情况，最适合选用Codex：

1. 你已经有 ChatGPT Plus/Pro 订阅，那就优先试 Codex。你每个月交的那 20 刀，终于不只是用来写周报了。

2. 你想要 GUI，不想在终端里和 AI 大眼瞪小眼，想点点鼠标就把活干了。

3. 你被账号稳定性折腾怕了，多一个官方工具，就多一条备用工作流。

4. 你想先低成本试试，Codex 是否包含在你的套餐里，以官方页面和客户端显示为准。能用就先用，别先付费上头。

5. 你喜欢 OpenAI 的模型能力，觉得 GPT 系列写代码、解释代码、改代码都比较顺手。

如果你没有 ChatGPT 订阅，也不想充钱，那也没关系，后面会讲怎么给它接入国内大模型。

五、如何安装 Codex ？

Codex的安装过程并不复杂，一共就几步，只要你的电脑配置不是太差，基本都能跑起来。

1. 环境要求

需要安装Node.js和git。

在本地终端检查一下环境：

node --version

npm --version

git --version

如果没有安装，先补上。这个环节没什么玄学，少一个后面都容易报错。

Node.js 下载地址：
https://nodejs.org/zh-cn/download

Git 下载地址：
https://git-scm.com/install/windows

这里提醒一下，如果你是 Windows 用户，最省心的方式是优先装 App。CLI 也能用，但如果遇到环境问题，可以考虑用 WSL，或者先跳到 App 部分。

2. 安装 CLI

CLI 适合已经习惯终端的人。两种方式，选一个：

# npm 安装
npm install -g @openai/codex

# Homebrew 安装（macOS）
brew install --cask codex

验证安装：

codex --version

看到版本号就说明成功了。

如果这里没看到版本号，优先检查 Node.js、npm 全局路径和网络。

3. App 安装

Windows 下载地址：

https://get.microsoft.com/installer/download/9PLM9XGG6VKS?cid=website_cta_psi

4. 云端版

直接访问：
https://chatgpt.com/codex/cloud

5. IDE 插件

如果你用 VS Code、Cursor 或 Windsurf，可以装插件：

安装地址：
https://developers.openai.com/codex/ide

装完之后在编辑器里就能直接调用 Codex。

到这里你已经有四条路了。新手建议从 App 开始，开发者建议从 CLI 开始，已经有 GitHub 仓库的人可以直接试云端版。

别纠结入口，工具不是对象，不需要从一而终。

六、在 CLI 端使用 Codex

CLI 是 Codex 最像“开发者工具”的形态。你在终端里说需求，它在项目里改文件、跑命令、修问题。

1. 启动

codex

首次启动会让你选择登录方式。

还有可能会报错：Error: account/read failed during TUI bootstrap

这个错误在官方 issue 里已经有人复现，重新登录就恢复了。

这种问题就别硬刚了，先登出再登录，很多时候比你研究半小时日志更有效。

直接执行：

codex logout

或者一步到位：

codex login

浏览器登录一遍基本就好了，很多人都是这样修复的。

2. 登录方式

方案一：Sign in with ChatGPT（推荐）

会打开浏览器，用你的 ChatGPT 账号授权。

方案二：Enter API Key

去
https://platform.openai.com/ 生成一个 API Key，粘贴进去。这种方式按 token 计费，适合已经习惯 OpenAI API 的用户。

3. 模型选择

模型以你当前客户端显示为准。

这里别死记型号，AI 工具更新很快，今天看到的默认模型，过段时间可能就变了。

如果想切换模型，用 /model 命令。

4. 30 秒上手

装好了，先跑一个试试。别上来就让它重构祖传系统，先拿小游戏练手，心态比较健康。

在 D 盘新建一个test文件夹，然后打开终端输入命令：

cd d:	est

然后输入下面命令：

codex "用 Python 写一个贪吃蛇的游戏"

就这么简单。Codex 会理解你的需求，生成代码，创建文件，甚至帮你运行。

你不需要一开始就告诉它用什么框架、怎么组织代码，它会先根据需求做判断。这就是 AI 编码工具的核心价值：你负责描述目标，它负责拆任务、改文件、跑命令。

试完这一个，你就知道 Codex 大概是什么感觉了。后面再把它放进真实项目里，价值会更明显。

当然，AI 写代码和人写代码一样，都需要你 review。不要把它当成完全不用检查的自动交付机器。

5. 常用命令

命令	用途
codex login	登录
codex logout	退出
codex app	启动桌面应用
/init	初始化
/model	切换模型
/compact	压缩上下文
/new	开启新会话
/plan	开启计划模式
/ask	仅提问不执行
/settings	打开设置

七、在 App 端使用 Codex

1. 启动

App 适合两类人：一类是不想一直待在终端里，另一类是希望同时看项目文件、对话记录和修改内容。

打开方式有两种，一种是直接双击桌面Codex的图标，一种是执行命令codex app

选择你的偏好后，点击继续，也可以点击跳过，后面再配置。

由于我之前登录过Codex CLI，所以 App 这边不用登录就可以直接使用了。后面的IDE 插件也是一样的道理，同一套登录状态可以复用。

2. 基础使用

点击项目，然后选择使用现有文件夹，找到刚刚上面制作贪吃蛇的那个文件夹test

可以看到刚刚的对话都已经加载进来了。这一点很关键：Codex 不是只能单次问答，它会围绕一个项目持续工作。

点击右上角的切换文件树，可以看到当前目录下的文件。点击具体文件后，左侧可以预览内容，也可以直接在文件里做注释，让 Codex 按你的反馈继续修改。

这时候它就不只是“问答机器人”了，而是能围绕项目上下文继续修改。

右下角的设置里面还可以查看剩余额度。轻度使用一般够用，但额度策略会变化，最终以客户端显示为准。

八、在云端使用 Codex

云端版适合处理已经放到 GitHub 上的项目。你可以把它理解成：本地 Codex 是在你电脑上干活，云端 Codex 是连到你的 GitHub 仓库里干活。

如果你已经有 GitHub 仓库，可以直接跳到“连接 Codex 到 GitHub”。下面这段是从零创建仓库的完整流程。

1. 初始化 Git 仓库

打开终端输入命令cd d: est

然后执行以下命令：

git init

执行完成后，可以看到 App 上面多了一个提交的按钮。

点击提交，在提交消息里填一段提交说明，然后点击继续，这样我们的修改记录就保存了。

这里不要学某些老项目，全员提交信息都是update，多年以后查记录，自己都想给自己一拳。

2. 创建 GitHub 远程仓库

接下来我们打开 GitHub，创建一个名为test的远程仓库。

创建完成后可以看到这些提示。

我们在刚刚打开的终端执行如下命令。注意把下面的地址替换成你自己的仓库地址：

git remote add origin https://github.com/ailot/test.git

执行完成后，可以看到 App 上面的推送按钮变成可点击的了。

在刚才的终端继续执行命令。

git branch -M main

git push -u origin main

在执行完第二条命令后，会提示你登录 GitHub。

选择浏览器登录Sign in with your browser，出现这个界面就表示成功了。

终端同样可以看到推送成功的日志。

GitHub 仓库也能够看到我们刚刚推送的文件。

3. 连接 Codex 到 GitHub

打开
https://chatgpt.com/codex/cloud，点击`连接到 GitHub`

点击继续 GitHub

选择Authorize进行授权。

然后我们进入云端 Codex 了。

按照如下步骤配置远端代码仓库。

选择刚刚我们在 GitHub 上面创建的test仓库，然后点击Install & Authorize，输入密码授权。

刷新页面，可以看到我们的test仓库已经在 Codex 里面了。

我让它看一下这是个什么项目。

这一步很适合用来测试 Codex 有没有看懂仓库。别一上来就让它“重构整个系统”，先问它“这是个什么项目”。

输完提示词，点击发送，可以看到它在下面创建了一个任务在执行。

点击进去可以看到具体的执行结果。

九、IDE 端使用 Codex

IDE 插件适合日常写代码的人。它最大的价值不是“再开一个聊天窗口”，而是直接读取当前项目上下文，在你写代码的位置帮你改。

这就很适合那种写到一半突然卡住的时刻：脑子说我懂了，手说你放过我。

打开VSCode，然后安装Codex IDE 插件，具体操作如下：

安装完成后重启 VS Code，然后打开刚刚我们在 D 盘的test文件夹，同样可以看到刚刚的对话都已经加载进来了。

后面还想怎么改，可以直接在对话框里面指挥。

我建议你从这几个场景开始用：

• 让它解释当前文件的作用
• 选中一段代码，让它重构或补注释
• 把报错信息贴进去，让它定位问题
• 让它给某个函数补单元测试

IDE 插件的优势是上下文更近，适合边写边改；CLI 的优势是执行力更强，适合让它完整跑一个任务。

简单说：IDE 插件适合边写边问，CLI 适合直接派活。

十、进阶用法

1. AGENTS.md 配置文件

在项目根目录创建一个 AGENTS.md 文件，告诉 Codex 你的项目规范。这个文件很重要，它相当于给 Codex 写一份”项目说明书”。

# 项目规范

- 语言：Python 3.11+
- 代码风格：PEP 8
- 测试框架：pytest
- 注释：中文注释

如果你是新手，可以先用下面这个更完整的模板：

# AGENTS.md

## 项目说明

这是一个 Python 项目，主要用于练习小游戏开发。

## 开发规范

- 使用 Python 3.11+
- 代码保持简单，优先可读性
- 新增功能时同步更新 README
- 修改代码后尽量运行测试或启动程序验证

## 交互偏好

- 先解释修改思路，再改代码
- 涉及删除文件、重构目录、安装依赖时先询问
- 回复使用中文

## Codex 特定配置

- 权限模式：自动审查（关键操作需确认）
- 默认模型：qwen3.6-plus（或 gpt-5.5）
- 技能路径：./.codex/skills（如有）

这样 Codex 后面生成代码、跑命令、解释问题时，会更贴合你的项目习惯。

AI 编码工具不是不会干活，它是不知道你的项目规则。AGENTS.md 就是把规则先写清楚，省得每次都重新说明。

2. 常用场景

Codex 不只是写代码，还能：

• • 代码重构，让它优化现有代码。
• • 写单元测试，给函数补测试用例。
• • 修复 Bug，把报错信息丢给它。
• • 代码审查，让它 review 你的代码。

3. 安全模式

Codex 有几种常见权限模式，不同版本界面里的中文翻译可能略有差异，但核心思路差不多：

• • 默认权限，只给建议，适合你想先看方案。
• • 自动审查，可以自动编辑文件，但关键操作会请示你。
• • 完全访问，权限更大，可以自动执行更多操作。

新手推荐配置：

• • 日常使用开"自动审查"模式。
• • 删除文件、安装依赖、推送代码必须手动确认。
• • 批量重构时，先让他制定方案，确认后再执行。

不要一开始就完全放权，等你熟悉了 Codex 的行为模式再逐步开放权限。

十一、接入国内大模型

国内很多平台提供了 OpenAI 兼容的 API，只要改一下配置和环境变量，就有机会让 Codex 使用国内模型。

但这里要先说清楚：OpenAI 兼容不等于 Codex 一定可用。

Codex 新版本更依赖 Responses API，如果平台只兼容 Chat Completions，可能会出现连得上但跑不起来的情况。

1. 支持的平台

• 通义千问，阿里系，稳定性好。
• 硅基流动，聚合平台，模型多。
• 智谱 AI，国产大模型，中文能力强。
• 其他提供 OpenAI 兼容 API 的平台。

本次我们选择阿里百炼的大模型。

为什么选它？主要是它这边适配情况相对更好，折腾成本低一点。

2. 配置方法

打开 App 的设置，进入配置文件进行修改。

将config.toml里面的配置改成下面内容：

model = "qwen3.6-plus"
model_provider = "bailian"


name = "bailian"
env_key = "BAILIAN_API_KEY"
base_url = "https://dashscope.aliyuncs.com/compatible-mode/v1"

然后在本地配置环境变量BAILIAN_API_KEY，具体步骤如下：

选中此电脑，点击右键，选择属性。

配置相关环境变量信息。

然后重启 Codex，配置即可生效。

3. 验证国内模型是否生效

配置完成后，用这个简单任务测试一下：

用中文写一个 Python 脚本，打印"Hello 国内大模型"，然后运行它。

如果Codex能理解中文指令、生成代码、成功运行，说明配置生效了。

十二、常见问题

大家安装和使用Codex的过程中，未必是一帆风顺的，小灰在此列出几个Codex使用的常见问题和解决方案：

1. Codex 登录失败

问题表现：

浏览器授权后回到终端，提示失败。

解决方法：

1. 1. 检查网络连接。
2. 2. 清除浏览器缓存重试。
3. 3. 换用 API Key 方式。
4. 4. 执行 codex logout 后重新登录。

2. codex 相关命令找不到

问题表现：

提示错误 codex: command not found

解决方法：

# 重新安装
npm install -g @openai/codex

# 检查 npm 全局路径
npm config get prefix

确保 npm 全局路径在你的 PATH 里。

Windows 用户如果 PATH 配置很麻烦，建议先用 App，不要卡在 CLI 环境上。

3. 接入国内模型时配置了环境变量，仍然提示找不到

解决方法：

Windows 用户配置完环境变量后，需要重启 Codex（完全退出再打开），如果还不行，试试重启电脑。

注意：由于 Codex 新版本使用 Responses API，不支持 wire_api = "chat" 配置，很多大模型厂家的 API 还没适配，所以能选择的模型不多。

因此大家能跑就用，跑不起来就换平台。

其中阿里百炼支持Responses接口的模型如下：

qwen3-max
qwen3-max-2026-01-23
qwen3.6-plus
qwen3.6-plus-2026-04-02
qwen3.5-plus
qwen3.5-plus-2026-02-15
qwen3.6-flash
qwen3.6-flash-2026-04-16
qwen3.5-flash
qwen3.5-flash-2026-02-23
qwen3.6-35b-a3b
qwen3.5-397b-a17b
qwen3.5-122b-a10b
qwen3.5-27b
qwen3.5-35b-a3b
qwen-plus
qwen-flash
qwen3-coder-plus
qwen3-coder-flash
qwen3-coder-next

十三、写在最后

好了，以上我们介绍了Codex的基本概念、安装过程、使用方法、进阶应用等等。建议大家一边阅读，一边进行实操，这样可以加深印象。

如果你是第一次使用 Codex，建议不要一上来就让它”开发一个完整系统”，而是先拿真实小任务练手：修一个报错、给旧代码补注释、给函数补测试、把脚本改成命令行工具。

AI 编码工具最适合从小任务开始磨合。你越清楚自己要什么，它越容易给你稳定结果。

说到底，工具没有绝对的好坏，只有合不合适。真正重要的不是站队，而是把 AI 编码工具放进你的真实工作流里，让它帮你少写重复代码、少查低级错误。

正在阅读这篇文章的朋友，你有在使用 Codex 吗？欢迎在留言区聊一聊你的体验。