# Find out why WordPress pages are not cached with Paperclip

> Finding out why pages are not cached with Paperclip means giving the problem to an agent as a ticket, letting it read xSpeed cache status and health checks through xSpeed Hub, and approving any fix it proposes on that ticket.

Page: https://xspeedcache.com/agent/paperclip/troubleshoot-cache/
Last updated: October 2026

In Paperclip, cache troubleshooting usually starts from a routine rather than a hunch. A weekly review fires on a cron schedule, wakes a reporting agent on a read-only connection and creates a task, and this week the task comes back with one line flagged: landing has page caching off. You open a ticket from it and assign it to an agent that can write, such as a Claude Code agent that reaches xSpeed Hub through a Paperclip connector with toggle_cache set to Ask first.

The agent reads get_cache_status and get_health and posts what it found on the ticket: caching off, the drop-in missing, WP_CACHE not defined, and no other plugin holding the cache. The fix is to turn page caching on. It proposes that on the ticket and stops, because the ticket says to wait for your reply. You answer Approved, it calls toggle_cache, then runs run_benchmark and posts the timings. The trace stays on the task: what the agent asked xSpeed Hub, what came back, and who approved the change.

Which route the agent uses decides what actually stops it. Through Paperclip's Connectors page, each Hub tool is set to Allowed, Ask first or Off, and a call on Ask first waits in Paperclip's review queue. Through the agent's own MCP config, those settings do not apply, and the Claude Code adapter runs headless with dangerouslySkipPermissions on by default, so a tool call runs without asking. On that route, waiting for your reply is a convention the agent follows, not a gate.

## Set up Paperclip 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 to the agent Paperclip runs

For a Claude Code agent, run this on the machine that hosts it, as the same OS user the Paperclip heartbeat runs as. Paperclip's docs say MCP wiring lives at the adapter and runtime layer, and user scope makes the Hub available to every Claude Code agent that user runs.

```bash
claude mcp add --transport http --scope user xspeedhub https://app.xspeedcache.com/xspeed/mcp
```

### 3. Sign in once, or use a token

Start claude interactively as that same user, run /mcp, choose xspeedhub and approve access on the xSpeed Hub page. Claude Code keeps the credentials, so later headless runs need no browser; claude mcp get xspeedhub shows the status. On a host with no browser, add the server with the connection token from Connect AI in the Hub instead, ideally with Read-only everywhere on.

```bash
# Interactive sign-in
claude
/mcp

# Or a token, no browser
claude mcp add --transport http --scope user xspeedhub https://app.xspeedcache.com/xspeed/mcp \
  --header "Authorization: Bearer <your connection token>"
```

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

### 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. Paperclip's Claude Code adapter runs headless with dangerouslySkipPermissions on by default, which lets the agent call MCP tools without asking. Set it to false and a tool that needs approval does not run. A server added on the adapter does not pass through Paperclip's action permissions or review queue. A Paperclip connector does: each Hub tool is set to Allowed, Ask first or Off, and because the Hub publishes no annotations Paperclip classifies them by name, which can under-classify, so start every write Off. xSpeed Hub has no confirmation step of its own, so a write that gets past those settings runs as soon as your connection allows writes. For unattended routines, send a connection token with Read-only everywhere on, which makes the Hub refuse every write tool.

## Prompts

- Ticket: use xSpeed Hub to find out why landing is not serving cached pages. Post the findings here and wait for my reply before any change.
- Weekly review: use xSpeed Hub to read the cache status of every site and post any with caching off. Read only.
- With xSpeed Hub, run the benchmark on every site and add any where the cached request missed to this ticket.

## Example session

```
You: Ticket: the weekly review flagged landing. Use xSpeed Hub to find out why pages are not cached, and wait for my reply before any change.
  → get_cache_status(site: landing) [read-only]: page caching is off, 0 cached pages, last purge 15 days ago
  → get_health(site: landing) [read-only]: 2 warnings: advanced-cache.php drop-in missing, WP_CACHE not defined; no plugin conflicts
Agent: Page caching is switched off on landing, which is why the drop-in and WP_CACHE are missing, and no other plugin owns the cache. Proposed fix: turn page caching on for landing. Reply to approve.
You: Approved.
  → toggle_cache(site: landing, enabled: true) [changes site]: page caching enabled, drop-in installed, WP_CACHE defined
  → run_benchmark(site: landing) [read-only]: home page: 488 ms uncached, 52 ms cached, cached request was a hit
Agent: Done and noted on the ticket: caching is on and the home page hits. I will close the ticket once next week's review shows the hit ratio back up.
```

