JohnRiceMLandClaude Opus 4.6
ecb4dbe62d
The wizard checked localStorage before verifying the server-side onboarded flag, so users who moved their workspace (or upgraded OpenClaw) were stuck with no wizard and had to use incognito to re-configure. Now the wizard always validates with the server and clears the stale localStorage flag when the workspace has changed. Also adds GitHub PR/issue templates, English-first and scope boundary policies in CONTRIBUTING.md, OpenClaw integration docs, and updates test counts across all docs. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
5.6 KiB
OpenClaw Integration Reference
This document covers how ClawPort integrates with OpenClaw -- the AI agent runtime that powers everything behind the dashboard.
Overview
OpenClaw is the runtime layer. ClawPort is the UI layer. The separation is deliberate:
| Layer | Responsibility | Repository |
|---|---|---|
| OpenClaw | Agent execution, gateway API, cron scheduling, memory management, CLI | openclaw.ai |
| ClawPort | Dashboard UI, visualization, chat interface, settings, theming | clawport-ui |
ClawPort never executes agents directly. It reads workspace data, calls gateway endpoints, and invokes CLI commands to present information and relay user actions.
How ClawPort Reads Workspace Data
ClawPort uses $WORKSPACE_PATH to read agent and operational data from the OpenClaw workspace on disk:
| Data | Source | ClawPort usage |
|---|---|---|
| Agents | $WORKSPACE_PATH/agents/*/SOUL.md |
Agent discovery, org map, profiles |
| Root agent | $WORKSPACE_PATH/SOUL.md, IDENTITY.md |
Root orchestrator node |
| Memory | $WORKSPACE_PATH/memory/ |
Memory browser |
| Cron runs | $WORKSPACE_PATH/cron-runs/ |
Cost dashboard, activity logs |
| Agent registry override | $WORKSPACE_PATH/clawport/agents.json |
Custom agent names, colors, hierarchy |
| Pipeline config | $WORKSPACE_PATH/clawport/pipelines.json |
Cron pipeline DAG |
| OpenClaw config | $WORKSPACE_PATH/../openclaw.json |
Memory status, gateway settings |
Gateway HTTP Endpoints
ClawPort routes all AI calls through the OpenClaw gateway (default localhost:18789):
| Endpoint | Method | Purpose | ClawPort usage |
|---|---|---|---|
/v1/chat/completions |
POST | Text chat (streaming SSE) | Agent chat, health check, cost analysis, pipeline wizard |
/v1/audio/transcriptions |
POST | Whisper transcription | Voice message transcription |
The gateway proxies requests to Claude using the workspace's configured API key. ClawPort authenticates with OPENCLAW_GATEWAY_TOKEN.
CLI Commands
For operations that require device keypair signing or aren't exposed via HTTP, ClawPort shells out to the openclaw CLI:
| Command | Purpose | ClawPort usage |
|---|---|---|
openclaw cron list --json |
List all cron jobs | Cron monitor, pipeline graph |
openclaw logs --follow --json |
Stream live logs | Live stream widget |
openclaw gateway call chat.send |
Send message with attachments | Vision pipeline (image chat) |
openclaw gateway call chat.history |
Get conversation history | Vision pipeline (poll for response) |
openclaw gateway call health |
Check gateway health | Status check, debugging |
Why CLI for vision? The gateway's HTTP endpoint strips image_url content from messages. The CLI has device keys for operator.write scope, which chat.send requires. ClawPort sends the image via CLI, then polls chat.history for the response.
Agent Client Protocol (ACP)
ACP is OpenClaw's protocol for external tools to interact with running agent sessions. Key concepts:
- Sessions -- identified by a
sessionKey(e.g.,agent:main:clawport), sessions scope conversations between a client and an agent - Device keys -- keypair-based authentication for write operations; the CLI manages these automatically
- Scopes --
operator.read(via HTTP) andoperator.write(via CLI with device keys)
ClawPort uses ACP implicitly through the gateway endpoints and CLI commands listed above. The vision pipeline is the primary ACP consumer, using chat.send and chat.history methods.
Recent OpenClaw Features
Features shipped in recent OpenClaw versions that are relevant to ClawPort:
v2026.3.7 -- Context Engine Plugins
- Pluggable context engine that agents can extend with custom providers
- Agents can register context plugins in their SOUL.md configuration
- ClawPort surfaces this via the agent detail view (tools and capabilities)
v2026.3.8 -- Backup & Provenance
openclaw backup create/openclaw backup restore-- workspace backup commands- Provenance tracking for agent outputs (which agent produced what, when)
- ClawPort's activity console can display provenance metadata in log entries
ACP Sessions
- Persistent conversation sessions between clients and agents
- Session history survives gateway restarts
- ClawPort's chat persistence (localStorage) complements server-side ACP session history
TUI Workspace Inference
- OpenClaw TUI auto-infers the active workspace from the current directory
clawport setupleverages the same detection logic forWORKSPACE_PATH
Scope Boundaries for Contributors
Understanding what belongs where prevents misrouted contributions:
Belongs in ClawPort (this repo)
- Dashboard UI components and pages
- Data visualization (charts, graphs, org map)
- Chat interface and message rendering
- Theme system and settings
- Client-side slash commands
- Reading and displaying workspace data
Belongs in OpenClaw (upstream)
- Agent execution and orchestration
- Gateway protocol and endpoints
- Cron scheduling and execution
- Memory management and storage
- CLI commands and flags
- ACP protocol changes
- New agent capabilities or tools
Grey area (discuss first)
- New API routes that invoke CLI commands not currently used
- Features that require new OpenClaw CLI flags or gateway endpoints
- Changes to how workspace data is structured or discovered
When in doubt, open an issue describing what you want to build and we'll help determine the right place for it.