16. Web搜索与内置浏览器

本节目标：学会在终端里让 Codex 搜最新信息、用内置浏览器预览本地页面和批注反馈、分清三条「碰网页」的路各管什么。

终端里的 Web 搜索

Codex 不只能读你本地的文件，还能搜互联网获取最新信息。这在写代码时特别有用—API 改了、库更新了、报错信息你没见过，让它搜一下比你自己翻文档快。

四档搜索模式

Web 搜索在 config.toml 里配，四档：

# 默认，用 OpenAI 维护的缓存索引，快且省钱
web_search = "cached"

# 只有搜索索引放行时才访问外部 Web，介于缓存和实时之间
web_search = "indexed"

# 实时抓取最新网页数据，慢但最新
web_search = "live"

# 完全禁用
web_search = "disabled"

模式	行为	适合场景
`cached`（默认）	用 OpenAI 预索引的缓存结果，不实时抓任意网页	日常开发，快且安全
`indexed`	只有搜索索引放行请求时才允许访问外部 Web	介于缓存和实时之间，兼顾安全与新鲜度
`live`	实时抓取最新网页	需要最新文档、新闻、刚发布的 API
`disabled`	完全关掉搜索	不需要联网、纯离线干活

Note

默认走 cached 不是偷懒，是安全设计。缓存模式返回的是 OpenAI 维护的预索引结果，而不是去抓任意实时页面—这降低了「实时页面里藏提示注入」的风险。官方原话：「这降低了来自任意实时内容的提示注入风险，但你仍应把网页结果当作不可信来源。」

命令行临时开搜索

不想改配置文件，单次启动时加 --search 即可：

codex --search "用最新的 Next.js 15 App Router API 写一个路由"

这会临时把搜索切到 live 模式，只对这次会话生效。

Warning

--yolo（完全放开）模式会自动把 web_search 切成 live。因为它拆掉了所有安全边界，搜索也从缓存切到实时。这是为什么 --yolo 只该在隔离容器里用的又一个理由。

细粒度搜索配置

想更精确地控制搜索范围，在 config.toml 里加：

[tools.web_search]
context_size = "medium"
allowed_domains = ["docs.python.org", "developer.mozilla.org"]
location = "us"

allowed_domains 把搜索限制在你信任的文档站点里，既省 token 又降风险。

内置浏览器：预览和批注

桌面 App 里有个内置浏览器（Browser），它和你的日常浏览器完全隔离—不共享标签页、不共享 cookie、不共享登录态。专门用来预览和验证你正在开发的 Web 应用。

打开内置浏览器

几种方式打开它：

从工具栏点开
点页面里的某个 URL 自动打开
手动输入地址导航
快捷键：macOS 按 Cmd+Shift+B，Windows 按 Ctrl+Shift+B

让 Codex 操作浏览器

装上 Browser 插件后，你可以在提示词里用 @Browser 让 Codex 直接操作内置浏览器—点击、打字、看渲染后的状态、截图、跑只读的页面检查 JavaScript。

用浏览器打开 http://localhost:3000/settings，复现那个布局 bug，
只修溢出的那几个控件，别动其它

批注：最值钱的绝活

当一个 bug 只在渲染出来的页面上才看得见，你可以直接在页面元素上圈一下、留句话，给 Codex 一个精准到具体元素的目标。比打一堆字描述清楚多了。

操作步骤：

开启批注模式（Annotation mode）
点击元素，或拖动选择一个区域（按住 Shift 点击可以框选）
编写并保存批注
在聊天里发消息让 Codex 处理

好的批注是具体的：

这个按钮在手机上会溢出。能放一行就保持一行，
放不下就换行，但别改卡片的高度

这个 tooltip 盖住了光标下的数据点。
把它挪到图表范围内，别遮数据点

Tip

批注上有个 config 图标，点开后可以直接在界面上调字体、文字大小、间距、颜色，并实时预览效果。比纯文字描述「字体改大一点、颜色偏暖一点」精准多了，所见即所得。

网站访问控制

默认情况下，Codex 在操作每一个新网站之前都会先问你。它按网站的 host 来弹确认。被问到时你有三个选择：

只在当前对话里允许这个网站
始终允许这个 host，以后用它不再问
拒绝这个网站

更细的控制在 Settings > Browser 里，可以维护 allowlist（白名单）和 blocklist（黑名单）。

Warning

