Summary

OpenClaw currently has multiple vectors where API keys can leak to the LLM or be exposed in chat. This roadmap proposes a layered approach to comprehensively protect secrets.

The Problem

1. LLM Provider Keys — Model catalog with resolved apiKey values is serialized into prompt context ([Security] Model catalog with resolved apiKey values injected into LLM prompt context on every turn #11202)
2. Agent-Accessible Keys — Agent can read .env files and accidentally display credentials in chat (Feature Request: Masked Secrets - Prevent Agent from Accessing Raw API Keys #10659)
3. Channel Tokens — Telegram, Discord, and other tokens are in openclaw.json, potentially accessible

These aren't edge cases. Real users have had keys exposed in chat while debugging.

Proposed Solution: Three Layers

Layer 1: Stop models.json Leak (Quick Fix)

Problem: models-config.ts writes apiKey to models.json, which gets serialized to prompt context.

Fix: Strip apiKey from models.json before writing. Store auth credentials separately for authentication only.

Files:

• src/agents/models-config.ts (~line 133)
• src/agents/models-config.providers.ts

Scope: ~100 lines
Timeline: Days
Impact: Stops LLM provider keys from leaking

Layer 2: Masked Secrets Architecture (#10659)

Problem: Agents can read any file they have permission to access, including .env files with secrets.

Fix: Implement proper secrets handling:

# Config uses placeholder
apiKey: "{{secret:ANTHROPIC_KEY}}"

# Agent sees placeholder, never real value
# Runtime substitutes when making API call
# Output is redacted if key appears accidentally

Components:

1. Secret placeholder syntax ({{secret:VAR}})
2. Runtime substitution layer
3. Output redaction filter
4. Secure secrets storage

Scope: Significant engineering
Timeline: Weeks
Impact: Protects ALL secrets (provider keys, channel tokens, external APIs)

Layer 3: Fix Upstream (pi-coding-agent)

Problem: The @mariozechner/pi-coding-agent package serializes model catalog (including apiKey) to prompt context.

Fix: That package should filter secret-looking fields before prompt serialization.

Scope: External dependency
Timeline: Depends on upstream maintainer
Impact: Fixes root cause for all users of that package

Workarounds Available Today

While waiting for platform fixes, users can protect agent-called APIs using Linux user isolation:

• Guide: https://github.com/jmkritt/openclaw-secrets-hardening
• Docs PR: docs(security): Add API key hardening guide #11622

This protects keys the agent calls (CRMs, external APIs) but doesn't address LLM provider keys or channel tokens.

Proposed Prioritization

1. Immediate: Layer 1 (quick fix, stops critical leak)
2. Short-term: Layer 2 (proper architecture)
3. Long-term: Layer 3 (upstream fix)

Related Issues

• Feature Request: Masked Secrets - Prevent Agent from Accessing Raw API Keys #10659 — Feature request for masked secrets
• [Security] Model catalog with resolved apiKey values injected into LLM prompt context on every turn #11202 — Model catalog apiKey leak to prompt context
• docs(security): Add API key hardening guide #11622 — Docs PR for user isolation workaround

Questions for Maintainers

1. Is this roadmap aligned with how you'd approach the problem?
2. Would Layer 1 be accepted as a PR while Layer 2 is designed?
3. Is there existing work on secrets handling we should know about?

Happy to help implement any of these layers.