你肯定遇到过这种情况想用 Codex 帮你写段代码、分析个日志或者自动化处理点杂活结果发现它要么“听不懂”你的需求要么执行起来总差那么点意思。比如你让它“帮我看看这个 API 接口”它可能真的只是“看看”然后告诉你“这是一个接口”而不是像你期望的那样自动去调用、测试并返回结果。问题出在哪很多时候不是 Codex 能力不行而是你和它之间还隔着一层“配置”的迷雾。配置听起来像是安装软件时那些枯燥的复选框和文本框。但在 Codex 这类智能体Agent的世界里配置远不止于此。它决定了 Codex 如何理解你的意图、拥有哪些权限、遵循什么规则以及最终以何种方式与你协作。一个精心配置的 Codex能从一个被动的问答机器转变为你工作流中一个主动、可靠、懂你习惯的“数字同事”。而一个未经配置的 Codex可能只是一个偶尔灵光、但更多时候需要你反复“调教”的初级助手。这篇文章不会是一份冷冰冰的官方文档翻译。我们将深入 Codex 的配置体系从“能用”到“好用”再到“如臂使指”。我会结合常见的工程实践告诉你哪些配置项是核心杠杆哪些“坑”可以提前避开以及如何通过配置让 Codex 真正融入你的开发习惯。1. 理解 Codex 的配置哲学从“通用助手”到“专属专家”在深入具体配置项之前我们需要先理解 Codex 配置设计的核心思想。它不是一个“一劳永逸”的设置而是一个分层、可组合、可演进的协作协议。1.1 配置的四个层级全局、用户、项目与托管Codex 的配置管理非常清晰遵循从通用到特定的优先级覆盖原则。理解这个层级是避免配置冲突和混乱的第一步。配置层级典型路径作用范围优先级适用场景托管配置由企业或团队管理员下发整个组织或团队最高强制执行安全策略、统一代码规范、禁用危险命令等。项目配置项目根目录下的.codex/config.toml单个代码仓库高定义项目特定的技术栈如 Python 3.9、依赖安装命令、测试运行方式、部署流程等。用户配置用户主目录下的~/.codex/config.toml用户的所有项目中设置个人偏好的默认模型、编辑器、常用技能Skills、审批策略等。全局默认Codex 应用内置所有用户最低提供最基础的、开箱即用的行为。合并规则很简单优先级高的配置会覆盖优先级低的配置。例如你在用户配置里设置了model gpt-4但在某个项目的配置里写了model claude-3-opus那么在这个项目里Codex 会使用 Claude 模型。这让你既能拥有个人工作习惯的基线又能为不同项目定制最合适的“专家”。实操建议我建议你先从用户级配置开始。这是你的“个人工作台”设置。在这里你可以设定一个你信任的、能力均衡的默认模型比如gpt-4o以及你常用的推理强度。这能确保你在打开任何新项目时都有一个可靠的基础体验。1.2 核心配置项模型、审批与工作方式打开 Codex App 的设置Cmd ,或Ctrl ,你会看到几个关键分类。我们挑最核心的讲模型选择 (model)这是 Codex 的“大脑”。选择哪个模型直接决定了它的代码生成、逻辑推理和问题解决能力。除了选择提供商如 OpenAI, Anthropic更要关注模型版本。gpt-4-turbo和gpt-4o在代码理解上可能差异不大但在长上下文处理和响应速度上各有千秋。不要盲目追求“最新最强”而要根据你的主要任务类型是快速原型还是深度调试和预算来选择。推理强度 (model_reasoning_effort)这个参数非常关键它控制着模型在给出答案前“思考”的深度。从minimal最快可能略过一些步骤到xhigh最慢但步骤最详尽。对于简单的代码补全low或medium可能就够了但对于复杂的系统设计或 Bug 排查设置为high能让 Codex 输出更严谨、更有步骤的解决方案。这是一个需要根据任务动态调整的“旋钮”。审批策略 (approval_policy)这定义了 Codex 的“自主权”。suggest仅建议模式下它只会给出代码建议由你手动复制粘贴auto-edit自动编辑模式下它可以在获得你单次批准后自动在文件中进行修改full-auto全自动则允许它在特定规则下完全自主操作。对于新手或高风险操作强烈建议从suggest开始。随着信任建立再对熟悉的、低风险的任务如格式化代码、添加注释尝试auto-edit。一个常见的误区很多人安装后就直接用忽略了这些设置。结果就是Codex 可能用一个较弱的模型、最低的推理强度在为你工作你自然会觉得它“不够聪明”。花 10 分钟调整这些基础配置体验提升是立竿见影的。2. 项目级定制用AGENTS.md和规则Rules塑造“项目专家”用户级配置让你有了得力的“通用助手”但要让 Codex 真正成为某个项目的专家你需要进行项目级定制。这里有两个核心工具AGENTS.md和规则文件。2.1AGENTS.md项目的“宪法”与工作说明书AGENTS.md不是一个普通的 Markdown 文档。它是你与 Codex 关于“在这个项目里该如何工作”的正式约定。把它想象成新员工入职时收到的项目手册。它应该包含什么技术栈与架构明确告诉 Codex 这个项目用 React TypeScript 还是 Vue后端是 Go 还是 Python FastAPI数据库是 PostgreSQL 还是 MongoDB。这能防止它写出风格不符或依赖错误的代码。代码规范缩进是 2 空格还是 4 空格命名用 camelCase 还是 snake_case是否需要严格的 TypeScript 类型把这些规则写清楚Codex 生成的代码会立刻符合团队规范。项目特定的约定比如“所有 API 响应必须包裹在{ data, message, code }的结构体中”“错误日志必须使用structured logging并包含request_id”。这些约定是 AI 难以从代码中自行推断的。安全与审查红线明确列出“禁止在日志中记录用户密码等 PII 信息”“所有数据库查询必须使用参数化查询以防止 SQL 注入”“新增外部依赖必须经过安全扫描”。这相当于给 Codex 设置了安全护栏。示例片段 (AGENTS.md):# 项目用户中心微服务 ## 技术栈 - 语言Go 1.21 - Web 框架Gin - 数据库PostgreSQL 15 (使用 pgx 驱动) - 缓存Redis 7 - 文档Swagger/OpenAPI 3.0 ## 开发规范 - 代码格式化必须使用 gofmt。 - 错误处理使用 errors.Wrapf 包装错误并附带上下文。 - 日志使用 slog 进行结构化日志记录级别为 Info 及以上需包含 trace_id。 - 配置管理使用 Viper配置从环境变量读取示例见 config.example.yaml。 ## API 设计规范 - 路径/api/v1/resource-name - 方法遵循 RESTful 约定。 - 响应统一格式 { code: 200, msg: ok, data: T }。 - 错误码见 pkg/errors/error_code.go。 ## 安全要求 - 【禁止】在日志、响应中暴露用户敏感信息手机号、邮箱、身份证号。 - 【必须】所有数据库交互使用参数化查询或 ORM 的防注入方法。 - 【必须】新增路由需在 main.go 中注册并在 docs/swagger.yaml 中更新文档。高级用法子目录覆盖你可以在子目录放置AGENTS.override.md来定义更具体的规则。例如在src/auth/目录下你可以强调“本模块所有密码必须使用 bcrypt 加密强度为 12”。这样当 Codex 在该目录下工作时它会优先采用这些更严格的规则。2.2 规则Rules定义命令执行的“交通法规”如果说AGENTS.md是工作说明书那么规则Rules就是安全护栏和权限系统。它用类 Python 的 Starlark 语言编写控制着 Codex 可以执行哪些命令、需要询问哪些命令、以及禁止哪些命令。为什么需要规则想象一下你让 Codex “清理一下临时文件”如果没有规则它可能直接执行rm -rf /tmp/*这通常是安全的。但如果它错误地理解了你的意图或者被恶意提示词诱导去执行rm -rf /删除根目录那将是灾难性的。规则就是为了防止这类情况。规则文件示例 (~/.codex/rules/default.rules):# 允许安全的系统信息查看命令 prefix_rule( pattern [df, -h], decision allow, justification 查看磁盘空间是安全的 ) # 允许本项目的 Git 操作假设项目路径是 /home/user/projects/my-app prefix_rule( pattern [git], decision allow, matcher { cwd_contains: my-app }, # 限制在当前项目目录 justification 允许在当前项目内进行 Git 操作 ) # 对于安装系统级包如 apt, yum必须询问 prefix_rule( pattern [apt, install], decision prompt, justification 安装系统软件包需要确认 ) prefix_rule( pattern [yum, install], decision prompt, justification 安装系统软件包需要确认 ) # 明确禁止高危命令无论在任何目录 prefix_rule( pattern [rm, -rf, /], decision forbidden, justification 绝对禁止删除根目录 ) prefix_rule( pattern [dd, if/dev/random], decision forbidden, justification 禁止使用 dd 进行危险磁盘操作 ) prefix_rule( pattern [:(){ :|: };:], # Fork Bomb decision forbidden, justification 禁止执行 fork 炸弹 )决策类型说明allow: 自动执行。适用于你完全信任的低风险操作如ls,pwd,cat非敏感文件以及项目内的npm run build,go test等。prompt: 执行前弹出窗口询问你。适用于有潜在影响的操作如npm install会修改node_modules、docker compose down会停止容器。forbidden: 直接拒绝执行。用于那些已知的、绝对危险的操作。配置策略建议白名单思维起步初期对你不熟悉的命令一律设为prompt或forbidden。随着使用将高频且安全的命令逐步加入allow列表。结合目录限制利用matcher如cwd_contains来限制命令的执行范围。允许git push很好但最好只允许它在你的代码项目目录下执行。定期审查与更新当你引入新的工具链如terraform,kubectl时记得更新规则文件。将AGENTS.md和规则文件纳入项目的版本控制如 Git能让整个团队的 Codex 都遵循同一套高质量、高安全的标准这是将 AI 协作从个人玩具升级为团队生产力的关键一步。3. 技能Skills与子代理Subagents扩展能力与分工协作当基础配置和项目规范就绪后Codex 已经是一个合格的“项目成员”了。但要让它成为“专家”你需要赋予它特定的技能甚至在复杂任务中让它“分身”协作。3.1 技能Skills封装可复用的专家流程技能Skill是 Codex 生态中最强大的概念之一。它允许你将一个复杂的、多步骤的任务如“执行一次标准的代码审查”、“为新功能生成完整的 CRUD API 骨架”封装成一个简单的命令。技能是什么你可以把它理解为一个针对特定任务的、加强版的“提示词模板执行脚本”。它不仅仅告诉 Codex“做什么”还定义了“怎么做”的完整流程、需要参考哪些文件、以及输出应该如何格式化。技能结构my-code-review-skill/ ├── SKILL.md # 技能的核心定义和说明 ├── scripts/ # 可选可执行的辅助脚本 ├── references/ # 可选技能所需的参考文档、规范 └── assets/ # 可选图标、模板等静态资源创建你的第一个技能假设你想创建一个“Go 项目代码审查”技能。创建技能目录在~/.agents/skills/用户级或你的项目.agents/skills/项目级下创建目录go-code-review。编写SKILL.md--- name: go-code-review description: 对 Go 项目进行全面的代码质量与安全审查。 tags: [go, review, security, quality] --- # Go 代码审查指南 请根据以下 checklist 审查指定的 Go 代码文件或目录 ## 1. 代码规范 - [ ] 使用 gofmt 格式化。 - [ ] 变量命名遵循 camelCase包外可见或 camelCase包内私有。 - [ ] 函数长度不超过 50 行复杂逻辑已抽取。 - [ ] 错误处理完善使用了 errors.Wrap 或 fmt.Errorf 附带上下文。 ## 2. 并发安全 - [ ] 对共享数据的访问使用了 sync.Mutex 或 sync.RWMutex。 - [ ] 检查是否存在数据竞争data race的可能性。 ## 3. 安全与漏洞 - [ ] 命令行参数或环境变量注入检查。 - [ ] 数据库查询使用了参数化如 sqlx.NamedExec防止 SQL 注入。 - [ ] 日志中未包含敏感信息密码、密钥、个人身份信息。 ## 4. 性能 - [ ] 在循环中避免重复分配内存如字符串拼接使用 strings.Builder。 - [ ] 检查是否有不必要的数据库查询或 HTTP 调用。 ## 输出格式 请以 Markdown 表格形式输出审查结果包含问题类型、位置文件:行号、描述、严重程度高/中/低、修复建议。使用技能在 Codex 对话中直接输入$go-code-review并指定文件或目录例如$go-code-review ./pkg/user/。Codex 会加载这个技能并按照你定义的 checklist 和格式进行审查。技能的价值它把一次性的、需要你反复描述的要求变成了一个可随时调用的、标准化的“专家服务”。团队可以共享一套技能库确保代码审查、API 测试、部署检查等任务的质量一致性。3.2 子代理Subagents让 Codex 学会“团队作战”对于极其复杂的任务比如“重构整个身份认证模块并更新所有相关文档和测试”单个 Codex 代理可能会力不从心。这时子代理Subagents就派上用场了。Codex 可以将一个大任务分解创建多个具有不同专长的子代理来并行处理。例如worker代理擅长执行具体的、指令明确的编码和修复任务。explorer代理擅长探索代码库、理解架构、发现依赖关系。你可以在~/.codex/config.toml中配置子代理的行为[agents] max_threads 4 # 最大并行子任务数 max_depth 2 # 任务分解的最大嵌套深度 job_max_runtime_seconds 1800 # 单个子任务最长运行时间30分钟你甚至可以定义自定义代理。创建一个~/.codex/agents/documenter.tomlname documenter description 专注于为代码生成和更新文档 nickname_candidates [DocBot, WriteStuff] developer_instructions 你是一个技术文档专家。你的任务是 1. 为函数、方法、结构体生成清晰的 GoDoc 风格注释。 2. 根据代码变更更新项目的 README 或 API 文档。 3. 确保文档示例代码是可运行的。 4. 使用简单、准确的语言避免歧义。 然后在主任务中你可以指示 Codex“请使用documenter子代理来为本次重构生成更新后的 API 文档。”使用场景当你面对一个涉及“探索-规划-实现-测试-文档”多阶段的大型任务时在AGENTS.md或初始提示中明确建议 Codex 使用子代理分工能显著提高任务完成的质量和效率。这相当于你拥有了一个随时待命的微型开发团队。4. 高级配置与实战避坑指南掌握了核心配置、项目定制和能力扩展后我们来看一些能进一步提升体验和规避风险的进阶配置。4.1 钩子Hooks在关键节点插入自定义逻辑钩子允许你在 Codex 生命周期的特定事件如会话开始、工具调用前后触发自定义脚本。这是实现自动化工作流和深度集成的利器。常见用例会话开始 (SessionStart)自动拉取最新代码或加载项目特定的环境变量。工具调用后 (PostToolUse)当 Codex 执行完一个测试命令后自动解析测试结果并生成摘要或者当它修改了文件后自动触发代码格式化。配置示例在config.toml中启用并定义首先确保启用钩子功能[features] codex_hooks true然后在规则文件同级目录或指定路径创建钩子定义如hooks.json{ hooks: [ { event: PostToolUse, matcher: { toolName: Bash, commandMatches: go test.* // 匹配执行 go test 的命令 }, hooks: [ { type: command, command: go tool cover -htmlcoverage.out -o coverage.html, // 生成覆盖率报告 timeout: 30, cwd: {{.Cwd}} // 使用当前工作目录 }, { type: notify, title: 测试完成, body: 覆盖率报告已生成: coverage.html } ] } ] }这个钩子会在每次 Codex 执行go test命令后自动生成一个 HTML 格式的测试覆盖率报告并发送通知。4.2 环境与路径让 Codex 在正确的上下文中工作很多“Codex 命令执行失败”的问题根源在于环境变量、工作目录或工具链路径不对。项目环境 ([environment])在项目级的.codex/config.toml中你可以预设环境变量。[environment] PYTHONPATH ./src # 添加 Python 模块搜索路径 DATABASE_URL postgresql://localhost/myapp_dev # 设置开发数据库连接Shell 配置Codex 启动的 Shell 环境可能和你终端里的不一样。确保你的PATH变量包含了所有必要工具的路径如node,python,go。有时需要你在用户配置中通过钩子或脚本显式地source ~/.bashrc或~/.zshrc。4.3 常见“坑”与排查清单即使配置得当过程中也可能遇到问题。下面是一个快速排查清单Codex 完全没反应或报错“无法连接”检查网络和代理确保 Codex 能访问其所需的 API 端点如 OpenAI, Anthropic。如果是企业环境可能需要配置网络代理。检查 API 密钥在 Codex App 的设置中确认相关模型的 API 密钥已正确配置且未过期。查看日志Codex 通常有应用日志位置可能在~/.codex/logs/或通过系统控制台查看。日志是定位连接、认证问题的一手资料。命令执行失败如npm: command not found检查PATH在 Codex 的对话中让它执行echo $PATH看看是否包含你所需工具的路径。使用绝对路径或配置别名在规则或技能中对于关键工具考虑使用绝对路径如/usr/local/bin/npm。确认上下文Codex 执行命令时所在的当前工作目录CWD是否正确它可能不在你期望的项目根目录。生成的代码不符合项目规范确认AGENTS.md位置与内容确保文件在项目根目录并且内容清晰、具体。Codex 会读取它但过于模糊的指令可能不被有效遵循。检查配置优先级是否有一个更高优先级的配置如托管配置覆盖了你的项目设置强化提示在任务描述中可以再次强调“请严格遵守项目根目录下AGENTS.md中定义的 Go 开发规范”。性能慢或消耗大量 Token调整model_reasoning_effort对于简单任务尝试降低推理强度。审查AGENTS.md大小AGENTS.md文件过大会消耗大量上下文。确保它简洁、聚焦。超过 32KiB 会被截断。使用更高效的模型对于不需要最强推理的日常任务可以切换到更轻量、更快的模型。配置 Codex 不是一个一次性的任务而是一个持续迭代和磨合的过程。最好的策略是从一个最小可用的配置开始比如只设置模型和审批策略然后在真实的使用中每当你发现一个重复性的痛点“要是它能自动做 X 就好了”或一个潜在的风险“这个命令不应该在这里执行”就去相应地完善你的AGENTS.md、规则或技能。久而久之Codex 将不再是那个需要你时时操心的“新员工”而会真正成长为理解你项目上下文、遵循你团队规范、并能安全高效执行复杂任务的“资深搭档”。
Codex智能体配置实战：从通用助手到专属项目专家的进阶指南
发布时间：2026/7/28 14:40:47
你肯定遇到过这种情况想用 Codex 帮你写段代码、分析个日志或者自动化处理点杂活结果发现它要么“听不懂”你的需求要么执行起来总差那么点意思。比如你让它“帮我看看这个 API 接口”它可能真的只是“看看”然后告诉你“这是一个接口”而不是像你期望的那样自动去调用、测试并返回结果。问题出在哪很多时候不是 Codex 能力不行而是你和它之间还隔着一层“配置”的迷雾。配置听起来像是安装软件时那些枯燥的复选框和文本框。但在 Codex 这类智能体Agent的世界里配置远不止于此。它决定了 Codex 如何理解你的意图、拥有哪些权限、遵循什么规则以及最终以何种方式与你协作。一个精心配置的 Codex能从一个被动的问答机器转变为你工作流中一个主动、可靠、懂你习惯的“数字同事”。而一个未经配置的 Codex可能只是一个偶尔灵光、但更多时候需要你反复“调教”的初级助手。这篇文章不会是一份冷冰冰的官方文档翻译。我们将深入 Codex 的配置体系从“能用”到“好用”再到“如臂使指”。我会结合常见的工程实践告诉你哪些配置项是核心杠杆哪些“坑”可以提前避开以及如何通过配置让 Codex 真正融入你的开发习惯。1. 理解 Codex 的配置哲学从“通用助手”到“专属专家”在深入具体配置项之前我们需要先理解 Codex 配置设计的核心思想。它不是一个“一劳永逸”的设置而是一个分层、可组合、可演进的协作协议。1.1 配置的四个层级全局、用户、项目与托管Codex 的配置管理非常清晰遵循从通用到特定的优先级覆盖原则。理解这个层级是避免配置冲突和混乱的第一步。配置层级典型路径作用范围优先级适用场景托管配置由企业或团队管理员下发整个组织或团队最高强制执行安全策略、统一代码规范、禁用危险命令等。项目配置项目根目录下的.codex/config.toml单个代码仓库高定义项目特定的技术栈如 Python 3.9、依赖安装命令、测试运行方式、部署流程等。用户配置用户主目录下的~/.codex/config.toml用户的所有项目中设置个人偏好的默认模型、编辑器、常用技能Skills、审批策略等。全局默认Codex 应用内置所有用户最低提供最基础的、开箱即用的行为。合并规则很简单优先级高的配置会覆盖优先级低的配置。例如你在用户配置里设置了model gpt-4但在某个项目的配置里写了model claude-3-opus那么在这个项目里Codex 会使用 Claude 模型。这让你既能拥有个人工作习惯的基线又能为不同项目定制最合适的“专家”。实操建议我建议你先从用户级配置开始。这是你的“个人工作台”设置。在这里你可以设定一个你信任的、能力均衡的默认模型比如gpt-4o以及你常用的推理强度。这能确保你在打开任何新项目时都有一个可靠的基础体验。1.2 核心配置项模型、审批与工作方式打开 Codex App 的设置Cmd ,或Ctrl ,你会看到几个关键分类。我们挑最核心的讲模型选择 (model)这是 Codex 的“大脑”。选择哪个模型直接决定了它的代码生成、逻辑推理和问题解决能力。除了选择提供商如 OpenAI, Anthropic更要关注模型版本。gpt-4-turbo和gpt-4o在代码理解上可能差异不大但在长上下文处理和响应速度上各有千秋。不要盲目追求“最新最强”而要根据你的主要任务类型是快速原型还是深度调试和预算来选择。推理强度 (model_reasoning_effort)这个参数非常关键它控制着模型在给出答案前“思考”的深度。从minimal最快可能略过一些步骤到xhigh最慢但步骤最详尽。对于简单的代码补全low或medium可能就够了但对于复杂的系统设计或 Bug 排查设置为high能让 Codex 输出更严谨、更有步骤的解决方案。这是一个需要根据任务动态调整的“旋钮”。审批策略 (approval_policy)这定义了 Codex 的“自主权”。suggest仅建议模式下它只会给出代码建议由你手动复制粘贴auto-edit自动编辑模式下它可以在获得你单次批准后自动在文件中进行修改full-auto全自动则允许它在特定规则下完全自主操作。对于新手或高风险操作强烈建议从suggest开始。随着信任建立再对熟悉的、低风险的任务如格式化代码、添加注释尝试auto-edit。一个常见的误区很多人安装后就直接用忽略了这些设置。结果就是Codex 可能用一个较弱的模型、最低的推理强度在为你工作你自然会觉得它“不够聪明”。花 10 分钟调整这些基础配置体验提升是立竿见影的。2. 项目级定制用AGENTS.md和规则Rules塑造“项目专家”用户级配置让你有了得力的“通用助手”但要让 Codex 真正成为某个项目的专家你需要进行项目级定制。这里有两个核心工具AGENTS.md和规则文件。2.1AGENTS.md项目的“宪法”与工作说明书AGENTS.md不是一个普通的 Markdown 文档。它是你与 Codex 关于“在这个项目里该如何工作”的正式约定。把它想象成新员工入职时收到的项目手册。它应该包含什么技术栈与架构明确告诉 Codex 这个项目用 React TypeScript 还是 Vue后端是 Go 还是 Python FastAPI数据库是 PostgreSQL 还是 MongoDB。这能防止它写出风格不符或依赖错误的代码。代码规范缩进是 2 空格还是 4 空格命名用 camelCase 还是 snake_case是否需要严格的 TypeScript 类型把这些规则写清楚Codex 生成的代码会立刻符合团队规范。项目特定的约定比如“所有 API 响应必须包裹在{ data, message, code }的结构体中”“错误日志必须使用structured logging并包含request_id”。这些约定是 AI 难以从代码中自行推断的。安全与审查红线明确列出“禁止在日志中记录用户密码等 PII 信息”“所有数据库查询必须使用参数化查询以防止 SQL 注入”“新增外部依赖必须经过安全扫描”。这相当于给 Codex 设置了安全护栏。示例片段 (AGENTS.md):# 项目用户中心微服务 ## 技术栈 - 语言Go 1.21 - Web 框架Gin - 数据库PostgreSQL 15 (使用 pgx 驱动) - 缓存Redis 7 - 文档Swagger/OpenAPI 3.0 ## 开发规范 - 代码格式化必须使用 gofmt。 - 错误处理使用 errors.Wrapf 包装错误并附带上下文。 - 日志使用 slog 进行结构化日志记录级别为 Info 及以上需包含 trace_id。 - 配置管理使用 Viper配置从环境变量读取示例见 config.example.yaml。 ## API 设计规范 - 路径/api/v1/resource-name - 方法遵循 RESTful 约定。 - 响应统一格式 { code: 200, msg: ok, data: T }。 - 错误码见 pkg/errors/error_code.go。 ## 安全要求 - 【禁止】在日志、响应中暴露用户敏感信息手机号、邮箱、身份证号。 - 【必须】所有数据库交互使用参数化查询或 ORM 的防注入方法。 - 【必须】新增路由需在 main.go 中注册并在 docs/swagger.yaml 中更新文档。高级用法子目录覆盖你可以在子目录放置AGENTS.override.md来定义更具体的规则。例如在src/auth/目录下你可以强调“本模块所有密码必须使用 bcrypt 加密强度为 12”。这样当 Codex 在该目录下工作时它会优先采用这些更严格的规则。2.2 规则Rules定义命令执行的“交通法规”如果说AGENTS.md是工作说明书那么规则Rules就是安全护栏和权限系统。它用类 Python 的 Starlark 语言编写控制着 Codex 可以执行哪些命令、需要询问哪些命令、以及禁止哪些命令。为什么需要规则想象一下你让 Codex “清理一下临时文件”如果没有规则它可能直接执行rm -rf /tmp/*这通常是安全的。但如果它错误地理解了你的意图或者被恶意提示词诱导去执行rm -rf /删除根目录那将是灾难性的。规则就是为了防止这类情况。规则文件示例 (~/.codex/rules/default.rules):# 允许安全的系统信息查看命令 prefix_rule( pattern [df, -h], decision allow, justification 查看磁盘空间是安全的 ) # 允许本项目的 Git 操作假设项目路径是 /home/user/projects/my-app prefix_rule( pattern [git], decision allow, matcher { cwd_contains: my-app }, # 限制在当前项目目录 justification 允许在当前项目内进行 Git 操作 ) # 对于安装系统级包如 apt, yum必须询问 prefix_rule( pattern [apt, install], decision prompt, justification 安装系统软件包需要确认 ) prefix_rule( pattern [yum, install], decision prompt, justification 安装系统软件包需要确认 ) # 明确禁止高危命令无论在任何目录 prefix_rule( pattern [rm, -rf, /], decision forbidden, justification 绝对禁止删除根目录 ) prefix_rule( pattern [dd, if/dev/random], decision forbidden, justification 禁止使用 dd 进行危险磁盘操作 ) prefix_rule( pattern [:(){ :|: };:], # Fork Bomb decision forbidden, justification 禁止执行 fork 炸弹 )决策类型说明allow: 自动执行。适用于你完全信任的低风险操作如ls,pwd,cat非敏感文件以及项目内的npm run build,go test等。prompt: 执行前弹出窗口询问你。适用于有潜在影响的操作如npm install会修改node_modules、docker compose down会停止容器。forbidden: 直接拒绝执行。用于那些已知的、绝对危险的操作。配置策略建议白名单思维起步初期对你不熟悉的命令一律设为prompt或forbidden。随着使用将高频且安全的命令逐步加入allow列表。结合目录限制利用matcher如cwd_contains来限制命令的执行范围。允许git push很好但最好只允许它在你的代码项目目录下执行。定期审查与更新当你引入新的工具链如terraform,kubectl时记得更新规则文件。将AGENTS.md和规则文件纳入项目的版本控制如 Git能让整个团队的 Codex 都遵循同一套高质量、高安全的标准这是将 AI 协作从个人玩具升级为团队生产力的关键一步。3. 技能Skills与子代理Subagents扩展能力与分工协作当基础配置和项目规范就绪后Codex 已经是一个合格的“项目成员”了。但要让它成为“专家”你需要赋予它特定的技能甚至在复杂任务中让它“分身”协作。3.1 技能Skills封装可复用的专家流程技能Skill是 Codex 生态中最强大的概念之一。它允许你将一个复杂的、多步骤的任务如“执行一次标准的代码审查”、“为新功能生成完整的 CRUD API 骨架”封装成一个简单的命令。技能是什么你可以把它理解为一个针对特定任务的、加强版的“提示词模板执行脚本”。它不仅仅告诉 Codex“做什么”还定义了“怎么做”的完整流程、需要参考哪些文件、以及输出应该如何格式化。技能结构my-code-review-skill/ ├── SKILL.md # 技能的核心定义和说明 ├── scripts/ # 可选可执行的辅助脚本 ├── references/ # 可选技能所需的参考文档、规范 └── assets/ # 可选图标、模板等静态资源创建你的第一个技能假设你想创建一个“Go 项目代码审查”技能。创建技能目录在~/.agents/skills/用户级或你的项目.agents/skills/项目级下创建目录go-code-review。编写SKILL.md--- name: go-code-review description: 对 Go 项目进行全面的代码质量与安全审查。 tags: [go, review, security, quality] --- # Go 代码审查指南 请根据以下 checklist 审查指定的 Go 代码文件或目录 ## 1. 代码规范 - [ ] 使用 gofmt 格式化。 - [ ] 变量命名遵循 camelCase包外可见或 camelCase包内私有。 - [ ] 函数长度不超过 50 行复杂逻辑已抽取。 - [ ] 错误处理完善使用了 errors.Wrap 或 fmt.Errorf 附带上下文。 ## 2. 并发安全 - [ ] 对共享数据的访问使用了 sync.Mutex 或 sync.RWMutex。 - [ ] 检查是否存在数据竞争data race的可能性。 ## 3. 安全与漏洞 - [ ] 命令行参数或环境变量注入检查。 - [ ] 数据库查询使用了参数化如 sqlx.NamedExec防止 SQL 注入。 - [ ] 日志中未包含敏感信息密码、密钥、个人身份信息。 ## 4. 性能 - [ ] 在循环中避免重复分配内存如字符串拼接使用 strings.Builder。 - [ ] 检查是否有不必要的数据库查询或 HTTP 调用。 ## 输出格式 请以 Markdown 表格形式输出审查结果包含问题类型、位置文件:行号、描述、严重程度高/中/低、修复建议。使用技能在 Codex 对话中直接输入$go-code-review并指定文件或目录例如$go-code-review ./pkg/user/。Codex 会加载这个技能并按照你定义的 checklist 和格式进行审查。技能的价值它把一次性的、需要你反复描述的要求变成了一个可随时调用的、标准化的“专家服务”。团队可以共享一套技能库确保代码审查、API 测试、部署检查等任务的质量一致性。3.2 子代理Subagents让 Codex 学会“团队作战”对于极其复杂的任务比如“重构整个身份认证模块并更新所有相关文档和测试”单个 Codex 代理可能会力不从心。这时子代理Subagents就派上用场了。Codex 可以将一个大任务分解创建多个具有不同专长的子代理来并行处理。例如worker代理擅长执行具体的、指令明确的编码和修复任务。explorer代理擅长探索代码库、理解架构、发现依赖关系。你可以在~/.codex/config.toml中配置子代理的行为[agents] max_threads 4 # 最大并行子任务数 max_depth 2 # 任务分解的最大嵌套深度 job_max_runtime_seconds 1800 # 单个子任务最长运行时间30分钟你甚至可以定义自定义代理。创建一个~/.codex/agents/documenter.tomlname documenter description 专注于为代码生成和更新文档 nickname_candidates [DocBot, WriteStuff] developer_instructions 你是一个技术文档专家。你的任务是 1. 为函数、方法、结构体生成清晰的 GoDoc 风格注释。 2. 根据代码变更更新项目的 README 或 API 文档。 3. 确保文档示例代码是可运行的。 4. 使用简单、准确的语言避免歧义。 然后在主任务中你可以指示 Codex“请使用documenter子代理来为本次重构生成更新后的 API 文档。”使用场景当你面对一个涉及“探索-规划-实现-测试-文档”多阶段的大型任务时在AGENTS.md或初始提示中明确建议 Codex 使用子代理分工能显著提高任务完成的质量和效率。这相当于你拥有了一个随时待命的微型开发团队。4. 高级配置与实战避坑指南掌握了核心配置、项目定制和能力扩展后我们来看一些能进一步提升体验和规避风险的进阶配置。4.1 钩子Hooks在关键节点插入自定义逻辑钩子允许你在 Codex 生命周期的特定事件如会话开始、工具调用前后触发自定义脚本。这是实现自动化工作流和深度集成的利器。常见用例会话开始 (SessionStart)自动拉取最新代码或加载项目特定的环境变量。工具调用后 (PostToolUse)当 Codex 执行完一个测试命令后自动解析测试结果并生成摘要或者当它修改了文件后自动触发代码格式化。配置示例在config.toml中启用并定义首先确保启用钩子功能[features] codex_hooks true然后在规则文件同级目录或指定路径创建钩子定义如hooks.json{ hooks: [ { event: PostToolUse, matcher: { toolName: Bash, commandMatches: go test.* // 匹配执行 go test 的命令 }, hooks: [ { type: command, command: go tool cover -htmlcoverage.out -o coverage.html, // 生成覆盖率报告 timeout: 30, cwd: {{.Cwd}} // 使用当前工作目录 }, { type: notify, title: 测试完成, body: 覆盖率报告已生成: coverage.html } ] } ] }这个钩子会在每次 Codex 执行go test命令后自动生成一个 HTML 格式的测试覆盖率报告并发送通知。4.2 环境与路径让 Codex 在正确的上下文中工作很多“Codex 命令执行失败”的问题根源在于环境变量、工作目录或工具链路径不对。项目环境 ([environment])在项目级的.codex/config.toml中你可以预设环境变量。[environment] PYTHONPATH ./src # 添加 Python 模块搜索路径 DATABASE_URL postgresql://localhost/myapp_dev # 设置开发数据库连接Shell 配置Codex 启动的 Shell 环境可能和你终端里的不一样。确保你的PATH变量包含了所有必要工具的路径如node,python,go。有时需要你在用户配置中通过钩子或脚本显式地source ~/.bashrc或~/.zshrc。4.3 常见“坑”与排查清单即使配置得当过程中也可能遇到问题。下面是一个快速排查清单Codex 完全没反应或报错“无法连接”检查网络和代理确保 Codex 能访问其所需的 API 端点如 OpenAI, Anthropic。如果是企业环境可能需要配置网络代理。检查 API 密钥在 Codex App 的设置中确认相关模型的 API 密钥已正确配置且未过期。查看日志Codex 通常有应用日志位置可能在~/.codex/logs/或通过系统控制台查看。日志是定位连接、认证问题的一手资料。命令执行失败如npm: command not found检查PATH在 Codex 的对话中让它执行echo $PATH看看是否包含你所需工具的路径。使用绝对路径或配置别名在规则或技能中对于关键工具考虑使用绝对路径如/usr/local/bin/npm。确认上下文Codex 执行命令时所在的当前工作目录CWD是否正确它可能不在你期望的项目根目录。生成的代码不符合项目规范确认AGENTS.md位置与内容确保文件在项目根目录并且内容清晰、具体。Codex 会读取它但过于模糊的指令可能不被有效遵循。检查配置优先级是否有一个更高优先级的配置如托管配置覆盖了你的项目设置强化提示在任务描述中可以再次强调“请严格遵守项目根目录下AGENTS.md中定义的 Go 开发规范”。性能慢或消耗大量 Token调整model_reasoning_effort对于简单任务尝试降低推理强度。审查AGENTS.md大小AGENTS.md文件过大会消耗大量上下文。确保它简洁、聚焦。超过 32KiB 会被截断。使用更高效的模型对于不需要最强推理的日常任务可以切换到更轻量、更快的模型。配置 Codex 不是一个一次性的任务而是一个持续迭代和磨合的过程。最好的策略是从一个最小可用的配置开始比如只设置模型和审批策略然后在真实的使用中每当你发现一个重复性的痛点“要是它能自动做 X 就好了”或一个潜在的风险“这个命令不应该在这里执行”就去相应地完善你的AGENTS.md、规则或技能。久而久之Codex 将不再是那个需要你时时操心的“新员工”而会真正成长为理解你项目上下文、遵循你团队规范、并能安全高效执行复杂任务的“资深搭档”。
![【Bug已解决】[RFC]: Remove Per-Block KV Transfer Error Handling 解决方案](http://pic.xiahunao.cn/yaotu/【Bug已解决】[RFC]: Remove Per-Block KV Transfer Error Handling 解决方案)
