Codex has a built-in web search tool that is on by default for local chats, and by default it runs in cached mode: results come from an OpenAI-maintained index rather than live pages. Pass --search or set web_search = "live" in config.toml for live results, or set web_search = "disabled" to turn it off.
This guide covers the four search modes, how to set them in the CLI, IDE extension and desktop app, how domain filters work, how web search relates to sandbox networking and Codex Cloud internet access, and the risks to keep in mind. Facts come from OpenAI's Web search page, Config basics and the configuration reference, all read on 26 October 2026.
How does web search work in Codex?
Web search is a first-party hosted tool. When Codex decides it needs outside information, or you ask it to look something up, it calls the tool and the search shows up in the transcript like any other tool call.
Where you see it depends on the surface:
| Surface | How search appears | How it is configured |
|---|---|---|
| Codex CLI | web_search items in the interactive transcript and in codex exec --json output |
--search flag or web_search in config.toml |
| IDE extension | Search activity in the chat transcript | Uses the connected Codex host's search mode |
| ChatGPT desktop app | Search activity recorded with the other tool calls | Local Codex chats use cached search by default; the page gives no app-specific switch |
| Codex Cloud | Not covered by the local setting | Per-environment internet access settings |
OpenAI's docs give one rule that applies everywhere: "Treat all web results as untrusted input." A search result can contain text written to steer an agent, so treat what comes back the way you would treat a stranger's pull request.
What are the Codex web search modes?
The web_search key takes one of four values. The configuration reference lists them as disabled | cached | indexed | live, with cached as the default.
| Mode | What it does | When to use it |
|---|---|---|
cached (default) |
Returns results from an OpenAI-maintained index without external web access | Everyday work: docs lookups, error messages, general questions |
indexed |
Permits external web access only when the search index gates the request | When you want some fresh access but still gated by the index |
live |
Fetches the most recent data from the web, same as --search |
Release notes, changelogs, anything newer than the index |
disabled |
Removes the tool | Sensitive repos, offline work, strict policies |
The config basics page explains why cached is the default: cached mode "returns pre-indexed results instead of fetching live pages," which "reduces exposure to prompt injection from arbitrary live content." The web search page is careful to say it lowers the risk but doesn't remove it.
One exception changes the default. If you run Codex with --yolo or another full access sandbox setting, web search defaults to live results. That is worth knowing, because a full access run plus live search is the combination with the most exposure.
How do you turn on live web search?
For a single run in the CLI, add --search. The CLI reference describes it as enabling live web search, setting web_search = "live" instead of the default "cached":
codex --search "Summarize the latest release notes for this dependency"
To make it the default, set the mode in ~/.codex/config.toml:
web_search = "live"
# web_search = "cached" # default
# web_search = "indexed"
# web_search = "disabled"
For a one-off override of any config key without a dedicated flag, Codex accepts -c key=value, parsed as TOML. Our Codex config.toml guide explains the layering, so you can also put web_search = "live" in a profile file and switch with --profile, as covered in the Codex profiles guide.
In the IDE extension, OpenAI's docs describe no separate switch: the extension uses the connected Codex host's search mode, and the CLI and IDE extension share the same configuration layers. Ask Codex to search while you work and the activity appears in the chat.
How do you limit which sites Codex can search?
The tools.web_search key accepts either a boolean or an object. The configuration reference lists the object form as { context_size = "low|medium|high", allowed_domains = [string], location = { country, region, city, timezone } }. OpenAI doesn't publish a full example, so the snippet below is built from that documented type. It is valid TOML, and Codex CLI 0.164.0 accepts it with --strict-config:
web_search = "live"
[tools.web_search]
context_size = "medium"
allowed_domains = ["learn.chatgpt.com", "github.com", "docs.python.org"]
Two caveats from OpenAI's docs matter here:
- Search domain filters "do not restrict local command traffic, apps, connectors, or MCP servers." They only shape the search tool.
- Older toggles
features.web_search,features.web_search_cachedandfeatures.web_search_requestare deprecated. Use the top-levelweb_searchkey instead.
Admins in managed workspaces can go further with allowed_web_search_modes in requirements.toml, which takes a list from disabled, cached, indexed and live. The reference notes that disabled is always allowed and "an empty list effectively allows only disabled."
Is web search the same as network access?
No, and this is the part people most often get wrong. The web search page states that web search "is a hosted tool, separate from sandboxed local command networking. It does not use the permission profile's network proxy or domain allowlist, and it can remain available when command network access is disabled."
In practice:
- Turning off network access for sandboxed commands (so
curlornpm installfail) does not turn off web search. - Turning off web search with
web_search = "disabled"does not change what commands can reach. - A network allowlist in your permission profile does not filter search results.
If you want Codex fully offline, set both: keep command networking off in your sandbox settings and set web_search = "disabled". The Codex approvals and sandbox guide covers the command side.
How does internet access work in Codex Cloud?
Cloud tasks run in OpenAI-hosted environments, and their network rules live in each environment rather than in your local config.toml. The current Cloud environments page describes the steps:
- In the environment configuration, turn on Allow Codex to access internet.
- Under Allow domains, choose Package managers or Custom domains only, then add hosts under Additional allowed domains. All (unrestricted) is available when a workflow needs broader access.
- Save and test during setup, then publish and verify access in a new task.
The Package managers preset covers registries such as registry.npmjs.org, pypi.org, crates.io and proxy.golang.org, plus GitHub source and release hosts. OpenAI also notes that allowing a destination "doesn't supply credentials or grant permissions in that service."
For Codex Cloud (Legacy), which OpenAI plans to deprecate, Codex blocks internet access during the agent phase by default, while setup scripts still run with internet access so you can install dependencies. Legacy environments also let you restrict requests to GET, HEAD and OPTIONS. Our Codex Cloud guide covers environments in more depth.
What are the risks of Codex web search?
OpenAI's legacy internet access page lists the risks of letting an agent reach the web:
- Prompt injection from untrusted web content
- Code or secret exfiltration
- Downloading malware or vulnerable dependencies
- Pulling in content with license restrictions
Prompt injection is the one that bites. A page or issue can contain instructions aimed at the agent, and if Codex follows them it may leak data or make unsafe changes. The agent approvals and security page puts it plainly: "Prompt injection can cause the agent to fetch and follow untrusted instructions."
Practical habits that follow from the docs:
- Leave search on
cachedunless the task needs fresh data. - Avoid pairing live search with full access; remember
--yoloswitches search to live. - Use
allowed_domainsto keep live search on sources you trust. - Keep approvals on for commands, so an injected instruction still needs your yes.
- Read the search items in the transcript when an answer depends on them.
Our prompt injection guide goes deeper on defenses across coding agents.
Does web search affect Codex memories?
It can. If you use the experimental memories feature, memories.disable_on_external_context = true keeps chats that used web search, MCP tool calls or tool search out of memory generation. The desktop app exposes the same idea as Allow memories from tool-assisted chats. See the Codex memories guide for the details.
Keep your search prompts reusable
Good research prompts for Codex tend to repeat: "check the latest release notes for X and list breaking changes," or "find the official docs for this error before proposing a fix." Kipt keeps prompts like these, with {{name}} blanks, as Markdown in a private GitHub repo you own, alongside any Agent Skills you install into Codex. For the rest of the settings file, see the Codex config.toml guide.