Pi integration architecture

OpenClaw integrates with pi-coding-agent and its sibling packages (

, , ) to power its AI agent capabilities.

Overview

OpenClaw uses the pi SDK to embed an AI coding agent into its messaging gateway architecture. Instead of spawning pi as a subprocess or using RPC mode, OpenClaw directly imports and instantiates pi's

via . This embedded approach provides:

• Full control over session lifecycle and event handling
• Custom tool injection (messaging, sandbox, channel-specific actions)
• System prompt customization per channel/context
• Session persistence with branching/compaction support
• Multi-account auth profile rotation with failover
• Provider-agnostic model switching

Package dependencies

json
Copy
{
  "@mariozechner/pi-agent-core": "0.70.2",
  "@mariozechner/pi-ai": "0.70.2",
  "@mariozechner/pi-coding-agent": "0.70.2",
  "@mariozechner/pi-tui": "0.70.2"
}

File structure

text
Copy
src/agents/
├── pi-embedded-runner.ts          # Re-exports from pi-embedded-runner/
├── pi-embedded-runner/
│   ├── run.ts                     # Main entry: runEmbeddedPiAgent()
│   ├── run/
│   │   ├── attempt.ts             # Single attempt logic with session setup
│   │   ├── params.ts              # RunEmbeddedPiAgentParams type
│   │   ├── payloads.ts            # Build response payloads from run results
│   │   ├── images.ts              # Vision model image injection
│   │   └── types.ts               # EmbeddedRunAttemptResult
│   ├── abort.ts                   # Abort error detection
│   ├── cache-ttl.ts               # Cache TTL tracking for context pruning
│   ├── compact.ts                 # Manual/auto compaction logic
│   ├── extensions.ts              # Load pi extensions for embedded runs
│   ├── extra-params.ts            # Provider-specific stream params
│   ├── google.ts                  # Google/Gemini turn ordering fixes
│   ├── history.ts                 # History limiting (DM vs group)
│   ├── lanes.ts                   # Session/global command lanes
│   ├── logger.ts                  # Subsystem logger
│   ├── model.ts                   # Model resolution via ModelRegistry
│   ├── runs.ts                    # Active run tracking, abort, queue
│   ├── sandbox-info.ts            # Sandbox info for system prompt
│   ├── session-manager-cache.ts   # SessionManager instance caching
│   ├── session-manager-init.ts    # Session file initialization
│   ├── system-prompt.ts           # System prompt builder
│   ├── tool-split.ts              # Split tools into builtIn vs custom
│   ├── types.ts                   # EmbeddedPiAgentMeta, EmbeddedPiRunResult
│   └── utils.ts                   # ThinkLevel mapping, error description
├── pi-embedded-subscribe.ts       # Session event subscription/dispatch
├── pi-embedded-subscribe.types.ts # SubscribeEmbeddedPiSessionParams
├── pi-embedded-subscribe.handlers.ts # Event handler factory
├── pi-embedded-subscribe.handlers.lifecycle.ts
├── pi-embedded-subscribe.handlers.types.ts
├── pi-embedded-block-chunker.ts   # Streaming block reply chunking
├── pi-embedded-messaging.ts       # Messaging tool sent tracking
├── pi-embedded-helpers.ts         # Error classification, turn validation
├── pi-embedded-helpers/           # Helper modules
├── pi-embedded-utils.ts           # Formatting utilities
├── pi-tools.ts                    # createOpenClawCodingTools()
├── pi-tools.abort.ts              # AbortSignal wrapping for tools
├── pi-tools.policy.ts             # Tool allowlist/denylist policy
├── pi-tools.read.ts               # Read tool customizations
├── pi-tools.schema.ts             # Tool schema normalization
├── pi-tools.types.ts              # AnyAgentTool type alias
├── pi-tool-definition-adapter.ts  # AgentTool -> ToolDefinition adapter
├── pi-settings.ts                 # Settings overrides
├── pi-hooks/                      # Custom pi hooks
│   ├── compaction-safeguard.ts    # Safeguard extension
│   ├── compaction-safeguard-runtime.ts
│   ├── context-pruning.ts         # Cache-TTL context pruning extension
│   └── context-pruning/
├── model-auth.ts                  # Auth profile resolution
├── auth-profiles.ts               # Profile store, cooldown, failover
├── model-selection.ts             # Default model resolution
├── models-config.ts               # models.json generation
├── model-catalog.ts               # Model catalog cache
├── context-window-guard.ts        # Context window validation
├── failover-error.ts              # FailoverError class
├── defaults.ts                    # DEFAULT_PROVIDER, DEFAULT_MODEL
├── system-prompt.ts               # buildAgentSystemPrompt()
├── system-prompt-params.ts        # System prompt parameter resolution
├── system-prompt-report.ts        # Debug report generation
├── tool-summaries.ts              # Tool description summaries
├── tool-policy.ts                 # Tool policy resolution
├── transcript-policy.ts           # Transcript validation policy
├── skills.ts                      # Skill snapshot/prompt building
├── skills/                        # Skill subsystem
├── sandbox.ts                     # Sandbox context resolution
├── sandbox/                       # Sandbox subsystem
├── channel-tools.ts               # Channel-specific tool injection
├── openclaw-tools.ts              # OpenClaw-specific tools
├── bash-tools.ts                  # exec/process tools
├── apply-patch.ts                 # apply_patch tool (OpenAI)
├── tools/                         # Individual tool implementations
│   ├── browser-tool.ts
│   ├── canvas-tool.ts
│   ├── cron-tool.ts
│   ├── gateway-tool.ts
│   ├── image-tool.ts
│   ├── message-tool.ts
│   ├── nodes-tool.ts
│   ├── session*.ts
│   ├── web-*.ts
│   └── ...
└── ...

