笔引子系统

PasClaw

PasClaw is an ultra-lightweight personal AI agent written in Delphi Object Pascal. It is a Delphi/FPC port inspired by picoclaw, with a command-line assistant, tool calling, MCP integration, an HTTP gateway, an OpenAI-compatible API surface, a small embedded web UI, scheduled tasks, skills, and channel integrations.

The main program lives at src/pasclaw/PasClaw.dpr. It initializes terminal color handling, prints the banner, applies timezone configuration, and dispatches into the command tree implemented under src/cmd/.

Features

LLM providers — 19-entry catalog covering Anthropic Messages, OpenAI Chat Completions, Google Gemini generateContent, plus OpenAI-protocol-compatible providers (Groq, DeepSeek, Mistral, Cerebras, OpenRouter, Zhipu, Qwen, Moonshot, MiniMax, NVIDIA NIM, Novita, MiMo, VolcEngine, Ollama, vLLM, LiteLLM). The full list lives in src/pkg/providers/PasClaw.Providers.Catalog.pas; adding a provider is a one-record append. Streaming SSE on all three protocol families; native search grounding on Gemini; citation collation on Perplexity. Fallback chain — Cfg.Fallbacks = ["openai", "gemini"] walks the list when the primary returns 429 / 5xx / network error. Code-driven SetProvider('anthropic', $ANTHROPIC_API_KEY) for embedders so no ~/.pasclaw/config.json is required.

Built-in tools — exposed to the model on every turn:

Parallel dispatch — when the model returns multiple tool_use blocks in one turn, read-only tools (web_search, web_fetch, fs_read/grep/list, memory_search) fan out on worker threads; mutating tools (fs_write, fs_edit_hashline, shell_exec) stay serial. ~50% wall-clock win on multi-network-tool turns.

MCP — both transports. Stdio MCP via spawned subprocess + JSON-RPC over pipes, and Streamable HTTP MCP (handles SSE-framed responses, Bearer-token auth). Catalog of public servers — pasclaw mcp install replicate / digitalocean-apps / digitalocean-databases / runpod-docs / huggingface — reads the right env var, writes the right Authorization header, never preloaded.

Skills — markdown manifests under $PASCLAW_HOME/workspace/skills/ advertised in the system prompt; the model loads the body via fs_read on demand. Install from GitHub (pasclaw skills install owner/repo[/path][@ref] — codeload zip, FPC's Zipper.TUnZipper or Delphi's System.Zip.TZipFile) or from ClawHub (pasclaw skills install clawhub:<slug>[@<version>]). Malware-flagged skills refused; suspicious-flagged install with a warning.

HTTP gateway — pasclaw gateway and pasclaw serve. OpenAI-compatible /v1/chat/completions (streaming + non-streaming) and /v1/responses (tool-passthrough so Codex CLI can drive its own tools). Embedded web UI (vanilla ES2020, single HTML file, no JS toolchain) with 8 tabs: Chat (SSE-streamed, tool activity surfaced inline), Memory, Files, MCP, Cron, Skills, Logs (live tail via SSE from the in-process ring buffer), Settings. Read-only inspection endpoints (/v1/mcp, /v1/cron, /v1/skills, /v1/memory, /v1/fs, /v1/config, /v1/logs) backed by the gateway's sandbox + secret-masking.

Chat channels — bidirectional (inbound message → agent loop → outbound reply): Telegram (long-poll bot), Discord (bot polling), LINE (webhook), WhatsApp (Cloud API webhook), Slack (Events API webhook + Incoming Webhook reply), Matrix (REST /sync long-poll, federated, self-hostable), IRC (TIdIRC), Email (SMTP send + IMAP poll, --email flag, env-var configured). Outbound-only: Microsoft Teams (Incoming Webhook), generic Webhook sink.

Cron — pasclaw cron add daily-summary "0 9 * * *" summarize "workspace/memory". Last-fired timestamp persisted to workspace/cron/state.json so a missed slot (gateway down, laptop closed) catches up on the next tick instead of being silently skipped. At-least-once delivery — the state file is written after the skill runs, so a crash in the window between the skill's side effects and the timestamp persist will replay the job on restart; idempotent skills are safe, side-effecting skills should self-deduplicate. Per-entry channel sink (--channel <kind>:<target>) posts skill output; output also appended to workspace/memory/<today>.md for the model to recall later.

