Control Codex web search with the web_search setting: disabled, cached, indexed, and live
The four values of Codex CLI's web_search setting and their defaults, the --search flag for one-off use, why indexed reduces prompt injection risk, and how to restrict domains.
Sometimes a task needs the latest release notes of a dependency, which means web access. But letting the agent read arbitrary web pages all the time opens a door to prompt injection. Codex CLI's web_search setting gives you four levels.
In short: set web_search in config.toml to disabled, cached, indexed, or live. The local default is cached, and --search turns on live search for a single run.
KEY POINT
What you will learn
- What the four values mean and when each is the default
- One-off enabling with
--search - Why
indexedreduces prompt injection risk, and how to restrict domains
The four values
# disabled | cached | indexed | live. Default: "cached"
web_search = "cached"| Value | Meaning |
|---|---|
disabled | turns the web search tool off entirely |
cached | uses cached search results; the default for local Codex chats |
indexed | permits external web access only when the search index gates the request, reducing prompt injection risk |
live | fetches current information directly; for tasks that depend on the latest information |
According to the docs, when Codex runs with full access, web search defaults to live results, while local chats enable cached search by default.
用語解説
Prompt injection: text planted in a web page or search result that tries to redirect an AI agent's behavior. live, where the agent reads arbitrary pages directly, has the widest attack surface.
Enabling it for one run
To use live search for a single task without touching the config file, pass --search.
codex --search "Summarize the latest release notes for this dependency"Keeping cached or disabled as the norm and reaching for --search when needed is a workable balance between risk and convenience.
Why indexed, and domain restrictions
indexed allows external access only for requests that go through the search index, closing the path of reading arbitrary URLs directly. The docs present it as a way to reduce prompt injection risk.
To narrow where searches may go, set tools.web_search.allowed_domains. To lock the permitted modes for an organization, use allowed_web_search_modes.
web_search = "indexed"
[tools.web_search]
allowed_domains = ["docs.python.org", "developer.mozilla.org"]Domain filters apply only to web search
The docs state that search domain filters do not restrict local command traffic, apps, connectors, or MCP servers. A curl from a command is governed by the sandbox's network_access, and MCP servers by their own configuration.
The older features.web_search flag is deprecated in favor of the web_search setting. Custom model_providers need supports_standalone_web_search = true (default false) to use search.
Sandbox network settings are covered in Codex approval modes and sandbox settings, and the config file as a whole in the hub article Configuring Codex with config.toml.
Summary
web_searchhas four levels:disabled,cached,indexed,live; local default iscached, full access defaults to livecodex --search "..."enables it for one runindexedgates requests through the search index and blocks direct reads of arbitrary pagestools.web_search.allowed_domainsnarrows search, but not command or MCP trafficfeatures.web_searchis deprecated; always treat web results as untrusted input
FAQ
- What is the default for web_search?
- cached for local Codex chats. When Codex runs with full access, live search is the default.
- I only want search for tasks that need the latest information.
- Launch that task with codex --search "...". No config change needed.
- Can I trust search results?
- The docs say to treat all web results as untrusted input. indexed lets the search index gate requests and lowers the risk.
Primary sources
This article was drafted by AI from official documentation and reviewed by the site operator before publishing. Found a mistake? Let us know via the contact page.