# Tune WordPress cache settings with Codex

> Tuning cache settings with Codex means asking it, in the terminal, to read the xSpeed settings of a WordPress site, propose a change and write it through xSpeed Hub, next to the code you are shipping.

Page: https://xspeedcache.com/agent/codex/cache-settings/
Last updated: October 2026

You are in a Codex session in the project that holds a theme, and a performance report says browsers re-download your fonts and stylesheets on every visit. You say that, and name the site. Codex calls list_sites, then list_modules to find the browser cache module, then get_settings for it, so it can read whether the cache headers are switched on at all and how long files and pages are allowed to live, in seconds, before it suggests anything.

What comes back is the finding, usually that the headers are off, next to the change Codex proposes: switch them on and give files a lifetime that suits assets that change only when you deploy, while pages keep a short one. Codex should pass on any warning in the result, such as a setting that is saved but has no effect on that server. The Hub tells the agent to briefly confirm intent before update_settings, so Codex states the change and waits for you. After your yes it calls update_settings and returns the stored values. If any key or value is wrong, the whole call is refused and nothing is stored, Pro-only settings are refused on an unlicensed site, and credential fields are refused over the Hub.

What differs in Codex is that it also has a shell, and MCP tools have their own approval setting. The sandbox and approval policy cover commands on your machine. Each MCP server takes default_tools_approval_mode (auto, prompt, writes or approve), and Codex asks by default only about calls that advertise side effects. The Hub's tools advertise none, so set the server to prompt. If Codex has a shell on the server, it can also read the same settings through wp xspeed settings. For several sites, the MCP route is simpler: one update_settings call returns a result per site.

## Set up Codex once

### 1. Put your sites in xSpeed Hub

Sign in at app.xspeedcache.com with Google or email; the Hub is free and has no site cap. Then connect each WordPress site from its own dashboard: click Connect Hub in the xSpeed Cache top bar, then Connect via xSpeed Hub. Each site needs the free xSpeed Cache plugin.

### 2. Add xSpeed Hub and sign in

Add the server with its URL, then log in. The login opens an xSpeed Hub page in your browser; approve access there. There is no token to paste, and Codex keeps the credentials it receives. Start Codex and type /mcp to see the server.

```bash
codex mcp add xspeedhub --url https://app.xspeedcache.com/xspeed/mcp
codex mcp login xspeedhub
```

### 3. Keep the Hub's tools on a prompt

Open ~/.codex/config.toml. Set the server to prompt for every tool, then let one read tool run without a question. The tool timeout defaults to 60 seconds, and a PageSpeed test can take up to about two minutes, so raise it.

File: `~/.codex/config.toml`

```toml
[mcp_servers.xspeedhub]
url = "https://app.xspeedcache.com/xspeed/mcp"
default_tools_approval_mode = "prompt"
tool_timeout_sec = 150

[mcp_servers.xspeedhub.tools.get_cache_status]
approval_mode = "approve"
```

Full setup: https://xspeedcache.com/agent/codex/

### Before you send a prompt that changes something

Reads change nothing on your sites, though contact_support emails xSpeed support. Writes run once your connection allows them, so your client's approval prompt and a read-only connection (the token's Read-only everywhere switch, or a Viewer sign-in) are the gates that matter. Codex has two layers for shell work: the sandbox mode limits what commands can touch, and the approval policy sets when Codex stops to ask. MCP tools have their own settings. Each server takes default_tools_approval_mode (auto, prompt, writes or approve) and each tool can override it with approval_mode. Codex also asks about MCP calls that advertise side effects or a destructive annotation, but xSpeed Hub's tool definitions do not declare either, so do not rely on that default for the Hub; set the server to prompt. approval_policy never, --yolo and an auto_review reviewer take the human out of the loop. xSpeed Hub has no confirmation step of its own, so an approved or auto-approved write runs as soon as your connection allows writes.

## Prompts

- Use xSpeed Hub to read the browser cache settings on shop and tell me whether the headers are on and what the file and page lifetimes are.
- With xSpeed Hub, turn on browser cache headers on shop with a one week file lifetime and leave the page lifetime alone. Show me the change before you write it.
- Ask xSpeed Hub for the modules on blog and tell me which ones have settings still at their defaults.

## Example session

```
You: Browsers keep re-downloading our CSS on shop. Check the browser cache settings with xSpeed Hub.
  → get_settings(site: shop, module: browser-cache) [read-only]: enabled false, asset_ttl 31536000, html_ttl 3600
Agent: The headers are off, so browsers have no instruction to keep your files. I would switch them on and set the file lifetime to one week, 604800 seconds, and leave the page lifetime at one hour. Apply it to shop?
You: Yes, one week is fine.
  → update_settings(site: shop, module: browser-cache, values: { enabled: true, asset_ttl: 604800 }) [changes site]: stored, enabled true, asset_ttl 604800 seconds
Agent: Done. Browsers will now keep CSS, scripts and images for a week after their next download. If the result carries a warning about the server rules, I will pass it on.
```

