Multi-channel AI Gateway — Connect your AI Agent to 27+ messaging platforms through a unified gateway.

PyClaw is a Python rewrite of openclaw/openclaw, featuring MCP tool integration, 20+ built-in tools, cross-platform UI (Web/Desktop/Mobile), and an OpenAI-compatible HTTP API.

Documentation — Quick Start, Installation Guide, Configuration, Concepts, Troubleshooting.

• Multi-provider LLM streaming (OpenAI, Anthropic, Google Gemini, Ollama, and 25+ more)
• 20+ built-in tools: file I/O, grep, find, exec, web search/fetch, browser, memory, cron, TTS, etc.
• MCP (Model Context Protocol) support — connect any stdio or HTTP MCP server
• Task planner with multi-step Plan/Step decomposition
• User interrupt system (cancel/append mid-generation)
• Sub-agent orchestration (spawn, steer, kill)
• SKILL.md-based skill injection with ClawHub marketplace

• Context compaction with LLM-based summarization
• Dialog persistence (JSONL format with date-based sharding)
• Hybrid search: SQLite FTS5 + LanceDB vector search
• Daily summary service for session consolidation
• Active Memory with multiple query modes
• Wiki System for structured knowledge base

Telegram, Discord, Slack, WhatsApp, Signal, iMessage, Feishu, DingTalk, QQ, MS Teams, Matrix, IRC, LINE, Twitch, Nostr, and more.

Unified ChannelPlugin interface — each channel is a self-contained module with DM/group policy, allowFrom whitelists, and mention gating.

• FastAPI + WebSocket v3 bidirectional protocol
• OpenAI-compatible HTTP API (/v1/chat/completions, /v1/responses, /v1/models)
• 25+ RPC methods: chat, sessions, agents, channels, config, models, browser, cron, plan, backup, tools, etc.
• Config hot-reload, channel health monitoring

• Next.js 15 Web Application
• Tauri 2.x Desktop App (macOS, Linux, Windows)
• Expo React Native Mobile App (iOS, Android)
• 17+ pages: Chat, Agents, Channels, Sessions, Usage, Cron, Plans, Skills, Nodes, Voice, Logs, Debug, Config, System, Settings, and more

• Command exec approval rules
• Workspace sandbox boundary
• SSRF prevention
• Plaintext secret scanning
• Configuration security audit

• Python >= 3.10
• An LLM API key (OpenAI, Anthropic, Google Gemini, Ollama, or any OpenAI-compatible provider)

# One-line install (macOS / Linux)
curl -fsSL https://raw.githubusercontent.com/chensaics/openclaw-py/master/scripts/install.sh | bash

# One-line install with local model support
curl -fsSL https://raw.githubusercontent.com/chensaics/openclaw-py/master/scripts/install.sh | bash -s -- --extras llamacpp
curl -fsSL https://raw.githubusercontent.com/chensaics/openclaw-py/master/scripts/install.sh | bash -s -- --extras mlx   # Apple Silicon only

# Windows (PowerShell)
irm https://raw.githubusercontent.com/chensaics/openclaw-py/master/scripts/install.ps1 | iex

# From PyPI (recommended)
pip install openclaw-py

# Or via pipx (isolated environment)
pipx install openclaw-py

# macOS via Homebrew
brew install chensaics/tap/pyclaw

# From source (development)
pip install -e ".[dev,ui]"

# Docker
docker run -it --rm -e OPENAI_API_KEY="sk-..." ghcr.io/chensaics/openclaw-py:latest pyclaw agent "Hello"

# 1. Interactive setup
pyclaw setup --wizard

# 2. Chat with the agent
pyclaw agent "What is the weather in Tokyo?"

# 3. Start the gateway
pyclaw gateway

# 4. Launch the desktop UI
pyclaw ui

# 5. Or launch as a web app
pyclaw ui --web --port 18776

Connect external tool servers via MCP. Config format is compatible with Claude Desktop and Cursor.

Add to ~/.pyclaw/pyclaw.json:

{
  "tools": {
    "mcpServers": {
      "filesystem": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
      },
      "remote-api": {
        "url": "https://example.com/mcp/",
        "headers": { "Authorization": "Bearer xxx" }
      }
    }
  }
}

