OpenClaw Architecture Analysis / Real-World Scenario Q&A

╔══════════════════════════════════════════════════════════════════════════╗
║                          OpenClaw System                                 ║
║                                                                          ║
║  ┌─────────────────────────────────────────────────────────────────┐    ║
║  │                    CLI Entry Layer                               │    ║
║  │  entry.ts → run-main.ts → program.ts → Commander.js commands    │    ║
║  │  openclaw onboard / gateway / agent / send / doctor / config    │    ║
║  └───────────────────────┬─────────────────────────────────────────┘    ║
║                          │ start                                         ║
║  ┌───────────────────────▼─────────────────────────────────────────┐    ║
║  │                    Gateway (Control Plane)                       │    ║
║  │   ws://127.0.0.1:18789  +  HTTP                                 │    ║
║  │                                                                  │    ║
║  │  server.impl.ts ──┬── server-http.ts (Express + WS)             │    ║
║  │                   ├── server-chat.ts (ChatRunRegistry)           │    ║
║  │                   ├── server-channels.ts (ChannelManager)        │    ║
║  │                   ├── server-cron.ts (Croner scheduler)          │    ║
║  │                   ├── server-plugins.ts (Plugin registry)        │    ║
║  │                   └── server-methods/ (100+ RPC handlers)        │    ║
║  └──────────┬─────────────────────────────┬───────────────────────┘    ║
║             │ WebSocket frames             │ Channel events              ║
║             ▼                             ▼                              ║
║  ┌──────────────────┐         ┌──────────────────────────────────────┐  ║
║  │   WS Clients     │         │         Channel Manager              │  ║
║  │                  │         │                                      │  ║
║  │ • Control UI     │         │  telegram/ discord/ slack/           │  ║
║  │ • macOS app      │         │  signal/  imessage/ whatsapp/        │  ║
║  │ • iOS/Android    │         │  line/    + 15 extensions            │  ║
║  │ • WebChat        │         └──────────────┬───────────────────────┘  ║
║  └──────────────────┘                        │ inbound/outbound          ║
║                                              ▼                           ║
║  ┌───────────────────────────────────────────────────────────────────┐  ║
║  │                      Agent Engine                                 │  ║
║  │                                                                   │  ║
║  │  agent-scope.ts ──→ ResolvedAgentConfig                          │  ║
║  │       │              (workspace, model, skills, heartbeat)        │  ║
║  │       ▼                                                           │  ║
║  │  pi-embedded-runner/ ──→ Pi Agent (RPC)                          │  ║
║  │       │                                                           │  ║
║  │       ├── tools/         (browser, canvas, cron, system)         │  ║
║  │       ├── skills/        (notion, github, spotify...)            │  ║
║  │       ├── memory/        (vector search, session files)          │  ║
║  │       └── infra/agent-events.ts (EventBus)                      │  ║
║  └───────────────────────────────────────────────────────────────────┘  ║
║             │                                                            ║
║             ▼                                                            ║
║  ┌──────────────────────────┐                                           ║
║  │   LLM Providers          │                                           ║
║  │  OpenAI / Anthropic /    │                                           ║
║  │  Google / 20+ others     │                                           ║
║  └──────────────────────────┘                                           ║
╚══════════════════════════════════════════════════════════════════════════╝

[Incoming user WhatsApp message]
        │
        ▼
src/web/ (WhatsApp Web handler)
  └── Message parsing & normalization
        │
        ▼
src/routing/session-key.ts
  └── Session key generated: "agent:main:whatsapp/+1234567890"
        │
        ▼
src/channels/allowlists/
  └── dmPolicy check
        ├── "pairing" → Request pairing code
        ├── "open"    → Allow processing
        └── "block"   → Block message
              │ if allowed
              ▼
src/gateway/server-chat.ts (ChatRunRegistry)
  └── Assign runId to session, enqueue
        │
        ▼
src/agents/pi-embedded-runner/
  └── Pi Agent RPC execution
        ├── LLM API call (streaming)
        └── Tool execution (if needed)
              │ on completion
              ▼
