上周帮一个做法律咨询的朋友配置 Codex，他上来就问：“这玩意儿能直接帮我写合同吗？”我说能，但前提是你得先告诉它，你的合同长什么样、要规避哪些风险、格式有什么讲究。他愣了一下：“这不就是配置吗？”
对，这就是配置。很多人把配置理解成“填几个参数”，但真正决定 Codex 能不能帮你高效工作的，不是那几个开关，而是你花了多少心思去定义它的行为边界、任务流程和输出标准。配置不是一次性设置，而是一个持续校准的过程——你得先想清楚自己要什么，再让工具学会你的工作方式。
这篇文章不会只给你一个配置清单。我会带你走完从“装好就能用”到“真正能用起来”的全过程，重点放在那些容易被忽略、但实际决定了长期使用体验的细节上。如果你已经装好了 Codex，却总觉得它“差点意思”，或者想让它更贴合你的专业工作流，接下来的内容应该能给你一些具体思路。
1. 先别急着调参数：理解 Codex 的配置到底在管什么
很多人一打开设置界面就开始逐个开关试效果，这其实效率很低。Codex 的配置体系是分层、分场景的，你得先知道每一层配置影响的范围和时机，才能避免“改了这里那里又不对”的反复折腾。
1.1 三层配置：从全局默认到项目专属
Codex 的配置管理遵循一个清晰的优先级链条：系统/托管配置 → 用户级配置 → 项目级配置。高优先级配置会覆盖低优先级配置。
- 用户级配置（
~/.codex/config.toml）：这是你的个人工作台默认设置。比如你习惯用哪个模型、默认的推理强度（reasoning effort）调到什么级别、审批策略（approval policy）是让 Codex 先建议再执行，还是完全自动执行。这里设置的是一切新会话的起点。 - 项目级配置（
.codex/config.toml）：放在项目根目录下。这个文件里的设置只对当前项目生效。比如某个前端项目你希望 Codex 用更严格的 TypeScript 规则，或者某个数据清洗项目需要它默认以“高推理强度”运行以确保逻辑严谨。项目配置会覆盖你的个人习惯，确保团队协作或特定任务类型下行为一致。 - 托管/企业级配置：通常由管理员统一下发，用于强制执行安全策略、统一模型版本或禁用某些高风险功能。个人用户一般接触不到，但需要知道它的存在——如果你发现某个设置怎么改都无效，可能是被这层锁定了。
一个常见的误区：在项目目录里改了配置，却纳闷为什么其他项目不受影响。记住，项目配置是隔离的。如果你想建立一套个人偏好的“基础模板”，应该在用户级配置里定义；而项目配置是用来处理“例外”和“特殊要求”的。
1.2 核心配置项：不只是模型选择
打开config.toml，你会看到一堆选项。除了显而易见的model（比如gpt-4o、claude-3.5-sonnet），真正影响使用体验的往往是下面这几个：
model_reasoning_effort：这个参数控制模型在“思考”上花多少算力。选项从minimal（最快，但可能思考不深入）到xhigh（最慢，但会尝试更复杂的推理链）。对于法律文书、代码审查这类需要严谨性的任务，建议至少设为medium或high。代价是响应时间会变长，但出错的概率会显著降低。model_reasoning_summary：决定模型是否以及如何向你展示它的思考过程。auto是让模型自己判断，concise只给关键结论，detailed会展示更多推理步骤，none则完全不显示。如果你在调试或学习阶段，设为detailed能帮你理解它的决策逻辑；进入稳定使用后，可以切回auto或concise以节省篇幅。approval_policy：这是安全阀门。suggest是只给建议，等你确认后再执行；auto-edit允许它自动编辑文件，但执行命令前会询问；full-auto则完全自动执行（慎用）。强烈建议新手和在生产环境使用时，先从suggest开始，等充分信任其行为模式后再逐步放宽。service_tier：flex和fast的选择。flex通常更便宜或配额更宽松，但可能在高峰时段排队；fast保证优先响应。根据你的使用频率和任务时效性决定。
配置的本质，是你在告诉 Codex：“我用你的时候，希望你是这样一种工作风格。” 所以，别把它当成一次性的填空题，而应该根据任务类型动态调整。比如，写快速原型时可以用fast+minimal；做正式合同审查时切到flex+high。
2. 让 Codex 理解你的项目：AGENTS.md 才是真正的“入职培训”
如果说config.toml是给 Codex 定了个性格基调，那么AGENTS.md就是给它的一份详细岗位说明书。很多用户抱怨 Codex 生成的代码风格不符、漏掉了关键的合规检查，问题往往出在没好好写这份说明书。
2.1 AGENTS.md 是什么？为什么它比提示词更有效？
你可以把AGENTS.md理解为项目级的“长期记忆”。每次 Codex 在你的项目里启动一个新会话，它都会先读取这个文件，了解这个项目的背景、规矩和禁忌。这比你在每次对话里重复输入“我们要用 React”、“函数要有 JSDoc”、“这里禁止 console.log”要高效得多。
它的生效范围是目录级的。你可以在项目根目录放一个总纲，在src/contracts/这样的子目录再放一个AGENTS.override.md，添加更具体的规则（比如“所有合同模板必须包含不可抗力条款”）。Codex 会合并这些规则，子目录的规则优先级更高。
2.2 一份给法律项目的 AGENTS.md 示例
光说理论不够直观，我们直接看一个为法律文档处理项目设计的AGENTS.md可能长什么样：
# 项目：法律文档智能辅助系统 ## 项目目标 协助律师及法务人员高效生成、审查和修订常见法律文书，重点确保格式规范、条款完备且符合中国法律实务。 ## 核心原则 1. **严谨优先**：任何不确定的表述、模糊的条款，必须标注“【待律师确认】”，不得自行臆断。 2. **格式至上**：所有输出文档必须严格遵循《国家行政机关公文格式》或客户指定的特定模板。 3. **风险提示**：在涉及责任界定、违约金、知识产权、保密条款等关键部分，必须主动添加风险评注。 ## 技术栈与工具约定 * **文档处理**：优先使用 Python `python-docx` 库进行 Word 文档操作。如无特殊要求，默认生成 `.docx` 格式。 * **命名规范**：文件命名采用 `[日期]_[文书类型]_[当事人简称]_[版本号].docx` 格式，例如 `20231027_委托代理合同_甲方A公司_v1.docx`。 * **版本控制**：所有文档修改必须通过 Git 提交，提交信息需简要说明修改内容及原因。 ## 文书生成与审查清单 ### 合同类文书 - [ ] 首部：当事人信息完整、准确（名称、地址、法定代表人、统一社会信用代码）。 - [ ] 鉴于条款：清晰陈述签约背景与目的。 - [ ] 权利义务条款：表述无歧义，履行标准明确。 - [ ] 价款与支付方式：金额大写小写一致，支付节点与合同义务挂钩。 - [ ] 违约责任：违约情形具体，违约金计算方式合法有效（根据《民法典》及相关司法解释）。 - [ ] 争议解决：明确约定管辖法院或仲裁机构，符合法律规定。 - [ ] 保密条款：保密信息定义清晰，保密期限合理。 - [ ] 不可抗力：定义明确，包括后果处理。 - [ ] 通知与送达：有效的送达地址条款。 - [ ] 合同生效、份数、附件等尾部条款完整。 ### 函件类文书（律师函、告知函等） - [ ] 抬头与落款格式规范。 - [ ] 事实陈述部分按时间顺序排列，客观准确。 - [ ] 法律依据引用准确（法律名称、条款号）。 - [ ] 诉求部分明确、具体、合法。 - [ ] 告知后果部分措辞严谨，不构成威胁。 ## 禁止与注意事项 1. **绝对禁止**：生成任何涉及现行法律明确禁止的内容，或提供规避法律的建议。 2. **避免绝对化表述**：如“完全”、“绝对”、“必须”等，除非引用法条原文。 3. **客户信息脱敏**：在示例、测试或共享代码中，所有客户名称、证件号、金额等敏感信息必须替换为明显的占位符，如 `[客户名称]`、`[身份证号]`、`[金额]`。 4. **及时更新法律依据**：如任务涉及特定法律领域（如数据安全、劳动法），需提示用户注意相关法律法规（如《个人信息保护法》、《劳动合同法》）的最新修订情况。 ## 输出格式要求 1. 所有生成的文书，应在文档末尾自动添加“【本文件由AI辅助生成，仅供参考，最终文本需经执业律师审定】”的提示水印。 2. 提供修订模式时，必须使用 Word 的“修订”功能或类似标记（如 `<<原内容>>` -> `<<新内容>>`）。 3. 审查报告应结构化输出，按“高风险条款”、“中风险条款”、“建议优化项”、“格式问题”分类，并附上具体位置和修改建议。这份AGENTS.md没有一行代码，但它清晰地定义了 Codex 在这个项目里的角色、行为边界和产出标准。当 Codex 读到它，它就知道在这个文件夹下干活，必须优先考虑严谨性、遵循特定格式、并主动进行风险提示。
2.3 如何维护和更新 AGENTS.md？
不要试图一次性写完一份完美的AGENTS.md。更好的方法是：
- 从最小集合开始：先写下你最不能忍受的3-5个问题（比如“永远用空格缩进”、“合同金额必须同时写大小写”）。
- 在协作中积累：每当 Codex 犯了同一个错误，或者你发现某个模式总是需要重复解释，就把它加到
AGENTS.md里。 - 按模块拆分：对于大型项目，在子目录使用
AGENTS.override.md。例如，/templates/目录下的覆盖文件可以专门规定模板填充规则，/review/目录下的可以规定审查报告的格式。 - 定期回顾：项目技术栈更新、团队规范变化时，记得同步更新这份文件。它是你和 Codex 之间的“合作章程”。
记住，AGENTS.md有 32 KiB 的大小限制。如果内容太多，考虑精简，或者将详细的规范移到项目 Wiki 中，在AGENTS.md里只做引用。
3. 从单次对话到流程固化：Skills 与 Rules 的实战配置
配置好了行为和规范，接下来要解决效率问题。总不能每次都从头开始描述任务吧？Codex 的 Skills（技能）和 Rules（规则）就是用来把常用流程打包成“快捷键”的。
3.1 Skills：把复杂任务变成一句命令
Skill 的本质是一个可复用的任务模板。它把一段复杂的提示词、一系列操作步骤，封装成一个简单的命令。比如，你可以创建一个contract-review技能，里面定义好审查合同的完整流程：先提取关键条款，再核对法律要件，最后生成风险报告。
Skill 放在哪里？
- 用户级技能 (
~/.agents/skills/): 你个人在任何项目都能用的技能，比如你的个人写作风格检查、常用代码片段生成。 - 项目级技能 (
REPO/.agents/skills/): 只针对当前项目的技能，比如这个法律项目特有的“生成借款合同”、“审查保密协议”流程。 - 系统级技能：通常由管理员部署，一般用户不用管。
创建一个 Skill 的步骤：
- 在对应的技能目录下新建一个文件夹，例如
~/.agents/skills/legal-doc-review/。 - 创建必需的
SKILL.md文件。 - 在
SKILL.md里定义技能。
一个法律文档审查技能的SKILL.md可能长这样：
--- name: legal-doc-review description: 对给定的法律文档（合同、协议等）进行结构化审查，识别潜在风险、格式问题并提供修改建议。 --- # 法律文档审查流程 ## 输入要求 请提供需要审查的文档全文或关键章节。 ## 审查步骤 1. **文档解析**：识别文档类型（如买卖合同、租赁合同、授权书等）和主要当事人。 2. **条款完整性检查**：对照该类文书的标准结构，检查必备条款是否缺失（如当事人信息、标的、价款、履行期限、违约责任、争议解决等）。 3. **风险点扫描**： * **模糊表述**：寻找“合理”、“及时”、“重大”等未量化的词语。 * **责任不对等**：检查双方权利义务是否显失公平。 * **法律依据**：核实引用的法律名称、条款是否准确、现行有效。 * **程序性缺陷**：检查生效条件、签署方式、通知送达条款是否明确可操作。 4. **格式与规范性检查**：检查编号体系、字体、间距、标题层级是否符合通用或指定规范。 5. **报告生成**：将发现的问题按“高风险”、“中风险”、“建议优化”三级分类，并附上具体位置（如“第3条第2款”）和修改建议文本。 ## 输出格式 请以 Markdown 表格形式输出审查报告，包含以下列：风险等级、问题位置、问题描述、修改建议、法律/依据参考。创建好后，在 Codex 对话中，你就可以直接输入$legal-doc-review加上你的文档内容，它会自动套用这套审查逻辑，而不需要你每次都重述一遍。
3.2 Rules：为自动执行设定安全边界
Skills 让 Codex 知道“怎么做”，Rules 则告诉它“什么能做，什么需要问我”。这是保障安全、防止误操作的关键。
Rules 使用 Starlark 语言（类似 Python）编写，放在~/.codex/rules/目录下。它的核心是定义一系列“模式-决策”对。
一个法律项目可能需要的 Rules 示例：
# ~/.codex/rules/legal_project.rules # 1. 允许所有 git 操作（通常安全） prefix_rule( pattern = ["git"], decision = "allow", justification = "版本控制操作是安全的" ) # 2. 允许使用项目指定的文档处理工具 prefix_rule( pattern = ["python", "-m", "pip", "install"], decision = "prompt", # 安装包需要确认 justification = "安装Python包可能影响环境" ) prefix_rule( pattern = ["python", "docx_handler.py"], # 假设这是我们的文档处理脚本 decision = "allow", justification = "这是项目批准的文档处理工具" ) # 3. 严格禁止任何形式的文件删除命令（防止误删合同原件） prefix_rule( pattern = ["rm", "-rf"], decision = "forbidden", justification = "禁止递归强制删除，以防误删重要文档" ) prefix_rule( pattern = ["del", "/f", "/s", "/q"], # Windows 下的强制删除 decision = "forbidden", justification = "禁止强制删除命令" ) # 4. 对任何涉及系统级或网络的操作进行询问 prefix_rule( pattern = ["curl", "wget", "ssh", "scp"], decision = "prompt", justification = "网络或系统操作需要明确授权" ) # 5. 对修改特定重要目录的文件进行询问 prefix_rule( pattern = ["*", "/templates/original/*"], # 保护原始模板目录 decision = "prompt", justification = "修改原始模板需要确认" )决策类型说明：
allow：自动放行。用于你完全信任的、低风险的操作（如git status,ls）。prompt：弹出询问，等你确认。用于有一定风险或你不希望完全自动化的操作（如安装依赖、修改核心文件）。forbidden：直接禁止。用于高风险操作（如删除命令、格式化磁盘）。
配置 Rules 的精髓在于“最小权限原则”。一开始可以严格一些，把所有你不确定的操作都设为prompt。随着你对 Codex 在特定任务上的行为越来越熟悉，再逐步将一些重复性高、模式固定的操作改为allow，以提升效率。
4. 进阶配置：Subagents、Hooks 与长期维护策略
当你和 Codex 的协作进入深水区，单一个“代理”可能不够用了。你需要它能够并行处理任务，或者在特定时刻自动执行一些清理、备份、日志记录操作。这就是 Subagents（子代理）和 Hooks（钩子）的用武之地。
4.1 Subagents：组建你的专属“律师团队”
想象一下，处理一个复杂的并购案件，你需要有人负责尽职调查（审阅文件），有人负责交易结构设计，还有人负责文书起草。Subagents 允许你创建多个具有不同专长和指令的“子代理”，让它们协同工作。
配置示例：在~/.codex/agents/下创建不同的代理配置文件：
审查专家 (
reviewer.toml)：name = "reviewer" description = "专注于法律文档的风险审查与条款分析" nickname_candidates = ["合规官", "风控员"] developer_instructions = """ 你的核心职责是发现风险，而不是创造内容。 1. 以挑剔的眼光审阅每一份文档。 2. 重点关注：权利义务对等性、违约责任合理性、争议解决条款有效性、保密与知识产权条款的完备性。 3. 所有发现必须引用具体的合同条款位置。 4. 输出必须结构化，按风险等级排序。 5. 对于不确定之处，明确标注“需结合具体案情及律师判断”。 """文书起草员 (
drafter.toml)：name = "drafter" description = "专注于根据模板和指令高效、规范地生成法律文书初稿" nickname_candidates = ["文书员", "起草助手"] developer_instructions = """ 你的核心职责是快速、准确地生成格式规范的文书初稿。 1. 严格遵循项目 AGENTS.md 中定义的文书格式和模板。 2. 优先使用项目提供的标准条款库。 3. 对于需要填充的变量（如当事人信息、金额、日期），确保清晰标记并提示用户输入。 4. 生成后，自动建议交由 `reviewer` 代理进行审查。 """
如何使用它们？在主会话中，你可以通过指令分配任务，例如：“请让reviewer代理分析一下这份保密协议的第5-8条。” 或者，在配置中设置工作流，让一个代理完成初步起草后，自动调用另一个代理进行交叉审查。
配置要点：
max_threads：控制最多可以同时运行多少个子任务。根据你的机器性能和任务需求调整，太多可能会拖慢整体响应。job_max_runtime_seconds：给单个任务设置超时，防止某个子代理陷入死循环。
4.2 Hooks：在关键节点插入自动化操作
Hooks 允许你在 Codex 生命周期的特定事件（如会话开始、工具调用前后）触发自定义脚本。这对于自动化日志、备份、数据清洗或触发外部系统非常有用。
一个实用的 Hook 场景：自动备份被修改的法律文档。
在config.toml中启用 Hooks：
[features] codex_hooks = true然后，创建一个 Hook 配置（例如hooks.json），监听文件写入事件，并自动复制一份到备份目录：
{ "hooks": [ { "event": "PostToolUse", "matcher": { "toolName": "FilesystemTool", // 匹配文件系统工具 "parameters": { "operation": "write" } // 匹配写操作 }, "hooks": [ { "type": "command", "command": "cp {{modified_file_path}} ./backups/$(date +%Y%m%d_%H%M%S)_{{(modified_file_path | basename)}}", "timeout": 5, "description": "自动备份被Codex修改的文件" } ] } ] }Hook 的常见用途：
- 会话开始 (
SessionStart)：自动加载项目环境变量，或发送通知。 - 工具调用前 (
PreToolUse)：检查命令是否在安全名单内，或对输入数据进行预处理。 - 工具调用后 (
PostToolUse)：记录操作日志、备份文件、将输出结果同步到数据库。
4.3 长期维护：配置不是一劳永逸
最后，也是最重要的一点：配置需要维护。
- 版本化你的配置：将你的
~/.codex/config.toml、重要的 Skills 和 Rules 文件纳入版本控制（如 Git）。这样可以在换机器、重装系统时快速恢复，也方便回溯配置变更历史。 - 定期审计 Rules：随着项目发展，有些当初设为
prompt的操作可能已经非常安全，可以改为allow来提升效率；反之，也可能需要添加新的forbidden规则来防范新出现的风险。 - 迭代 AGENTS.md 和 Skills：它们是活的文档。每当团队引入新的工具、规范，或者总结出新的高效工作模式，都应该及时更新它们。可以建立一个简单的流程，比如在团队周会上回顾并更新一次。
- 监控与日志：关注 Codex 的运行日志（如果有），特别是被 Rules 拦截或需要频繁 Prompt 的操作。这些地方往往是优化配置、提升自动化程度的关键切入点。
配置 Codex 的最高境界，不是让它变成一个什么都能做的“万能助手”，而是让它变成一个深刻理解你和你所在领域工作习惯的“专业搭档”。这个搭档的能力边界、行事风格、安全底线，都是由你通过这一层层配置精心塑造的。这个过程开始时可能需要一些投入，但一旦磨合完成，它带来的效率提升和可靠性保障，将是单纯“调几个参数”无法比拟的。