## How it works

1. **List the modules**: list_modules returns every Free and Pro module available on one site, with its settings schema and status. It tells the agent which module slugs exist, such as minify or gzip, and what each setting accepts.
2. **Read the current settings**: get_settings takes a module slug and returns its settings. Credential fields come back masked, so an agent cannot read a stored API token or password back in plain text.
3. **Change them**: update_settings takes the module and a values object of setting keys. The site checks the whole object first. If any key is unknown, any value is outside the schema, or a field is pinned by a constant in wp-config.php, it refuses the write, writes nothing and says which keys and why, sometimes with a "did you mean" hint.
4. **Turn page caching on or off**: Page caching has its own tool, toggle_cache, because it installs or removes the cache drop-in and the WP_CACHE constant. Asking update_settings to set cache_enabled does not work and is refused. If another caching plugin owns the drop-in, the site declines to enable xSpeed and returns blocked: true with the reason.
5. **Check the effect**: The result of a settings write is the stored settings. A module can add a warning when a setting is saved but has no effect on this server, for example Brotli on a server without the module for it, and the agent should pass that on. run_benchmark then times cached against uncached to see whether the change helped.
6. **Apply to many sites only after reading one**: update_settings and toggle_cache accept site: "all" or a list of handles. Each site validates against its own schema and answers in its own row, so a module missing on one site fails that row and the others still apply. Read one site first, then apply.

## Reference

| | |
| --- | --- |
| Discover | list_modules (read): Free and Pro modules, settings schema, status, per site |
| Read settings | get_settings (read): argument module; credential fields masked |
| Change settings | update_settings (write): arguments module and values; validated by the site |
| Bad input | The whole write is refused and nothing is written; the error names the keys and reasons |
| Page cache on or off | toggle_cache (write): argument enabled; cache_enabled in update_settings is refused |
| Blocked by another plugin | toggle_cache returns blocked: true with blocked_reason when another plugin owns the cache drop-in |
| Every site at once | update_settings and toggle_cache accept site: "all" or a list of handles, one result per site |
| Pro modules | A Pro module on a site without an active licence cannot be read or written; the site refuses |
| Credential fields | Refused by default over MCP; set them in the xSpeed dashboard, not through the agent |
| Read-only connection | The connection token with Read-only everywhere on, or a Viewer member's sign-in: update_settings and toggle_cache are refused; list_modules and get_settings still work. An OAuth sign-in gets the scopes the client asks for, read and write by default, clamped to the member's role |
| Confirmation | None on the Hub; the Hub tells the agent to briefly confirm intent for these two, and your client's prompt is the gate |

## Rules

- Read before you write. Ask for list_modules and get_settings first, so the agent changes real keys with valid values instead of guessing.
- update_settings and toggle_cache change how a live site behaves. They run as soon as your connection allows writes. The Hub tells the agent to briefly confirm intent first, which is guidance to the agent, so your client's approval prompt and a read-only connection (the connection token with Read-only everywhere on, or a Viewer sign-in) are the gates. The switch does not limit an OAuth sign-in.
- For site: "all", the Hub tells the agent to confirm once with "this will touch all N sites", then make one call. The result is per site, and some sites failing is a partial result to report, not a blanket success or failure.
- Do not ask an agent to set credentials such as a Cloudflare token or Redis password. The site refuses those writes by default, and they belong in the xSpeed dashboard.
- If a settings result says a value is saved but inactive on this server, relay that. Do not tell the user the feature is enabled.

## Good to know with Codex

Codex's default prompt for MCP calls depends on tools advertising side effects, and the Hub's tools do not, so the default does not cover update_settings or toggle_cache. Set default_tools_approval_mode to prompt for the server. With approval_policy never, the yolo flag, an auto_review reviewer or a per-tool approve setting, update_settings reaches your live site with only the Hub's request to confirm intent in the way. For a look-only session, or a codex exec run in a script, connect with the connection token and Read-only everywhere on, or sign in as a Viewer member, and the Hub refuses every write.

## More prompts for this job

They work in any client connected to xSpeed Hub.

- Use xSpeed Hub to list the modules on shop and tell me which ones are off.
- Ask xSpeed Hub for the current minify settings on blog.
- With xSpeed Hub, turn on HTML minification on blog, then benchmark the cache and tell me if it helped.
- Use xSpeed Hub to turn page caching off on staging while I debug, and tell me when it is off.
- Using xSpeed Hub, read the gzip settings on shop first, then enable the same options on every site.
- Use xSpeed Hub to set the page cache lifespan on docs to 30 days, and if the site refuses it, tell me why.

## Frequently asked questions

### Should Codex use the Hub or wp xspeed settings to change a setting?

Use the Hub when you work across sites or have no server access: one call, a result per site. Use WP-CLI when the agent already has a shell on the server for that one site. Both change the same stored settings, so pick the route you can approve more easily.

