NilClaw is a multi-agent AI gateway built on Bun + TypeScript. It connects LLMs to your tools, channels, and data with zero-config setup.

Highlights

• TypeScript-native — Built on Bun runtime with full type safety, no compilation step
• 11 LLM Providers — Anthropic (native SSE + prompt caching), OpenAI, OpenRouter, Groq, DeepSeek, Gemini, Mistral, xAI, MiniMax, Cohere, Perplexity
• Agent Orchestration — Teams, delegation (sync/async), handoff, evaluate-loop quality gates
• Skill Factory — LLM-powered skill generation, eval system with grading, benchmarking, A/B comparison, description optimization
• 6 Messaging Channels — Telegram, Discord, Slack, WhatsApp, Zalo, Feishu/Lark
• Dual Storage — File-based standalone or PostgreSQL managed mode with migrations
• Production Security — Rate limiting, injection detection, SSRF protection, credential scrubbing

Quick Start

# Install globally
bun i -g nilclaw

# Set a provider key
export NILCLAW_ANTHROPIC_API_KEY=sk-your-key

# Start the gateway
nilclaw start

From Source

git clone https://github.com/nilclaw/nilclaw.git
cd nilclaw
bun install
bun run dev

Architecture

 Clients (Telegram, Discord, Slack, HTTP API, CLI)
                    │
         ┌──────────▼──────────┐
         │   NilClaw Gateway   │
         │   (Bun HTTP Server) │
         └──────────┬──────────┘
                    │
    ┌───────────────┼───────────────┐
    ▼               ▼               ▼
 Auth Layer    Message Bus     Scheduler
 (Bearer)      (Dedupe)       (Lanes)
                    │
         ┌──────────▼──────────┐
         │    Agent Router     │
         │   (Lazy Resolve)    │
         └──────────┬──────────┘
                    │
         ┌──────────▼──────────┐
         │     Agent Loop      │
         │  think → act → obs  │
         └──┬──────┬──────┬────┘
            ▼      ▼      ▼
         Tools   LLM    Stores
                Providers

See docs/system-architecture.md for detailed architecture diagrams and component interactions.

Configuration

Essential Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | NILCLAW_PROVIDER | Default LLM provider | anthropic | | NILCLAW_MODEL | Default model | claude-sonnet-4-5-20250929 | | NILCLAW_GATEWAY_TOKEN | API authentication token | — | | NILCLAW_HOST | Server bind address | 0.0.0.0 | | NILCLAW_PORT | Server port | 18790 | | NILCLAW_MODE | standalone or managed | standalone |

Provider API Keys (set at least one)

| Variable | Provider | |----------|----------| | NILCLAW_ANTHROPIC_API_KEY | Anthropic Claude | | NILCLAW_OPENAI_API_KEY | OpenAI | | NILCLAW_OPENROUTER_API_KEY | OpenRouter | | NILCLAW_GROQ_API_KEY | Groq | | NILCLAW_DEEPSEEK_API_KEY | DeepSeek | | NILCLAW_GEMINI_API_KEY | Google Gemini | | NILCLAW_MISTRAL_API_KEY | Mistral AI | | NILCLAW_XAI_API_KEY | xAI Grok | | NILCLAW_MINIMAX_API_KEY | MiniMax | | NILCLAW_COHERE_API_KEY | Cohere | | NILCLAW_PERPLEXITY_API_KEY | Perplexity |

Managed Mode (PostgreSQL)

export NILCLAW_MODE=managed
export NILCLAW_POSTGRES_DSN="postgres://user:pass@localhost:5432/nilclaw?sslmode=disable"
export NILCLAW_ENCRYPTION_KEY=$(openssl rand -hex 32)
nilclaw start

Full configuration reference: docs/QUICK-REFERENCE.md

HTTP API