Channel-specific message action runtimes now live in the plugin-owned extension directories instead of under

, for example:

• the Discord plugin action runtime files
• the Slack plugin action runtime file
• the Telegram plugin action runtime file
• the WhatsApp plugin action runtime file

Core integration flow

1. Running an Embedded Agent

The main entry point is

in :

typescript
Copy
import { runEmbeddedPiAgent } from "./agents/pi-embedded-runner.js";

const result = await runEmbeddedPiAgent({
  sessionId: "user-123",
  sessionKey: "main:whatsapp:+1234567890",
  sessionFile: "/path/to/session.jsonl",
  workspaceDir: "/path/to/workspace",
  config: openclawConfig,
  prompt: "Hello, how are you?",
  provider: "anthropic",
  model: "claude-sonnet-4-6",
  timeoutMs: 120_000,
  runId: "run-abc",
  onBlockReply: async (payload) => {
    await sendToChannel(payload.text, payload.mediaUrls);
  },
});

2. Session Creation

Inside

(called by ), the pi SDK is used:

typescript
Copy
import {
  createAgentSession,
  DefaultResourceLoader,
  SessionManager,
  SettingsManager,
} from "@mariozechner/pi-coding-agent";

const resourceLoader = new DefaultResourceLoader({
  cwd: resolvedWorkspace,
  agentDir,
  settingsManager,
  additionalExtensionPaths,
});
await resourceLoader.reload();

const { session } = await createAgentSession({
  cwd: resolvedWorkspace,
  agentDir,
  authStorage: params.authStorage,
  modelRegistry: params.modelRegistry,
  model: params.model,
  thinkingLevel: mapThinkingLevel(params.thinkLevel),
  tools: builtInTools,
  customTools: allCustomTools,
  sessionManager,
  settingsManager,
  resourceLoader,
});

applySystemPromptOverrideToSession(session, systemPromptOverride);

3. Event Subscription

subscribes to pi's events:

typescript
Copy
const subscription = subscribeEmbeddedPiSession({
  session: activeSession,
  runId: params.runId,
  verboseLevel: params.verboseLevel,
  reasoningMode: params.reasoningLevel,
  toolResultFormat: params.toolResultFormat,
  onToolResult: params.onToolResult,
  onReasoningStream: params.onReasoningStream,
  onBlockReply: params.onBlockReply,
  onPartialReply: params.onPartialReply,
  onAgentEvent: params.onAgentEvent,
});

Events handled include:

• text

  Copy

  message_start
  /
  text

  Copy

  message_end
  /
  text

  Copy

  message_update
  (streaming text/thinking)
• text

  Copy

  tool_execution_start
  /
  text

  Copy

  tool_execution_update
  /
  text

  Copy

  tool_execution_end
• text

  Copy

  turn_start
  /
  text

  Copy

  turn_end
• text

  Copy

  agent_start
  /
  text

  Copy

  agent_end
• text

  Copy

  compaction_start
  /
  text

  Copy

  compaction_end

4. Prompting

After setup, the session is prompted:

typescript
Copy
await session.prompt(effectivePrompt, { images: imageResult.images });

The SDK handles the full agent loop: sending to LLM, executing tool calls, streaming responses.

Image injection is prompt-local: OpenClaw loads image refs from the current prompt and passes them via

for that turn only. It does not re-scan older history turns to re-inject image payloads.

Tool architecture

Tool pipeline

1. Base Tools: pi's
   text

   Copy

   codingTools
   (read, bash, edit, write)