### What happens if Codex sends a value the module does not accept?

The site checks every key and value against the module schema, and if any one is wrong it refuses the whole call and stores nothing. Codex can read the schema from list_modules, correct the call and try again, and it should ask you again if the change is different from the one you agreed to.

### How does an agent know which settings exist?

It calls list_modules for the site, which returns every available module with its settings schema and status, then get_settings for the one module it wants to change. The schema says which keys exist and what values each accepts.

### What happens if the agent sends a wrong setting key?

The site refuses the whole update and writes nothing. The error names the keys it rejected and why, such as an unknown key, a value outside the allowed range, or a field fixed by a constant in wp-config.php, and it can suggest the nearest valid key.

### How do I turn page caching on or off with an agent?

Use toggle_cache with enabled set to true or false. It installs or removes the cache drop-in and the WP_CACHE constant. Setting cache_enabled through update_settings does not work. If another caching plugin already owns the drop-in, the site will not enable xSpeed and says why.

### Can one prompt change settings on all of my sites?

Yes. update_settings and toggle_cache accept site: "all", and the Hub runs the sites one after another with a one-second pause and returns a result per site. Each site checks the values against its own schema, so a site that lacks the module fails its own row while the others apply.

### Can the agent change my Cloudflare or Redis credentials?

Not by default. Writing credential fields over MCP is off unless the site owner allows it, and the site refuses the write and names the fields. Set credentials in the xSpeed dashboard. Credential values also come back masked when an agent reads settings.

## Tune cache settings with other agents

[Claude Code](https://xspeedcache.com/agent/claude-code/cache-settings/) · [Claude](https://xspeedcache.com/agent/claude/cache-settings/) · [Claude Cowork](https://xspeedcache.com/agent/claude-cowork/cache-settings/) · [ChatGPT](https://xspeedcache.com/agent/chatgpt/cache-settings/) · [Cursor](https://xspeedcache.com/agent/cursor/cache-settings/) · [GitHub Copilot in VS Code](https://xspeedcache.com/agent/github-copilot/cache-settings/) · [Windsurf](https://xspeedcache.com/agent/windsurf/cache-settings/) · [Gemini CLI](https://xspeedcache.com/agent/gemini-cli/cache-settings/) · [Antigravity](https://xspeedcache.com/agent/antigravity/cache-settings/) · [Zed](https://xspeedcache.com/agent/zed/cache-settings/) · [Kiro](https://xspeedcache.com/agent/kiro/cache-settings/) · [OpenCode](https://xspeedcache.com/agent/opencode/cache-settings/) · [OpenClaw](https://xspeedcache.com/agent/openclaw/cache-settings/) · [Hermes Agent](https://xspeedcache.com/agent/hermes-agent/cache-settings/) · [Grok Build](https://xspeedcache.com/agent/grok-build/cache-settings/) · [ChatGPT dots](https://xspeedcache.com/agent/chatgpt-dots/cache-settings/) · [Grok](https://xspeedcache.com/agent/grok/cache-settings/) · [Grok Bot](https://xspeedcache.com/agent/grok-bot/cache-settings/) · [Muse](https://xspeedcache.com/agent/muse/cache-settings/) · [Manus](https://xspeedcache.com/agent/manus/cache-settings/) · [Kimi Code](https://xspeedcache.com/agent/kimi/cache-settings/) · [Paperclip](https://xspeedcache.com/agent/paperclip/cache-settings/) · [NanoClaw](https://xspeedcache.com/agent/nanoclaw/cache-settings/)

## More with Codex

- [Purge the WordPress cache with Codex](https://xspeedcache.com/agent/codex/purge-cache/)
- [Find out why WordPress pages are not cached with Codex](https://xspeedcache.com/agent/codex/troubleshoot-cache/)
- [Scan a website for speed problems with Codex](https://xspeedcache.com/agent/codex/speed-scan/)
- [Run and track PageSpeed tests with Codex](https://xspeedcache.com/agent/codex/pagespeed-tests/)
- [Raise a WordPress site's PageSpeed score with Codex](https://xspeedcache.com/agent/codex/optimize-site/)
- [Warm the WordPress cache with Codex](https://xspeedcache.com/agent/codex/preload-cache/)
- [Set up the Redis object cache with Codex](https://xspeedcache.com/agent/codex/object-cache/)
- [Manage Cloudflare caching with Codex](https://xspeedcache.com/agent/codex/cloudflare/)
- [Manage every WordPress site at once with Codex](https://xspeedcache.com/agent/codex/fleet/)

## Documentation

- How to enable Page Cache: https://xspeedcache.com/docs/page-cache/
- How to minify CSS and JavaScript: https://xspeedcache.com/docs/minify/
- How to add cache rules and bypasses: https://xspeedcache.com/docs/rules-and-bypass/
- Site MCP tool reference: https://xspeedcache.com/docs/mcp-tool-reference/