## How it works

1. **Start with the quick summary**: get_cache_status returns whether page caching is on, the stats (cached pages, size, hit ratio, last purge) and the web server xSpeed detected. It is a glance. If caching is off, or the hit ratio is far below what you expect, the agent moves on to the diagnostic.
2. **Run the diagnostic**: get_health is the tool for troubleshooting. It returns the environment checks with pass or warn tones (the advanced-cache.php drop-in, the WP_CACHE constant, rewrite rules, PHP and WordPress versions, caching plugin conflicts), the cache stats, 24 hourly hit and miss buckets and a 30-day hit-ratio series. The Hub tells the agent to use it, not get_cache_status, when you are troubleshooting rather than glancing.
3. **Time cached against uncached**: run_benchmark requests the home page once with the cache bypassed and once normally, after a warm-up request, and returns the timings. If the second request still is not a cache hit, the page cache is not serving the home page, and the result says so. It measures xSpeed's own response time. It does not return a Lighthouse score.
4. **Read what the checks mean**: A warn is a lead, not always a fault. A static-file rewrite warning, for example, can mean the nginx snippet is not in your server config yet, or that xSpeed could not verify it, which is not evidence the config is wrong. The agent reads the detail line and tells you which one it is.
5. **Fix it or hand it over**: If caching is simply off, toggle_cache turns it on. If another caching plugin owns the drop-in, the site refuses to enable xSpeed and says why; removing the other plugin is yours to do. If nothing explains it, contact_support emails xSpeed support with the agent's summary, after the agent has confirmed the message with you.

## Reference

| | |
| --- | --- |
| Quick check | get_cache_status (read): cache on or off, stats, detected web server |
| Diagnostic | get_health (read): environment checks, 24 hourly buckets, 30-day hit-ratio series, recent activity |
| One site per call | get_health does not accept site: "all"; call it for each site you care about |
| Benchmark | run_benchmark (read): home page only, cache bypassed against cache served, timings in milliseconds |
| Benchmark on every site | run_benchmark accepts site: "all" or a list of handles, one result per site |
| Benchmark history | get_benchmark_history reads past runs and the settings changes on the same timeline |
| Pro suggestions | get_pro_audit (read): which Pro features would help this site, from its settings and stats |
| Hit ratio scope | Counts requests that reach your server; pages answered by a CDN or Cloudflare edge are not counted |
| Support | contact_support emails xSpeed support with your account email and site list attached; classed read |
| Turning caching on | toggle_cache (write); refused by the site when another plugin owns the cache drop-in |

## Rules

- Diagnose with the read tools first. get_cache_status, get_health, run_benchmark and get_pro_audit change nothing on the site, so a read-only connection can run all of them. For clients that send the connection token, that means Read-only everywhere on; an OAuth sign-in gets the scopes the client asks for, unless the member is a Viewer.
- Do not answer a PageSpeed question with run_benchmark. It measures cached against uncached response time and returns no Lighthouse score; for a score, use the speed test or scan jobs.
- toggle_cache is a write. It runs as soon as your connection allows writes, and the Hub tells the agent to confirm the target site first. That is guidance to the agent, so your client's approval prompt is the gate that matters.
- contact_support sends a real email. The Hub tells the agent to confirm the message with you before sending, but the tool is classed read, so even a read-only connection can send one.
- The agent cannot edit your server configuration or another plugin's settings. When a check needs an nginx snippet or a conflicting plugin removed, it tells you what to do and you do it.

## Good to know with Paperclip

Paperclip classifies the Hub's tools by name, because the Hub publishes no annotations, so check where toggle_cache and contact_support landed before you trust the connector route. contact_support is the one to watch: it sends an email to xSpeed support, the Hub classes it as a read, and a classifier working from names can file it as harmless. Set it to Ask first or Off. For the weekly routine, keep the instructions read only and give its agent a connection token with Read-only everywhere on, so the Hub refuses every write while nobody is watching; that token still allows contact_support. A browser sign-in cannot finish headless, so sign in once interactively as the heartbeat's OS user, and a 401 after some hours means you need to sign in again.

