“把重复的折腾交给工具，把判断留给自己。”

🚀 前言

最近把 Codex 当成日常开发助手用了起来，感觉它和普通聊天机器人最大的区别是：它不是只给建议，而是可以在项目目录里读文件、改代码、跑命令、看报错、继续修复，最后把结果交给你确认。

这篇文章记录一份 Codex 上手配置，从安装、登录、用户配置、个性化设置，到插件、Skills、MCP、AGENTS.md 项目规则都整理一下。以后换电脑、重装系统或者给新项目接入 Codex，可以直接照着这篇走。

本文写于 2026-06-06。Codex 变化比较快，安装命令、模型名称、插件入口以官方文档为准：
Codex Quickstart / Codex CLI / Codex Plugins

🧭 Codex 是什么

Codex 是 OpenAI 面向软件开发的编码智能体，可以帮助我们完成这些工作：

• 阅读和解释项目代码
• 新增功能、修 bug、补测试
• 运行本地命令并根据输出继续修改
• 做代码审查，找高风险问题
• 通过插件、MCP、Skills 连接浏览器、GitHub、文档、设计稿等外部工具
• 在 CLI、IDE、桌面 App、Web/Cloud 等不同入口里工作

我的理解是：ChatGPT 更像问答和讨论入口，Codex 更像可以进入项目现场一起干活的搭档。

📦 安装教程

macOS / Linux 安装 CLI

官方提供了安装脚本，终端执行：

1

curl -fsSL https://chatgpt.com/codex/install.sh | sh

安装完成后检查版本：

1

codex --version

如果命令找不到，一般是安装目录没有进入 PATH。可以先重新打开终端，还是不行再检查 ~/.local/bin 是否在 PATH 中。

Windows 安装

Windows 可以优先使用 Microsoft Store / winget：

1

winget install Codex -s msstore

也可以使用官方 PowerShell 安装脚本：

1

irm https://chatgpt.com/codex/install.ps1 | iex

如果项目主要放在 WSL2 里，建议在 WSL2 内也安装 CLI，这样 Codex 读写路径、运行依赖、执行测试都会更自然。

打开桌面 App

安装 CLI 后，可以在项目目录下执行：

1

codex app .

如果本机还没有安装 Codex 桌面 App，这个命令会进入安装流程；如果已经安装，就会直接用当前目录作为工作区打开 App。

IDE 扩展

如果平时主要用 VS Code、Cursor、Windsurf 这类 VS Code 兼容编辑器，可以安装 Codex IDE 扩展。扩展和 CLI 使用同一套 Codex agent，也共享 ~/.codex/config.toml 里的模型、权限、MCP 等配置。

常用入口：

• 在编辑器扩展市场搜索 Codex
• 登录后打开侧边栏聊天
• 选中代码或打开文件后直接提问
• 用 @文件名 把文件加入上下文
• 用 /review、/status、/cloud 等命令切换工作流

🔐 登录与认证

Codex 支持两种主要登录方式：

第一次使用 CLI 时可以执行：

1

codex login

默认会打开浏览器完成 ChatGPT 登录。如果在远程服务器、SSH、无桌面环境中使用，可以试试设备码登录：

1

codex login --device-auth

登录状态会缓存在本机。需要排查登录问题时，可以运行：

1

codex doctor

API Key 登录思路

如果使用 API Key，先在 OpenAI Platform 创建 key，然后按 Codex 登录流程选择 API Key，或在自动化环境中通过环境变量传入。

注意不要把 API Key 写进仓库，不要提交 .env，也不要把 ~/.codex/auth.json 发给别人。这个文件可能包含访问令牌，应当像密码一样保护。

⚙️ 用户配置教程

Codex 的用户级配置文件是：

1

~/.codex/config.toml

项目级配置可以放在：

1

项目根目录/.codex/config.toml

项目级 .codex/ 配置只会在你信任该项目时加载。日常建议：个人偏好写到用户配置，项目规则写到 AGENTS.md 或项目级配置。

配置优先级

Codex 大致按下面顺序读取配置，越靠前优先级越高：

1. CLI 参数和 --config 临时覆盖
2. 项目内 .codex/config.toml
3. 使用 --profile 选择的 profile 配置
4. 用户级 ~/.codex/config.toml
5. 系统级配置
6. 内置默认值

推荐基础配置

下面是一份适合个人开发的起步配置，可以按需复制到 ~/.codex/config.toml：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

