LeoYeAI/agent-master-skills / skills/bengii-gemini-fix
openclaw
FlaggedComprehensive guide for installing, configuring, operating, and troubleshooting OpenClaw — a self-hosted, multi-channel AI agent gateway. Use when the user asks about OpenClaw setup, configuration, channel management (WhatsApp/Telegram/Discord/Slack/iMessage/etc.), model provider setup, Gateway operations, multi-agent routing, security hardening, troubleshooting, or any maintenance task related to their local OpenClaw installation. Also use when encountering errors from `openclaw` CLI commands or the Gateway daemon.
references/agent_runtime.md
View on GitHub# Agent Runtime & Agent Loop
> Sources:
> - https://docs.openclaw.ai/concepts/agent
> - https://docs.openclaw.ai/concepts/agent-loop
> - https://docs.openclaw.ai/concepts/agent-workspace
## Agent Runtime
### Workspace (Required)
- Set via `agents.defaults.workspace` or `cwd` during `openclaw setup`.
- Config: `~/.openclaw/openclaw.json`.
- Sandbox: `agents.defaults.sandbox` / `agents.defaults.sandbox.workspaceRoot`.
### Bootstrap Files (Injected)
Files injected into `agents.defaults.workspace`:
| File | Purpose |
|---|---|
| `AGENTS.md` | Operating instructions + "memory" |
| `SOUL.md` | Persona, boundaries, tone |
| `TOOLS.md` | User-maintained tool notes (e.g. imsg, sag, conventions) |
| `BOOTSTRAP.md` | One-time first-run ritual (deleted after completion) |
| `IDENTITY.md` | Agent name/vibe/emoji |
| `USER.md` | User profile + preferred address |
- Created by `openclaw setup`.
- Skip bootstrap: `{ agent: { skipBootstrap: true } }`.
### Skills
- Bundled (shipped with the install)
- Managed/local: `~/.openclaw/skills`
- Workspace: `<workspace>/skills`
### pi-mono Integration
- No pi-coding agent runtime.
- No `~/.pi/agent` or `<workspace>/.pi` settings are consulted.
### Sessions
- Stored at: `~/.openclaw/agents/<agentId>/sessions/<SessionId>.jsonl`
### Steering While Streaming
- `steer` / `followup` / `collect` modes.
- Config: `agents.defaults.blockStreamingDefault: "off"`, `agents.defaults.blockStreamingBreak`, `agents.defaults.blockStreamingChunk`, `agents.defaults.blockStreamingCoalesce`.
- Per-channel: `*.blockStreaming: true`.
### Model Refs
- Config at `agents.defaults.model` / `agents.defaults.models`.
- Use `provider/model` format. If model ID itself contains `/` (OpenRouter-style), include the provider prefix (e.g. `openrouter/moonshotai/kimi-k2`).
- If provider is omitted, OpenClaw treats input as an alias or model for the default provider.
### Minimal Configuration
- `agents.defaults.workspace`
- `channels.whatsapp.allowFrom` (strongly recommended)
---
## Agent Loop
### Entry Points
- Gateway RPC: `agent` and `agent.wait`.
- CLI: `agent` command.
### How It Works (High-Level)
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
- Loads skills snapshot
- Calls `runEmbeddedPiAgent` (pi-agent-core runtime)
- Emits lifecycle end/error if the embedded loop does not emit one
3. `runEmbeddedPiAgent`:
- Serializes runs via per-session + global queues
- Resolves model + auth profile and builds the pi session
- Subscribes to pi events and streams assistant/tool deltas
- Enforces timeout → aborts run if exceeded
- Returns payloads + usage metadata
4. `subscribeEmbeddedPiSession` bridges pi-agent-core events to OpenClaw agent stream:
- tool events ⇒ `stream: "tool"`
- assistant deltas ⇒ `stream: "assistant"`
- lifecycle events ⇒ `stream: "lifecycle"` (`phase: "start" | "end" | "error"`)
5. `agent.wait` uses `waitForAgentJob`:
- Waits for lifecycle end/error for `runId`
- Returns `{ status: ok|error|timeout, startedAt, endedAt, error? }`
### Queueing + Concurrency
- Runs are serialized per session key (session lane) and optionally through a global lane.
- Prevents tool/session races and keeps session history consistent.
- Messaging channels can choose queue modes (`collect`/`steer`/`followup`).
### Prompt Assembly + System Prompt
- Built from OpenClaw's base prompt, skills prompt, bootstrap context, and per-run overrides.
- Model-specific limits and compaction reserve tokens are enforced.
### Hook Points
#### Internal Hooks (Gateway Hooks)
- `agent:bootstrap`: runs while building bootstrap files before the system prompt is finalized.
- Command hooks: `/new`, `/reset`, `/stop`, and other command events.
#### Plugin Hooks (Agent + Gateway Lifecycle)
| Hook | Description |
|---|---|
| `before_model_resolve` | Pre-session (no messages), override provider/model |
| `before_prompt_build` | Post-session load, inject `prependContext`, `systemPrompt`, etc. |
| `before_agent_start` | Legacy compatibility hook |
| `agent_end` | Inspect final messages and run metadata |
| `before_compaction` / `after_compaction` | Observe/annotate compaction cycles |
| `before_tool_call` / `after_tool_call` | Intercept tool params/results |
| `tool_result_persist` | Transform tool results before session write |
| `message_received` / `message_sending` / `message_sent` | Inbound + outbound message hooks |
| `session_start` / `session_end` | Session lifecycle boundaries |
| `gateway_start` / `gateway_stop` | Gateway lifecycle events |
### Streaming + Partial Replies
- Assistant deltas streamed from pi-agent-core as `assistant` events.
- Block streaming on `text_end` or `message_end`.
### Reply Shaping + Suppression
- `NO_REPLY` is treated as a silent token, filtered from outgoing payloads.
- Messaging tool duplicates are removed from the final payload list.
- If no renderable payloads remain and a tool errored, a fallback tool error reply is emitted.
### Timeouts
- `agent.wait` default: 30s (just the wait). `timeoutMs` param overrides.
- Agent runtime: `agents.defaults.timeoutSeconds` default 600s; enforced in `runEmbeddedPiAgent` abort timer.
### Event Streams
| Stream | Source |
|---|---|
| `lifecycle` | `subscribeEmbeddedPiSession` (and fallback `agentCommand`) |
| `assistant` | Streamed deltas from pi-agent-core |
| `tool` | Streamed tool events from pi-agent-core |
### Where Things Can End Early
- Agent timeout (abort)
- AbortSignal (cancel)
- Gateway disconnect or RPC timeout
- `agent.wait` timeout (wait-only, does not stop agent)
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |