Skip to content

LeoYeAI/agent-master-skills / skills/bengii-gemini-fix

openclaw

Flagged

Comprehensive 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.

FileKindSize
README.mdmarkdown7.5 KB
README_CN.mdmarkdown7.3 KB
SKILL.mdskill md18.7 KB
_meta.jsonconfig286 B
references/acp_agents.mdmarkdown12.6 KB
references/agent_runtime.mdmarkdown5.6 KB
references/architecture.mdmarkdown3.8 KB
references/automation.mdmarkdown5.8 KB
references/bonjour.mdmarkdown3.3 KB
references/browser.mdmarkdown8.5 KB
references/channel_routing.mdmarkdown4.0 KB
references/channel_troubleshooting.mdmarkdown11.6 KB
references/channels.mdmarkdown6.2 KB
references/clawhub.mdmarkdown3.6 KB
references/config_reference.mdmarkdown11.2 KB
references/diffs_firecrawl.mdmarkdown3.3 KB
references/elevated.mdmarkdown2.8 KB
references/exec.mdmarkdown6.5 KB
references/exec_approvals.mdmarkdown3.1 KB
references/gateway_internals.mdmarkdown7.7 KB
references/gateway_ops.mdmarkdown9.6 KB
references/heartbeat.mdmarkdown4.9 KB
references/hooks.mdmarkdown14.6 KB
references/install.mdmarkdown4.1 KB
references/llm_task.mdmarkdown2.6 KB
references/lobster.mdmarkdown7.8 KB
references/media.mdmarkdown4.2 KB
references/memory.mdmarkdown11.9 KB
references/model_failover.mdmarkdown3.1 KB
references/multi_agent.mdmarkdown4.4 KB
references/nodes.mdmarkdown8.8 KB
references/openprose.mdmarkdown2.6 KB
references/pairing.mdmarkdown3.1 KB
references/pdf_tool.mdmarkdown3.5 KB
references/platforms.mdmarkdown2.7 KB
references/plugins.mdmarkdown6.9 KB
references/polls.mdmarkdown2.2 KB
references/presence_discovery.mdmarkdown2.2 KB
references/providers.mdmarkdown6.0 KB
references/queue.mdmarkdown2.1 KB
references/remote_access.mdmarkdown4.7 KB
references/sandboxing.mdmarkdown5.6 KB
references/secrets.mdmarkdown5.4 KB
references/security.mdmarkdown24.5 KB
references/sessions.mdmarkdown8.9 KB
references/skills.mdmarkdown4.4 KB
references/slash_commands.mdmarkdown5.1 KB
references/streaming.mdmarkdown1.8 KB
references/subagents.mdmarkdown12.3 KB
references/thinking.mdmarkdown2.8 KB
references/tools.mdmarkdown13.3 KB
references/tui.mdmarkdown4.0 KB
references/voice.mdmarkdown2.7 KB
references/web_tools.mdmarkdown2.7 KB
references/web_ui.mdmarkdown4.5 KB

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)
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: 471kUpdated Claude CodeCodexVerifiedInstall
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: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall