真实配置 | 前端开发如何高效配置 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 创建它。用文本编辑器打开，粘贴以下前端友好的保守型配置：
# 审批策略：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 文件。必须包含以下内容：
- 技术栈：准确列出真实的框架、构建工具、样式方案和包管理器。
- 常用命令：提取出真实的 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. 下载与安装
- 下载：前往项目的 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 结对编程搭档！
本文由 AI图鉴自动抓取并翻译，版权归原作者所有；如需查看原文请点下方链接。
How efficiently do you configure the Codex desktop? Guide on best practices and hole avoidance
Background
As a front-end development, have you ever experienced a situation where an AI can write your code, instead of a pnpm in your project; or a component that is written that does not fit your code code; or an operation that messes up the project environment.
Actually, the key to Codex's good use is whether the configuration is enough to understand your project. Official best practices point out that many quality issues are in fact environmental problems.
This paper takes you to complete the entire configuration of the Codex desktop, which evolves from an "Auto-Completion that writes code" to a true front-end collaborator.
Step 1: General user-level configuration (completed in Settings interface)
Opens the Cordex desktop end, clicking on Settings, the lower left corner, to enter the General page.
- Default missions: recommended to keep it open.
- Full access: keep it closed (or on a temporary basis, as required).
The logic behind this: this corresponds to the bottom sandbox and approval strategy. For front-end development, we recommend a combination of on-request and workspace-write. Thus, Codex can regularly modify your project documents, but you will be asked for permission before carrying out high-risk operations (e.g. access to the external catalogue of the project) to balance safety and efficiency.
Step 2: Edit global AGENTS.md (user level)
This is the most leveraged step! This document corresponds to Codex's “default personality”, which will be read as a global instruction for all projects.
File path: ~/.codex/AGENTS.md
Operating entry: The Codex entry is found on the Settings Personalization page, clicking on the editor.
• Content reference (global personal rules):
# Global personal rules — Code of Conduct for Codex
- Answer or comment first in Chinese.
- Thinking in Chinese.
- To comply strictly with the requirements and not to comply with them, even if there is a need for them, please list them before they are finalized.
Step 3: Configure user-level config.toml
If AGENTS.md is a code of conduct, config.toml is a physical engine. It determines models, the intensity of reasoning and the boundaries of security.
File path:
- macOS / Linux: ~/.codex/config.toml
- Windows: %USERPROFILE%\.codex\config.toml
You can start it directly at the terminal mkdir-p ~/.codex & & touch ~/.codex/config.toml. Open with a text editor and paste the following front-end friendly conservative configuration:
# Approving policy: On-request indicates that you will be asked before taking high-risk operations (e.g. by visiting out-of-project documents).
approval_policy = "on-request"
# Sandbox mode: workspace-write allows Codex to read and write freely in the current project area, but cannot touch the outside files.
sandbox_mode = "workspace-write"
# Online search: Codex is allowed to use cache web search results to support the answer.
web_search = "cached"
# Intensity of reasoning: Mediam is the recommended balance between complex front-end tasks and response speed.
model_reasoning_effort = "medium"
• Validation of validity:
Ask it in the dialogue box: Check your currently valid configuration file, what's the approval policy and Sandbox mode, respectively?
If it returns the value you just filled in, the configuration is loaded successfully.
Step 4: Generate Project Level AGENTS.md
The best way to save effort is for Codex to scan and generate itself.
Ensure that you send the following Prompt under specific projects (e.g. xx-project):
"Please scan the root directory structure of the current project and other configuration files such as package.json. Help me generate a unique AGENTS.md file in the project root directory based on scanning results. The following must be included:
- Technical stacks: an accurate description of the true framework, construction tools, style programmes and packages manager.
- Common commands: extract real dev, build, test, lint.
- Code engagement: summary based on the existing code structure (e.g. component code, name code).
- Prohibition matters: for example, not to add any new reliance, not to modify a particular document, etc.
- Completion criteria: e.g. type checks must be passed, build must be successful, etc.
Please list your scan results and plans, and then write the contents directly to the AGENTS.md in the root directory.
Codex will analyze your code library and generate files. If certain rules are not in line with team habits (e.g., the package manager is wrong), then just tell it to change.
A quality AGENTS.md should contain:
- Project fingerprints: framework, construction tools, style schemes, etc.
- Develop command: real dev/test command, not allow AI to guess.
- Code Code: Directory structure, name code.
- A secure red line: a no-go zone.
• Validation of validity:
Ask it: What are the commonly used orders and prohibitions in AGENTS.md, the current project? It's a success if it's accurate.
How do you verify the configuration?
Validation of AGENTS.md Entry into force: Ask it in Codex: What are the commonly used commands and prohibitions in AGENTS.md of the current project? If it can be accurately repeated, it will indicate that the configuration is in effect.
Step 5: Configure MCP Connections
MCP used to connect external tools (e.g. browsers, drafts), Codex natives cannot see the page after rendering, and MCP (Model Context Protocol) can compensate for this blind zone.
Playwright, for example, gives Codex a front-end visual authentication capability.
Modify profile (both user and project levels):
[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest"]
Before installation:
Modify the config.toml file to:
[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest"]
⚠️ Pipe = "stdio" field. Otherwise the Codex desktopend will report unrecognized coordination setting warnings. Codex defaults to automatically recognize as stdio by command field.
How do you verify the configuration?
Ask it in Codex: Please call Playwright MCP and open https://www.baidu.com, and take a look at this to see if it can be successfully returned:
Step six: Hanish (optional enhancements)
If you prefer an all-Chinese interface experience, it is recommended to use open source projects. This is a Cordex Chinese Chinese starter designed for Mac and Windows, without modifying the official files of Cordex, and secure and stable.
Method of operation:
1. Downloading and installation
- Download: Go to the Releases page of the project and download the corresponding compressor according to your Mac chip:
Apple Silicon (M1/M2/M3/M4). Download Codex-Zh-Launcher-macOS-arm64.zip.
- Intel chip: Download Codex-Zh-Launcher-macOS-x64.zip.
- Installation: Unpression ZIP file to drag the unpressure application into the Application folder.
2. Initial start-up and security settings
When opened for the first time, MacOS may be prevented by security restrictions.
Method of operation: In the Application folder, right-click on the application icon and select Open. If you are still blocked, go to System Settings > Privacy and Security, find a hint at the bottom of the page and click "Stand to Open."
3. Handanization and activation of Codex
Make sure Codex is completely out.
And then run the "Codex Han status enhancement tool" just installed.
Waits for the tool to automatically detect Cordex and click "Handled and Start." Tools automatically start Codex in Chinese.
When started, you can see and choose Chinese (China) in Codex settings.
⚠️ This tool loads the Chinese interface through the starter, and it is suggested that it will all be used to start Codex to get a full Chinese menu experience.
We're going to the hole.
MacOS soft link error
In the configuration, if you have an initialized sandbox that is similar to the symlinked writeable roots are not reported, this is a miscalculation by the macOS bottom mechanism.
Solutions: Add this to the bottom of ~/.codex/config.toml and restart App:
allow_symlinked_codex_home = true
Summary
The core idea of this configuration is to use AGENTS.md to fix personal habits, project-level AGENTS.md to bind technology vaults, to draw secure boundaries with config.toml, and MCP to supplement the most needed “visional authentication” capability at the front end.
When the configuration is complete, try to get it to "write a component and screen-check it," and you'll find that it has a qualitative leap. I hope you all have a safe front.
Auto-fetched and translated by AI Atlas. All rights belong to the original author.