2. Custom Replacements: OpenClaw replaces bash with
   text

   Copy

   exec
   /
   text

   Copy

   process
   , customizes read/edit/write for sandbox
3. OpenClaw Tools: messaging, browser, canvas, sessions, cron, gateway, etc.
4. Channel Tools: Discord/Telegram/Slack/WhatsApp-specific action tools
5. Policy Filtering: Tools filtered by profile, provider, agent, group, sandbox policies
6. Schema Normalization: Schemas cleaned for Gemini/OpenAI quirks
7. AbortSignal Wrapping: Tools wrapped to respect abort signals

Tool definition adapter

pi-agent-core's

has a different signature than pi-coding-agent's . The adapter in bridges this:

typescript
Copy
export function toToolDefinitions(tools: AnyAgentTool[]): ToolDefinition[] {
  return tools.map((tool) => ({
    name: tool.name,
    label: tool.label ?? name,
    description: tool.description ?? "",
    parameters: tool.parameters,
    execute: async (toolCallId, params, onUpdate, _ctx, signal) => {
      // pi-coding-agent signature differs from pi-agent-core
      return await tool.execute(toolCallId, params, signal, onUpdate);
    },
  }));
}

Tool split strategy

passes all tools via :

typescript
Copy
export function splitSdkTools(options: { tools: AnyAgentTool[]; sandboxEnabled: boolean }) {
  return {
    builtInTools: [], // Empty. We override everything
    customTools: toToolDefinitions(options.tools),
  };
}

This ensures OpenClaw's policy filtering, sandbox integration, and extended toolset remain consistent across providers.

System prompt construction

The system prompt is built in

(). It assembles a full prompt with sections including Tooling, Tool Call Style, Safety guardrails, OpenClaw CLI reference, Skills, Docs, Workspace, Sandbox, Messaging, Reply Tags, Voice, Silent Replies, Heartbeats, Runtime metadata, plus Memory and Reactions when enabled, and optional context files and extra system prompt content. Sections are trimmed for minimal prompt mode used by subagents.

The prompt is applied after session creation via

:

typescript
Copy
const systemPromptOverride = createSystemPromptOverride(appendPrompt);
applySystemPromptOverrideToSession(session, systemPromptOverride);

Session management

Session files

Sessions are JSONL files with tree structure (id/parentId linking). Pi's

handles persistence:

typescript
Copy
const sessionManager = SessionManager.open(params.sessionFile);

OpenClaw wraps this with

for tool result safety.

Session caching

caches SessionManager instances to avoid repeated file parsing:

typescript
Copy
await prewarmSessionFile(params.sessionFile);
sessionManager = SessionManager.open(params.sessionFile);
trackSessionManagerAccess(params.sessionFile);

History limiting

trims conversation history based on channel type (DM vs group).

Compaction

Auto-compaction triggers on context overflow. Common overflow signatures include

, , , , , and . handles manual compaction:

typescript
Copy
const compactResult = await compactEmbeddedPiSessionDirect({
  sessionId, sessionFile, provider, model, ...
});

Authentication & Model Resolution

Auth profiles

OpenClaw maintains an auth profile store with multiple API keys per provider:

typescript
Copy
const authStore = ensureAuthProfileStore(agentDir, { allowKeychainPrompt: false });
const profileOrder = resolveAuthProfileOrder({ cfg, store: authStore, provider, preferredProfile });

Profiles rotate on failures with cooldown tracking:

typescript
Copy
await markAuthProfileFailure({ store, profileId, reason, cfg, agentDir });
const rotated = await advanceAuthProfile();

Model resolution

typescript
Copy
import { resolveModel } from "./pi-embedded-runner/model.js";

const { model, error, authStorage, modelRegistry } = resolveModel(
  provider,
  modelId,
  agentDir,
  config,
);

// Uses pi's ModelRegistry and AuthStorage
authStorage.setRuntimeApiKey(model.provider, apiKeyInfo.apiKey);

Failover

triggers model fallback when configured:

typescript
Copy
if (fallbackConfigured && isFailoverErrorMessage(errorText)) {
  throw new FailoverError(errorText, {
    reason: promptFailoverReason ?? "unknown",
    provider,
    model: modelId,
    profileId,
    status: resolveFailoverStatus(promptFailoverReason),
  });
}

Pi extensions

OpenClaw loads custom pi extensions for specialized behavior:

Compaction safeguard

adds guardrails to compaction, including adaptive token budgeting plus tool failure and file operation summaries:

typescript
Copy
if (resolveCompactionMode(params.cfg) === "safeguard") {
  setCompactionSafeguardRuntime(params.sessionManager, { maxHistoryShare });
  paths.push(resolvePiExtensionPath("compaction-safeguard"));
}

