Skip to content

Commit 4b78d6b

Browse files
author
Kevin Hopper
committed
Reframe docs to position bots as native Crow citizens via CrowClaw
Restructure integration-overview.md with Native Bots as Pattern 3, rename openclaw-bridge.md to bot-management.md, simplify platforms/openclaw.md to lead with CrowClaw install, add CrowClaw architecture doc, and update extensions, storage, platforms index, and README with bot management content.
1 parent 40823f1 commit 4b78d6b

11 files changed

Lines changed: 483 additions & 331 deletions

File tree

‎README.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ Published by [Maestro Press](https://maestro.press) | [Product Page](https://mae
2222
│ ├── crow-sharing (P2P encrypted sharing + Nostr messaging) │
2323
│ ├── crow-storage (S3-compatible file storage + quotas) │
2424
│ ├── crow-blog (publishing platform + RSS/Atom feeds) │
25+
│ ├── CrowClaw (bot management: lifecycle, BYOAI bridge, skills) │
2526
│ └── proxy → GitHub, Slack, Notion, Gmail, Trello, Discord, etc. │
2627
└──────────────────────────────┬───────────────────────────────────────┘
2728
│
@@ -62,6 +63,17 @@ Use the Crow's Nest as a chat frontend with your own AI provider — OpenAI, Ant
6263
6364
> **[Chat Architecture](https://maestro.press/software/crow/architecture/gateway#chat-api)**
6465
66+
## Bot Management (CrowClaw)
67+
68+
Manage AI bots on Discord, WhatsApp, Telegram, and other chat platforms directly from the dashboard. The CrowClaw extension handles bot lifecycle, AI provider configuration, skill deployment, and monitoring. Bots share the same database as every other connection — memories, projects, files, and messages are all accessible from any platform.
69+
70+
- **Install and go** — CrowClaw auto-configures bot AI from Crow's existing providers (BYOAI bridge)
71+
- **One inbox** — Bots appear in the Messages panel alongside peers and AI chat
72+
- **Bots control Crow apps** — A bot can publish blog posts, organize files, manage projects, and control integrations via the same MCP tools available to Claude or ChatGPT
73+
- **Message attachments** — Send images to bots with vision model analysis (when S3 storage is configured)
74+
75+
> **[Bot Management Guide](https://maestro.press/software/crow/guide/bot-management)** · **[Architecture](https://maestro.press/software/crow/architecture/crowclaw)**
76+
6577
## Works With
6678
6779
| Claude | ChatGPT | Gemini | Grok | Cursor | Windsurf | Cline | Claude Code |

‎docs/.vitepress/config.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -163,6 +163,7 @@ export default defineConfig({
163163
{ text: 'Portable Identity', link: '/architecture/portable-identity' },
164164
{ text: 'Context Management', link: '/architecture/context-management' },
165165
{ text: 'Multi-Instance Sync', link: '/architecture/instances' },
166+
{ text: 'CrowClaw', link: '/architecture/crowclaw' },
166167
{ text: 'Data Dashboard', link: '/architecture/data-dashboard' },
167168
],
168169
},
@@ -183,7 +184,7 @@ export default defineConfig({
183184
{ text: 'Relays', link: '/guide/relays' },
184185
{ text: 'Social & Messaging', link: '/guide/social' },
185186
{ text: 'Contact Discovery', link: '/guide/contact-discovery' },
186-
{ text: 'OpenClaw Bridge', link: '/guide/openclaw-bridge' },
187+
{ text: 'Bot Management', link: '/guide/bot-management' },
187188
{ text: 'Context & Performance', link: '/guide/context-performance' },
188189
{ text: 'Data Backends', link: '/guide/data-backends' },
189190
{ text: 'Deployment Tiers', link: '/guide/deployment-tiers' },

‎docs/architecture/crowclaw.md‎

Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
---
2+
title: CrowClaw Architecture
3+
---
4+
5+
# CrowClaw
6+
7+
CrowClaw is a Crow bundle (`type: "mcp-server"`) that provides bot management through 20 MCP tools and a dashboard panel. It runs as a child process of the Crow gateway, sharing the same `crow.db` database.
8+
9+
## Architecture
10+
11+
```
12+
┌──────────────────────────────────────────────────────────────────┐
13+
│ Crow's Nest Dashboard │
14+
│ └── Bots Panel (/dashboard/bots) │
15+
│ ├── Bot list (status, health, controls) │
16+
│ ├── Create / configure / deploy / delete │
17+
│ └── Messages integration (bot chat) │
18+
├──────────────────────────────────────────────────────────────────┤
19+
│ CrowClaw MCP Server (20 tools) │
20+
│ ├── Bot Lifecycle (7): create, configure, deploy, start/stop/restart, delete │
21+
│ ├── Monitoring (3): status, logs, health │
22+
│ ├── User Profiles (4): create, update, list, delete │
23+
│ └── Workspace & Skills (6): templates, workspace files, skills │
24+
├──────────────────────────────────────────────────────────────────┤
25+
│ BYOAI Bridge │
26+
│ └── Crow AI profiles → bot models.json (auto on deploy) │
27+
├──────────────────────────────────────────────────────────────────┤
28+
│ Bot Chat Routes │
29+
│ └── REST API: GET messages, POST message (polling), POST new-session │
30+
├──────────────────────────────────────────────────────────────────┤
31+
│ crow.db (SQLite, WAL mode, shared by 6+ processes) │
32+
│ └── Tables: crowclaw_bots, crowclaw_user_profiles, │
33+
│ crowclaw_workspace_files, crowclaw_deployments, │
34+
│ crowclaw_skills, crowclaw_safety_events, crowclaw_bot_messages │
35+
└──────────────────────────────────────────────────────────────────┘
36+
│ │
37+
systemctl --user OpenClaw Engine
38+
(bot services) (per-bot gateway)
39+
```
40+
41+
## Bundle Registration
42+
43+
CrowClaw must be registered in three places for Crow to discover it:
44+
45+
| File | Purpose |
46+
|------|---------|
47+
| `~/.crow/installed.json` | Bundle entry with `id: "crowclaw"` |
48+
| `~/.crow/mcp-addons.json` | MCP server config with `cwd` pointing to bundle dir |
49+
| `~/.crow/panels.json` | Panel ID `"bots"` (routes to `/dashboard/bots`) |
50+
51+
The panel ID is `"bots"` (not `"crowclaw"`). The extension proxy route is `/proxy/crowclaw/`.
52+
53+
## MCP Tools
54+
55+
### Bot Lifecycle (7)
56+
57+
| Tool | Description |
58+
|------|-------------|
59+
| `crow_create_bot` | Create a new bot with name, platform credentials, AI config |
60+
| `crow_configure_bot` | Update bot settings (model, skills, safety) |
61+
| `crow_deploy_bot` | Deploy bot config, generate models.json, start service |
62+
| `crow_start_bot` | Start the bot's systemd service |
63+
| `crow_stop_bot` | Stop the bot's systemd service |
64+
| `crow_restart_bot` | Restart the bot's systemd service |
65+
| `crow_delete_bot` | Remove bot, config files, and service (confirm gate) |
66+
67+
### Monitoring (3)
68+
69+
| Tool | Description |
70+
|------|-------------|
71+
| `crow_bot_status` | Status of all bots or a specific bot (running, stopped, errors) |
72+
| `crow_bot_logs` | Recent journal logs for a bot's systemd service |
73+
| `crow_bot_health` | Health metrics: uptime, error rate, last activity |
74+
75+
### User Profiles (4)
76+
77+
| Tool | Description |
78+
|------|-------------|
79+
| `crow_create_user_profile` | Create a user profile (name, platform IDs, permissions) |
80+
| `crow_update_user_profile` | Update profile fields |
81+
| `crow_list_user_profiles` | List all profiles |
82+
| `crow_delete_user_profile` | Remove a profile (confirm gate) |
83+
84+
### Workspace & Skills (6)
85+
86+
| Tool | Description |
87+
|------|-------------|
88+
| `crow_list_workspace_templates` | List available bot workspace templates |
89+
| `crow_update_workspace_file` | Write a file to a bot's workspace |
90+
| `crow_get_workspace_file` | Read a file from a bot's workspace |
91+
| `crow_list_bot_skills` | List skills deployed to a bot |
92+
| `crow_deploy_skill` | Push a SKILL.md file to a bot (confirm gate) |
93+
| `crow_remove_skill` | Remove a skill from a bot (confirm gate) |
94+
95+
## Confirm Gate
96+
97+
Destructive operations require a two-call confirmation pattern (`server/confirm.js`):
98+
99+
1. **First call**: Returns a confirmation token and description of what will happen
100+
2. **Second call**: Same parameters plus the confirmation token — executes the operation
101+
102+
This prevents accidental deletions from a single misrouted tool call. Protected operations: deploy, delete bot, delete profile, remove skill.
103+
104+
## Database Tables
105+
106+
All tables live in Crow's shared `crow.db` (WAL mode, `busy_timeout = 5000`).
107+
108+
| Table | Purpose |
109+
|-------|---------|
110+
| `crowclaw_bots` | Bot definitions: name, platform, AI config, status |
111+
| `crowclaw_user_profiles` | Platform user profiles and permissions |
112+
| `crowclaw_workspace_files` | Bot workspace file contents |
113+
| `crowclaw_deployments` | Deployment history and timestamps |
114+
| `crowclaw_skills` | Skills deployed to each bot |
115+
| `crowclaw_safety_events` | Content moderation and safety audit log |
116+
| `crowclaw_bot_messages` | Bot chat messages (with attachments JSON column) |
117+
118+
Schema is defined in `server/init-tables.js` and runs `CREATE TABLE IF NOT EXISTS` on every startup.
119+
120+
## BYOAI Bridge
121+
122+
`server/byoai-bridge.js` generates a bot's `models.json` from Crow's AI profiles stored in `dashboard_settings.ai_profiles`.
123+
124+
### Provider Mapping
125+
126+
The bridge maps base URLs to OpenClaw provider namespaces using `openclawProviderFromBaseUrl()`. Provider keys in `models.json` must match OpenClaw's auth profile names (`zai`, `qwen-portal`, `meta`, etc.) — not arbitrary names. Mismatches cause silent auth failures.
127+
128+
### Vision Detection
129+
130+
`isVisionModel()` is a heuristic (regex patterns for known vision model names). When a vision model is detected, the bridge outputs a provider-qualified `imageModel` (e.g., `zai/glm-4.6v`) and configures `tools.media.models` with the appropriate timeout.
131+
132+
### Path Discovery
133+
134+
Uses `openclaw config file` CLI with `OPENCLAW_CONFIG_PATH` env var to find the bot's state directory. The CLI may return tilde paths — these are expanded before `resolve()`.
135+
136+
### Deploy Trigger
137+
138+
When `deployBot()` runs for a bot with `ai_source: "byoai"`, it calls `generateModelsJson()` which writes the bot's `models.json`. This merges ALL Crow AI profiles into one file.
139+
140+
## Bot Chat
141+
142+
`server/bot-chat.js` provides REST routes for the Messages panel:
143+
144+
| Route | Method | Purpose |
145+
|-------|--------|---------|
146+
| `/bot-chat/:botId/messages` | GET | Fetch message history |
147+
| `/bot-chat/:botId/message` | POST | Send message to bot (polls for response) |
148+
| `/bot-chat/:botId/new-session` | POST | Start a new conversation session |
149+
150+
All routes require `dashboardAuth` middleware.
151+
152+
### Vision Pipeline
153+
154+
When an image is attached to a bot message:
155+
156+
1. Image downloaded from S3 to a temp file
157+
2. Vision model called directly via API (config from `openclaw.json` → `tools.media.models`)
158+
3. API credentials resolved from Crow's AI profiles
159+
4. Text description injected as `[Image N analysis]` context before the user's message
160+
5. Combined message sent to bot via `openclaw agent` CLI
161+
6. Temp files cleaned up after the bot responds
162+
163+
This bypasses the limitation that `openclaw agent` has no `--media` flag and the gateway WebSocket protocol doesn't support inline images with non-vision primary models.
164+
165+
## Panel
166+
167+
The dashboard panel (`panel/crowclaw.js`) serves at `/dashboard/bots`. It renders the bot management UI including:
168+
169+
- Bot list with status indicators
170+
- Create/configure/deploy forms
171+
- Real-time log viewer
172+
- Messages integration for bot chat
173+
174+
The OpenClaw Control UI is proxied through Crow at `/proxy/crowclaw/` with the gateway token auto-injected via URL hash.
175+
176+
## Systemd Integration
177+
178+
Each bot runs as a user-level systemd service (`systemctl --user`). CrowClaw manages the service lifecycle:
179+
180+
- `crow_start_bot` → `systemctl --user start openclaw-gateway.service`
181+
- `crow_stop_bot` → `systemctl --user stop openclaw-gateway.service`
182+
- `crow_bot_logs` → `journalctl --user -u openclaw-gateway.service`
183+
184+
## Related
185+
186+
- [Bot Management Guide](/guide/bot-management) — User-facing guide for bot setup and management
187+
- [Integration Overview](/guide/integration-overview) — How bots fit into Crow's connection patterns
188+
- [OpenClaw Platform Guide](/platforms/openclaw) — OpenClaw setup and configuration
189+
- [Storage Server](/architecture/storage-server) — File storage and attachment handling

‎docs/architecture/storage-server.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -163,3 +163,49 @@ Allowed categories:
163163
- `audio/*` — MP3, WAV, OGG
164164

165165
Executables, scripts, and archive formats are rejected by default.
166+
167+
## Message Attachments
168+
169+
The Messages panel uses the storage server for file attachments across all conversation types (peer messages, AI chat, bot chat).
170+
171+
```
172+
┌─────────────────────────────────────────────────────────┐
173+
│ Messages Panel (attachment UI) │
174+
│ ├── Select file → preview (thumbnail / file card) │
175+
│ ├── Send message │
176+
│ │ └── POST /storage/upload (multipart) │
177+
│ │ └── MinIO bucket (crow-files) │
178+
│ │ └── s3_key stored in message record │
179+
│ └── Display message │
180+
│ └── Presigned URL generated on read │
181+
│ └── Inline image / download link │
182+
└─────────────────────────────────────────────────────────┘
183+
```
184+
185+
### Flow
186+
187+
1. User selects a file via the attachment UI (shared component across all message types)
188+
2. On send, the file is uploaded to MinIO via `POST /storage/upload`
189+
3. The returned `s3_key`, `name`, `mime_type`, and `size` are stored as JSON in the message's `attachments` column
190+
4. When messages are loaded, presigned URLs are generated from the stored `s3_key` for display
191+
5. Images render inline; other file types show as download links
192+
193+
### Bot Vision Pipeline
194+
195+
When an image is attached to a bot message:
196+
197+
1. The image is downloaded from S3 to a temporary file
198+
2. A vision model (configured in the bot's `openclaw.json`) analyzes the image via direct API call
199+
3. The vision model's text description is injected as context before the user's message
200+
4. The temporary file is cleaned up after the bot responds
201+
202+
This allows non-vision primary models (e.g., `glm-5`) to understand image content through a separate vision model (e.g., `glm-4.6v`).
203+
204+
### AI Chat Attachments
205+
206+
For BYOAI AI Chat, image attachments are passed as multimodal content parts to the AI provider:
207+
208+
- **OpenAI-compatible**: `image_url` content part with presigned S3 URL
209+
- **Anthropic**: `image` content part with presigned S3 URL
210+
211+
This requires the configured AI model to support vision (e.g., GPT-4o, Claude Sonnet).

0 commit comments

Comments
 (0)