目录

七、最佳实践

7.1 写好 Prompt

7.2 将重复指导移入 AGENTS.md

7.3 按场景选择权限

7.4 用 MCP 连接外部系统

7.5 复杂任务先规划

八、故障排除

九、官方资源

---

七、最佳实践

7.1 写好 Prompt

高质量 prompt 包含四个要素：

1. Goal（目标） ：要完成什么

2. Context（上下文） ：相关文件、约束条件

3. Constraints（约束） ：不能做什么、必须遵守的规则

4. Acceptance（验收） ：如何验证完成

对于复杂或高风险任务，先让 Codex 输出计划（Plan mode），确认后再执行。

7.2 将重复指导移入 AGENTS.md

不要把规则每次都写在 prompt 里。构建命令、测试要求、代码风格、安全边界等，统一写入 AGENTS.md，Codex 会自动读取。

7.3 按场景选择权限

新手从 read-only 开始，熟悉后逐步过渡到 workspace-write（默认）。danger-full-access 仅在完全受控的环境中使用。

7.4 用 MCP 连接外部系统

把需要反复查询的外部信息源（如 API 文档、设计系统、监控面板）通过 MCP 接入 Codex，减少手动提供上下文的负担。

7.5 复杂任务先规划

对于涉及多文件、多步骤的任务，先让 Codex 输出执行计划，人工审阅后再批准执行。这能显著降低“做错方向”的风险。

八、故障排除

CLI 启动异常：在 Windows 上，运行 codex doctor 诊断启动、连接和性能问题。

国内登录问题：桌面端 OAuth 登录可能受限。替代方案包括手动配置 auth.json，或使用 CC Switch / Codex++ 等社区工具完成认证。

扩展找不到：在 VS Code 扩展市场搜索时，确保使用 Codex 作为关键词，并认准 OpenAI 官方发布者标识。

九、官方资源

• 官方文档：developers.openai.com/codex/ — 最权威的起点，涵盖配置、安全、企业部署等完整分区

• GitHub 仓库：github.com/openai/codex — CLI 开源仓库（Apache-2.0），可查看源码、发布说明和 changelog

• 帮助中心：help.openai.com — 套餐、账号、故障排除

• 中文社区手册：github.com/freestylefly/CodexGuide — 社区维护的中文指南，涵盖 CLI、AGENTS.md、MCP、排障等内容