拿到 codex 第一步
英文标题：拿到 codex 第一步
别再让 AI 瞎猜你的项目环境了！从全局指令到项目规范，再到 MCP 视觉外挂，这是一份手把手教你调教 Codex 的前端专属配置指南。
3.2 KB
589 B
126.6 KB
70.9 KB
54.4 KB
24.5 KB
74.4 KB
1.4 KB
中文
真实配置 | 前端开发如何高效配置 Codex 桌面端？附最佳实践与避坑指南
背景
作为前端开发，你是否遇到过这样的情况：让 AI 帮你写代码，它却用了 npm 而不是你项目里的 pnpm；或者写出来的组件不符合你们的代码规范；或者一顿操作后把项目环境搞乱了。
其实，Codex 用得好不好的关键，在于配置 是否足够“懂”你的项目。官方的最佳实践指出，很多质量问题其实是环境设置问题 。
本文将手把手带你完成 Codex 桌面端的全套配置，让它从“会写代码的自动补全”进化成真正懂你项目的前端协作者 。
第一步：通用用户级配置（在 Settings 界面完成）
打开 Codex 桌面端，点击左下角的设置（Settings），进入 General 页面。
- Default permissions ：建议保持开启。
- Full access ：保持关闭（或按需临时开启）。
背后的逻辑 ：这对应了底层的沙箱与审批策略。对于前端开发，我们推荐使用 on-request 和 workspace-write 的组合。这样 Codex 能正常修改你的项目文件，但在执行高风险操作（如访问项目外目录）前会先征求你的同意，兼顾安全与效率。
第二步：编辑全局 AGENTS.md（用户级）
这是杠杆率最高的一步！这个文件相当于 Codex 的“默认人格”，会作为所有项目的全局指令被读取。
文件路径 ：~/.codex/AGENTS.md 操作入口 ：在 Settings 的 Personalization 页面，找到 Codex instructions，点击进入编辑。
✨ 内容参考（全局个人规则） ：
# 全局个人规则——给 Codex 的“行为准则”
- 回答或注释优先使用中文。
- 思考过程也用中文。
- 严格遵守需求，不要顺手修，即使有需要修的，请先列出来等确定后再执行。
第三步：配置用户级 config.toml
如果说 AGENTS.md 是行为准则，那么 config.toml 就是物理引擎。它决定了模型、推理强度以及安全边界。
文件路径 ：
- macOS / Linux:
~/.codex/config.toml - Windows:
%USERPROFILE%\.codex\config.toml
你可以直接在终端运行 mkdir -p ~/.codex && touch ~/.codex/config.toml 创建它。用文本编辑器打开，粘贴以下前端友好的保守型配置：
approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached"
model_reasoning_effort = "medium"
✅ 验证是否生效 ： 在对话框里问它：检查一下你当前生效的配置文件中，approval_policy 和 sandbox_mode 分别是什么？ 如果它返回了你刚填入的值，说明配置已成功加载。
第四步：生成项目级 AGENTS.md
最省力的办法是让 Codex 自己去扫描并生成 。
确保你在具体项目下（比如 xxx-project），发送以下 Prompt：
“请扫描当前项目的根目录结构和
package.json等配置文件。基于扫描结果，帮我在项目根目录生成一个专属的AGENTS.md文件。必须包含以下内容：
- 技术栈：准确列出真实的框架、构建工具、样式方案和包管理器。
- 常用命令：提取出真实的 dev、build、test、lint 命令。
- 代码约定：根据现有代码结构总结（如组件规范、命名规范）。
- 禁止事项：例如不要随意添加新依赖、不要修改特定文件等。
- 完成标准：例如类型检查必须通过、build 必须成功等。 请先列出你的扫描结果和计划，然后直接把内容写入到项目根目录的
AGENTS.md中。”
Codex 会分析你的代码库并生成文件。如果某些规则不符合团队习惯（比如包管理器写错了），直接告诉它修改即可。
✨ 一份高质量的 AGENTS.md 应包含 ：
- 项目指纹 ：框架、构建工具、样式方案等。
- 开发命令 ：真实的 dev/test 命令，不让 AI 瞎猜。
- 代码规范 ：目录结构、命名规范。
- 安全红线 ：绝对不能碰的禁区。
✅ 验证是否生效 ： 问它：当前项目的 AGENTS.md 里规定了哪些常用命令和禁止事项？ 能准确复述即成功。
✅ 如何验证配置生效？
验证 AGENTS.md 生效：在 Codex 里问它：当前项目的 AGENTS.md 里规定了哪些常用命令和禁止事项？，如果它能准确复述，说明配置已生效。
第五步：配置 MCP 连接
MCP 用于连接外部工具（如浏览器、设计稿），Codex 原生看不到渲染后的页面，而 MCP (Model Context Protocol) 能弥补这个盲区。
以 Playwright 为例，让 Codex 具备前端视觉验证能力。
修改配置文件（用户级或项目级均可）：
[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest"]
未安装之前：
修改 config.toml 文件，配置内容为：
[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest"]
⚠️ 避坑指南 ：这里千万不要加
type = "stdio"字段，否则 Codex 桌面端会报unrecognized configuration setting警告。Codex 默认通过command字段自动识别为 stdio 通信。
✅ 如何验证配置生效？
在 Codex 里问它：请调用 Playwright MCP 打开 https://www.baidu.com，并帮我截个图看看，观察是否能成功返回截图：
第六步：汉化（可选增强）
🍎 如果你更喜欢全中文的界面体验，推荐使用开源项目 shibaweidu/codex-desktop-zh。这是一个专为 Mac 和 Windows 设计的 Codex 中文汉化启动器，不修改 Codex 的官方文件，安全稳定。
操作方法 ：
1. 下载与安装
2. 首次启动与安全设置
首次打开时，macOS 可能会因安全限制阻止运行。
操作方法：在“应用程序”文件夹中，右键点击该应用图标，选择 “打开”。如果依然被阻止，请前往 “系统设置” > “隐私与安全性”，在页面底部找到相关提示，点击 “仍要打开” 即可。
3. 汉化并启动 Codex
确保 Codex 完全退出。
然后运行刚刚安装的 “Codex 汉化增强工具”。
等待工具自动检测到 Codex 后，点击 “汉化并启动”。工具会自动以中文模式启动 Codex。
启动后，你就可以在 Codex 的 设置 → General → Language 中看到并选择“中文（中国）”了。
⚠️ 这个工具通过启动器来加载中文界面，以后建议都通过它来启动 Codex，以获得完整的中文菜单体验。
💡 进阶避坑补充
macOS 软链接报错
在配置过程中，如果你遇到了类似 symlinked writable roots are not supported 的沙箱初始化报错，这是 macOS 底层机制导致的误判。
解决办法 ：在 ~/.codex/config.toml 底部加上这句配置，然后重启 App：
allow_symlinked_codex_home = true
📒总结
这套配置的核心思路是：用全局AGENTS.md 固化个人习惯，用项目级 AGENTS.md 约束技术栈，用 config.toml 划清安全边界，再用 MCP 补上前端最需要的“视觉验证”能力。
配置完成后，试着让它“写一个组件并截图验证”，你会发现它的靠谱程度会有质的飞跃。祝大家都能拥有一个省心的前端 AI 结对编程搭档！
English / 原文
真实配置 | 前端开发如何高效配置 Codex 桌面端？附最佳实践与避坑指南
背景
作为前端开发，你是否遇到过这样的情况：让 AI 帮你写代码，它却用了 npm 而不是你项目里的 pnpm；或者写出来的组件不符合你们的代码规范；或者一顿操作后把项目环境搞乱了。
其实，Codex 用得好不好的关键，在于配置 是否足够“懂”你的项目。官方的最佳实践指出，很多质量问题其实是环境设置问题 。
本文将手把手带你完成 Codex 桌面端的全套配置，让它从“会写代码的自动补全”进化成真正懂你项目的前端协作者 。
第一步：通用用户级配置（在 Settings 界面完成）
打开 Codex 桌面端，点击左下角的设置（Settings），进入 General 页面。
- Default permissions ：建议保持开启。
- Full access ：保持关闭（或按需临时开启）。
背后的逻辑 ：这对应了底层的沙箱与审批策略。对于前端开发，我们推荐使用 on-request 和 workspace-write 的组合。这样 Codex 能正常修改你的项目文件，但在执行高风险操作（如访问项目外目录）前会先征求你的同意，兼顾安全与效率。
第二步：编辑全局 AGENTS.md（用户级）
这是杠杆率最高的一步！这个文件相当于 Codex 的“默认人格”，会作为所有项目的全局指令被读取。
文件路径 ：~/.codex/AGENTS.md 操作入口 ：在 Settings 的 Personalization 页面，找到 Codex instructions，点击进入编辑。
✨ 内容参考（全局个人规则） ：
# 全局个人规则——给 Codex 的“行为准则”
- 回答或注释优先使用中文。
- 思考过程也用中文。
- 严格遵守需求，不要顺手修，即使有需要修的，请先列出来等确定后再执行。
第三步：配置用户级 config.toml
如果说 AGENTS.md 是行为准则，那么 config.toml 就是物理引擎。它决定了模型、推理强度以及安全边界。
文件路径 ：
- macOS / Linux:
~/.codex/config.toml - Windows:
%USERPROFILE%\.codex\config.toml
你可以直接在终端运行 mkdir -p ~/.codex && touch ~/.codex/config.toml 创建它。用文本编辑器打开，粘贴以下前端友好的保守型配置：
approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached"
model_reasoning_effort = "medium"
✅ 验证是否生效 ： 在对话框里问它：检查一下你当前生效的配置文件中，approval_policy 和 sandbox_mode 分别是什么？ 如果它返回了你刚填入的值，说明配置已成功加载。
第四步：生成项目级 AGENTS.md
最省力的办法是让 Codex 自己去扫描并生成 。
确保你在具体项目下（比如 xxx-project），发送以下 Prompt：
“请扫描当前项目的根目录结构和
package.json等配置文件。基于扫描结果，帮我在项目根目录生成一个专属的AGENTS.md文件。必须包含以下内容：
- 技术栈：准确列出真实的框架、构建工具、样式方案和包管理器。
- 常用命令：提取出真实的 dev、build、test、lint 命令。
- 代码约定：根据现有代码结构总结（如组件规范、命名规范）。
- 禁止事项：例如不要随意添加新依赖、不要修改特定文件等。
- 完成标准：例如类型检查必须通过、build 必须成功等。 请先列出你的扫描结果和计划，然后直接把内容写入到项目根目录的
AGENTS.md中。”
Codex 会分析你的代码库并生成文件。如果某些规则不符合团队习惯（比如包管理器写错了），直接告诉它修改即可。
✨ 一份高质量的 AGENTS.md 应包含 ：
- 项目指纹 ：框架、构建工具、样式方案等。
- 开发命令 ：真实的 dev/test 命令，不让 AI 瞎猜。
- 代码规范 ：目录结构、命名规范。
- 安全红线 ：绝对不能碰的禁区。
✅ 验证是否生效 ： 问它：当前项目的 AGENTS.md 里规定了哪些常用命令和禁止事项？ 能准确复述即成功。
✅ 如何验证配置生效？
验证 AGENTS.md 生效：在 Codex 里问它：当前项目的 AGENTS.md 里规定了哪些常用命令和禁止事项？，如果它能准确复述，说明配置已生效。
第五步：配置 MCP 连接
MCP 用于连接外部工具（如浏览器、设计稿），Codex 原生看不到渲染后的页面，而 MCP (Model Context Protocol) 能弥补这个盲区。
以 Playwright 为例，让 Codex 具备前端视觉验证能力。
修改配置文件（用户级或项目级均可）：
[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest"]
未安装之前：
修改 config.toml 文件，配置内容为：
[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest"]
⚠️ 避坑指南 ：这里千万不要加
type = "stdio"字段，否则 Codex 桌面端会报unrecognized configuration setting警告。Codex 默认通过command字段自动识别为 stdio 通信。
✅ 如何验证配置生效？
在 Codex 里问它：请调用 Playwright MCP 打开 https://www.baidu.com，并帮我截个图看看，观察是否能成功返回截图：
第六步：汉化（可选增强）
🍎 如果你更喜欢全中文的界面体验，推荐使用开源项目 shibaweidu/codex-desktop-zh。这是一个专为 Mac 和 Windows 设计的 Codex 中文汉化启动器，不修改 Codex 的官方文件，安全稳定。
操作方法 ：
1. 下载与安装
2. 首次启动与安全设置
首次打开时，macOS 可能会因安全限制阻止运行。
操作方法：在“应用程序”文件夹中，右键点击该应用图标，选择 “打开”。如果依然被阻止，请前往 “系统设置” > “隐私与安全性”，在页面底部找到相关提示，点击 “仍要打开” 即可。
3. 汉化并启动 Codex
确保 Codex 完全退出。
然后运行刚刚安装的 “Codex 汉化增强工具”。
等待工具自动检测到 Codex 后，点击 “汉化并启动”。工具会自动以中文模式启动 Codex。
启动后，你就可以在 Codex 的 设置 → General → Language 中看到并选择“中文（中国）”了。
⚠️ 这个工具通过启动器来加载中文界面，以后建议都通过它来启动 Codex，以获得完整的中文菜单体验。
💡 进阶避坑补充
macOS 软链接报错
在配置过程中，如果你遇到了类似 symlinked writable roots are not supported 的沙箱初始化报错，这是 macOS 底层机制导致的误判。
解决办法 ：在 ~/.codex/config.toml 底部加上这句配置，然后重启 App：
allow_symlinked_codex_home = true
📒总结
这套配置的核心思路是：用全局AGENTS.md 固化个人习惯，用项目级 AGENTS.md 约束技术栈，用 config.toml 划清安全边界，再用 MCP 补上前端最需要的“视觉验证”能力。
配置完成后，试着让它“写一个组件并截图验证”，你会发现它的靠谱程度会有质的飞跃。祝大家都能拥有一个省心的前端 AI 结对编程搭档！