model = "gpt-5.5"
model_reasoning_effort = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached"
personality = "friendly"
cli_auth_credentials_store = "keyring"

[features]
shell_snapshot = true
hooks = true
multi_agent = true

说明：

• model：默认模型。官方当前推荐一般任务从 gpt-5.5 开始。
• model_reasoning_effort：推理强度。普通任务用 medium，复杂重构再开 high。
• approval_policy：权限确认策略。on-request 比较适合日常开发。
• sandbox_mode：沙盒范围。workspace-write 允许 Codex 在当前工作区内修改文件。
• web_search：默认使用缓存搜索，需要最新信息时可以临时加 --search。
• personality：沟通风格，可选 friendly、pragmatic、none 等。
• cli_auth_credentials_store：建议用系统钥匙串/凭据管理器保存登录信息。

临时覆盖配置

有时候不想改全局配置，只想当前这次任务换模型或权限：

1
2
3
4

codex --model gpt-5.5
codex --sandbox read-only
codex --ask-for-approval on-request
codex --search "查一下最新文档并更新 README"

如果只想临时覆盖某个配置项：

1

codex -c model_reasoning_effort="high" "帮我审查这次重构"

🎨 个性化设置

主题和终端体验

CLI 里可以输入：

1

/theme

选择喜欢的终端主题。保存后会写入 ~/.codex/config.toml。

Zsh 自动补全可以这样加：

1

eval "$(codex completion zsh)"

如果遇到 compdef 相关报错，在 .zshrc 前面加：

1

autoload -Uz compinit && compinit

权限模式

Codex 的权限控制很重要，建议先理解再放开：

在 CLI 会话里可以用：

1

/permissions

随时切换。

Memories

如果想让 Codex 记住稳定偏好、常用工作流、项目习惯，可以开启 Memories：

1
2

[features]
memories = true

注意：团队规则、必须遵守的安全约束、项目构建命令，不建议只放在 Memories 里，应该写进仓库的 AGENTS.md，这样更稳定。

📄 AGENTS.md 项目规则

AGENTS.md 是我最推荐先配置的部分。它相当于给 Codex 的项目说明书，适合记录：

• 项目是什么
• 常用命令
• 构建、测试、预览方式
• 安全规则
• 不要改哪些目录
• 提交信息格式
• 文章、组件、接口等项目约定

下面是我当前的全局 AGENTS.md 示例，位置在 ~/.codex/AGENTS.md：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

## Safety Rules
禁止批量删除文件或目录。
不要使用：
- `del /s`
- `rd /s`
- `rmdir /s`
- `Remove-Item -Recurse`
- `rm -rf`
需要删除文件时，只能一次删除一个明确路径的文件。
正确示例：
`Remove-Item "c:\path\to\file.txt"`
如果需要批量删除文件或目录，必须停止操作，并向用户请求，让用户手动删除。

## AI Coding Discipline
- 编码前先思考：需求有歧义时先说明假设；猜测有风险时先询问用户；涉及取舍时说明影响。
- 简洁优先：使用能解决问题的最小改动，不添加未要求的功能、抽象、配置项或扩展性。
- 精准修改：只修改和用户请求直接相关的文件和代码行，不做无关重构、格式化、重命名或清理。
- 目标可验证：修 bug 时尽量先复现再修复；改行为时视风险添加或更新测试；完成前运行最相关的验证。
- 尊重现有项目：遵循已有代码风格、目录结构和工具链；不引入新依赖，除非必要并得到用户同意。
- 不覆盖、回滚或删除用户已有改动，除非用户明确要求。

## 项目处理
- 处理git项目时，先拉取远端项目。
- 若项目中有AGENTS.md则进行读取，若没有则读取项目后在根目录创建AGENTS.md并写入项目内容。
- 提交推送时，使用中文推送信息。
- 推送完成后若有相关编译，请关闭相关编译。
- 每次对项目改动后，则对AGENTS.md进行进一步完善。

Codex 会从仓库根目录一路读取到当前工作目录，越靠近当前目录的规则越具体。如果某个子项目有特殊要求，可以在子目录再放一个 AGENTS.md 或 AGENTS.override.md。

🧩 Skills：把常用流程做成技能

Skills 适合封装“经常重复的一套做事流程”。比如：

• 写博客文章
• 修 GitHub Actions
• 处理 PR Review 评论
• 生成 PPT
• 分析表格
• 生成图片素材

一个 Skill 本质上是一个目录，里面至少有 SKILL.md：