| Endpoint | Description | |----------|-------------| | GET /health | Health check | | POST /v1/chat/completions | OpenAI-compatible chat completions | | GET/POST/PUT/DELETE /v1/agents | Agent CRUD | | GET/POST/PUT/DELETE /v1/providers | Provider management | | GET/DELETE /v1/sessions | Session management | | GET/POST /v1/skills | Skill CRUD + generation (SSE) | | POST /v1/skills/:name/eval/* | Eval system (run, grade, benchmark, compare, optimize) | | GET/POST/PUT/DELETE /v1/mcp/servers | MCP server management |

Auth: Authorization: Bearer <NILCLAW_GATEWAY_TOKEN>

Example

curl -X POST http://localhost:18790/v1/chat/completions \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5-20250929",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Deployment Modes

| Capability | Standalone | Managed | |-----------|:----------:|:-------:| | Agent loop + tools | ✅ | ✅ | | Messaging channels | ✅ | ✅ | | Memory (FTS) | ✅ | ✅ | | Agent teams & delegation | — | ✅ | | Skills (BM25 + pgvector) | Basic | ✅ | | MCP server integration | — | ✅ | | Tracing | — | ✅ | | API key encryption | — | ✅ |

Source Modules

| Module | Description | |--------|-------------| | agent/ | Agent loop (think-act-observe), router, system prompt, context pruning | | bootstrap/ | Workspace seeding with default files | | bus/ | Message bus with deduplication and debounce | | channels/ | Channel adapters (Telegram, Discord, Slack, WhatsApp, Zalo, Feishu) | | config/ | Config loading (JSON5 + env overlay), hot reload | | cron/ | Cron service — at, every, and cron expressions | | gateway/ | Gateway server, WebSocket, connection management | | http/ | HTTP API server, CRUD handlers, chat completions, auth | | mcp/ | MCP manager — stdio, SSE, streamable-http | | memory/ | Long-term memory — FTS (standalone) + pgvector (managed) | | packaging/ | Agent export/import as .nilclaw ZIP bundles | | providers/ | LLM adapters — Anthropic (native SSE), OpenAI-compatible | | scheduler/ | Lane-based scheduler — main, subagent, delegate, cron | | skill-factory/ | LLM-powered skill generation, eval, grading, optimization | | skills/ | Skill system — SKILL.md parsing, BM25 + embedding search | | store/ | Data stores — file-based + PostgreSQL | | tools/ | Tool registry + 30+ built-in tools |

Full module breakdown: docs/codebase-summary.md

Built-in Tools

| Tool | Description | |------|-------------| | read_file, write_file, edit_file, list_files | Filesystem operations | | exec | Shell command execution (with approval) | | web_search, web_fetch | Web search and content fetching | | memory | Long-term memory (FTS + vector) | | skill_search | Skill search (BM25 + embedding) | | spawn | Spawn subagents | | delegate, handoff, evaluate_loop | Agent orchestration | | team_tasks, team_message | Team collaboration | | sessions_list, sessions_history, sessions_send | Session management | | cron | Job scheduling |

CLI

nilclaw                    Start gateway (default)
nilclaw start              Start the NilClaw gateway
nilclaw stop               Stop the running gateway
nilclaw version            Print version info
nilclaw doctor             System health check

Flags:
  --config, -c    Config file path (default: config.json)
  --verbose, -v   Enable debug logging
  --port, -p      Override port

Development

bun install        # Install dependencies
bun run dev        # Dev mode (hot reload)
bun test           # Run tests
bun run build      # Build for production
bun run migrate:up # Run DB migrations (managed mode)

Documentation

| Document | Description | |----------|-------------| | Project Overview & PDR | Vision, features, requirements, roadmap | | System Architecture | Architecture diagrams, data flows, components | | Codebase Summary | Module breakdown, file counts, dependencies | | Code Standards | Conventions, patterns, security practices | | Skill Factory API | Skill generation, eval, grading, optimization API | | Quick Reference | Common tasks, API examples, troubleshooting | | Documentation Index | Navigation guide, reading strategies by role |

License

MIT