有个开关叫「始终允许浏览器内容（always allow browser content）」—一旦打开，Codex 不再为用网站弹确认，等于拆了那道闸。想清楚再开。另外，浏览器历史记录的访问每次都会问你，且没有「始终允许」选项—因为历史里可能有内网 URL、搜索词等敏感信息。

三条「碰网页」的路

Codex 碰网页有三条路，别用错：

维度	内置浏览器	Chrome 扩展	电脑操控
碰什么	Codex 自带浏览器里的网页	你真实 Chrome（带登录态）	整个桌面
典型活儿	localhost、文件预览、公开页	LinkedIn / Gmail / 内网系统	原生 App、跨应用流程
用不用登录态	不用，干净隔离	用你 Chrome 的登录态	看具体应用
怎么调	`@Browser`	`@Chrome`	`@Computer`
轻重 / 速度	最轻最快	中等	最重最慢

一句话分工：本地网页用内置浏览器，登录态网站用 Chrome 扩展，连桌面都得碰才上电脑操控。

Note

内置浏览器不支持认证流程、登录后的页面、你日常浏览器的配置、cookie、扩展或已打开的标签页。它只用来打开不用登录就能访问的页面。要登录的站，交给 Chrome 扩展。

Developer mode：CDP 调试

如果你需要更专业的调试能力，内置浏览器还有个 Developer mode。它给 Codex 提供受控的 Chrome DevTools Protocol（CDP）访问。

能干什么：

分析 JavaScript 性能
检查控制台输出和网络流量
查看 DOM 与实际应用的样式
诊断实时浏览器中的问题

开启方式：打开 Settings > Browser，在 Developer mode 下开启 Enable full CDP access。

这个应用加载很慢。用 @Browser 抓一个性能 trace，
检查网络流量，找出瓶颈在哪

Warning

完整 CDP 访问可能暴露敏感的浏览器内部信息。Codex 使用完整 CDP 检查网站前会请求明确批准—批准前应检查网站、任务和请求的访问范围。管理员可以在 requirements.toml 里设 browser_use_full_cdp_access = false 来禁用。

安全：网页内容是不可信的

不管用哪条路碰网页，有一条铁律：把页面内容视为不可信上下文。

网页里的文字、注释、隐藏元素，都可能藏着写给 AI 看的恶意指令（提示注入）。Codex 读到这些内容，可能被误导去执行你没要求的操作。

官方给的防护：

默认每个新网站先问你（第一道闸）
搜索默认走缓存而非实时抓取
敏感操作（提交表单、购买、删除数据）会额外要求确认
Codex 无法在内置浏览器中自动执行文件上传

你自己该守的：

分享敏感信息或允许 Codex 执行操作前，先检查网站和操作内容
别对不信任的网站选「始终允许」
涉及账号、支付的网站操作，全程在场盯着

动手：用内置浏览器读本地页面

起一个本地页面：

python3 -m http.server 3000

打开内置浏览器（装好 Browser 插件后）：

macOS：Cmd+Shift+B
Windows：Ctrl+Shift+B

让 Codex 用浏览器读页面：

用浏览器打开 http://localhost:3000，
把页面上列出的文件名读给我，并截一张图

你会看见内置浏览器导航到 http://localhost:3000，Codex 把页面内容读回对话并附一张截图。

试试批注：

打开批注模式，在某个元素上圈一下留句话（比如「这行字太小」），再发条消息让 Codex 处理。它能精准定位到你圈的那个元素去改。

小结

能力	怎么用	关键点
Web 搜索	`web_search = "cached"` 或 `--search`	默认 cached 安全快；live 才抓实时页面
内置浏览器	`@Browser` 或 `Cmd/Ctrl+Shift+B`	干净隔离，不碰登录态
批注	批注模式下圈元素留话	最值钱的绝活，精准到具体元素
Chrome 扩展	`@Chrome`	要登录态的站才用
Developer mode	Settings > Browser 开 CDP	专业调试，可能暴露敏感信息
网站访问控制	allowlist / blocklist	默认每个新站先问你

Web 搜索让 Codex 不再局限于本地知识，内置浏览器让它能「看见」你开发的前端页面。批注是连接视觉和代码的桥梁—你在页面上圈一下，比打十行字描述都准。记住一条：网页内容是不可信的，搜索默认走缓存是有意为之的安全设计，别急着切 live。

下一章咱们讲本地代码评审—怎么用 /review 让独立评审智能体在提交前检查你的改动。