1
2
3
4
5
6
7
8
9

---
name: blog-writer
description: 当需要为 Hugo 博客新增或修改中文文章时使用。
---

1. 先读取 AGENTS.md 和现有文章风格。
2. 新文章使用 Page Bundle：content/post/<slug>/index.md。
3. front matter 使用 YAML。
4. 完成后运行 hugo -D 验证构建。

常见保存位置：

创建 Skill 可以直接让 Codex 帮忙：

1

$skill-creator

安装已有的精选 Skill 可以用：

1

$skill-installer

在 CLI / IDE 中也可以用 /skills 或输入 $ 显式调用某个 Skill。

🔌 插件 Plugins

Skills 更像“工作流说明”，Plugins 则是更完整的可安装包。一个插件可以包含：

• Skills
• App 连接器
• MCP 服务器配置
• Hooks
• 图标、元数据、市场入口

安装插件

桌面 App 中可以打开 Plugins 页面，浏览和安装插件。

CLI 中可以进入 Codex 后输入：

1

/plugins

安装后，新开一个线程，再直接描述任务即可。例如：

1

用 Browser 插件打开本地 localhost:1313，帮我检查 Hugo 页面是否正常。

或者显式指定插件/技能：

1

@browser 打开 http://localhost:1313

关闭插件

如果插件装了但暂时不用，可以在 ~/.codex/config.toml 中关闭：

1
2

[plugins."gmail@openai-curated"]
enabled = false

修改配置后重启 Codex。

创建自己的插件

如果只是个人流程，先做 Skill 就够了；如果要分发给其他人、打包多个 Skills、附带 MCP 或 App 集成，再考虑插件。

可以用内置工具脚手架：

1

@plugin-creator

一个最小插件大概长这样：

1
2
3
4
5
6

my-first-plugin/
├── .codex-plugin/
│   └── plugin.json
└── skills/
    └── hello/
        └── SKILL.md

plugin.json 示例：

1
2
3
4
5
6

{
  "name": "my-first-plugin",
  "version": "1.0.0",
  "description": "Reusable workflow examples",
  "skills": "./skills/"
}

🔗 MCP：连接外部工具和数据

MCP（Model Context Protocol）可以把外部工具接给 Codex，比如：

• OpenAI Docs：查官方文档
• Context7：查开发库文档
• Figma：读取设计稿
• Playwright / Chrome DevTools：控制浏览器做测试
• Sentry：查看线上错误
• GitHub：处理 PR、Issue、仓库信息

用 CLI 添加 MCP

以 Context7 为例：

1

codex mcp add context7 -- npx -y @upstash/context7-mcp

进入 Codex 后可以用：

1

/mcp

查看当前可用的 MCP 服务。

用 config.toml 配置 MCP

也可以直接写配置：

1
2
3

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

HTTP 类型 MCP 示例：

1
2
3

[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"

如果 MCP 会访问私有数据，一定要先想清楚权限、token 和数据范围，不要把凭据写死进仓库。

🧪 日常使用方式

解释项目

1

codex "先阅读这个项目，说明目录结构、启动方式和主要功能"

修改代码

1

codex "修复登录页在移动端按钮文字换行的问题，完成后运行相关测试"

只做代码审查

1

/review

可以审查未提交内容、某个 commit，或者和基础分支对比。

非交互执行

适合脚本或简单任务：

1

codex exec "检查 README 中是否有过期命令，并给出修改建议"

继续上次会话

1
2

codex resume
codex resume --last

如果一个问题没修完，或者刚刚中断了，resume 很好用。

✅ 我的推荐配置流程

如果是第一次使用，我建议按这个顺序来：

1. 安装 CLI 和桌面 App
2. codex login 登录 ChatGPT
3. 写好 ~/.codex/config.toml
4. 给常用项目补 AGENTS.md
5. 从 Read-only / workspace-write 权限开始用
6. 熟悉 /status、/permissions、/review、/plugins、/mcp
7. 把重复流程整理成 Skill
8. 需要外部工具时再接 MCP 或插件

对我来说，Codex 最舒服的使用方式不是“让它完全自动干完所有事”，而是让它承担读取、修改、验证、查资料这些耗时步骤，而我负责给目标、定边界、看取舍、验结果。

📚 参考资料

• Codex Quickstart
• Codex CLI
• Codex Configuration
• Codex Authentication
• AGENTS.md 指南
• Codex Skills
• Codex Plugins
• Codex MCP