#16779: feat: add `openclaw sessions scrub` command and doctor check for secret leaks
docs
gateway
cli
commands
size: L
## Summary
Closes #11468
Recreated from #11544 as a clean single-commit branch (the previous PR was closed for having too many unrelated commits).
Adds two features to address `config.get` leaking secrets into session transcripts:
1. **`openclaw sessions scrub`** — CLI command that scans historical session JSONL files and redacts leaked secrets in-place (with backup by default)
2. **`openclaw doctor` check** — detects unredacted secrets in session files and warns the user
## What's included
### New files
- `src/commands/sessions-scrub.ts` — scrub command implementation
- `src/commands/doctor-sessions-secrets.ts` — doctor check for session secrets
- `docs/cli/sessions-scrub.md` — documentation
### Modified files
- `src/cli/program/register.status-health-sessions.ts` — Commander.js registration, `sessions` becomes a command group with backward compat
- `src/commands/doctor.ts` — wires in the new session secrets check
### Design decisions
- Reuses canonical `maskToken()` pattern from `src/logging/redact.ts` — no duplicated regex
- Creates `.bak` backups by default; `--no-backup` to skip
- Doctor check scans all files if ≤200, deterministic sample for larger dirs
- `openclaw sessions` (no subcommand) still works as before (lists sessions)
- Multi-pass scrub loop with oscillation guard for stable redaction
### Tests
- 10 unit tests for sessions scrub (`src/commands/sessions-scrub.test.ts`)
- 7 unit tests for doctor check (`src/commands/doctor-sessions-secrets.test.ts`)
- All 17 tests passing
<!-- greptile_comment -->
<h3>Greptile Summary</h3>
Adds `openclaw sessions scrub` command and `openclaw doctor` check for detecting and redacting leaked secrets (API keys, tokens, passwords) from session transcript files.
**Key changes:**
- New `sessions scrub` command scrubs secrets from `.jsonl` transcript files using canonical `redactSensitiveText()` patterns from `redact.ts`
- Multi-pass redaction with oscillation detection handles patterns revealed by prior masking
- Bounded concurrency (default 20 workers) with `.bak` backups by default
- New doctor check scans up to 200 session files (deterministic sample for larger sets) and warns if unredacted secrets detected
- Backward compatible: `openclaw sessions` (no subcommand) still lists sessions via default `list` subcommand
- Fast-route updated to allow `sessions scrub` and `sessions doctor` subcommands through
**Implementation quality:**
- All three issues from previous review threads have been addressed in commit `73bdd3b5`
- Comprehensive test coverage (17 tests total: 10 for scrub, 7 for doctor check)
- Reuses canonical redaction patterns - no duplication
- Proper error handling and graceful degradation
<h3>Confidence Score: 5/5</h3>
- This PR is safe to merge with high confidence
- All previous review issues have been thoroughly addressed. The implementation is well-tested with 17 passing tests, follows established patterns (reuses `redactSensitiveText()` from `redact.ts`), includes proper error handling, and has backward compatibility built in. The code is production-ready with appropriate safety mechanisms (backups, dry-run mode, bounded concurrency).
- No files require special attention
<sub>Last reviewed commit: 73bdd3b</sub>
<!-- greptile_other_comments_section -->
<!-- /greptile_comment -->
Most Similar PRs
#12296: security: persistence-only secret redaction for session transcripts
by akoscz · 2026-02-09
80.4%
#18179: CLI: add sessions --json-debug diagnostics
by p6l-richard · 2026-02-16
80.0%
#12260: fix: redact secrets in tool results before persisting to session tr...
by Yida-Dev · 2026-02-09
77.0%
#17026: fix(doctor): handle invalid session file paths gracefully
by Limitless2023 · 2026-02-15
77.0%
#21240: fix: GH#20607 prevent doctor from dropping custom config sections
by theognis1002 · 2026-02-19
75.2%
#11602: fix(config): skip stale legacy config files when openclaw.json exists
by akoscz · 2026-02-08
74.9%
#16135: fix: handle session file paths from other agents in doctor command
by MisterGuy420 · 2026-02-14
74.8%
#22231: fix(security): redact sensitive data in session transcripts
by novalis133 · 2026-02-20
74.5%
#15050: fix: transcript corruption resilience — strip aborted tool_use bloc...
by yashchitneni · 2026-02-12
74.4%
#16928: fix(security): OC-07 redact session history credentials and enforce...
by aether-ai-agent · 2026-02-15
74.3%