diff --git a/docs/cli/hooks.md b/docs/cli/hooks.md index 77592c664fb..b6b1af0a6ef 100644 --- a/docs/cli/hooks.md +++ b/docs/cli/hooks.md @@ -17,7 +17,7 @@ Related: - Hooks: [Hooks](/automation/hooks) - Plugin hooks: [Plugin hooks](/plugins/hooks) -## List All Hooks +## List all hooks ```bash openclaw hooks list @@ -60,7 +60,7 @@ openclaw hooks list --json Returns structured JSON for programmatic use. -## Get Hook Information +## Get hook information ```bash openclaw hooks info @@ -100,7 +100,7 @@ Requirements: Config: ✓ workspace.dir ``` -## Check Hooks Eligibility +## Check hooks eligibility ```bash openclaw hooks check @@ -194,7 +194,7 @@ openclaw hooks disable command-logger - `openclaw hooks list --json`, `info --json`, and `check --json` write structured JSON directly to stdout. - Plugin-managed hooks cannot be enabled or disabled here; enable or disable the owning plugin instead. -## Install Hook Packs +## Install hook packs ```bash openclaw plugins install # ClawHub first, then npm @@ -248,7 +248,7 @@ openclaw plugins install -l ./my-hook-pack Linked hook packs are treated as managed hooks from an operator-configured directory, not as workspace hooks. -## Update Hook Packs +## Update hook packs ```bash openclaw plugins update @@ -269,7 +269,7 @@ When a stored integrity hash exists and the fetched artifact hash changes, OpenClaw prints a warning and asks for confirmation before proceeding. Use global `--yes` to bypass prompts in CI/non-interactive runs. -## Bundled Hooks +## Bundled hooks ### session-memory diff --git a/docs/install/ansible.md b/docs/install/ansible.md index c26e90e5da0..48d53ad0f44 100644 --- a/docs/install/ansible.md +++ b/docs/install/ansible.md @@ -24,7 +24,7 @@ The [openclaw-ansible](https://github.com/openclaw/openclaw-ansible) repo is the | **Network** | Internet connection for package installation | | **Ansible** | 2.14+ (installed automatically by the quick-start script) | -## What You Get +## What you get - **Firewall-first security** -- UFW + Docker isolation (only SSH + Tailscale accessible) - **Tailscale VPN** -- secure remote access without exposing services publicly @@ -33,7 +33,7 @@ The [openclaw-ansible](https://github.com/openclaw/openclaw-ansible) repo is the - **Systemd integration** -- auto-start on boot with hardening - **One-command setup** -- complete deployment in minutes -## Quick Start +## Quick start One-command install: @@ -41,7 +41,7 @@ One-command install: curl -fsSL https://raw.githubusercontent.com/openclaw/openclaw-ansible/main/install.sh | bash ``` -## What Gets Installed +## What gets installed The Ansible playbook installs and configures: @@ -86,7 +86,7 @@ backend. See [Sandboxing](/gateway/sandboxing) for details and other backends. -### Quick Commands +### Quick commands ```bash # Check service status @@ -103,7 +103,7 @@ sudo -i -u openclaw openclaw channels login ``` -## Security Architecture +## Security architecture The deployment uses a 4-layer defense model: @@ -122,7 +122,7 @@ Only port 22 (SSH) should be open. All other services (gateway, Docker) are lock Docker is installed for agent sandboxes (isolated tool execution), not for running the gateway itself. See [Multi-Agent Sandbox and Tools](/tools/multi-agent-sandbox-tools) for sandbox configuration. -## Manual Installation +## Manual installation If you prefer manual control over the automation: @@ -216,7 +216,7 @@ This is idempotent and safe to run multiple times. -## Advanced Configuration +## Advanced configuration For detailed security architecture and troubleshooting, see the openclaw-ansible repo: diff --git a/docs/pi.md b/docs/pi.md index cd862f9124c..06e9767f7c6 100644 --- a/docs/pi.md +++ b/docs/pi.md @@ -19,7 +19,7 @@ OpenClaw uses the pi SDK to embed an AI coding agent into its messaging gateway - Multi-account auth profile rotation with failover - Provider-agnostic model switching -## Package Dependencies +## Package dependencies ```json { @@ -37,7 +37,7 @@ OpenClaw uses the pi SDK to embed an AI coding agent into its messaging gateway | `pi-coding-agent` | High-level SDK: `createAgentSession`, `SessionManager`, `AuthStorage`, `ModelRegistry`, built-in tools | | `pi-tui` | Terminal UI components (used in OpenClaw's local TUI mode) | -## File Structure +## File structure ``` src/agents/ @@ -239,9 +239,9 @@ Image injection is prompt-local: OpenClaw loads image refs from the current prom passes them via `images` for that turn only. It does not re-scan older history turns to re-inject image payloads. -## Tool Architecture +## Tool architecture -### Tool Pipeline +### Tool pipeline 1. **Base Tools**: pi's `codingTools` (read, bash, edit, write) 2. **Custom Replacements**: OpenClaw replaces bash with `exec`/`process`, customizes read/edit/write for sandbox @@ -251,7 +251,7 @@ to re-inject image payloads. 6. **Schema Normalization**: Schemas cleaned for Gemini/OpenAI quirks 7. **AbortSignal Wrapping**: Tools wrapped to respect abort signals -### Tool Definition Adapter +### Tool definition adapter pi-agent-core's `AgentTool` has a different `execute` signature than pi-coding-agent's `ToolDefinition`. The adapter in `pi-tool-definition-adapter.ts` bridges this: @@ -270,7 +270,7 @@ export function toToolDefinitions(tools: AnyAgentTool[]): ToolDefinition[] { } ``` -### Tool Split Strategy +### Tool split strategy `splitSdkTools()` passes all tools via `customTools`: @@ -296,9 +296,9 @@ const systemPromptOverride = createSystemPromptOverride(appendPrompt); applySystemPromptOverrideToSession(session, systemPromptOverride); ``` -## Session Management +## Session management -### Session Files +### Session files Sessions are JSONL files with tree structure (id/parentId linking). Pi's `SessionManager` handles persistence: @@ -308,7 +308,7 @@ const sessionManager = SessionManager.open(params.sessionFile); OpenClaw wraps this with `guardSessionManager()` for tool result safety. -### Session Caching +### Session caching `session-manager-cache.ts` caches SessionManager instances to avoid repeated file parsing: @@ -318,7 +318,7 @@ sessionManager = SessionManager.open(params.sessionFile); trackSessionManagerAccess(params.sessionFile); ``` -### History Limiting +### History limiting `limitHistoryTurns()` trims conversation history based on channel type (DM vs group). @@ -339,7 +339,7 @@ const compactResult = await compactEmbeddedPiSessionDirect({ ## Authentication & Model Resolution -### Auth Profiles +### Auth profiles OpenClaw maintains an auth profile store with multiple API keys per provider: @@ -355,7 +355,7 @@ await markAuthProfileFailure({ store, profileId, reason, cfg, agentDir }); const rotated = await advanceAuthProfile(); ``` -### Model Resolution +### Model resolution ```typescript import { resolveModel } from "./pi-embedded-runner/model.js"; @@ -387,11 +387,11 @@ if (fallbackConfigured && isFailoverErrorMessage(errorText)) { } ``` -## Pi Extensions +## Pi extensions OpenClaw loads custom pi extensions for specialized behavior: -### Compaction Safeguard +### Compaction safeguard `src/agents/pi-hooks/compaction-safeguard.ts` adds guardrails to compaction, including adaptive token budgeting plus tool failure and file operation summaries: @@ -402,7 +402,7 @@ if (resolveCompactionMode(params.cfg) === "safeguard") { } ``` -### Context Pruning +### Context pruning `src/agents/pi-hooks/context-pruning.ts` implements cache-TTL based context pruning: @@ -420,7 +420,7 @@ if (cfg?.agents?.defaults?.contextPruning?.mode === "cache-ttl") { ## Streaming & Block Replies -### Block Chunking +### Block chunking `EmbeddedBlockChunker` manages streaming text into discrete reply blocks: @@ -439,7 +439,7 @@ const stripBlockTags = (text: string, state: { thinking: boolean; final: boolean }; ``` -### Reply Directives +### Reply directives Reply directives like `[[media:url]]`, `[[voice]]`, `[[reply:id]]` are parsed and extracted: @@ -447,9 +447,9 @@ Reply directives like `[[media:url]]`, `[[voice]]`, `[[reply:id]]` are parsed an const { text: cleanedText, mediaUrls, audioAsVoice, replyToId } = consumeReplyDirectives(chunk); ``` -## Error Handling +## Error handling -### Error Classification +### Error classification `pi-embedded-helpers.ts` classifies errors for appropriate handling: @@ -462,7 +462,7 @@ isFailoverAssistantError(...) // Should failover classifyFailoverReason(errorText) // "auth" | "rate_limit" | "quota" | "timeout" | ... ``` -### Thinking Level Fallback +### Thinking level fallback If a thinking level is unsupported, it falls back: @@ -477,7 +477,7 @@ if (fallbackThinking) { } ``` -## Sandbox Integration +## Sandbox integration When sandbox mode is enabled, tools and paths are constrained: @@ -523,7 +523,7 @@ import { ... } from "@mariozechner/pi-tui"; This provides the interactive terminal experience similar to pi's native mode. -## Key Differences from Pi CLI +## Key differences from Pi CLI | Aspect | Pi CLI | OpenClaw Embedded | | --------------- | ----------------------- | ---------------------------------------------------------------------------------------------- | @@ -535,7 +535,7 @@ This provides the interactive terminal experience similar to pi's native mode. | Extensions | Loaded from disk | Programmatic + disk paths | | Event handling | TUI rendering | Callback-based (onBlockReply, etc.) | -## Future Considerations +## Future considerations Areas for potential rework: diff --git a/docs/plan/ui-channels.md b/docs/plan/ui-channels.md index 10456f2a63c..a12e778c191 100644 --- a/docs/plan/ui-channels.md +++ b/docs/plan/ui-channels.md @@ -43,14 +43,14 @@ This makes core aware of native UI shapes, weakens plugin runtime laziness, and - Unsupported presentation features auto-degrade to the best text representation. - Delivery behavior such as pinning a sent message is generic delivery metadata, not presentation. -## Non Goals +## Non goals - No backwards compatibility shim for `buildCrossContextComponents`. - No public native escape hatches for `components`, `blocks`, `buttons`, or `card`. - No core imports of channel-native UI libraries. - No provider-specific SDK seams for bundled channels. -## Target Model +## Target model Add a core-owned `presentation` field to `ReplyPayload`. @@ -91,7 +91,7 @@ type MessagePresentationOption = { The external agent and CLI schemas now use `presentation`; `interactive` remains an internal legacy parser/rendering helper for existing reply producers. -## Delivery Metadata +## Delivery metadata Add a core-owned `delivery` field for send behavior that is not UI. @@ -116,7 +116,7 @@ Semantics: Current Telegram ACP topic binding should move from `channelData.telegram.pin = true` to `delivery.pin = true`. -## Runtime Capability Contract +## Runtime capability contract Add presentation and delivery render hooks to the runtime outbound adapter, not the control-plane channel plugin. @@ -165,7 +165,7 @@ Core behavior: - If no renderer exists, convert presentation to text fallback. - After successful send, call `pinDeliveredMessage` when `delivery.pin` is requested and supported. -## Channel Mapping +## Channel mapping Discord: @@ -212,7 +212,7 @@ Plain or limited channels: - Convert presentation to text with conservative formatting. -## Refactor Steps +## Refactor steps 1. Reapply the Discord release fix that splits `ui-colors.ts` from Carbon-backed UI and removes `DiscordUiContainer` from `extensions/discord/src/channel.ts`. 2. Add `presentation` and `delivery` to `ReplyPayload`, outbound payload normalization, delivery summaries, and hook payloads. @@ -245,7 +245,7 @@ Add or update: - Discord entrypoint import-laziness regression covering Carbon. - Delivery pin tests covering Telegram and generic fallback. -## Open Questions +## Open questions - Should `delivery.pin` be implemented for Discord, Slack, MS Teams, and Feishu in the first pass, or only Telegram first? - Should `delivery` eventually absorb existing fields such as `replyToId`, `replyToCurrent`, `silent`, and `audioAsVoice`, or stay focused on post-send behaviors? diff --git a/docs/plugins/message-presentation.md b/docs/plugins/message-presentation.md index 509f69fdb7c..6b9130ae728 100644 --- a/docs/plugins/message-presentation.md +++ b/docs/plugins/message-presentation.md @@ -91,7 +91,7 @@ Select semantics: select support. - If a channel does not support selects, fallback text lists the labels. -## Producer Examples +## Producer examples Simple card: @@ -175,7 +175,7 @@ Pinned delivery with explicit JSON: } ``` -## Renderer Contract +## Renderer contract Channel plugins declare render support on their outbound adapter: @@ -206,7 +206,7 @@ renderer can make interactive, not every native platform limit. Renderers still own platform-specific limits such as maximum button count, block count, and card size. -## Core Render Flow +## Core render flow When a `ReplyPayload` or message action includes `presentation`, core: @@ -222,7 +222,7 @@ When a `ReplyPayload` or message action includes `presentation`, core: Core owns fallback behavior so producers can stay channel-agnostic. Channel plugins own native rendering and interaction handling. -## Degradation Rules +## Degradation rules Presentation must be safe to send on limited channels. @@ -246,7 +246,7 @@ Examples: The main exception is `delivery.pin.required: true`; if pinning is requested as required and the channel cannot pin the sent message, delivery reports failure. -## Provider Mapping +## Provider mapping Current bundled renderers: @@ -295,7 +295,7 @@ import { New code should accept or produce `MessagePresentation` directly. -## Delivery Pin +## Delivery pin Pinning is delivery behavior, not presentation. Use `delivery.pin` instead of provider-native fields such as `channelData.telegram.pin`. @@ -312,7 +312,7 @@ Semantics: Manual `pin`, `unpin`, and `pins` message actions still exist for existing messages where the provider supports those operations. -## Plugin Author Checklist +## Plugin author checklist - Declare `presentation` from `describeMessageTool(...)` when the channel can render or safely degrade semantic presentation. @@ -328,7 +328,7 @@ messages where the provider supports those operations. - Do not expose new provider-native card/block/component/button fields through the shared message action schema. -## Related Docs +## Related docs - [Message CLI](/cli/message) - [Plugin SDK Overview](/plugins/sdk-overview)