Codex 的配置文件怎么写，项目级怎么覆盖用户级
Codex 的配置是分层的，从命令行覆盖到内置默认一共七层，越靠近当前项目的越优先。用户级放在 ~/.codex/config.toml，项目级放在 .codex/config.toml 且只在信任该项目时才加载。实务上最重要的一条判断是：模型和推理强度可以放全局，沙箱和审批不要放全局——读报表、生成内容、抓数据这三类活需要的权限档位不同，写死一套全局配置要么处处受限，要么处处放开。
Codex 的配置能力不复杂，但有一条实务判断值得先说：
模型、推理强度这类偏好，可以写进全局配置；沙箱和审批这类权限，不要写死在全局。
原因很简单。跨境运营的活分好几类：读报表只需要只读权限，生成 Listing 需要写权限，抓竞品数据还需要联网。写一套全局配置，只有两个结果：
两种都不对。正确的做法是全局只放偏好，权限按项目给。这篇讲怎么做到。
两个位置：
~/.codex/config.toml，对所有项目生效.codex/config.toml有一条限制必须知道：项目级配置只在你信任该项目时才会被加载。
这是个安全设计。想想反面：如果 clone 下来的任意仓库，它自带的 .codex/config.toml 就能把沙箱调成全权限，那沙箱等于不存在。所以 Codex 要求你先明确信任这个项目。
对跨境团队的实际影响：你自己建的工作目录，信任一次之后就一直生效；从外面拿来的项目要留个心眼，看一眼它带没带配置文件。
Codex 从多个地方读配置，从高到低是：
--config 覆盖--profile 指定~/.codex/config.toml/etc/codex/config.toml实际用到的主要是 1、2、4 这三层。记住一句话就够：越靠近当前项目的配置优先级越高，命令行永远最高。
第 2 层里「从根目录到当前工作目录」这个细节值得留意：如果你的目录是嵌套的，每一层都可以有自己的配置，越深的越优先。这和后面 AGENTS.md 的合并逻辑是一致的，两者可以配合用。
配置文件是 TOML 格式，长这样：
# 用哪个模型
model = "..."
# 推理强度
model_reasoning_effort = "high"
# 什么时候停下来问
approval_policy = "on-request"
# 能碰到什么
sandbox_mode = "workspace-write"
# 工作区可写模式下的细项
[sandbox_workspace_write]
network_access = false
逐条说明。
用哪个模型。
**这里不写具体模型名。**模型迭代比任何教程都快，写死一个版本号过几个月就是错的。实际做法是进会话敲 /model 看当前有哪些可选，或者以官方文档为准。
控制它想多深，直接影响耗时和成本。
实务上的分法：
如果你发现某类任务经常要返工，先试着调高这一项，再考虑改规则。
这两个是权限相关的核心，一个管「什么时候问你」，一个管「能碰什么」。它们是正交的两个开关，下一篇专门讲。
这里只说和配置有关的部分：这两项最适合放在项目级配置里，而不是用户级。
工作区可写模式下要不要给网络，默认是 false。
跨境团队一定会撞上这条——抓竞品页面、调接口都需要它。但同样建议不要在全局打开，理由下一篇细说。
不想改文件、只想这一次生效，用 -c：
codex -c log_dir=./.codex-log
嵌套的配置项用点号连起来：
codex -c 'sandbox_workspace_write.network_access=true'
这个写法在两种场合特别有用：
第二种是推荐做法。比如平时不给网络，只在做竞品调研那一次临时开。做完关掉终端，权限就回到默认。
除了自己写配置，Codex 有几个内置的权限 Profile：
:read-only:workspace:danger-full-access名字已经说明了各自的范围。用 Profile 的好处是不用记具体配置项，切换也快。
对刚上手的人，这是个比手写配置更稳的起点：先用 :read-only 把流程跑通，确实需要写文件了再换 :workspace。
回到开头那条判断，落到具体做法上。
~/.codex/config.toml：
model = "..."
model_reasoning_effort = "high"
就这么多。不写沙箱，不写审批，不写网络。
报表分析目录 ops/reports/.codex/config.toml：
sandbox_mode = "read-only"
approval_policy = "on-request"
只读。它能读你的广告报表、订单导出、库存表，能跑脚本算，但改不了任何东西。分析类的活全放这里。
内容生成目录 ops/content/.codex/config.toml：
sandbox_mode = "workspace-write"
approval_policy = "on-request"
[sandbox_workspace_write]
network_access = false
能写文件，但没有网络。生成 Listing、写 SEO 信息、出周报，都在这个目录里干。
调研目录 ops/research/.codex/config.toml：
sandbox_mode = "workspace-write"
approval_policy = "on-request"
[sandbox_workspace_write]
network_access = true
唯一一个开网络的目录。抓竞品、查关键词在这里做。
**第一，不用每次纠结权限。**进哪个目录，权限就是配好的那一档。你的注意力可以放在活本身上。
**第二，数据也跟着分开了。**工作区正好是沙箱的边界，所以目录分开意味着广告报表不会和客户邮件混在一个可写范围里。调研目录开着网络，但它里面只有调研数据，没有你的客户名单。
**第三，出问题好定位。**如果发现某个操作不该发生，看它是在哪个目录跑的，就知道当时的权限档位是什么。
配置里最常动的一项就是模型。有三种改法，作用范围不同。
会话里临时换，进会话敲：
/model
写进配置，长期生效：
model = "..."
跟模型相关的还有两项值得知道：
model_reasoning_effort = "high" # 想多深
model_context_window = 200000 # 这个模型可用的上下文长度
model_context_window 在接非官方服务商时特别有用——如果对方的模型上下文和默认值不一致，不写清楚容易出现莫名其妙的截断。
再说一次前面提过的原则：**别把模型名写死在教程和脚本里。**模型迭代比文档快，用 /model 看当前有什么可选，或者以服务商文档为准。
这是 Codex 和很多同类工具做法不一样的地方，也是网络受限或者想控成本时最有用的一块。
Codex 允许你在配置里定义自己的模型服务商，然后指过去。
model_provider = "my-provider"
model = "服务商的模型名"
[model_providers.my-provider]
base_url = "https://服务商给的地址"
env_key = "MY_PROVIDER_API_KEY"
两个必填字段：
base_url：服务地址env_key：从哪个环境变量读密钥注意第二条的设计——**密钥不写在配置文件里，只写变量名。**这意味着配置文件可以安全地提交到版本库，密钥各人放各人的环境里。前面说的「配置进版本库、密钥不进」，这个字段就是为它准备的。
还有几个按需使用的字段：
wire_api：协议类型http_headers 和 env_http_headers：需要额外请求头时用，后者从环境变量取值query_params：需要在请求上带查询参数时用wire_api 目前只支持 responses 这一种协议。
实际含义是：**不是随便一个「OpenAI 兼容」的地址都能直接接上。**对方的接口得讲这套协议，才能作为 Codex 的服务商用。
接之前先确认这一点，能省掉很多「配好了但一直报错」的排查时间。
有三个 ID 是内置的、不能覆盖：
openaiollamalmstudio后两个是本地模型的运行环境。它们内置在这里，意味着跑本地模型是一条官方支持的路径，不需要自己拼配置。
对两类人有用：
代价也要说清楚：本地模型的能力和云端有差距，多步任务的规划、长上下文的处理、工具调用的准确度都会打折。所以合理的用法不是全部本地化，而是按数据敏感度分流——常规分析用云端，涉及敏感数据的那部分用本地。
这个分流可以直接落到目录上：敏感数据放一个专门目录，那个目录的 .codex/config.toml 里指向本地服务商。进那个目录干活，用的就是本地模型。
前面讲的都是 CLI。Codex 还有 IDE 扩展和云端两个入口，配置方式不完全一样。
AGENTS.md 和 .codex/config.toml 仍然生效，因为它们跟着项目走对跨境运营的实际建议：**主力用 CLI。**运营的活基本围绕本地文件——导出的报表、整理好的资料、生成的报告，CLI 在目录里干活路径最短，配置和沙箱边界也最清楚。IDE 扩展适合边看边改，云端适合跑长任务，都可以后面再说。
改完别假设生效了。进会话看：
/status
它会显示当前会话实际用的模型、沙箱和审批设置。
如果和你写的不一致，按这个顺序查：
第 2 条是最常见的原因，也最容易被忽略，因为它不报错，就是静静地不生效。
.codex/config.toml 建议提交到版本库，和团队共享。
理由是它定义的是「这类活允许干到什么程度」，属于团队约定，不是个人偏好。同事 clone 下来，权限档位是一致的，不会出现你这边只读、他那边全开的情况。
但有一条例外：**任何带密钥的东西都不要写进项目配置文件。**那种东西走环境变量或本地文件，不进版本库。这条和平时管数据库密码是一样的道理。
配置里最关键的两项是沙箱和审批。下一篇把这两个开关的所有取值、组合效果、每类活该配哪一档讲完，包括跨境场景里最容易踩的那个默认设定。
作者
大阪烧鸟
大阪烧鸟，关注 AI 在跨境电商运营中的实际应用、Shopify 独立站与日本商业观察，偏爱把复杂问题拆成可执行的方法。