## More prompts for this job

They work in any client connected to xSpeed Hub.

- Using xSpeed Hub, why is the cache hit ratio so low on shop? Run the full health check and tell me the most likely cause.
- Using xSpeed Hub, is page caching actually working on blog? Benchmark cached against uncached and tell me if the second request was a hit.
- xSpeed Hub's get_health on docs shows a warning about the static-file rewrite. What does it mean and do I need to act?
- Use xSpeed Hub to check whether another caching plugin is conflicting with xSpeed on shop.
- Caching looks off on the staging site. Use xSpeed Hub to turn it on and tell me if the site refuses.
- Using xSpeed Hub, which Pro features would help the shop site, based on how it is set up now?
- With xSpeed Hub, compare the last few benchmark runs on blog and tell me whether my settings changes helped.

## Frequently asked questions

### Does a Paperclip agent wait for my approval before fixing the cache?

Only if something makes it. On the Connectors route, set toggle_cache to Ask first and the call waits in Paperclip's review queue. On the adapter route, the Claude Code adapter skips permission prompts by default, so a reply on the ticket is a convention. Setting dangerouslySkipPermissions to false stops a tool that needs approval from running at all.

### Can a Paperclip routine troubleshoot my sites every week?

Yes. A routine fires on a cron schedule, creates a task and wakes the agent you assign. Keep it read only, such as cache status and health for every site, and give that agent a connection token with Read-only everywhere on.

### Why are my WordPress pages not being cached?

The common causes are that page caching is switched off, the advanced-cache.php drop-in or the WP_CACHE constant in wp-config.php is missing, another caching plugin owns the drop-in, or the pages set cookies or headers that make them uncacheable. An agent can read all of these from get_health through xSpeed Hub and tell you which one applies to your site.

### What is the difference between get_cache_status and get_health?

get_cache_status is a quick summary: whether caching is on, the stats and the detected web server. get_health is the diagnostic. It adds the environment checks with pass or warn tones, 24 hourly hit and miss buckets and a 30-day hit-ratio series. The Hub tells the agent to use get_health when you are troubleshooting.

### Does run_benchmark give me a PageSpeed score?

No. run_benchmark measures how fast your own cache answers compared with an uncached request for the home page. For a Lighthouse score, ask for a speed test or a speed scan instead.

### Can the agent check every site at once?

Only partly. run_benchmark accepts every site in one call. get_cache_status and get_health take one site per call, and get_health does not accept site: "all", so for a fleet the agent calls them site by site or you use the Hub dashboard for the rollup.

### Will troubleshooting change anything on my site?

Not with the diagnostic tools. They are read tools and change nothing. Changes only happen if the agent calls a write tool such as toggle_cache, which runs once your connection allows writes, so your AI 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.

## Find out why pages are not cached with other agents

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

## More with Paperclip

- [Purge the WordPress cache with Paperclip](https://xspeedcache.com/agent/paperclip/purge-cache/)
- [Scan a website for speed problems with Paperclip](https://xspeedcache.com/agent/paperclip/speed-scan/)
- [Run and track PageSpeed tests with Paperclip](https://xspeedcache.com/agent/paperclip/pagespeed-tests/)
- [Raise a WordPress site's PageSpeed score with Paperclip](https://xspeedcache.com/agent/paperclip/optimize-site/)
- [Tune WordPress cache settings with Paperclip](https://xspeedcache.com/agent/paperclip/cache-settings/)
- [Warm the WordPress cache with Paperclip](https://xspeedcache.com/agent/paperclip/preload-cache/)
- [Set up the Redis object cache with Paperclip](https://xspeedcache.com/agent/paperclip/object-cache/)
- [Manage Cloudflare caching with Paperclip](https://xspeedcache.com/agent/paperclip/cloudflare/)
- [Manage every WordPress site at once with Paperclip](https://xspeedcache.com/agent/paperclip/fleet/)

## Documentation

- How to read your cache diagnostics: https://xspeedcache.com/docs/cache-diagnostics/
- Understanding cache hits and misses: https://xspeedcache.com/docs/hits-and-misses/
- How to check your site health: https://xspeedcache.com/docs/health/
- Common problems and troubleshooting: https://xspeedcache.com/docs/common-problems-and-troubleshooting/
- How to enable Page Cache: https://xspeedcache.com/docs/page-cache/