Memory — SQLite FTS5 BM25 index over workspace/memory/*.md and MEMORY.md. pasclaw migrate (re-)indexes; pasclaw membench --records N benchmarks. Conversation history compaction (pasclaw compaction.threshold_tokens) kicks in mid-loop, summarises the older portion via the same provider, folds the summary into the system prompt, falls back to verbatim on summariser failure (no silent context loss).

Sandbox + safety — read/write path allowlists, shell-command denylist (separate restrict_to_workspace denylist + shell_deny_enabled global), SSRF guard on web_fetch (IPv4 blocklist incl. 169.254.169.254, redirect re-check), hashline patches require matching file-hash header (stale patches abort without writing). TLS required for HTTPS provider/MCP calls via Indy's OpenSSL IO handler.

Embedding — TPasClawAgent and TPasClawServer as TComponents in PasClaw.Agent:

uses PasClaw.Agent, PasClaw.Tools;

Agent := TPasClawAgent.Create('claude-opus-4-7');
Agent.SetProvider('anthropic', GetEnvironmentVariable('ANTHROPIC_API_KEY'));
Agent.RegisterTool(TWebSearchTool.Create);
Agent.RegisterTool(TFileSystemTool.Create);
WriteLn(Agent.Run('Summarize the latest Delphi release notes.'));
Agent.Free;

Form-designable with published properties for the VCL/FMX path; code-driven OOP API for everything else. Custom tools subclass TPasClawTool and override Name / Description / Schema / Run / Category. Single-process server: TPasClawServer.Create('0.0.0.0', 8088); Server.Run; blocks until Stop is signalled from another thread.

Interactive chat — pasclaw agent and pasclaw tui ship slash commands: /help lists them; /status shows model + provider + message count + thinking state; /new starts a fresh session (new id, history cleared); /reset clears history in the current session; /compact forces a summariser pass; /think toggles extended-thinking mode for the next turn (Anthropic Claude); /tools lists registered tools; /quit exits.

Persistent sessions — pasclaw agent serialises conversation history to $PASCLAW_HOME/workspace/sessions/<id>.json after every turn (messages + tool_calls + tool_results + model + provider + compaction summary). Persistence is on by default — every interactive pasclaw agent run auto-allocates a fresh id and the conversation survives Ctrl-C / crash without any flag. Resume with pasclaw resume <id> or pasclaw agent --session <id>; an id that doesn't yet exist starts a fresh session at that id (handy for scripts pre-seeding e.g. daily-2026-06-01). pasclaw session list / show / delete / export manages saved sessions. Session ids are yyyymmddTHHMMSS-<8 hex> — sortable and collision-safe. Not yet wired: pasclaw tui keeps history in process memory only.

Prompt caching — on by default for Anthropic and OpenAI. The Anthropic request builder emits cache_control: { type: "ephemeral" } on the system prompt and the trailing tools-array entry (uses 2 of the 4-breakpoint budget; caches the largest stable prefix on every turn), with optional ttl: "1h" extended-TTL hint. OpenAI gets prompt_cache_key anchored to the persistent session id so each conversation routes to its own cache bucket. Cache hit / write tokens roll up in /status (cache: on, N read / M written (X% hit on input so far)) and surface inline in the per-turn [tokens in=… out=… cache_r=… cache_w=…] summary. Disable via prompt_cache.enabled: false in config.json; extend the TTL via prompt_cache.ttl: "1h". Gemini caching not yet wired — implicit caching applies automatically on supported models.

Hooks + steering — TPasClawHook (in PasClaw.Agent.Hooks) is the typed callback surface for embedders to observe, transform, or veto agent events. Four virtuals: BeforeTurn(var ContinueTurn, var Messages) — set ContinueTurn := False to abort cleanly; BeforeToolCall(call, var Cancel, var SyntheticResult) — Cancel := True bypasses the real tool handler and uses SyntheticResult as the tool_result (the approval-gate pattern); AfterToolResult(call, var ResultText, var ErrMsg, var SteeringMessage) — rewrite results inline AND inject a system note before the next LLM round (picoclaw's steering); OnError(Stage, Msg) — observe failures. Register via Agent.RegisterHook(THook.Create); multiple hooks form an ordered chain in registration order.

Subagents — fan-out to focused specialists via a spawn(agent, prompt) tool. Declare them in config.json's subagents: array (name + description + system prompt + tool allowlist + optional model / max-iterations override). Each spawn runs a short RunToolLoop against the parent's provider + fallback chain with a registry filtered to the named tools and a specialist system prompt; result lands back as the parent's tool_result. Implementation in src/pkg/agent/PasClaw.Agent.Subagent.pas — picoclaw's SubTurn pattern, nanobot's subagent module, openclaw's multi-agent routing, ~300 LOC.

"subagents": [
  { "name": "researcher",
    "description": "Web search + summary specialist",
    "system_prompt": "You search the web and produce a 3-bullet summary...",
    "tools": ["web_search", "web_fetch"],
    "max_iterations": 4 },
  { "name": "coder",
    "description": "Code editor",
    "system_prompt": "You edit code precisely using hashline patches...",
    "tools": ["fs_read", "fs_write", "fs_grep", "fs_edit_hashline"] }
]

Cross-platform — Linux x86_64 + aarch64 under FPC 3.2+; macOS x86_64 + arm64 under FPC (Homebrew unit paths autodetected); Windows x64 + Linux + macOS under Delphi 12 / RAD Studio. Windows-on-ARM64 builds via FPC are supported through the Makefile's CROSS_TARGET=aarch64-win64 override (pair with FPC_UNITS_DIR pointing at the cross-build's unit tree); the updater emits windows_arm64.exe as the release-asset suffix on those builds. The Delphi 13 WinArm64EC target isn't wired into PasClaw.dproj yet — add the platform via the IDE's Project Manager when you're ready to ship for it. Three sample binaries under samples/component-console/ plus matching .dproj files for RAD Studio and dcc32.cfg / dcc64.cfg for cmdline Delphi builds.