Summary

Two related gaps in the programmatic compaction API surface:

Gap A — sessions.compact RPC is undocumented and has no first-class CLI command.
The only working programmatic compaction path is a raw gateway RPC call. It is not in docs/cli/sessions.md, not surfaced as openclaw sessions compact <key>, and not discoverable without reading gateway source code. Users with a wedged session have no documented recovery path.

Gap B — openclaw agent --message '/compact ...' silently no-ops with exit 0.
The natural workaround — send the slash command via CLI — fails silently. The slash command handler's authorized-sender check rejects CLI-originated turns; the message becomes a plain agent turn, nothing compacts, and the process exits 0. There is no error, no warning, no indication the command was not executed.

Together these mean: when a session is wedged, the correct recovery path is completely undiscoverable, and the obvious workaround gives false confidence that it worked.

Environment

• OpenClaw: 2026.6.1 (2e08f0f)
• OS: macOS 26.5.1 (arm64), Node v24.16.0

Reproducing Gap A — no first-class compact command

openclaw sessions --help
# No "compact" subcommand listed

openclaw gateway call sessions.compact \
  --params '{"key":"agent:main:slack:direct:<uid>"}' \
  --timeout 180000 --json
# Works — returns {"ok":true,"compacted":true,"result":{"tokensBefore":243868,"tokensAfter":34941}}
# But this is undiscoverable and undocumented

Reproducing Gap B — agent --message silent no-op

openclaw agent \
  --session-key 'agent:main:slack:direct:<uid>' \
  --message '/compact Auto-compaction. Keep recent decisions.'
# Exit: 0
# Effect: plain text agent turn — no compaction
# No error, no warning

# Confirmed by checking session token count before and after:
# Before: 157,661 tokens
# After:  157,800 tokens (slightly higher — the no-op turn added tokens)

The slash command handler rejects the CLI-originated turn at the authorized-sender check. The message falls through to a normal agent turn. The agent receives /compact ... as user text and responds to it as prose.

Expected Behavior

Gap A: openclaw sessions compact <session-key> should exist as a documented first-class command, equivalent to the existing sessions.compact RPC.

Gap B: openclaw agent --message '/compact ...' should either:

• (a) Execute the compaction (bypass the authorized-sender check for known CLI-originated slash commands), or
• (b) Exit non-zero with a clear error: "Slash commands cannot be executed via --message from the CLI. Use: openclaw sessions compact <key>"

Currently it exits 0 with no effect and no output. This is a silent false-positive failure mode.

Actual Behavior

• No openclaw sessions compact command exists.
• openclaw agent --message '/compact ...' exits 0 with no effect and no error.
• sessions.compact RPC works but is invisible and undocumented.

Impact

We discovered the working path only by testing openclaw gateway call commands empirically. Before finding it, we attempted agent --message '/compact' multiple times, believed it was working (exit 0), and did not understand why sessions kept growing. This contributed to the $305 Slack DM session cost incident (see related issue on compaction mode).

The gap also affects any automation (crons, scripts) that tries to compact a session programmatically. Our weekly-slack-dm-compact cron was silently failing for weeks because it used the agent --message path.

Suggested Fix

1. Add openclaw sessions compact <session-key> as a documented CLI command backed by the sessions.compact RPC.
2. Make openclaw agent --message '/compact ...' exit non-zero with a descriptive error when the slash command is rejected by the authorized-sender check.
3. Document sessions.compact in docs/cli/sessions.md with the full parameter schema and example output.