拿到 codex 第一步

review44543
4 阅读6分钟

真实配置 | 前端开发如何高效配置 Codex 桌面端？附最佳实践与避坑指南

背景

作为前端开发，你是否遇到过这样的情况：让 AI 帮你写代码，它却用了 npm 而不是你项目里的 pnpm；或者写出来的组件不符合你们的代码规范；或者一顿操作后把项目环境搞乱了。

其实，Codex 用得好不好的关键，在于配置是否足够“懂”你的项目。官方的最佳实践指出，很多质量问题其实是环境设置问题。

本文将手把手带你完成 Codex 桌面端的全套配置，让它从“会写代码的自动补全”进化成真正懂你项目的前端协作者。

第一步：通用用户级配置（在 Settings 界面完成）

打开 Codex 桌面端，点击左下角的设置（Settings），进入 General 页面。

  • Default permissions：建议保持开启。
  • Full access：保持关闭（或按需临时开启）。

image.png

背后的逻辑：这对应了底层的沙箱与审批策略。对于前端开发，我们推荐使用 on-request 和 workspace-write 的组合。这样 Codex 能正常修改你的项目文件，但在执行高风险操作（如访问项目外目录）前会先征求你的同意，兼顾安全与效率。

第二步：编辑全局 AGENTS.md（用户级）

这是杠杆率最高的一步！这个文件相当于 Codex 的“默认人格”，会作为所有项目的全局指令被读取。

文件路径：~/.codex/AGENTS.md 操作入口：在 Settings 的 Personalization 页面，找到 Codex instructions，点击进入编辑。

image.png

image.png

✨ 内容参考（全局个人规则）：

# 全局个人规则——给 Codex 的“行为准则”
- 回答或注释优先使用中文。
- 思考过程也用中文。
- 严格遵守需求，不要顺手修，即使有需要修的，请先列出来等确定后再执行。

第三步：配置用户级 config.toml

如果说 AGENTS.md 是行为准则，那么 config.toml 就是物理引擎。它决定了模型、推理强度以及安全边界。

文件路径：

  • macOS / Linux: ~/.codex/config.toml
  • Windows: %USERPROFILE%\.codex\config.toml

你可以直接在终端运行 mkdir -p ~/.codex && touch ~/.codex/config.toml 创建它。用文本编辑器打开，粘贴以下前端友好的保守型配置：

# 审批策略：on-request 表示在采取高风险操作前（如访问项目外文件）会先询问你。
approval_policy = "on-request"

# 沙箱模式：workspace-write 允许 Codex 在当前项目工作区内自由读写，但无法触碰项目外文件。
sandbox_mode = "workspace-write"

# 联网搜索：允许 Codex 使用缓存的网页搜索结果来辅助回答。
web_search = "cached"

# 推理强度：medium 是在复杂前端任务和响应速度之间的推荐平衡点。
model_reasoning_effort = "medium"

✅ 验证是否生效： 在对话框里问它：检查一下你当前生效的配置文件中，approval_policy 和 sandbox_mode 分别是什么？ 如果它返回了你刚填入的值，说明配置已成功加载。

第四步：生成项目级 AGENTS.md

最省力的办法是让 Codex 自己去扫描并生成。

确保你在具体项目下（比如 xxx-project），发送以下 Prompt：

“请扫描当前项目的根目录结构和 package.json 等配置文件。基于扫描结果，帮我在项目根目录生成一个专属的 AGENTS.md 文件。必须包含以下内容：

  1. 技术栈：准确列出真实的框架、构建工具、样式方案和包管理器。
  2. 常用命令：提取出真实的 dev、build、test、lint 命令。
  3. 代码约定：根据现有代码结构总结（如组件规范、命名规范）。
  4. 禁止事项：例如不要随意添加新依赖、不要修改特定文件等。
  5. 完成标准：例如类型检查必须通过、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"]

未安装之前：

image.png

修改 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，并帮我截个图看看，观察是否能成功返回截图：

image.png

第六步：汉化（可选增强）

🍎 如果你更喜欢全中文的界面体验，推荐使用开源项目 shibaweidu/codex-desktop-zh。这是一个专为 Mac 和 Windows 设计的 Codex 中文汉化启动器，不修改 Codex 的官方文件，安全稳定。

操作方法：

1. 下载与安装

  • 下载：前往项目的 Releases 页面，根据你的 Mac 芯片下载对应的压缩包：

    • Apple Silicon (M1/M2/M3/M4)：下载 Codex-Zh-Launcher-macOS-arm64.zip。
    • Intel 芯片：下载 Codex-Zh-Launcher-macOS-x64.zip。

  • 安装：解压 ZIP 文件，将解压出的应用拖拽到 “应用程序” 文件夹中。

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 结对编程搭档！

avatar
文章
阅读
粉丝