openclaw-py 0.2.4

Multi-channel AI gateway with extensible messaging integrations

PyClaw

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.

---

Features

🤖 Agent Runtime

• 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

🧠 Memory System

• 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

💬 27+ Messaging Channels

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.

🚪 Gateway

• 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

🖥️ Cross-Platform UI

• 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

🛡️ Security

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

---

Quick Start

Requirements

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

Install

# 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
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"

Optional Extras

Extra	What it adds
ui	TypeScript client (Web/Desktop/Mobile)
matrix	Matrix channel (matrix-nio)
whatsapp	WhatsApp channel (neonize)
voice	Voice TTS (edge-tts)
dev	Testing + linting (pytest, ruff, mypy)
all	ui + matrix + voice + more

First Run

# 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

---

CLI Reference

Core Commands

Command	Description
pyclaw setup --wizard	Interactive setup wizard
pyclaw setup --non-interactive	Headless setup (env vars)
pyclaw agent <message>	Run a single agent turn
pyclaw gateway	Start the gateway server
pyclaw ui	Launch desktop UI
pyclaw ui --web	Launch web UI
pyclaw status [--deep]	Show status / probe health
pyclaw doctor	Run diagnostics

Configuration

Command	Description
pyclaw config list	Show all config
pyclaw config get <key>	Get a config value
pyclaw config set <key> <value>	Set a config value

Agents & Channels

Command	Description
pyclaw agents list	List agents
pyclaw agents add <name> --model <model>	Add an agent
pyclaw channels list	List channels
pyclaw channels status	Connection status

Auth & MCP

Command	Description
pyclaw auth login --provider <name>	Add API key profile
pyclaw auth status	Show auth profiles
pyclaw mcp status	Show MCP servers and tools
pyclaw mcp list-tools	List available MCP tools

Operations

Command	Description
pyclaw service install	Install as system service
pyclaw secrets audit	Scan for plaintext secrets
pyclaw security audit	Security audit
pyclaw logs [--follow]	Tail runtime logs
pyclaw backup export	Export config and sessions

---

Supported Channels

Channel	Library	Type
Telegram	aiogram	Core
Discord	discord.py	Core
Slack	slack-bolt (Socket Mode)	Core
WhatsApp	neonize (Baileys)	Core
Signal	signal-cli JSON-RPC	Core
iMessage	imsg JSON-RPC	Core
Web	Built-in	Core
Feishu / Lark	Open Platform API	Extension
DingTalk	Stream Mode	Extension
QQ	QQ Bot	Extension
MS Teams	Bot Framework	Extension
Matrix	matrix-nio	Extension
IRC	Native TCP/TLS	Extension
LINE	Messaging API	Extension
Twitch	IRC/TLS	Extension
Nostr	NIP-04 relay	Extension
BlueBubbles	REST webhook	Extension
Google Chat	OAuth webhook	Extension
Mattermost	REST + WebSocket	Extension
Nextcloud Talk	REST webhook	Extension
Synology Chat	Incoming webhook	Extension
Tlon / Urbit	HTTP API	Extension
Zalo	Official API	Extension
Voice Call	Twilio	Extension

---

Supported LLM Providers

Core Providers

Provider	Models
OpenAI	GPT-4o, GPT-4o-mini, o1, o3-mini
Anthropic	Claude Opus, Claude Sonnet, Claude Haiku
Google Gemini	Gemini 2.0 Flash, Gemini Pro
Ollama	Any locally hosted model

OpenAI-Compatible Providers

Provider	Notes
OpenRouter	Access to all models
Together AI	Open-source models
Groq	Fast inference
Fireworks AI	Fast inference
Perplexity	Search-augmented

Chinese Providers

Provider	Notes
DeepSeek	DeepSeek-V2 / DeepSeek-Coder
Moonshot / Kimi	128k context
Zhipu / GLM	GLM-4 series
Qwen / DashScope	Qwen series
Volcengine	Doubao models
MiniMax	MiniMax models
Qianfan / 百度	ERNIE series

---

MCP (Model Context Protocol)

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" }
      }
    }
  }
}

---

Configuration

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.)

Example Config

{
  "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"]
    }
  }
}

Environment Variables

Variable	Description
OPENAI_API_KEY	OpenAI API key
ANTHROPIC_API_KEY	Anthropic API key
GOOGLE_API_KEY	Google AI API key
TELEGRAM_BOT_TOKEN	Telegram bot token
PYCLAW_GATEWAY_PORT	Gateway port (default: 18777)

---

Gateway API

WebSocket (port 18777)

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

HTTP (OpenAI-compatible)

Endpoint	Description
POST /v1/chat/completions	Chat completions (streaming SSE)
POST /v1/responses	Responses API (streaming SSE)
GET /v1/models	List available models

---

Docker

Docker Compose (recommended)

# 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

Docker

# Build
docker build -t pyclaw .

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

---

Architecture

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

Tech Stack

Layer	Technology
Language	Python 3.10+
Web framework	FastAPI + Uvicorn
WebSocket	websockets
HTTP client	httpx
CLI	Typer + Rich
Data validation	Pydantic v2
Config format	JSON5
Database	SQLite + FTS5
Vector search	LanceDB
UI (Web)	Next.js 15
UI (Desktop)	Tauri 2.x
UI (Mobile)	Expo React Native
Testing	pytest, pytest-asyncio
Linting	ruff
Type checking	mypy
Build	Hatch

---

Project Stats

Metric	Value
Source files	658 Python files
Test files	297 test files
Channels	27
LLM providers	25+
Built-in tools	20+
RPC methods	25+
CLI commands	25+ groups
UI pages	17+

---

Development

# 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/

---

Contributing

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

---

Acknowledgements

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

---

License

MIT — Copyright (c) 2026 CHEN SAI

---

中文版 README