Codex 联网搜索的四种模式：默认 `cached` 既不是关闭也不是实时
Codex（OpenAI Codex）的联网搜索是个特别容易被误会的地方。我见过两种相反的误会：一种是「我没加 --search，所以它肯定完全不上网」；另一种是「我配了搜索，那它给我的库版本号应该是最新的」。这两句话在 codex-cli 0.147.0 这个版本上都站不住，原因是同一个——这个开关不是二值的，它有四档，而默认值落在中间。
下面全部只讲 Codex CLI。IDE 扩展和桌面应用那两个面我们没有实测，不在本文范围内。
一、先看官方给的这一行
官方《Configuration Reference》页里，联网搜索相关的键只有很小的一块：
| 配置键 | 默认值 | 取值 |
|---|---|---|
web_search | cached | disabled / cached / indexed / live |
tools.web_search | — | 布尔或表，可配上下文大小与域名过滤 |
这张表要这么读：顶层 web_search 是模式选择器，四选一，默认落在 cached。 它既不是 disabled，也不是 live。所以「默认是关的」和「默认是实时的」这两种说法都不对。
另外要注意 tools.web_search 是另一个键，不是同一个东西换了个写法。它在官方表里的类型是「布尔或表」，能配上下文大小与域名过滤。也就是说，模式选哪一档归 web_search 管，而工具本身的细粒度参数（比如你想限制只允许某些域名）归 tools.web_search 管。把这两个混着用，最典型的后果就是改了半天没有你想要的效果。
二、四档里我能负责任地讲清楚的部分
必须先把话说死：官方的 Configuration Reference 页在这一格里只给了枚举值和默认值，并没有逐档展开每种模式的抓取行为。所以 cached 和 indexed 到底差在哪、缓存有多新，我这里不会给你一个听上去很顺的解释——那只能靠猜，而猜出来的机制说明比不写更有害。
能确定的是这两头：
disabled是关闭这一档。live是实时这一档，因为 CLI 侧的--search明确对应「开启实时联网搜索」。
中间的 cached 和 indexed，如果你真的要在它们之间做选择，别照着单词猜，去官方《Web search》页（/docs/web-search）确认。这里有个省事的技巧：learn.chatgpt.com 的文档页 URL 后面加 .md 后缀就能拿到 Markdown 版本，站点还提供 llms.txt（页面索引）和 llms-full.txt（合并全文），可以直接喂给手边的 AI 工具去问「cached 和 indexed 的区别」，比自己在网页上翻快。
判断依据：真正需要你在 cached 与 indexed 之间纠结的场景其实很少。大多数人的诉求只有三种——「我不想让它自己上网」（选 disabled）、「我要它拿到当下的信息」（走 live）、「我不确定」（那就别动，默认就是 cached）。只有当你已经明确知道自己要的是某种索引式的检索行为时，才有必要去啃那一页文档。
三、--search 到底改了什么
codex --help 里对 --search 的原文说明有三层信息（本机在 codex-cli 0.147.0（Windows 11）上执行 codex --help 读到）：
- 开启的是实时联网搜索；
- 启用后，原生 Responses 的
web_search工具对模型可用； - 无逐次调用审批。
第三条是这篇里最该被记住的一句。它意味着一旦你在这次会话里加了 --search，模型什么时候搜、搜几次，不会像沙箱提权那样弹出来问你一句。你要么在启动这次会话时就接受这一点，要么就别加。
由此得到一条很实际的判断依据：--search 是会话级的临时决定，适合「我这一次要查点东西」；它不适合当成常态默认值随手写进别名里。 如果你的工作目录里有不适合外发的内容，加 --search 之前最好想一遍——不是说加了就一定会出事，而是这条链路上没有一个逐次确认的关卡替你兜底。
反过来，如果你要的是持久生效而不是这一次，那就该去改配置，而不是每次敲 --search。
四、把模式写进配置：三种粒度
从临时到持久，有三种改法，粒度依次变大。
粒度一，只影响这一条命令，用顶层的 -c：
codex -c web_search="live" exec "查一下这个依赖最近的破坏性变更"
-c, --config <key=value> 的官方说明是：覆盖 ~/.codex/config.toml 里的值，点号路径表示嵌套，value 按 TOML 解析，解析失败则按字面字符串处理。官方给的示例本身就是带引号的（-c model="o3"），所以这里的 "live" 我也照着加了引号——虽然按「解析失败按字面字符串处理」的规则，不加引号大概率也能落成字符串，但让它走正常的 TOML 字符串解析路径显然更稳。
还有一点跟 Codex 本身无关，但抄命令时容易撞上：官方示例里那种 -c 'sandbox_permissions=["disk-full-read-access"]' 的写法用的是 POSIX shell 的引号习惯。本机的实测环境是 Git Bash，换到 PowerShell 请按该 shell 自己的引号规则改写——这一路本文没有实测过，不给具体结论。
粒度二，某一类工作长期生效，用配置档。-p, --profile <CONFIG_PROFILE_V2> 会把 $CODEX_HOME/<name>.config.toml 叠加到基础用户配置之上。于是你可以让日常会话保持默认，只在调研型的工作里切到实时：
# ~/.codex/research.config.toml
web_search = "live"
codex -p research
粒度三，全局默认，直接写 ~/.codex/config.toml 的顶层：
web_search = "disabled"
以上为按官方文档键位组合的示例，未逐项实测，以官方文档为准。
这里顺手说一个边界：本机没有实测过命令行 --search 与顶层 web_search 配置之间谁压谁，所以我不会告诉你写了 disabled 就一定拦得住某次会话。如果你的目的是「我个人默认不想联网」，写 disabled 是合适的，它就是一条个人偏好设置；但如果你的目的是「团队里谁都不许联网」，别把这一行当强制闸门用，那种约束该去看官方的受管配置那条线。
五、老配置要迁移：三个已弃用的开关
如果你的 config.toml 是从更早的版本一路带过来的，或者你参考的教程有点年纪，很可能会看到这类写法：
[features]
web_search = true
web_search_cached = true
官方 Configuration Reference 在特性开关那一节明确写了：features.web_search、features.web_search_cached、features.web_search_request 均已弃用（deprecated），改用顶层 web_search。
本机在 codex-cli 0.147.0（Windows 11）上执行 codex features list，输出是三列（特性名、阶段、当前生效值），其中能看到：
| 特性 | 阶段 | 生效值 |
|---|---|---|
web_search_cached | deprecated | false |
web_search_request | deprecated | false |
standalone_web_search | under development | false |
这份 list 和官方文档是对得上的：web_search_cached、web_search_request 在本机这一版上都带着 deprecated 标签，官方 Configuration Reference 也把这三个 features.* 开关标为弃用、改用顶层 web_search。两边指向同一件事——老写法该迁了。
至于「我现在到底处于哪一档」，答案要去配置本身里找：打开 ~/.codex/config.toml，看顶层那个 web_search 写的是什么；没写就是默认的 cached。
顺带说一个高频误读：codex features list 里除了 stable / experimental / deprecated / under development，还有 removed 这一档，而且本机观测到部分 removed 项的生效值是 true。所以 removed 的意思更接近「这个开关本身不再需要你控制、行为已经固化」，不等于功能被删掉了。看到 deprecated 就该动手迁移，看到 removed 反而不用慌。
六、第三方模型接进来时的额外一档
上面那张表里 standalone_web_search 阶段是 under development（本机 0.147.0 上生效值 false），这是个还在开发中的特性，不该当稳定能力来规划。
与之呼应的是，官方在自定义模型提供方（model_providers.<id>）下有一个 supports_standalone_web_search 键，默认 false。
判断依据：如果你不是直连官方提供方，而是自己配了 model_providers 接别的服务，那么「联网搜索能不能用」这件事就不只取决于你把 web_search 设成了哪一档，还取决于那个提供方这边的支持声明——而它默认是不支持的。所以「我在官方账号下用得好好的搜索，换到自建 provider 就没了」，先去看这个默认值，别一头扎进 web_search 那四个取值里反复试。
同一节里还有一条更硬的前提：wire_api 默认 responses，且官方明确只支持 responses。这条决定了不是随便一个 OpenAI 兼容端点都能接进来。至于具体某家服务行不行，我没验证过，不评论。
七、别改错键：三组容易混的网络开关
这是我认为最值得单独拎出来的一段。Codex 配置里跟「网络」沾边的键至少有三组，长得像，管的完全不是一回事：
| 你想做的事 | 该看的键 |
|---|---|
| 模型能不能自己发起网页搜索、用哪一档 | 顶层 web_search；细粒度参数看 tools.web_search |
| 沙箱里跑的命令（比如装依赖、拉接口）能不能出网 | sandbox_workspace_write.network_access |
| 某个权限档下的联网策略、域名允许/拒绝 | permissions.<name>.network.enabled / .mode（limited 或 full）/ .domains.<pattern> |
判断依据：先问自己「是模型要查资料，还是我的命令要连服务器」。如果是后者——npm install 装不上、curl 连不通——那把 web_search 从 cached 改成 live 一点用都没有，你要动的是沙箱和权限档那两组键。反过来，如果你只是希望模型查文档时更准，去动 sandbox_workspace_write.network_access 同样文不对题。
至于域名白名单，也分两处：tools.web_search 的表里可以配域名过滤，permissions.<name>.network.domains.<pattern> 是权限档层面的域名 allow/deny（支持精确主机与通配）。前者约束的是搜索工具，后者约束的是权限档的联网。想清楚你要限的是哪一层再动手。
另外提一句，官方还有一个 features.network_proxy，本机 0.147.0 上阶段是 experimental，生效值 false。实验阶段的东西可以试，但别写进团队的标准配置。
八、改完怎么确认真的生效了
配置改了没反应，八成不是模式选错，而是配置压根没加载成功。这一步有一手实测结论可用。
本机在 codex-cli 0.147.0（Windows 11）上故意传了一段语法不合法的 TOML：
codex -c 'features=[unclosed' doctor --summary
命令没有崩溃退出，doctor 照常跑完，但在输出里出现了这一行：
✗ config config could not be loaded - Fix the reported config error, then rerun codex doctor.
这条结论的价值在于：Codex 在配置坏掉时不会拦着你，它会带着「配置没加载」继续跑。 所以「我明明改了 web_search，行为一点没变」的第一步排查不是再改一遍配置，而是跑一次 codex doctor --summary，先看 config 这一行是 ✓ loaded 还是 ✗。
codex doctor --json 的官方说明是输出脱敏（redacted）的机器可读报告，所以真要贴给同事或提 issue，用 --json 这一份比截屏安全。
还有个看起来很像救命稻草、但有边界的选项：--strict-config，官方说明是 config.toml 里出现本版本不认识的字段时直接报错退出。听上去正好能拦住 web_search 拼错。但本机在 codex-cli 0.147.0（Windows 11）上实测：
codex -c model_reasoning_effortt=high --strict-config exec --help
结果是正常打印了 help，没有报未知字段错误。也就是说，校验发生在真正加载配置去跑会话的时候，--help 这类不进入会话的路径不触发。所以别把 --strict-config 理解成「任何情况下都能帮我抓拼写错误」，你得用一条真会起会话的命令去验它。
九、什么时候干脆别折腾这个
三种情况我建议直接跳过本文的所有配置：
一是你只是偶尔要查点资料——加 --search 起一次会话就够了，别为此改全局配置。
二是你的问题其实是「命令连不上网」——那是沙箱和权限档的事，方向从一开始就错了。
三是你想靠 web_search = "disabled" 做合规管控——本机没有实测过它与命令行 --search 的优先级关系，把一条个人配置当强制闸门本身就不牢靠。团队级的强制约束要去看官方的受管配置那条线，那部分我们没有实测，不在这里展开。
最后回到开头那句：这个版本上默认值是 cached。不是关，也不是实时。 你在做任何关于「它到底会不会联网 / 拿到的信息有多新」的判断之前，先把这一行记住，后面的选择才不会跑偏。
相关阅读
- 第一次用 Codex CLI：先把这五件事定下来
- Codex 生命周期钩子怎么配：事件、匹配器组与 Windows 专属覆盖
- Codex 多代理配置怎么定：并发上限、子代理默认模型与角色定义
- Codex 的六个使用面：一张图看懂该用哪个
本文依据 Codex 官方文档（learn.chatgpt.com/docs/ 的《Configuration Reference》页面）整理，核对日 2026-08-09；文中标注「本机实测」的部分基于 codex-cli 0.147.0 / Windows 11 环境下的只读命令输出（仅只读命令，未发起模型对话请求）。文中提到的《Web search》页仅作为进一步查阅的指路，本文未取用其内容。产品功能、模型与价格以官方最新说明为准。