src/infra/agent-events.ts (EventBus)
  └── Publish AgentEventPayload
      { stream: "assistant", data: "response text" }
        │
        ├── → gateway/server/ws-connection.ts
        │         Deliver in real time to Control UI via WebSocket
        │
        └── → src/infra/outbound/
                  └── Send response back to originating channel (WhatsApp)

1. Load & validate config (config/config.ts)
2. Initialize authentication (auth.ts)
3. Load plugins (server-plugins.ts)
4. Create channel manager (server-channels.ts)
5. Create HTTP/HTTPS server (server-http.ts)
6. Attach WebSocket server
7. Register RPC methods (server-methods/)
8. Start health monitoring
9. Start cron service
10. Start maintenance timer

GatewayFrame // Request/response (method calls)
EventFrame // Broadcast events
ChatEvent // Chat streaming updates
AgentEvent // Agent state updates
HelloOk // Connection handshake

OpenClawConfig.agents.list[n]
  → ResolvedAgentConfig {
      name,
      workspace,    // ~/.openclaw/agents/<id>/
      model,        // LLM model configuration
      skills,       // List of available skills
      heartbeat,    // Periodic execution settings
      sandbox       // Sandbox policy
    }
  → AgentScope
  → Agent execution context

AgentEventPayload {
  runId: string        // Execution unit ID
  seq: number          // Monotonically increasing sequence number
  stream:              // Event stream type
    | "lifecycle"      // Agent start/stop
    | "tool"           // Tool execution events
    | "assistant"      // Response text
    | "error"          // Error events
  data: Record<string, unknown>
  sessionKey?: string  // Session routing
}

ChannelEntryMatch {
  entry,           // Direct match (e.g. telegram/+1234)
  wildcardEntry,   // Wildcard match (*)
  parentEntry,     // Inherit parent channel config
  matchSource      // Track match origin
}

# config.yml
channels:
  telegram:
    dmPolicy: 'pairing' # default: pairing code required
    # dmPolicy: "open"    # explicit opt-in required
    # dmPolicy: "block"   # block all
    allowFrom:
      - '+1234567890' # allowed contacts
      # - "*"             # allow all (dangerous)

ChannelRuntimeSnapshot {
  channels: Map<channelId, ChannelPlugin>
  channelAccounts: Map<accountId, ChannelAccountSnapshot>
}

ChannelAccountSnapshot {
  accountId: string
  defaultRuntime: ChannelRuntime
  health: "ok" | "degraded" | "down"
}

