- Multi-account auth profile rotation with failover

- Provider-agnostic model switching

## Package Dependencies

## Package dependencies

```json

{

| `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/

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

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:

}

```

### Tool Split Strategy

### Tool split strategy

`splitSdkTools()` passes all tools via `customTools`:

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:

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:

trackSessionManagerAccess(params.sessionFile);

```

### History Limiting

### History limiting

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

## Authentication & Model Resolution

### Auth Profiles

### Auth profiles

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

const rotated = await advanceAuthProfile();

```

### Model Resolution

### Model resolution

```typescript

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

}

```

## 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:

}

```

### Context Pruning

### Context pruning

`src/agents/pi-hooks/context-pruning.ts` implements cache-TTL based context pruning:

## Streaming & Block Replies

### Block Chunking

### Block chunking

`EmbeddedBlockChunker` manages streaming text into discrete reply blocks:

};

```

### Reply Directives

### Reply directives

Reply directives like `[[media:url]]`, `[[voice]]`, `[[reply:id]]` are parsed and extracted:

```typescript

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:

classifyFailoverReason(errorText) // "auth" | "rate_limit" | "quota" | "timeout" | ...

```

### Thinking Level Fallback

### Thinking level fallback

If a thinking level is unsupported, it falls back:

}

```

## Sandbox Integration

## Sandbox integration

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

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 |

| --------------- | ----------------------- | ---------------------------------------------------------------------------------------------- |

| Extensions | Loaded from disk | Programmatic + disk paths |

| Event handling | TUI rendering | Callback-based (onBlockReply, etc.) |

## Future Considerations

## Future considerations

Areas for potential rework: