crawclaw

CrawClaw

English · 简体中文

CrawClaw is a self-hosted Gateway for AI agents. It runs one local or server process that connects chat channels, Gateway clients, model providers, tools, memory, automation, and plugins through a runtime you control.

Use CrawClaw when you want an always-available assistant that can answer from Feishu, DingTalk, QQ Bot, Weixin, WebChat, a terminal UI, or your own Gateway client while keeping configuration and runtime state on your machine.

Quick Start

Requirements:

• Node 24 recommended
• Node 22.14+ supported
• A model provider account or API key

Install with the recommended script:

curl -fsSL https://crawclaw.ai/install.sh | bash

Windows PowerShell:

iwr -useb https://crawclaw.ai/install.ps1 | iex

Run onboarding and install the local Gateway service:

crawclaw onboard --install-daemon

Verify the Gateway and start chatting:

crawclaw gateway status
crawclaw tui

Docs:

• Getting Started
• Install
• Onboarding
• Gateway Runbook
• Troubleshooting

Install Options

If you already manage Node yourself, npm and pnpm installs are also supported:

npm install -g crawclaw@latest
crawclaw onboard --install-daemon

pnpm add -g crawclaw@latest
pnpm approve-builds -g
crawclaw onboard --install-daemon

For contributors:

git clone https://github.com/qianleigood/crawclaw.git
cd crawclaw
pnpm install
pnpm build
pnpm crawclaw onboard

Docker is optional and useful for isolated or headless deployments:

./scripts/docker/setup.sh
docker compose run --rm crawclaw-cli tui

More install paths:

• Docker
• Nix
• Podman
• Cloud and VPS deployments
• Updating
• Uninstall

What You Can Connect

CrawClaw is channel-first. QuickStart and the main channel picker prioritize China-focused channels:

• DingTalk
• Feishu
• QQ Bot
• Weixin

Optional and legacy channels are still available for explicit setup, including BlueBubbles, Discord, Google Chat, iMessage, IRC, LINE, Matrix, Mattermost, Microsoft Teams, Nextcloud Talk, Nostr, Signal, Slack, Synology Chat, Telegram, Tlon, Twitch, Voice Call, WebChat, WhatsApp, Zalo, and Zalo Personal.

Start here:

• Chat Channels
• Pairing and allowlists
• Channel troubleshooting
• WebChat

What CrawClaw Provides

• Gateway runtime: one long-running process owns routing, auth, sessions, channel events, WebSocket/HTTP APIs, OpenAI-compatible endpoints, and client connections.
• Agent runtime: model calls, streaming, tool calls, subagents, sandboxing, execution events, and provider orchestration run behind the Gateway.
• Tools and skills: built-in tools cover shell execution, file edits, browser automation, web search/fetch, messaging, media, cron, sessions, and device nodes. Skills teach the agent when and how to use those tools.
• Memory runtime: context assembly, compaction, durable extraction, recall, session summaries, and maintenance flows are runtime services.
• Automation: scheduled tasks, background tasks, task flows, hooks, standing orders, and main-session wakes replace ad hoc heartbeat-style automation.
• Plugin ecosystem: plugins add channels, providers, tools, skills, speech, image generation, browser backends, setup flows, and runtime hooks through the plugin SDK.

Useful references:

• Tools and Plugins
• Model Providers
• Automation and Tasks
• Memory
• Plugin Architecture

Architecture

flowchart LR
  Channels["Chat channels"] --> Gateway["Gateway"]
  Clients["CLI, TUI, WebChat, custom clients"] --> Gateway
  Nodes["Paired nodes"] --> Gateway
  Gateway --> Agent["Agent runtime"]
  Agent --> Tools["Typed tools and policy"]
  Agent --> Providers["Model providers"]
  Agent --> Memory["Memory runtime"]
  Agent --> Automation["Tasks, cron, hooks"]
  Plugins["Plugin SDK"] --> Channels
  Plugins --> Tools
  Plugins --> Providers

The Gateway is the central boundary. Clients and channels connect to it; the agent runtime sits behind it; tools, providers, memory, automation, plugins, and nodes integrate through explicit runtime contracts.

Key docs:

• Gateway Architecture
• Gateway Protocol
• Agent Loop
• Configuration
• Security

Repository Map

Path	Purpose
src/gateway	Gateway control plane, protocol, auth, health, pairing, and runtime services
src/agents	Agent runtime, tools, subagents, sandboxing, provider execution, and events
src/memory	Durable memory, recall, summaries, compaction, and context assembly
src/workflows	Workflow registry, n8n bridge, execution records, and workflow operations
src/channels	Core channel implementation behind the channel/plugin boundary
src/plugins	Plugin discovery, manifests, loading, registry, and contract enforcement
src/plugin-sdk	Public SDK contracts for plugin-facing code
extensions	Bundled plugins for channels, providers, browser backends, speech, media, and tools
packages	Workspace support packages
skills	Shipped runtime skills
docs	Mintlify documentation source
test	Shared test infrastructure and fixtures
scripts	Install, build, Docker, release, generated baseline, and maintenance scripts

Maintainer docs:

• Repository Structure
• Skills Catalog

Development

Install dependencies:

pnpm install

Run the CLI from source:

pnpm crawclaw --help
pnpm crawclaw gateway status

Common local checks:

pnpm check
pnpm test
pnpm build

Docs and generated baselines:

pnpm check:docs
pnpm docs:check-links
pnpm config:docs:check
pnpm plugin-sdk:api:check

More:

• Testing
• CLI Reference
• Configuration Reference
• Building Plugins

License

CrawClaw is MIT licensed. See LICENSE.