diff --git a/.openclaw-sync/source.json b/.openclaw-sync/source.json index 4a4c4c7e9..a642f12bb 100644 --- a/.openclaw-sync/source.json +++ b/.openclaw-sync/source.json @@ -1,5 +1,5 @@ { "repository": "openclaw/openclaw", - "sha": "000fc7f233469b2d64223cc10e6fbce75bdb0748", - "syncedAt": "2026-04-12T18:03:38.674Z" + "sha": "c37e49f275fbf76b89f3f51a4b950a795a3f5917", + "syncedAt": "2026-04-12T18:21:12.096Z" } diff --git a/docs/channels/group-messages.md b/docs/channels/group-messages.md index f62842ab8..1d5950440 100644 --- a/docs/channels/group-messages.md +++ b/docs/channels/group-messages.md @@ -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::whatsapp:group:` 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::whatsapp:group:` 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 diff --git a/docs/cli/index.md b/docs/cli/index.md index 6f11e01cd..687bf623b 100644 --- a/docs/cli/index.md +++ b/docs/cli/index.md @@ -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`). diff --git a/docs/concepts/active-memory.md b/docs/concepts/active-memory.md index 00b04c1f4..d47b35fd4 100644 --- a/docs/concepts/active-memory.md +++ b/docs/concepts/active-memory.md @@ -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) diff --git a/docs/concepts/agent-loop.md b/docs/concepts/agent-loop.md index 580187b54..5671016f5 100644 --- a/docs/concepts/agent-loop.md +++ b/docs/concepts/agent-loop.md @@ -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 diff --git a/docs/concepts/context.md b/docs/concepts/context.md index 5d9bd60af..348bb9d53 100644 --- a/docs/concepts/context.md +++ b/docs/concepts/context.md @@ -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. diff --git a/docs/gateway/security/index.md b/docs/gateway/security/index.md index 699ad3730..66c0ad8a4 100644 --- a/docs/gateway/security/index.md +++ b/docs/gateway/security/index.md @@ -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) diff --git a/docs/help/debugging.md b/docs/help/debugging.md index dc6a83780..88de00e6c 100644 --- a/docs/help/debugging.md +++ b/docs/help/debugging.md @@ -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: diff --git a/docs/help/faq.md b/docs/help/faq.md index 0b9bdda16..9dd5a8b0d 100644 --- a/docs/help/faq.md +++ b/docs/help/faq.md @@ -3192,13 +3192,14 @@ Related: [/concepts/oauth](/concepts/oauth) (OAuth flows, token storage, multi-a - 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 ``` diff --git a/docs/tools/slash-commands.md b/docs/tools/slash-commands.md index d77b0cd6c..2a39e765f 100644 --- a/docs/tools/slash-commands.md +++ b/docs/tools/slash-commands.md @@ -14,7 +14,7 @@ The host-only bash chat command uses `! ` (with `/bash ` 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 ` and `/session max-age ` manage thread-binding expiry. - `/think ` 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`. diff --git a/docs/tools/thinking.md b/docs/tools/thinking.md index 196ded24f..3fc3c06ae 100644 --- a/docs/tools/thinking.md +++ b/docs/tools/thinking.md @@ -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`. diff --git a/docs/web/control-ui.md b/docs/web/control-ui.md index b88c4310e..32623f9c6 100644 --- a/docs/web/control-ui.md +++ b/docs/web/control-ui.md @@ -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.*`) diff --git a/docs/web/tui.md b/docs/web/tui.md index 4d3eaef7e..d643c6f10 100644 --- a/docs/web/tui.md +++ b/docs/web/tui.md @@ -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 ` - `/fast ` - `/verbose ` +- `/trace ` - `/reasoning ` - `/usage ` - `/elevated ` (alias: `/elev`)