Context pruning

implements cache-TTL based context pruning:

typescript
Copy
if (cfg?.agents?.defaults?.contextPruning?.mode === "cache-ttl") {
  setContextPruningRuntime(params.sessionManager, {
    settings,
    contextWindowTokens,
    isToolPrunable,
    lastCacheTouchAt,
  });
  paths.push(resolvePiExtensionPath("context-pruning"));
}

Streaming & Block Replies

Block chunking

manages streaming text into discrete reply blocks:

typescript
Copy
const blockChunker = blockChunking ? new EmbeddedBlockChunker(blockChunking) : null;

Thinking/Final Tag Stripping

Streaming output is processed to strip

/ blocks and extract content:

typescript
Copy
const stripBlockTags = (text: string, state: { thinking: boolean; final: boolean }) => {
  // Strip <think>...</think> content
  // If enforceFinalTag, only return <final>...</final> content
};

Reply directives

Reply directives like

, , are parsed and extracted:

typescript
Copy
const { text: cleanedText, mediaUrls, audioAsVoice, replyToId } = consumeReplyDirectives(chunk);

Error handling

Error classification

classifies errors for appropriate handling:

typescript
Copy
isContextOverflowError(errorText)     // Context too large
isCompactionFailureError(errorText)   // Compaction failed
isAuthAssistantError(lastAssistant)   // Auth failure
isRateLimitAssistantError(...)        // Rate limited
isFailoverAssistantError(...)         // Should failover
classifyFailoverReason(errorText)     // "auth" | "rate_limit" | "quota" | "timeout" | ...

Thinking level fallback

If a thinking level is unsupported, it falls back:

typescript
Copy
const fallbackThinking = pickFallbackThinkingLevel({
  message: errorText,
  attempted: attemptedThinking,
});
if (fallbackThinking) {
  thinkLevel = fallbackThinking;
  continue;
}

Sandbox integration

When sandbox mode is enabled, tools and paths are constrained:

typescript
Copy
const sandbox = await resolveSandboxContext({
  config: params.config,
  sessionKey: sandboxSessionKey,
  workspaceDir: resolvedWorkspace,
});

if (sandboxRoot) {
  // Use sandboxed read/edit/write tools
  // Exec runs in container
  // Browser uses bridge URL
}

Provider-Specific Handling

Anthropic

• Refusal magic string scrubbing
• Turn validation for consecutive roles
• Strict upstream Pi tool parameter validation

Google/Gemini

• Plugin-owned tool schema sanitization

OpenAI

• text

  Copy

  apply_patch
  tool for Codex models
• Thinking level downgrade handling

TUI Integration

OpenClaw also has a local TUI mode that uses pi-tui components directly:

typescript
Copy
// src/tui/tui.ts
import { ... } from "@mariozechner/pi-tui";

This provides the interactive terminal experience similar to pi's native mode.

Key differences from Pi CLI

Future considerations

Areas for potential rework:

1. Tool signature alignment: Currently adapting between pi-agent-core and pi-coding-agent signatures
2. Session manager wrapping:
   text

   Copy

   guardSessionManager
   adds safety but increases complexity
3. Extension loading: Could use pi's
   text

   Copy

   ResourceLoader
   more directly
4. Streaming handler complexity:
   text

   Copy

   subscribeEmbeddedPiSession
   has grown large
5. Provider quirks: Many provider-specific codepaths that pi could potentially handle

Tests

Pi integration coverage spans these suites:

• text

  Copy

  src/agents/pi-*.test.ts
• text

  Copy

  src/agents/pi-auth-json.test.ts
• text

  Copy

  src/agents/pi-embedded-*.test.ts
• text

  Copy

  src/agents/pi-embedded-helpers*.test.ts
• text

  Copy

  src/agents/pi-embedded-runner*.test.ts
• text

  Copy

  src/agents/pi-embedded-runner/**/*.test.ts
• text

  Copy

  src/agents/pi-embedded-subscribe*.test.ts
• text

  Copy

  src/agents/pi-tools*.test.ts
• text

  Copy

  src/agents/pi-tool-definition-adapter*.test.ts
• text

  Copy

  src/agents/pi-settings.test.ts
• text

  Copy

  src/agents/pi-hooks/**/*.test.ts

Live/opt-in:

• text

  Copy

  src/agents/pi-embedded-runner-extraparams.live.test.ts
  (enable
  text

  Copy

  OPENCLAW_LIVE_TEST=1
  )

For current run commands, see Pi Development Workflow.

Related

• Pi development workflow
• Install overview