OpenClaw Integration Research
Research for Project Kaze Source: OpenClaw codebase at
/Users/eledra/Work/speedrun/openclaw
1. What OpenClaw Is
OpenClaw is a multi-channel AI gateway — not a simple chat wrapper. It's a full control plane that:
- Routes messages between 40+ communication channels (WhatsApp, Telegram, Discord, Slack, Signal, iMessage, LINE, etc.) and LLM-powered agents
- Manages agent execution (Claude CLI, Ollama, custom backends)
- Provides a mature plugin system for extending functionality
- Handles session management, message history, and conversation compaction
- Supports the Agent Client Protocol (ACP) for IDE integrations
Architecture
┌──────────────────────────────────────────────────────┐
│ Channels │
│ WhatsApp · Telegram · Discord · Slack · Signal · ... │
└──────────────────┬───────────────────────────────────┘
│ inbound messages
┌──────────────────▼───────────────────────────────────┐
│ Gateway (Control Plane) │
│ • HTTP/WebSocket server │
│ • Message routing & session management │
│ • Plugin lifecycle management │
│ • Security (allowlists, auth) │
│ • Config management (JSON5 + Zod validation) │
└──────────────────┬───────────────────────────────────┘
│ dispatch to agent
┌──────────────────▼───────────────────────────────────┐
│ Agent Execution │
│ • Spawns LLM backend as subprocess │
│ • Builds prompt (system + history + tools + message) │
│ • Streams response, parses tool calls │
│ • Continues agentic loop until completion │
└──────────────────────────────────────────────────────┘Key Technical Details
- Language: TypeScript, Node.js 22+
- Build: tsdown bundler
- Config: JSON5 + Zod validation at
~/.openclaw/config.json5 - Sessions: JSONL files on disk
- Memory: LanceDB for vector search (via plugin)
- Testing: Vitest
- Versioning: CalVer (2026.2.25)
2. Plugin System
The primary extension mechanism. OpenClaw ships with 40+ bundled plugins (all channels, memory, etc.) — the system is battle-tested.
Plugin Definition
A plugin registers capabilities via the OpenClawPluginApi:
Plugin
├── register(api) ← Entry point, called at load time
│
├── api.registerTool() ← Add capabilities agents can call
├── api.registerHook() ← Intercept agent lifecycle events
├── api.registerChannel() ← Add communication surfaces
├── api.registerService() ← Run background processes
├── api.registerGatewayMethod() ← Add HTTP endpoints
├── api.registerCommand() ← Quick commands (bypass agent)
└── api.registerProvider() ← Add auth methodsPlugin Sources
Plugins are discovered from multiple locations:
- Bundled — Built-in (
extensions/directory) - Global — User's
~/.openclaw/plugins/ - Workspace — Project-specific plugins
- Config — Declared in
config.json5
Plugin Config
Each plugin can define a Zod-validated config schema. Config lives in the main config.json5 under the plugin's key.
3. Available Hooks
Hooks let plugins intercept and modify agent behavior at every phase:
| Phase | Hooks |
|---|---|
| Agent startup | before_model_resolve, before_prompt_build, before_agent_start |
| LLM interaction | llm_input, llm_output |
| Tool execution | before_tool_call, after_tool_call, tool_result_persist |
| Messages | message_received, message_sending, message_sent, before_message_write |
| Session | session_start, session_end |
| Subagents | subagent_spawning, subagent_spawned, subagent_ended |
| Memory | before_compaction, after_compaction, before_reset |
| Gateway | gateway_start, gateway_stop |
| Agent end | agent_end |
4. How Kaze Integrates
Kaze integrates as an OpenClaw plugin — not a replacement. OpenClaw handles conversation management and channel routing. Kaze adds the knowledge layer, memory system, and vertical-specific agent capabilities on top.
Integration Architecture
┌──────────────────────────────────────────────────────┐
│ OpenClaw Gateway │
│ Channels · Routing · Sessions · Agent Execution │
│ │
│ ┌────────────────────────────────────────────────┐ │
│ │ Kaze Plugin │ │
│ │ │ │
│ │ Tools: │ │
│ │ • kaze_knowledge_query → Knowledge System │ │
│ │ • kaze_knowledge_commit → Knowledge System │ │
│ │ • kaze_dispatch_task → Agent Runtime │ │
│ │ • kaze_budget_check → LLM Gateway │ │
│ │ │ │
│ │ Hooks: │ │
│ │ • before_prompt_build → inject memories │ │
│ │ • after_tool_call → log observations │ │
│ │ • llm_output → track token usage │ │
│ │ • agent_end → persist learnings │ │
│ │ │ │
│ │ Services: │ │
│ │ • Task Scheduler → cron + events │ │
│ │ • Knowledge Consolidator → background indexing │ │
│ │ │ │
│ │ Gateway Methods: │ │
│ │ • kaze/status → health + metrics │ │
│ │ • kaze/agents → list running agents │ │
│ │ • kaze/knowledge → query knowledge API │ │
│ └────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────┘
│ │ │
┌────▼────┐ ┌──────▼──────┐ ┌─────▼─────┐
│ Postgres │ │ Mem0 │ │ Vault │
│ pgvector │ │ │ │ │
└─────────┘ └─────────────┘ └───────────┘What Kaze Registers
Tools — Agents call these during reasoning:
| Tool | Purpose |
|---|---|
kaze_knowledge_query | Search knowledge by text, memory type, domain |
kaze_knowledge_commit | Store new knowledge with provenance |
kaze_dispatch_task | Dispatch a task to another Kaze agent |
kaze_budget_check | Check remaining token budget |
Hooks — Automatic context enrichment:
| Hook | What Kaze Does |
|---|---|
before_prompt_build | Inject relevant memories into system prompt (tri-factor scored) |
after_tool_call | Log tool execution to Observation Logger |
llm_output | Track token usage against budgets |
agent_end | Persist session learnings to knowledge system |
message_received | Route to appropriate Kaze vertical agent |
Services — Background processes:
| Service | What It Does |
|---|---|
| Task Scheduler | Runs cron-triggered and event-triggered agent tasks |
| Knowledge Consolidator | Episodic → semantic distillation, contradiction detection |
Gateway Methods — HTTP API for external access:
| Endpoint | What It Does |
|---|---|
kaze/status | Platform health, agent count, budget usage |
kaze/agents | List running agents and their states |
kaze/knowledge | Direct knowledge query (for dashboards, debugging) |
5. What This Changes About Our Design
Confirmed Assumptions
- OpenClaw as conversation layer (D28) — confirmed. Plugin system is mature enough to build on.
- Multi-channel interaction — already handled by OpenClaw's 40+ channel plugins. Kaze doesn't need to build channel adapters.
- Direct calls for MVP (D29) — OpenClaw's plugin tools are direct function calls. Natural fit.
Revised Assumptions
- Layer 0.5 (Interaction Layer) in our architecture is largely OpenClaw itself. Kaze's Conversation Manager design (Q5) may not need to be a separate component — OpenClaw already manages unified conversations across channels.
- Subagent spawning — OpenClaw has built-in subagent support. Kaze's agent-to-agent delegation can use this rather than building its own.
- Session management — OpenClaw handles session state (JSONL). Kaze's episodic memory (Mem0) adds persistent cross-session knowledge on top.
New Considerations
- Single-user model — OpenClaw is personal/single-user, not multi-tenant. For the agency SaaS model, each client would need their own OpenClaw instance (aligns with cell-based deployment).
- Agent execution backend — OpenClaw spawns agents as subprocesses. Kaze's actor-based agent runtime may need to integrate as a custom backend rather than as a tool-only plugin.
- LLM routing — OpenClaw has its own model resolution. Kaze's LLM Gateway would need to either replace OpenClaw's provider system or sit behind it. Likely: Kaze registers as a provider plugin.
6. Open Questions for Integration
| # | Question | Impact |
|---|---|---|
| I1 | Should Kaze's LLM Gateway replace or wrap OpenClaw's provider system? | High — affects budget tracking and key routing |
| I2 | Does Kaze's Agent Runtime run as an OpenClaw agent backend or as a separate service called via tools? | High — affects architecture layering |
| I3 | How does multi-tenancy work with OpenClaw's single-user model? | Medium — one OpenClaw per cell, or shared gateway with tenant routing? |
| I4 | Can OpenClaw's subagent system handle Kaze's supervision ramp? | Medium — may need hook-based supervision layer |