Summary

Code changes in this PR were made with the help of AI.

Describe the problem and fix in 2–5 bullets:

• Problem: prompt-cache locality was weak because OpenClaw did not enforce a stable per-install cache partition at the very start of the system prompt.
• Why it matters: shared early prompt prefixes can cause cache slot contention across installs, reducing cache-read tokens and increasing cost/latency.
• What changed: added an auto-generated, persisted agents.defaults.promptCachePartition, injected as the first system-prompt line, and threaded into OpenRouter prompt_cache_key as an additive routing hint.
• What did NOT change (scope boundary): Anthropic-specific caching behavior and existing cache-control handling were not modified.

Change Type (select all)

• Bug fix
• Feature
• Refactor
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Related Feature Request: Support prompt_cache_key metadata for provider-side cache routing #16357
• Related [Bug]: 5x API costs due to ineffective prompt caching #23715

User-visible / Behavior Changes

• New config field: agents.defaults.promptCachePartition.
• If missing, it is auto-generated and persisted on config load.
• System prompt now starts with <!-- openclaw-cache-partition:<key> --> (including promptMode: "none").
• For OpenRouter only, outbound payload now includes prompt_cache_key from this partition unless already set or overridden.

Security Impact (required)

• New permissions/capabilities? (No)
• Secrets/tokens handling changed? (No)
• New/changed network calls? (No)
• Command/tool execution surface changed? (No)
• Data access scope changed? (No)
• If any Yes, explain risk + mitigation:

Repro + Verification

Environment

• OS: Linux
• Runtime/container: local dev runtime
• Model/provider: OpenRouter (openai-completions), Anthropic path unchanged
• Integration/channel (if any): N/A
• Relevant config (redacted):
  • agents.defaults.promptCachePartition = <auto-generated 32-hex>

Steps

1. Start with config missing agents.defaults.promptCachePartition.
2. Load config once.
3. Build system prompt and inspect first line; run OpenRouter payload path.

Expected

• Config gets persisted with stable partition key.
• System prompt first line contains partition marker.
• OpenRouter payload gets prompt_cache_key (unless already present/overridden).

Actual

• Matches expected in tests.

Evidence

Attach at least one:

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios:
  • Personally verified cache tokens working via manual testing on OpenRouter.
• What you did not verify:
  • Providers other than OpenRouter

Compatibility / Migration

• Backward compatible? (Yes)
• Config/env changes? (Yes)
• Migration needed? (No)

Failure Recovery (if this breaks)

• How to disable/revert this change quickly:
  • Remove/ignore agents.defaults.promptCachePartition and revert this PR.
• Files/config to restore:
  • src/agents/prompt-cache-partition.ts
  • src/config/io.ts
  • src/agents/system-prompt.ts
  • src/agents/pi-embedded-runner/extra-params.ts
• Known bad symptoms reviewers should watch for:
  • System prompt missing the partition marker on line 1.
  • OpenRouter payload missing prompt_cache_key despite a configured partition.

Risks and Mitigations

List only real risks for this PR. Add/remove entries as needed. If none, write None.

• Risk: HTML comment visible to LLM adds ~10 tokens per request
  • Mitigation: negligible vs. the thousands of tokens saved per turn by proper caching

Greptile Summary

This PR adds per-install prompt cache partitioning to improve cache-read token efficiency and reduce cross-install cache slot contention. The implementation introduces an auto-generated, persisted agents.defaults.promptCachePartition config field that is injected as the first line of system prompts and threaded into OpenRouter's prompt_cache_key parameter.

Key changes:

• New prompt-cache-partition.ts module with ensurePromptCachePartition generates a 32-character hex key if missing
• Config I/O automatically generates and persists the partition key on first load (similar to ownerDisplaySecret pattern)
• System prompt prepends <!-- openclaw-cache-partition:<key> --> as line 1 for all prompt modes including "none"
• OpenRouter wrapper injects prompt_cache_key from partition unless already set or overridden via model params
• Anthropic-specific caching behavior unchanged (scope boundary respected)

The implementation follows existing patterns for auto-generated config fields, includes comprehensive test coverage, and maintains backward compatibility.

Confidence Score: 5/5

• This PR is safe to merge with minimal risk
• The implementation follows established patterns in the codebase (similar to ownerDisplaySecret auto-generation), includes comprehensive unit tests for all new functionality, maintains backward compatibility, and has a clear scope boundary that explicitly excludes Anthropic-specific behavior. The changes are additive and non-breaking, with proper test coverage for edge cases like missing configs, existing values, and provider-specific integration.
• No files require special attention

_{Last reviewed commit: 52b6e53}

_{(2/5) Greptile learns from your feedback when you react with thumbs up/down!}