~/.openclaw/
  ├── config.yml          # Main config (JSON5 format)
  ├── credentials/        # Auth credentials (encrypted)
  ├── sessions/           # Session records
  │   ├── main.json
  │   └── <agentId>.json
  └── agents/
      └── <agentId>/
          └── sessions/*.jsonl

Detect config.yml file change (chokidar)
  → Reload plugins
  → Restart channels (changed channels only)
  → Update secrets
  → Refresh memory index

extensions/
  ├── Channel plugins
  │   ├── discord          # Discord extension
  │   ├── line             # LINE messaging
  │   ├── msteams          # Microsoft Teams
  │   ├── matrix           # Matrix protocol
  │   ├── feishu           # Feishu/Lark
  │   ├── googlechat       # Google Chat
  │   ├── irc              # IRC
  │   ├── mattermost       # Mattermost
  │   ├── nostr            # Nostr protocol
  │   ├── zalo / zalouser  # Zalo (Vietnam)
  │   ├── bluebubbles      # BlueBubbles (iMessage)
  │   └── ...
  ├── Memory plugins
  │   ├── memory-core      # Basic memory
  │   └── memory-lancedb   # LanceDB vector search
  └── Integration plugins
      ├── llm-task         # LLM tasks
      ├── diagnostics-otel # OpenTelemetry
      └── ...

skills/
  ├── Development
  │   ├── coding-agent     # Coding automation
  │   └── gh-issues        # GitHub issue management
  ├── Productivity
  │   ├── notion           # Notion integration
  │   ├── obsidian         # Obsidian integration
  │   ├── things-mac       # Things 3 (macOS)
  │   └── trello           # Trello integration
  ├── Content
  │   ├── blogwatcher      # Blog monitoring
  │   └── summarize        # Content summarization
  └── System
      ├── healthcheck      # System health check
      ├── tmux             # tmux control
      └── voice-call       # Voice calls

// plugins/registry.ts
// Dynamically loaded from npm packages or local paths
import { loadPlugin } from 'openclaw/plugin-sdk'

// Plugin interface
interface OpenClawPlugin {
  id: string
  channels?: ChannelPlugin[]
  skills?: SkillPlugin[]
  memory?: MemoryPlugin
  cli?: CLIPlugin
}

"agent:main:telegram/+1234567890"
   │     │    └── channel/account
   │     └── agentId ("main" or custom)
   └── prefix

Special cases:
  "agent:main:__default"  # Default account
  "cron:<jobId>"          # Cron job session
  "acp:<id>"              # Agent Control Protocol

ChannelId
  → Agent
    → SessionKey
      → ChatRunEntry { sessionKey, clientRunId }
        → AgentEventPayload (stream: lifecycle|tool|assistant)
          → ChatEvent (WS frame)
            → WebSocket Client (Control UI / channel response)

AgentRunContext {
  sessionKey: string
  verboseLevel: "low" | "medium" | "high"
  isHeartbeat: boolean
  runId: string
}

entry.ts
  └── cli/run-main.ts
        └── cli/program.ts (Commander.js)
              └── commands/ (284 command handlers)
                    └── gateway/server.impl.ts  ← core hub
                          ├── config/config.ts         (config)
                          ├── channels/plugins/        (channels)
                          ├── agents/agent-scope.ts    (agents)
                          ├── infra/agent-events.ts    (EventBus)
                          ├── gateway/server-http.ts   (WS server)
                          └── gateway/server-methods/  (RPC API)

Dependency direction:
  CLI → Gateway → {Channels, Agents, Config, Infra}
  Agents → {LLM Providers, Tools, Memory}
  Channels → {Channel SDKs, Gateway EventBus}
  Config → {File System, Migration, Zod Schemas}

openclaw/
├── src/                      # TypeScript source
│   ├── entry.ts              # CLI entry point
│   ├── index.ts              # Public API exports
│   ├── cli/                  # CLI layer (168 files)
│   │   ├── program/
│   │   ├── daemon-cli/
│   │   ├── gateway-cli/
│   │   ├── run-main.ts
│   │   └── argv.ts
│   ├── gateway/              # Gateway server (236 files)
│   │   ├── server.impl.ts    # Main server
│   │   ├── server-http.ts    # HTTP/WS
│   │   ├── server-chat.ts    # Chat events
│   │   ├── server-channels.ts
│   │   ├── protocol/         # WS frame schemas
│   │   └── server-methods/   # RPC handlers (65 files)
│   ├── agents/               # Agent engine (530 files)
│   │   ├── agent-scope.ts
│   │   ├── pi-embedded-runner/
│   │   ├── auth-profiles/
│   │   ├── skills/
│   │   └── tools/
│   ├── channels/             # Channel abstraction (65 files)
│   │   ├── plugins/
│   │   ├── allowlists/
│   │   └── dock.ts
│   ├── config/               # Config management (207 files)
│   │   ├── config.ts
│   │   ├── sessions/
│   │   └── zod-schema.*.ts
│   ├── infra/                # Infrastructure utilities (297 files)
│   │   ├── agent-events.ts   # EventBus
│   │   ├── outbound/
│   │   └── heartbeat-runner.ts
│   ├── memory/               # Memory system (97 files)
│   ├── browser/              # Browser automation (127 files)
│   ├── media/                # Media pipeline
│   ├── routing/              # Message routing
│   ├── secrets/              # Credential management
│   ├── security/             # Security
│   ├── commands/             # Command handlers (284 files)
│   ├── telegram/             # Telegram implementation
│   ├── discord/              # Discord implementation
│   ├── slack/                # Slack implementation
│   ├── signal/               # Signal implementation
│   ├── imessage/             # iMessage implementation
│   └── web/                  # WhatsApp Web implementation
├── extensions/               # 42 plugins
├── skills/                   # 50+ skills
├── apps/                     # Native apps
│   ├── macos/                # SwiftUI menu bar app
│   ├── ios/                  # Swift/SwiftUI iOS
│   ├── android/              # Kotlin Android
│   └── shared/               # Cross-platform shared
├── ui/                       # Web UI (Lit + Vite)
├── docs/                     # Documentation (Mintlify)
├── scripts/                  # Automation scripts (100+)
├── packages/                 # Internal packages
├── package.json
├── pnpm-workspace.yaml
└── tsconfig.json

What a human does                  What Playwright does
────────────────────────────────────────────────────
Open a Chrome window          →   chromium.launch()
Type a URL in the address bar →   page.goto(url)
Visually scan page structure  →   page.ariaSnapshot()
Click a link                  →   locator.click()
Type in a search box          →   locator.fill("search term")
Run code in the JS console    →   page.evaluate(fn)
Take a screenshot             →   page.screenshot()

LLM (decision-making)
  │
  │  "I should click this button"
  ▼
Browser Tool (src/agents/tools/browser-tool.ts)
  │
  │  { action: "act", request: { kind: "click", ref: "e5" } }
  ▼
Playwright API (src/browser/pw-tools-core.interactions.ts)
  │
  │  locator.click({ timeout: 8000 })
  ▼
Chrome DevTools Protocol (CDP) via WebSocket
  │
  ▼
Actual Chrome browser

// Example from src/agents/tools/browser-tool.ts
{
  name: "browser",                    // Name the LLM calls
  description: "Control a browser",  // Description that tells the LLM when to use it
  inputSchema: {                      // Parameter definition the LLM must provide
    action: "navigate | snapshot | act | screenshot ...",
    url: "string",
    ref: "string",
  },
  execute: async (toolCallId, args) => {  // Actual execution code
    return result
  }
}

LLM → generate tool_use block
  │
  ▼
src/agents/pi-embedded-subscribe.handlers.ts
  case "tool_execution_start" → publish tool execution start event
  │
  ▼
src/agents/tools/<tool>.ts
  execute(toolCallId, args) called
  │
  ▼
src/infra/agent-events.ts (EventBus)
  tool_execution_end → return result
  │
  ▼
LLM → read result, decide next step

[Single-turn — Generic LLM]
User: "Crawl the Naver news"
LLM:  "I can't access the internet directly, so I'm unable to crawl."
End.

[Multi-turn — OpenClaw]
User: "Crawl the Naver sports news"

Turn 1: LLM → browser.open("sports.naver.com")
        Result: { url: "https://sports.naver.com", ok: true }

Turn 2: LLM → browser.snapshot()
        Result: { refs: { e1: "International Football", e5: "Article 1"... } }

Turn 3: LLM → browser.act({ kind: "click", ref: "e1" })
        Result: { ok: true }

Turn 4: LLM → browser.act({ kind: "evaluate", fn: "..." })
        Result: { articles: [...] }

Turn 5: LLM → generate final response (no more tools needed)
User: "Here are 3 articles: ..."

src/agents/pi-embedded-runner/run.ts

while (true) {
  response = await llm.send(messages + toolResults)

  if (response.stopReason === "end_turn") break  // done

  if (response.stopReason === "tool_use") {
    result = await executeTool(response.toolCall)
    messages.push({ role: "tool", content: result })
    // continue to next turn
  }
}

// Browser management
"status"     → Check browser running state
"start"      → Start browser
"stop"       → Stop browser

// Tab management
"open"       → Open a new tab (URL optional)
"tabs"       → List open tabs
"focus"      → Switch focus to a specific tab
"close"      → Close a tab

// Page inspection
"navigate"   → Navigate to a URL
"snapshot"   → Extract page structure (ARIA tree, generate refs)
"screenshot" → Capture screen (save as PNG)
"pdf"        → Save page as PDF

// Interaction (act)
"act" + kind:
  "click"          → Click an element
  "dblclick"       → Double-click
  "hover"          → Mouse over
  "type"           → Keyboard input
  "fill"           → Fill a form field
  "press"          → Press a specific key (Enter, Tab, etc.)
  "select"         → Select a dropdown option
  "drag"           → Drag and drop
  "scrollIntoView" → Scroll element into view
  "wait"           → Wait for a condition
  "evaluate"       → Execute arbitrary JavaScript
  "resize"         → Resize the viewport

// File/dialog
"upload"     → Upload a file
"dialog"     → Handle browser dialogs
"console"    → Execute JavaScript in developer console

snapshot() called
  → Convert all page elements to an ARIA tree
  → Assign short ref IDs to each element: e1, e2, e3 ...
  → Return to LLM

LLM reads the snapshot:
  "link 'International Football' <e1>"
  "article 'Son Heung-min goal' <e5>"

act(click, ref: "e5") called
  → Dereference ref "e5" to the actual DOM element
  → Convert to Playwright locator → execute click

┌─────────────────────────────────────────────────────────────┐
│                      Multi-turn loop                        │
│                                                             │
│  ┌──────────┐    tool_use     ┌──────────────────────────┐  │
│  │          │ ─────────────→  │         Tool             │  │
│  │   LLM    │                 │  (browser / read / exec) │  │
│  │          │ ←─────────────  │                          │  │
│  └──────────┘   tool_result   └────────────┬─────────────┘  │
│       │                                    │                │
│       │ (next turn)                        │ Action exec    │
│       └────────────────────────────────────┘                │
└─────────────────────────────────────────────────────────────┘
                                │
                    Action (navigate, snapshot, act ...)
                                │
                                ▼
                    ┌───────────────────────┐
                    │      Playwright       │
                    │  page.goto()          │
                    │  page.ariaSnapshot()  │
                    │  locator.click()      │
                    │  page.evaluate()      │
                    └───────────┬───────────┘
                                │
                                ▼
                         Actual Chrome browser

2022 ──────────────────────────────────────────────────── 2026

  [Gen 1: Experiments]  [Gen 2: Frameworks]  [Gen 3: Standards]  [Gen 4: Personal AI]
         │                    │                    │                      │
  2023.3 AutoGPT       2023   LangChain      2024.11 MCP          2025   OpenClaw
  2023.4 BabyAGI       2023.6 Function      (Anthropic)           2026.1 NanoClaw
  2023   AgentGPT            Calling                               2026   MicroClaw
  2024   CrewAI        2024   AutoGen
         SuperAGI

AutoGPT (2023.3, 100K+ GitHub Stars explosion)
  - "Give it a goal and the LLM plans, executes, and iterates on its own"
  - Tool integrations: web search, file writes, code execution
  - Structure: LLM → task decomposition → execution → incorporate results → repeat

BabyAGI / AgentGPT (2023.4+)
  - Derivative projects that simplified the task queue + LLM loop pattern
  - BabyAGI: task creation → execution → priority reordering

ReAct = Reasoning + Acting

LLM decides: "I need to know the weather"
    │
    ▼
Tool call: weather_api("Seoul")
    │
    ▼
Observation: "22°C, clear"
    │
    ▼
LLM re-reasons: "I have enough information, generate a response"
    │
    ▼
Final response

Before: LLM outputs text "I need to search the web" → developer parses it
After:  LLM returns { "tool": "search", "query": "..." } structured output
        → The beginning of standardized tool integration

Before MCP:
  Claude ──own way──→ Tool A
  GPT-4  ──own way──→ Tool B  (every model has its own integration)
  Gemini ──own way──→ Tool C

After MCP:
  Claude ─┐
  GPT-4  ─┼──[MCP]──→ Tool A / Tool B / Tool C
  Gemini ─┘           (common standard interface)

① Always-on
   → Registered as a daemon, auto-starts at boot

② Messenger-first
   → Converse directly in 22+ messengers

③ Secure defaults
   → DM pairing, exec-approval blocks dangerous commands

④ Consumer-grade UX
   → Install with the openclaw onboard wizard, no coding knowledge needed

⑤ Local-first
   → Gateway runs on your device; your data never passes through OpenClaw servers

OpenClaw approach (app-level isolation):
  Personal agent ─┐
                  ├─ Single Node process (shared memory)
  Work agent ─────┘

NanoClaw approach (OS-level isolation):
  Personal agent → Linux container A (independent filesystem)
  Work agent     → Linux container B (independent filesystem)
  → Apple Container (macOS) / Docker supported
  → Containers are created fresh and discarded after each run (ephemeral)

Before: User → 1 agent → response

Swarms:
  User → Manager agent
               ├─ Research agent (container A)
               ├─ Coding agent   (container B)
               └─ Review agent   (container C)
            → Aggregate results → response

Gen 1 lesson: LLMs can execute autonomously, but reliability is the problem
Gen 2 lesson: Without tool integration standards, ecosystems fragment
Gen 3 lesson: A common protocol (MCP) causes explosive ecosystem growth
Gen 4 lesson: UX matters more than tech (developer → consumer transition)
Gen 5 lesson: Security must be solved at the OS level, not the app level
              (OpenClaw → NanoClaw's container isolation)

User message
    │
    ▼
Pi Agent (pi-embedded-runner/run.ts)
→ LLM determines "browser tool needed"
    │
    ▼
Browser Tool registered (src/agents/openclaw-tools.ts:125)
    │
    ▼
Chrome launched (src/browser/chrome.ts)
→ Run with --remote-debugging-port flag
→ Wait for CDP WebSocket connection
    │
    ▼
Playwright session connected (src/browser/pw-session.ts)
    │
    ▼
Multi-turn execution loop

📱 User (WhatsApp)
        │
        ▼
1. WhatsApp channel receives message (src/web/, @whiskeysockets/baileys)
        │
        ▼
2. Security check (dmPolicy = "pairing")
   ├─ Registered number → allow ✅
   └─ Unregistered number → request pairing code 🔒
        │
        ▼
3. Session key generated: "agent:main:whatsapp/+1234567890"
        │
        ▼
4. Pi Agent → LLM decides: "browser tool needed"
        │
        ▼
5. Browser automation loop

LLM API call (once) = sum of all the following
──────────────────────────────────────────────────────
① System prompt                  ~5,000–15,000 tokens
   - Agent instructions
   - Workspace files (bootstrap)
   - Skill descriptions

② Tool schemas                   ~2,000–5,000 tokens
   - browser, read, edit, exec, memory...
   - Entire schema sent on every call

③ Session history                variable (grows unboundedly)
   - All past conversation turns
   - Diary entries
   - Cron job execution results

④ Memory retrieval results       ~1,000–3,000 tokens

Total → 10,000–20,000 tokens even for a trivial question

runEmbeddedAttempt()
  → buildEmbeddedSystemPrompt()   ← ① rebuilt on every call
  → SessionManager.open()         ← ③ loads full session file
  → limitHistoryTurns()           ← trims only when DM limit is set

Session file: ~/.openclaw/agents/{agentId}/sessions/{sessionId}.jsonl

One diary entry recorded
  → Added as messages to the session (user + assistant + tool results)
  → On the next question, this diary content is included in history

30 diary entries accumulated
  → Every question includes all 30 conversation entries in history
  → Even a simple "What's the weather today?" carries the entire diary as context

src/agents/pi-embedded-runner/compact.ts

compactEmbeddedPiSession()
  → Load sessionId.jsonl (entire conversation record)
  → contextEngine.assemble() to summarize/compress
  → Replace file with compressed content (original deleted)
  → Increment compactionCount++ in sessions.json

Case A: Cron job explicitly defined in config.yml
  → Instructions live in config.yml, so they survive compaction ✅
  → BUT: accumulated cron execution results are erased ⚠️

Case B: Cron job instructed via conversation ("write a diary for me every morning")
  → Agent "remembers" only through the session history
  → After compaction, those instructions are deleted from history ❌
  → Agent "forgets" the instruction → cron job misbehaves

# ~/.openclaw/config.yml
cron:
  jobs:
    # ✅ Correct approach
    - id: 'daily-diary'
      name: 'Daily diary entry'
      schedule:
        kind: 'cron'
        expr: '0 22 * * *'
      payload:
        kind: 'agentTurn'
        message: 'Summarize today and save it as ~/diary/YYYY-MM-DD.md'
      sessionKey: 'cron:daily-diary' # ← use an isolated session


    # ❌ Wrong: instructed via conversation → forgotten after compaction

agents:
  list:
    - id: 'quick' # For everyday Q&A
      model: { name: 'claude-haiku-4-5' }
      session:
        dmHistoryLimit: 5 # Keep only the last 5 turns

    - id: 'main' # For coding / long tasks
      model: { name: 'claude-sonnet-4-6' }
      session:
        dmHistoryLimit: 20

agents:
  defaults:
    session:
      pruning:
        maxEntries: 50 # Cap total message count
        pruneAfter: '7d' # Auto-delete messages older than 7 days
      dmHistoryLimit: 10 # DM sessions: pass only the last 10 turns to the LLM

User: "Save this instruction to memory:
       'Every night at 10pm, summarize what I learned today and save it to the diary folder'"

Saved to: ~/.openclaw/agents/{agentId}/memory/instructions.md
→ Not subject to compaction (separate file)
→ Retrievable again via memory_search tool

[Before]
One simple question:
  System prompt:    8,000 tokens
  Tool schemas:     3,000 tokens
  Session history: 12,000 tokens (30 diary entries + cron results)
  Memory results:   2,000 tokens
  Total:           25,000 tokens

[After] (quick agent, haiku model, dmHistoryLimit=3)
  System prompt:    5,000 tokens
  Tool schemas:     2,000 tokens
  Session history:    800 tokens (last 3 turns only)
  Memory results:       0 tokens
  Total:            7,800 tokens  ← ~70% reduction

---
name: skill-name
version: "1.0"
description: "What this skill does"

# Activation conditions (gating)
requires:
  bins: ["gh", "git"]          # Activate only if these binaries exist
  env: ["GITHUB_TOKEN"]        # Activate only if these env vars are set
  config:                      # Conditions on config.yml values
    - path: "features.github"
      value: true
  platform: ["darwin", "linux"] # Activate only on macOS/Linux
---

# Skill body (markdown instructions)

When this skill is active, behave as follows:

## When to use this skill
- When the user requests ~

## Step-by-step procedure
1. First check X
2. Then use tool Y
3. Return the result in format Z

agents/skills/workspace.ts
  → Scan skills/ directory (54 bundled)
  → Scan ~/.openclaw/skills/ (workspace/managed)
  → Scan plugin skills
  → Parse front matter of each SKILL.md
  → Check gating conditions (bins/env/config/platform)
  → Filter to skills that pass

pi-embedded-runner/run/attempt.ts
  → Call assembleContext()
  → Inject active skill contents into system prompt
  → Pass to LLM API call

workspace > managed > plugin > bundled

Phase 1: Understand the issue
  → Read the issue body with gh issue view <number>
  → Explore related code files (grep, find)
  → Determine reproduction conditions

Phase 2: Validate the environment
  → Create branch: git checkout -b fix/issue-<number>
  → Install dependencies, verify build works

Phase 3: Root cause analysis
  → Run related tests → confirm failures
  → Analyze stack traces
  → Trace the cause using the 5 Whys methodology

Phase 4: Implement the fix
  → Minimal-scope changes (no unrelated refactoring)
  → Re-run tests after fixing → confirm they pass

Phase 5: Submit PR
  → Write commit message (Conventional Commit format)
  → Create PR with gh pr create
  → Auto-link issue number

Phase 6: Validation
  → Confirm CI passes
  → Assign reviewer (refer to CODEOWNERS)

User: "Fix GitHub issue #1234"

LLM follows gh-issues skill instructions:
1. exec tool → gh issue view 1234
2. read_file tool → read related files
3. exec tool → git checkout -b fix/issue-1234
4. write_file tool → apply code changes
5. exec tool → pnpm test
6. exec tool → gh pr create ...

## Coding agent delegation guidelines

For complex coding tasks (changes spanning hundreds of lines,
architecture refactoring), delegate to a specialized coding agent
rather than handling them directly.

### Delegating to Claude Code

Use the exec tool:
claude --dangerously-skip-permissions \
 -p "task instructions" \
 /path/to/project

### Pre-delegation checklist

- [ ] Verify current git state (no uncommitted changes)
- [ ] Clearly specify the target directory
- [ ] Document success criteria (tests pass, build passes, etc.)

### Post-delegation verification

- Check the list of changed files
- Confirm test execution results
- Review git diff for unintended changes

Step 1: Check running processes
  exec → ps aux | grep openclaw
  → Detect unexpected processes

Step 2: Network connection status
  exec → ss -ltnp | grep 18789
  → Confirm gateway port binding (loopback only?)

Step 3: Config file permissions
  exec → ls -la ~/.openclaw/config.yml
  → Should be 0600 (owner read/write only)

Step 4: Credential file inspection
  exec → ls -la ~/.openclaw/credentials/
  → Verify each file is 0600

Step 5: exec-approval policy review
  read_file → ~/.openclaw/config.yml
  → Verify execApproval.mode is "always"

Step 6: Plugin integrity
  → Check list of installed plugins
  → Warn for plugins from unknown sources

Step 7: Session file size warning
  → Detect abnormally large session files (sign of token spike)

Step 8: Generate security report
  write_file → ~/.openclaw/health-report.md
  → Document findings and recommended actions

User: "Run a security check"

LLM reads healthcheck skill instructions
→ Executes the 8 steps in order using exec tool
→ Analyzes each step's result
→ Saves final report to file

- pomodoro-timer: Pomodoro timer + task log
- stock-monitor: Stock price monitoring + alerts
- recipe-assistant: Recipe recommendations from fridge contents
- meeting-notes: Auto-summarize meetings + save to Notion
- github-reviewer: Automated PR code review comments

User message: "Fix GitHub issue #1234"
         │
         ▼
┌─────────────────────────────────────────────┐
│              LLM (Claude)                   │
│                                             │
│  Injected into system prompt:               │
│  ┌─────────────────────────────────────┐    │
│  │ [gh-issues SKILL.md contents]        │   │
│  │ Phase 1: Read with gh issue view     │   │
│  │ Phase 2: Create branch               │   │
│  │ Phase 3: Root cause analysis         │   │
│  │ Phase 4: Apply code changes          │   │
│  │ Phase 5: Submit PR                   │   │
│  │ Phase 6: Validation                  │   │
│  └─────────────────────────────────────┘   │
│                                             │
│  LLM reads skill instructions and decides:  │
│  → "I should run gh issue view 1234 via exec tool"   │
│  → "I should read related files via read_file tool"  │
│  → "I should run git checkout -b via exec tool"      │
└─────────────────────────────────────────────┘
         │
         ▼ tool_use request
┌─────────────────────────────────────────────┐
│              Tool execution layer            │
│  exec → actually run gh/git commands         │
│  read_file → actually read files             │
│  write_file → actually write files           │
│  browser → actually open web pages           │
└─────────────────────────────────────────────┘
         │
         ▼ tool_result returned
  LLM receives result and continues to next step...