结论先说
- 本地 Codex 会话默认开启
cached(缓存)联网搜索,从 OpenAI 维护的索引缓存里取结果,而不是实时抓任意网页,用来降低网页提示词注入风险。 - 命令行单次要查最新网页,直接加
--search(等价于把当次运行切到live实时搜索)。 - 想持久修改或彻底关掉,在
~/.codex/config.toml顶层设置web_search,可选"cached"、"live"、"indexed"、"disabled"四档。 - 开启完全访问沙箱(如
--yolo或danger-full-access)时,web_search默认会自动变成"live"。 - 联网搜索是云端托管工具,和本地命令沙箱网络是两套独立开关:即使沙箱禁止本地
curl/npm联网,web_search没设为"disabled"时依然可用。

图:本站根据 Codex 官方文档:Web search 整理的示意图
本文根据 Codex 官方文档《Web search》《Sample Configuration》与《Managed configuration》整理,资料核对于 2026-11-18。配图为本站整理的示意图,不是界面截图。本站(bigolab.com)不是 OpenAI 官方网站。普通网页版搜索与 API 搜索工具见 ChatGPT 搜索怎么用 和 OpenAI API 联网搜索工具怎么用。
适用于谁
- 想让 Codex CLI 或桌面端查当天刚发布的第三方库更新说明,发现默认搜不到最新网页的人;
- 在涉密或离线合规项目里,需要彻底关掉 Codex 联网搜索或只允许查指定技术文档域名的人;
- 分不清「
web_search搜索工具」与「本地沙箱命令出网权限(network_access)」为什么互不影响的人。
一、四种联网搜索模式有什么区别
按官方《Web search》与示例配置的说明,web_search 顶层键支持四个取值,官方同时强调要把所有网页搜索结果当作不可信输入对待:
"cached"(默认):直接从 OpenAI 维护的搜索索引缓存返回预收录结果,不去目标站点实时拉页面。好处是速度快,且能减少(但不能完全消除)恶意网页里的提示词注入风险。"live"(实时):实时联网获取最新数据,适合查刚发布的框架变更日志、当天报错公告。需要注意,当你使用--yolo等完全访问沙箱运行时,默认档位会从cached自动切为live。"indexed"(索引门控):仅在请求经过搜索索引门控的前提下允许外部网页访问,介于纯缓存与完全实时之间。"disabled"(关闭):完全停用内置网页搜索工具。
二、命令行单次开关与 config.toml 持久配置

图:本站根据 Codex 官方文档:Web search 与托管配置整理的示意图
1. 命令行临时开启实时搜索:--search
平时保持默认 cached,偶尔有一回需要查最新外部资料时,在启动 CLI 时加上 --search 即可:
bash
codex --search "查看这个依赖库最新版本的破坏性变更说明"
在交互式对话记录和 codex exec --json 的事件流里,搜索动作会以 web_search 条目的形式清晰列出来。
2. 在 config.toml 里持久开启或关闭
打开 ~/.codex/config.toml(完整层级与语法见 Codex config.toml 完整详解),在所有 [表] 之前的根级区域写入:
toml
# 四选一:"cached" | "live" | "indexed" | "disabled"
web_search = "live"
如果只想允许搜索白名单内的技术文档站点,官方还支持配合 tools.web_search.allowed_domains 做域名过滤。IDE 扩展(如 VS Code)不单独维护搜索模式,直接沿用所连接的 Codex 主机设置。
3. 在桌面端与网页版做深度多源调研
除了写代码时顺带查文档,官方《Web search》还介绍了做多源长报告的做法:在桌面端切到 Work 打开 插件(Plugins) 启用 Deep research,或在网页版 Work 点输入框旁的 + 号选 Deep research,就能结合上传文件做跨信源对比报告。想在 Plus 或 Pro 上畅用 Work、Codex 与联网检索,可看本站 ChatGPT Plus 充值说明。
三、别把「搜索开关」和「沙箱命令联网」搞混
这是很多人在配安全策略时最容易踩的坑。官方文档专门划清了两者的边界(沙箱配置见 Codex 权限与沙箱设置):
web_search是官方托管工具,不走你本机权限配置里的网络代理(network_proxy)或命令域名白名单。就算sandbox_workspace_write.network_access是默认的false(禁止子进程自己发网络请求),只要web_search没关,Codex 仍能调用托管搜索。- 反过来也一样:你在搜索工具上配的
tools.web_search.allowed_domains只管内置网页搜索,管不住本地 Shell 命令、连接器(Connectors)或 MCP 服务器发出的网络流量。两边要各自独立配置。
四、团队管理员强制限制与自定义模型提供方
- 管理员锁定模式:如果公司不允许成员开启实时搜索(哪怕成员自己加了
--yolo),管理员可在后台requirements.toml里写allowed_web_search_modes = ["cached"](此时disabled仍隐式允许);写成空数组allowed_web_search_modes = []则强制全员只能处于disabled关闭状态。公司团队开通与管理可了解本站 ChatGPT Business 团队版定制。 - 自定义模型提供方:如果你接的是自定义 Responses API 提供方(配法见 Codex 怎么配置 Azure OpenAI 等官方模型提供方),官方说明其
supports_standalone_web_search默认是false,且独立网页搜索功能仍在开发中,只有提供方接口、所选模型和运行时三方同时支持才会生效。
常见问题
问:我已经设了 web_search = "live",为什么运行后还是只能用 cached 或搜不了?
答:先在 CLI 里运行 /debug-config,看是不是被项目级 .codex/config.toml、当前选用的 --profile 文件,或者工作区管理员下发的 allowed_web_search_modes 强约束覆盖了。
问:Codex Cloud(云端任务)里的联网规则也归 web_search 管吗?
答:本地会话由上述 web_search 控制;云端容器环境的互联网进出边界由云端环境自身的网络设置单独控制。
问:开启联网搜索会额外扣套餐额度吗?
答:网页搜索返回的结果会作为工具输出进入上下文,占用 token 并计入你当前的套餐使用限额(或按 token 扣 Credits / API 费用)。
相关教程
- Codex config.toml 完整详解
- Codex 权限与沙箱设置
- OpenAI API 联网搜索工具(web search)怎么用
- ChatGPT 搜索怎么用
- Codex 怎么配置 Azure OpenAI 等官方模型提供方
参考资料
- Codex 官方文档:Web search — https://learn.chatgpt.com/docs/web-search
- Codex 官方文档:Sample Configuration — https://learn.chatgpt.com/docs/config-file/config-sample
- Codex 官方文档:Managed configuration — https://learn.chatgpt.com/docs/enterprise/managed-configuration
0 条评论
还没有评论,来抢沙发~