// LLM knowledge base for Organized-AI/ClawBox — Tauri v2 desktop client for the OpenClaw Gateway
#id, a type badge, a one-paragraph description, and chips linking to what it depends on and what depends on it. Load this page as context when reasoning about ClawBox internals rather than scanning the repo tree. Source of truth: github.com/Organized-AI/ClawBox at v2026.3.17.
┌─────────────────────────── CLAWBOX ───────────────────────────┐ │ │ │ Tauri v2 shell (Rust) OS integration, updater │ │ │ │ │ ▼ │ │ React 18 SPA ──── fetch http://127.0.0.1:13000 ───┐ │ │ src/ · Vite :14200 │ │ │ ▼ │ │ Bun / Hono │ │ internal/ │ │ routes + logic │ │ │ │ │ │ WS-RPC │ │ ▼ │ │ OpenClaw Gateway │ │ :18789/v1 · separate │ └───────────────────────────────────────────────────────────────┘
Tauri v2 Rust shell under src-tauri/. OS integration, window management, autoupdate. No business logic — hosts the React SPA and starts the Bun backend.
React 18 + Vite SPA under src/. Dev port 14200. Tailwind CSS. i18n across en / zh. Only talks to the local Bun backend on 127.0.0.1:13000 — never to the Gateway directly.
Bun runtime + Hono router under internal/. Listens on 127.0.0.1:13000. One route module per domain in internal/routes/. Talks to the OpenClaw Gateway over WebSocket RPC.
Separate process. Not bundled by ClawBox. URL shape http://127.0.0.1:18789/v1. Installed via portable app-managed runtime or system npm i -g openclaw. Recommended baseline >= 2026.3.12.
First frame after Tauri window mounts. Probes the OpenClaw runtime while the user sees progress text. Hands off to OnboardView when the runtime isn't ready.
Six-step setup wizard — probe → choose mode → bootstrap → start Gateway → provider config → model pick. State lives in internal/onboard/.
Primary surface. Session list + transcript + composer. Consumes chat.ts + sessions.ts. TypewriterText renders streaming assistant output. SuggestedQuestions provides prompt nudges.
Edit the agent's Soul file (persona · style · constraints). Backed by soul.ts. Subcomponents live in src/components/soul/.
Plugin / channel manager. Starts, stops, configures channels registered with the Gateway. Backed by channels.ts.
Browse + configure skills. Backed by skills.ts + logic under internal/skills/. Subcomponents in src/components/skills/.
Gateway URL · provider · default model · language · theme · telemetry. Backed by config.ts + models.ts.
Catches Gateway disconnects. Banner across the top; hint component inline. Prompts a restart without losing state.
Streaming-text renderer. Used by ChatView to render assistant responses as they arrive.
Chat-view nudges. Renders prompt suggestions fetched from titles.ts or seeded locally.
Two locales (en / zh) via src/locales/; light / dark theme via Tailwind. Kept in sync with i18n.ts.
Agent roster + agent detail. Exposes the Gateway's agent list to the frontend.
Channel lifecycle — start / stop / list / status. Channel logic lives in internal/channels/.
Chat send + history. Depends on the Gateway's chat.send + chat.history RPCs. Uses the optional tool-events capability.
Gateway + app config. config.get / config.patch. Consumed by SettingsView.
List / refresh provider models. Provider implementations live in internal/providers/.
Wizard state + runtime probes + bootstrap actions. Logic in internal/onboard/.
Session list / preview / patch / reset / delete. Thin wrapper over the Gateway's session RPCs.
Auto-titles for new sessions. Also seeds prompt suggestions for SuggestedQuestions.
Tool manifest + tool-call summaries. internal/tool-call-summaries/ holds formatters that turn raw tool events into chat-view blocks.
Gateway returns the model catalog for the configured provider. Minimum RPC — present on the mock gateway for smoke tests.
Gateway config CRUD. config.get returns the current state; config.patch accepts partial updates.
Full session CRUD over WebSocket. Same set the mock gateway implements — so any ClawBox feature that only touches these RPCs is safe to smoke-test against the mock.
Submit a user message. Streams assistant output back; ChatView renders via TypewriterText. Optional capability tool-events layers on tool-call streaming.
Optional Gateway capability currently used by ClawBox chat. Drives the tool-call stream that internal/tool-call-summaries/ formats into chat-view blocks.
Connect flow: challenge / response handshake with a local device identity. Runs over the WS upgraded from the configured HTTP URL.
Name clawbox · version 2026.3.17 · MIT · engines node>=20 · bun>=1.1. Scripts drive the dev + build + audit flows.
Bun/Hono backend entry. Wires every route module; starts the HTTP listener on 127.0.0.1:13000. Run directly via bun --watch internal/index.ts.
Frontend router root. Decides whether to show StartupScreen, OnboardView, or the main dashboard based on onboarding state.
ClawBox ↔ OpenClaw compatibility matrix. Consumed by the Gateway-probe logic during onboarding + GatewayRestartBanner.
User-facing strings. Must stay in sync across languages per the Development Notes in the README.
Source of truth for the supported baseline + transport expectations + minimum RPC surface. Update this when the compat matrix moves.
Release + signing playbook. Referenced from the README Installation Matrix.
Tauri v2 Rust shell. Cargo.toml verified via cargo check; bundles build through tauri build. Windows signing via auxiliary scripts; macOS publish is currently unnotarised.
Stand-in Gateway implementing the minimum RPC surface: models.list · config.{get,patch} · sessions.{list,preview,patch,reset,delete} · chat.{history,send}. Run with node scripts/mock-gateway.mjs --port 18789.
End-to-end smoke test against the mock gateway. Wired as npm run smoke:backend. Lightweight — doesn't require a live OpenClaw runtime.
Syncs version across package.json, src-tauri/Cargo.toml, and tauri.conf.json. Run before release.
Release-version helper. Wrapped by npm run release:version.
Backend build — runs at npm run build:backend. Produces the Bun bundle consumed by the Tauri package.
Windows code-signing step. Paired with sign-win-installer.mjs to sign both the compiled binary and the NSIS installer in the signed build path.
Repo-hygiene scanner. Public-mode via npm run scan:public. Pairs with license + dep audits.
App-managed Node.js + OpenClaw bundle that the wizard prepares when the user picks Portable (Built-in). The alternative is System Install, where the user manages OpenClaw themselves via npm i -g openclaw.
Upstream model provider. Either CommonStack (default project path) or a Custom Provider (OpenAI- or Anthropic-compatible endpoint). Saved via config.ts + consumed by models.ts.
ClawBox owns: desktop shell · frontend · backend bridge · onboarding UI · packaging logic. OpenClaw owns: Gateway protocol · channel runtime · daemon behavior. Report bugs where the contract broke — not where symptoms show.
ClawBox is the desktop surface of the Organized Market project. It's the machine-side client through which a user participates in the broader marketplace described by organized-market-arch.
Three standing audits: scan:repo (public-mode scan of sensitive patterns), audit:licenses, audit:deps. Run before shipping a release artefact.
concurrently runs bun --watch internal/index.ts + vite --port 14200. Named prefixes backend / frontend.
Run the full desktop app under Tauri. Hosts the frontend and starts the backend in-process.
Wraps node scripts/mock-gateway.mjs. Run before smoke:backend (or the smoke script will start one if not already).
Lightweight backend smoke. Doesn't require a live OpenClaw. CI uses this.
macOS .dmg build. Runs the tauri:clean-dmg preflight first to detach any still-mounted DMG from a prior run.
Four-step signed Windows build: compile (no-bundle) → sign exe → bundle NSIS → sign installer.
Standing audits wrapped around scripts/scan-repo-hygiene.mjs and the platform dep/license tooling.
Starts an OpenClaw Gateway for local development. Loopback-bound; auth disabled. Not for production.
macOS workaround for the unnotarised release. Only apply to builds downloaded from the official Releases page.
Human-readable operator guide. 10 tabs — Overview · Install · Architecture · App Views · Backend Routes · Onboarding · Dev · Build & Release · OpenClaw Compat · Market Context.
OpenClaw Gateway architecture reference. ClawBox is a client of this Gateway — any protocol question routes here.
Architecture of the surrounding marketplace + orchestration. ClawBox is one component inside this broader project.
Cloudflare-edge session orchestrator. ClawBox's web/edge counterpart — same "personal AI control plane" pattern, different runtime.