mirror of
https://github.com/openclaw/openclaw.git
synced 2026-05-06 16:20:43 +00:00
Add /trace toggle and fix Active Memory diagnostics
This commit is contained in:
Tak Hoffman
@@ -15,7 +15,7 @@ Note: `agents.list[].groupChat.mentionPatterns` is now used by Telegram/Discord/
|
||||
|
||||
- Activation modes: `mention` (default) or `always`. `mention` requires a ping (real WhatsApp @-mentions via `mentionedJids`, safe regex patterns, or the bot’s E.164 anywhere in the text). `always` wakes the agent on every message but it should reply only when it can add meaningful value; otherwise it returns the exact silent token `NO_REPLY` / `no_reply`. Defaults can be set in config (`channels.whatsapp.groups`) and overridden per group via `/activation`. When `channels.whatsapp.groups` is set, it also acts as a group allowlist (include `"*"` to allow all).
|
||||
- Group policy: `channels.whatsapp.groupPolicy` controls whether group messages are accepted (`open|disabled|allowlist`). `allowlist` uses `channels.whatsapp.groupAllowFrom` (fallback: explicit `channels.whatsapp.allowFrom`). Default is `allowlist` (blocked until you add senders).
|
||||
- Per-group sessions: session keys look like `agent:<agentId>:whatsapp:group:<jid>` so commands such as `/verbose on` or `/think high` (sent as standalone messages) are scoped to that group; personal DM state is untouched. Heartbeats are skipped for group threads.
|
||||
- Per-group sessions: session keys look like `agent:<agentId>:whatsapp:group:<jid>` so commands such as `/verbose on`, `/trace on`, or `/think high` (sent as standalone messages) are scoped to that group; personal DM state is untouched. Heartbeats are skipped for group threads.
|
||||
- Context injection: **pending-only** group messages (default 50) that _did not_ trigger a run are prefixed under `[Chat messages since your last reply - for context]`, with the triggering line under `[Current message - respond to this]`. Messages already in the session are not re-injected.
|
||||
- Sender surfacing: every group batch now ends with `[from: Sender Name (+E164)]` so Pi knows who is speaking.
|
||||
- Ephemeral/view-once: we unwrap those before extracting text/mentions, so pings inside them still trigger.
|
||||
@@ -67,7 +67,7 @@ Only the owner number (from `channels.whatsapp.allowFrom`, or the bot’s own E.
|
||||
1. Add your WhatsApp account (the one running OpenClaw) to the group.
|
||||
2. Say `@openclaw …` (or include the number). Only allowlisted senders can trigger it unless you set `groupPolicy: "open"`.
|
||||
3. The agent prompt will include recent group context plus the trailing `[from: …]` marker so it can address the right person.
|
||||
4. Session-level directives (`/verbose on`, `/think high`, `/new` or `/reset`, `/compact`) apply only to that group’s session; send them as standalone messages so they register. Your personal DM session remains independent.
|
||||
4. Session-level directives (`/verbose on`, `/trace on`, `/think high`, `/new` or `/reset`, `/compact`) apply only to that group’s session; send them as standalone messages so they register. Your personal DM session remains independent.
|
||||
|
||||
## Testing / verification
|
||||
|
||||
|
||||
@@ -473,6 +473,7 @@ Chat messages support `/...` commands (text and native). See [/tools/slash-comma
|
||||
Highlights:
|
||||
|
||||
- `/status` for quick diagnostics.
|
||||
- `/trace` for session-scoped plugin trace/debug lines.
|
||||
- `/config` for persisted config changes.
|
||||
- `/debug` for runtime-only config overrides (memory, not disk; requires `commands.debug: true`).
|
||||
|
||||
|
||||
@@ -64,6 +64,7 @@ To inspect it live in a conversation:
|
||||
|
||||
```text
|
||||
/verbose on
|
||||
/trace on
|
||||
```
|
||||
|
||||
## Turn active memory on
|
||||
@@ -148,21 +149,24 @@ The global form writes `plugins.entries.active-memory.config.enabled`. It leaves
|
||||
`plugins.entries.active-memory.enabled` on so the command remains available to
|
||||
turn active memory back on later.
|
||||
|
||||
If you want to see what active memory is doing in a live session, turn verbose
|
||||
mode on for that session:
|
||||
If you want to see what active memory is doing in a live session, turn on the
|
||||
session toggles that match the output you want:
|
||||
|
||||
```text
|
||||
/verbose on
|
||||
/trace on
|
||||
```
|
||||
|
||||
With verbose enabled, OpenClaw can show:
|
||||
With those enabled, OpenClaw can show:
|
||||
|
||||
- an active memory status line such as `Active Memory: ok 842ms recent 34 chars`
|
||||
- a readable debug summary such as `Active Memory Debug: Lemon pepper wings with blue cheese.`
|
||||
- an active memory status line such as `Active Memory: ok 842ms recent 34 chars` when `/verbose on`
|
||||
- a readable debug summary such as `Active Memory Debug: Lemon pepper wings with blue cheese.` when `/trace on`
|
||||
|
||||
Those lines are derived from the same active memory pass that feeds the hidden
|
||||
system context, but they are formatted for humans instead of exposing raw prompt
|
||||
markup.
|
||||
markup. They are sent as a follow-up diagnostic message after the normal
|
||||
assistant reply so channel clients like Telegram do not flash a separate
|
||||
pre-reply diagnostic bubble.
|
||||
|
||||
By default, the blocking memory sub-agent transcript is temporary and deleted
|
||||
after the run completes.
|
||||
@@ -171,6 +175,7 @@ Example flow:
|
||||
|
||||
```text
|
||||
/verbose on
|
||||
/trace on
|
||||
what wings should i order?
|
||||
```
|
||||
|
||||
@@ -568,8 +573,10 @@ Start with `recent`.
|
||||
}
|
||||
```
|
||||
|
||||
If you want to inspect live behavior while tuning, use `/verbose on` in the
|
||||
session instead of looking for a separate active-memory debug command.
|
||||
If you want to inspect live behavior while tuning, use `/verbose on` for the
|
||||
normal status line and `/trace on` for the active-memory debug summary instead
|
||||
of looking for a separate active-memory debug command. In chat channels, those
|
||||
diagnostic lines are sent after the main assistant reply rather than before it.
|
||||
|
||||
Then move to:
|
||||
|
||||
@@ -597,6 +604,58 @@ If active memory is too slow:
|
||||
- reduce recent turn counts
|
||||
- reduce per-turn char caps
|
||||
|
||||
## Common issues
|
||||
|
||||
### Embedding provider changed unexpectedly
|
||||
|
||||
Active Memory relies on the normal memory search embedding provider under
|
||||
`agents.defaults.memorySearch`. If you do not set that provider explicitly,
|
||||
OpenClaw auto-detects the first available embedding provider.
|
||||
|
||||
That can be confusing in real deployments:
|
||||
|
||||
- a newly available API key can change which provider memory search uses
|
||||
- one command or diagnostics surface may make the selected provider look
|
||||
different from the path you are actually hitting during live memory sync or
|
||||
search bootstrap
|
||||
- hosted providers can fail with quota or rate-limit errors that only show up
|
||||
once Active Memory starts issuing recall searches before each reply
|
||||
|
||||
If you care about predictable behavior, pin the memory embedding provider
|
||||
explicitly instead of relying on auto-detection.
|
||||
|
||||
Example:
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
memorySearch: {
|
||||
provider: "ollama",
|
||||
model: "nomic-embed-text",
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Or, if you want Gemini embeddings:
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
memorySearch: {
|
||||
provider: "gemini",
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
After changing the provider, restart the gateway and run a fresh test with
|
||||
`/trace on` so the Active Memory debug line reflects the new embedding path.
|
||||
|
||||
## Related pages
|
||||
|
||||
- [Memory Search](/concepts/memory-search)
|
||||
|
||||
@@ -24,7 +24,7 @@ wired end-to-end.
|
||||
|
||||
1. `agent` RPC validates params, resolves session (sessionKey/sessionId), persists session metadata, returns `{ runId, acceptedAt }` immediately.
|
||||
2. `agentCommand` runs the agent:
|
||||
- resolves model + thinking/verbose defaults
|
||||
- resolves model + thinking/verbose/trace defaults
|
||||
- loads skills snapshot
|
||||
- calls `runEmbeddedPiAgent` (pi-agent-core runtime)
|
||||
- emits **lifecycle end/error** if the embedded loop does not emit one
|
||||
|
||||
@@ -136,7 +136,7 @@ Tools affect context in two ways:
|
||||
Slash commands are handled by the Gateway. There are a few different behaviors:
|
||||
|
||||
- **Standalone commands**: a message that is only `/...` runs as a command.
|
||||
- **Directives**: `/think`, `/verbose`, `/reasoning`, `/elevated`, `/model`, `/queue` are stripped before the model sees the message.
|
||||
- **Directives**: `/think`, `/verbose`, `/trace`, `/reasoning`, `/elevated`, `/model`, `/queue` are stripped before the model sees the message.
|
||||
- Directive-only messages persist session settings.
|
||||
- Inline directives in a normal message act as per-message hints.
|
||||
- **Inline shortcuts** (allowlisted senders only): certain `/...` tokens inside a normal message can run immediately (example: “hey /status”), and are stripped before the model sees the remaining text.
|
||||
|
||||
@@ -730,15 +730,16 @@ Recommendations:
|
||||
|
||||
## Reasoning & verbose output in groups
|
||||
|
||||
`/reasoning` and `/verbose` can expose internal reasoning or tool output that
|
||||
`/reasoning`, `/verbose`, and `/trace` can expose internal reasoning, tool
|
||||
output, or plugin diagnostics that
|
||||
was not meant for a public channel. In group settings, treat them as **debug
|
||||
only** and keep them off unless you explicitly need them.
|
||||
|
||||
Guidance:
|
||||
|
||||
- Keep `/reasoning` and `/verbose` disabled in public rooms.
|
||||
- Keep `/reasoning`, `/verbose`, and `/trace` disabled in public rooms.
|
||||
- If you enable them, do so only in trusted DMs or tightly controlled rooms.
|
||||
- Remember: verbose output can include tool args, URLs, and data the model saw.
|
||||
- Remember: verbose and trace output can include tool args, URLs, plugin diagnostics, and data the model saw.
|
||||
|
||||
## Configuration Hardening (examples)
|
||||
|
||||
|
||||
@@ -29,6 +29,23 @@ Examples:
|
||||
|
||||
`/debug reset` clears all overrides and returns to the on-disk config.
|
||||
|
||||
## Session trace output
|
||||
|
||||
Use `/trace` when you want to see plugin-owned trace/debug lines in one session
|
||||
without turning on full verbose mode.
|
||||
|
||||
Examples:
|
||||
|
||||
```text
|
||||
/trace
|
||||
/trace on
|
||||
/trace off
|
||||
```
|
||||
|
||||
Use `/trace` for plugin diagnostics such as Active Memory debug summaries.
|
||||
Keep using `/verbose` for normal verbose status/tool output, and keep using
|
||||
`/debug` for runtime-only config overrides.
|
||||
|
||||
## Gateway watch mode
|
||||
|
||||
For fast iteration, run the gateway under the file watcher:
|
||||
|
||||
@@ -3192,13 +3192,14 @@ Related: [/concepts/oauth](/concepts/oauth) (OAuth flows, token storage, multi-a
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="How do I stop internal system messages from showing in chat?">
|
||||
Most internal or tool messages only appear when **verbose** or **reasoning** is enabled
|
||||
Most internal or tool messages only appear when **verbose**, **trace**, or **reasoning** is enabled
|
||||
for that session.
|
||||
|
||||
Fix in the chat where you see it:
|
||||
|
||||
```
|
||||
/verbose off
|
||||
/trace off
|
||||
/reasoning off
|
||||
```
|
||||
|
||||
|
||||
@@ -14,7 +14,7 @@ The host-only bash chat command uses `! <cmd>` (with `/bash <cmd>` as an alias).
|
||||
There are two related systems:
|
||||
|
||||
- **Commands**: standalone `/...` messages.
|
||||
- **Directives**: `/think`, `/fast`, `/verbose`, `/reasoning`, `/elevated`, `/exec`, `/model`, `/queue`.
|
||||
- **Directives**: `/think`, `/fast`, `/verbose`, `/trace`, `/reasoning`, `/elevated`, `/exec`, `/model`, `/queue`.
|
||||
- Directives are stripped from the message before the model sees it.
|
||||
- In normal chat messages (not directive-only), they are treated as “inline hints” and do **not** persist session settings.
|
||||
- In directive-only messages (the message contains only directives), they persist to the session and reply with an acknowledgement.
|
||||
@@ -95,6 +95,7 @@ Built-in commands available today:
|
||||
- `/session idle <duration|off>` and `/session max-age <duration|off>` manage thread-binding expiry.
|
||||
- `/think <off|minimal|low|medium|high|xhigh>` sets the thinking level. Aliases: `/thinking`, `/t`.
|
||||
- `/verbose on|off|full` toggles verbose output. Alias: `/v`.
|
||||
- `/trace on|off` toggles plugin trace output for the current session.
|
||||
- `/fast [status|on|off]` shows or sets fast mode.
|
||||
- `/reasoning [on|off|stream]` toggles reasoning visibility. Alias: `/reason`.
|
||||
- `/elevated [on|off|ask|full]` toggles elevated mode. Alias: `/elev`.
|
||||
@@ -183,10 +184,11 @@ Notes:
|
||||
- Discord thread-binding commands (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`) require effective thread bindings to be enabled (`session.threadBindings.enabled` and/or `channels.discord.threadBindings.enabled`).
|
||||
- ACP command reference and runtime behavior: [ACP Agents](/tools/acp-agents).
|
||||
- `/verbose` is meant for debugging and extra visibility; keep it **off** in normal use.
|
||||
- `/trace` is narrower than `/verbose`: it only reveals plugin-owned trace/debug lines and keeps normal verbose tool chatter off.
|
||||
- `/fast on|off` persists a session override. Use the Sessions UI `inherit` option to clear it and fall back to config defaults.
|
||||
- `/fast` is provider-specific: OpenAI/OpenAI Codex map it to `service_tier=priority` on native Responses endpoints, while direct public Anthropic requests, including OAuth-authenticated traffic sent to `api.anthropic.com`, map it to `service_tier=auto` or `standard_only`. See [OpenAI](/providers/openai) and [Anthropic](/providers/anthropic).
|
||||
- Tool failure summaries are still shown when relevant, but detailed failure text is only included when `/verbose` is `on` or `full`.
|
||||
- `/reasoning` (and `/verbose`) are risky in group settings: they may reveal internal reasoning or tool output you did not intend to expose. Prefer leaving them off, especially in group chats.
|
||||
- `/reasoning`, `/verbose`, and `/trace` are risky in group settings: they may reveal internal reasoning, tool output, or plugin diagnostics you did not intend to expose. Prefer leaving them off, especially in group chats.
|
||||
- `/model` persists the new session model immediately.
|
||||
- If the agent is idle, the next run uses it right away.
|
||||
- If a run is already active, OpenClaw marks a live switch as pending and only restarts into the new model at a clean retry point.
|
||||
@@ -268,6 +270,27 @@ Notes:
|
||||
- Overrides apply immediately to new config reads, but do **not** write to `openclaw.json`.
|
||||
- Use `/debug reset` to clear all overrides and return to the on-disk config.
|
||||
|
||||
## Plugin trace output
|
||||
|
||||
`/trace` lets you toggle **session-scoped plugin trace/debug lines** without turning on full verbose mode.
|
||||
|
||||
Examples:
|
||||
|
||||
```text
|
||||
/trace
|
||||
/trace on
|
||||
/trace off
|
||||
```
|
||||
|
||||
Notes:
|
||||
|
||||
- `/trace` with no argument shows the current session trace state.
|
||||
- `/trace on` enables plugin trace lines for the current session.
|
||||
- `/trace off` disables them again.
|
||||
- Plugin trace lines can appear in `/status` and as a follow-up diagnostic message after the normal assistant reply.
|
||||
- `/trace` does not replace `/debug`; `/debug` still manages runtime-only config overrides.
|
||||
- `/trace` does not replace `/verbose`; normal verbose tool/status output still belongs to `/verbose`.
|
||||
|
||||
## Config updates
|
||||
|
||||
`/config` writes to your on-disk config (`openclaw.json`). Owner-only. Disabled by default; enable with `commands.config: true`.
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
---
|
||||
summary: "Directive syntax for /think, /fast, /verbose, and reasoning visibility"
|
||||
summary: "Directive syntax for /think, /fast, /verbose, /trace, and reasoning visibility"
|
||||
read_when:
|
||||
- Adjusting thinking, fast-mode, or verbose directive parsing or defaults
|
||||
title: "Thinking Levels"
|
||||
@@ -72,6 +72,15 @@ title: "Thinking Levels"
|
||||
- Tool failure summaries remain visible in normal mode, but raw error detail suffixes are hidden unless verbose is `on` or `full`.
|
||||
- When verbose is `full`, tool outputs are also forwarded after completion (separate bubble, truncated to a safe length). If you toggle `/verbose on|full|off` while a run is in-flight, subsequent tool bubbles honor the new setting.
|
||||
|
||||
## Plugin trace directives (/trace)
|
||||
|
||||
- Levels: `on` | `off` (default).
|
||||
- Directive-only message toggles session plugin trace output and replies `Plugin trace enabled.` / `Plugin trace disabled.`.
|
||||
- Inline directive affects only that message; session/global defaults apply otherwise.
|
||||
- Send `/trace` (or `/trace:`) with no argument to see the current trace level.
|
||||
- `/trace` is narrower than `/verbose`: it only exposes plugin-owned trace/debug lines such as Active Memory debug summaries.
|
||||
- Trace lines can appear in `/status` and as a follow-up diagnostic message after the normal assistant reply.
|
||||
|
||||
## Reasoning visibility (/reasoning)
|
||||
|
||||
- Levels: `on|off|stream`.
|
||||
|
||||
@@ -88,7 +88,7 @@ locale picker lives in the Gateway Access card, not under Appearance.
|
||||
- Stream tool calls + live tool output cards in Chat (agent events)
|
||||
- Channels: built-in plus bundled/external plugin channels status, QR login, and per-channel config (`channels.status`, `web.login.*`, `config.patch`)
|
||||
- Instances: presence list + refresh (`system-presence`)
|
||||
- Sessions: list + per-session model/thinking/fast/verbose/reasoning overrides (`sessions.list`, `sessions.patch`)
|
||||
- Sessions: list + per-session model/thinking/fast/verbose/trace/reasoning overrides (`sessions.list`, `sessions.patch`)
|
||||
- Dreams: dreaming status, enable/disable toggle, and Dream Diary reader (`doctor.memory.status`, `doctor.memory.dreamDiary`, `config.patch`)
|
||||
- Cron jobs: list/add/edit/run/enable/disable + run history (`cron.*`)
|
||||
- Skills: status, enable/disable, install, API key updates (`skills.*`)
|
||||
|
||||
@@ -37,7 +37,7 @@ Use `--password` if your Gateway uses password auth.
|
||||
- Header: connection URL, current agent, current session.
|
||||
- Chat log: user messages, assistant replies, system notices, tool cards.
|
||||
- Status line: connection/run state (connecting, running, streaming, idle, error).
|
||||
- Footer: connection state + agent + session + model + think/fast/verbose/reasoning + token counts + deliver.
|
||||
- Footer: connection state + agent + session + model + think/fast/verbose/trace/reasoning + token counts + deliver.
|
||||
- Input: text editor with autocomplete.
|
||||
|
||||
## Mental model: agents + sessions
|
||||
@@ -94,6 +94,7 @@ Session controls:
|
||||
- `/think <off|minimal|low|medium|high>`
|
||||
- `/fast <status|on|off>`
|
||||
- `/verbose <on|full|off>`
|
||||
- `/trace <on|off>`
|
||||
- `/reasoning <on|off|stream>`
|
||||
- `/usage <off|tokens|full>`
|
||||
- `/elevated <on|off|ask|full>` (alias: `/elev`)
|
||||
|
||||
Reference in New Issue
Block a user