PyClaw stores its state in ~/.pyclaw/:

~/.pyclaw/
├── pyclaw.json          # Main config (JSON5 with comments)
├── auth-profiles.json   # API keys and OAuth credentials
├── credentials/         # Web provider credential files
├── sessions/            # Agent session transcripts (JSONL)
└── workspace/           # Workspace files (AGENTS.md, HEARTBEAT.md, etc.)

{
  "models": {
    "providers": {
      "openai": { "apiKey": "sk-..." },
      "anthropic": { "apiKey": "sk-ant-..." }
    }
  },
  "agents": {
    "defaults": {
      "model": "gpt-4o",
      "provider": "openai"
    }
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "123456:ABC-DEF",
      "allowFrom": ["your_user_id"]
    }
  }
}

Full bidirectional protocol for real-time agent interaction. 25+ RPC methods:

• connect, health, status
• chat.send, chat.abort
• sessions.list, sessions.get
• config.get, config.set
• agents.list, agents.bindings
• channels.list, channels.status
• models.list, models.probe
• browser.*, cron.*, tools.*
• plan.list, plan.resume
• backup.export, backup.import

# Setup
docker compose run --rm pyclaw-cli setup --non-interactive --accept-risk

# Start gateway
docker compose up -d pyclaw-gateway

# View logs
docker compose logs -f pyclaw-gateway

# Build
docker build -t pyclaw .

# Run gateway
docker run -v ~/.pyclaw:/root/.pyclaw -p 18777:18777 pyclaw gateway

openclaw-py/
├── src/pyclaw/           # Python backend (658 files)
│   ├── agents/           # Agent runtime
│   │   ├── runner.py     # Core loop
│   │   ├── stream.py     # Multi-provider streaming
│   │   ├── session.py    # JSONL DAG session storage
│   │   ├── planner.py    # Task Plan/Step decomposition
│   │   ├── providers/    # 25+ LLM provider adapters
│   │   ├── skills/       # SKILL.md discovery
│   │   └── tools/        # 20+ built-in tools + MCP bridge
│   │
│   ├── gateway/          # Gateway server
│   │   ├── server.py     # FastAPI + WebSocket v3
│   │   ├── openai_compat.py  # /v1/chat/completions
│   │   └── methods/      # 25+ RPC handlers
│   │
│   ├── channels/         # 27 messaging channels
│   │   ├── base.py       # ChannelPlugin interface
│   │   ├── telegram/     # aiogram
│   │   ├── discord/      # discord.py
│   │   ├── slack/        # slack-bolt
│   │   └── ...           # + 24 more
│   │
│   ├── config/           # Configuration (Pydantic + JSON5)
│   ├── memory/           # Memory (SQLite + LanceDB)
│   ├── mcp/              # MCP client
│   ├── security/         # Security modules
│   ├── cron/             # APScheduler jobs
│   └── cli/              # Typer CLI (25+ commands)
│
├── apps/                 # TypeScript clients
│   ├── web/              # Next.js 15 Web app
│   ├── desktop/          # Tauri 2.x Desktop app
│   └── mobile/           # Expo React Native app
│
├── packages/             # Shared packages
│   ├── shared/           # Types, API client, Store
│   └── ui/               # UI components
│
├── tests/                # 297 test files
└── docs/                 # Documentation

# Install with dev dependencies
pip install -e ".[dev,ui]"

# Run tests
pytest

# Run tests with coverage
pytest --cov=pyclaw --cov-report=term-missing

# Lint
ruff check src/ tests/

# Format
ruff format src/ tests/

# Type check
mypy src/pyclaw/

Pull requests welcome. The project follows standard Python conventions:

• Code style enforced by ruff
• Type annotations enforced by mypy
• All new features should include tests
• Async-first architecture throughout

This project is inspired by OpenClaw (originally built with TypeScript). PyClaw is a ground-up rewrite using Python + TypeScript, with additional features.

Thanks to:

• OpenClaw — original project inspiration
• Next.js — React framework
• Tauri — Desktop apps
• Expo — Mobile apps

MIT — Copyright (c) 2026 CHEN SAI

中文版 README