web_search

Values

web_search is a plain string. Four modes, and they differ by how far Codex is allowed to reach off your machine.

Value	What it does
cached (default)	Answers from OpenAI’s maintained index. No live fetch.
indexed	Search queries go out live, but page fetches are capped to URLs the index admits.
live	Unrestricted live search and page retrieval.
disabled	Removes the web search tool from the model entirely.

The mode lives on the top-level key. Fine-tuning the tool itself is a separate object, tools.web_search, which carries context_size (low/medium/high), allowed_domains (array of strings), and location (an object of country, region, city, timezone). You can run both together.

# ~/.codex/config.toml
web_search = "indexed"

# tune the tool itself (optional)
tools.web_search = { context_size = "medium", allowed_domains = ["docs.rs", "developer.mozilla.org"] }

When to change it

1. You need current info. A library shipped a breaking change this morning, or you want today’s release notes read back to you. cached will not have it. Set live, or run codex --search to flip a single session live without touching the file. That flag is the official global option that sets web_search = "live" instead of the default.
2. You want fresh search but you’re wary of prompt injection from random pages. indexed plus an allowed_domains list is the middle setting: queries stay live, page fetches stay on domains you trust.
3. Locked-down or air-gapped work. disabled takes the tool off the table so the model can’t reach out at all.

Gotchas

The big one is that cached is the default and it can be stale. People expect live search and quietly get an index that’s behind, which is the whole reason the “stale by default” complaint exists. If freshness matters, don’t rely on the default.

If you’re copying an old config, the four predecessors here (features.web_search, features.web_search_cached, features.web_search_request, and the boolean tools.web_search) are deprecated. The _cached flag maps to cached, the _request flag maps to live, and a bare boolean maps onto this key. They still parse, but they’re the dead form.

indexed is the newest mode. On builds where it just landed it may sit behind [features] standalone_web_search = true, which is how the maintainer gated it in the PR. If indexed seems to no-op on your version, that flag is the first thing to check.

Related settings

• sandbox_workspace_write.network_access: live and indexed both need the network open, and a locked sandbox will starve them.
• mcp_servers.<id>.command for the other half of Codex’s toolset when the built-in search isn’t enough.