Metadata-Version: 2.4
Name: openclaw-py
Version: 0.3.0
Summary: Multi-channel AI gateway with extensible messaging integrations
Project-URL: Homepage, https://github.com/chensaics/openclaw-py
Project-URL: Documentation, https://github.com/chensaics/openclaw-py/tree/main/docs
Project-URL: Repository, https://github.com/chensaics/openclaw-py
Project-URL: Issues, https://github.com/chensaics/openclaw-py/issues
Project-URL: Changelog, https://github.com/chensaics/openclaw-py/releases
Author-email: CHEN SAI <chensai@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: agent,ai,anthropic,chatbot,gateway,llm,mcp,multi-channel,openai,openclaw,skills
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: aiofiles>=24
Requires-Dist: apscheduler>=3.10
Requires-Dist: cachetools>=5.5
Requires-Dist: httpx>=0.28
Requires-Dist: json5>=0.10
Requires-Dist: openai>=1.60
Requires-Dist: pydantic>=2.10
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13
Requires-Dist: typer>=0.15
Provides-Extra: all
Requires-Dist: aiogram>=3.17; extra == 'all'
Requires-Dist: discord-py>=2.4; extra == 'all'
Requires-Dist: edge-tts>=7; extra == 'all'
Requires-Dist: fastapi>=0.115; extra == 'all'
Requires-Dist: google-generativeai>=0.8; extra == 'all'
Requires-Dist: matrix-nio>=0.24; extra == 'all'
Requires-Dist: mss>=9; extra == 'all'
Requires-Dist: openpyxl>=3.1; extra == 'all'
Requires-Dist: pillow>=11; extra == 'all'
Requires-Dist: playwright>=1.50; extra == 'all'
Requires-Dist: pypdf>=5; extra == 'all'
Requires-Dist: python-docx>=1.1; extra == 'all'
Requires-Dist: python-pptx>=1.0; extra == 'all'
Requires-Dist: slack-bolt>=1.22; extra == 'all'
Requires-Dist: websockets>=14; extra == 'all'
Provides-Extra: channels
Requires-Dist: aiogram>=3.17; extra == 'channels'
Requires-Dist: discord-py>=2.4; extra == 'channels'
Requires-Dist: slack-bolt>=1.22; extra == 'channels'
Provides-Extra: dev
Requires-Dist: fastapi>=0.115; extra == 'dev'
Requires-Dist: mypy>=1.14; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.25; extra == 'dev'
Requires-Dist: pytest-cov>=6; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.9; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
Requires-Dist: types-requests; extra == 'dev'
Requires-Dist: types-setuptools>=70; extra == 'dev'
Requires-Dist: websockets>=14; extra == 'dev'
Provides-Extra: docker
Requires-Dist: aiogram>=3.17; extra == 'docker'
Requires-Dist: discord-py>=2.4; extra == 'docker'
Requires-Dist: edge-tts>=7; extra == 'docker'
Requires-Dist: fastapi>=0.115; extra == 'docker'
Requires-Dist: google-generativeai>=0.8; extra == 'docker'
Requires-Dist: matrix-nio>=0.24; extra == 'docker'
Requires-Dist: mss>=9; extra == 'docker'
Requires-Dist: openpyxl>=3.1; extra == 'docker'
Requires-Dist: pillow>=11; extra == 'docker'
Requires-Dist: playwright>=1.50; extra == 'docker'
Requires-Dist: pypdf>=5; extra == 'docker'
Requires-Dist: python-docx>=1.1; extra == 'docker'
Requires-Dist: python-pptx>=1.0; extra == 'docker'
Requires-Dist: slack-bolt>=1.22; extra == 'docker'
Requires-Dist: websockets>=14; extra == 'docker'
Provides-Extra: gemini
Requires-Dist: google-generativeai>=0.8; extra == 'gemini'
Provides-Extra: llamacpp
Requires-Dist: huggingface-hub>=0.20; extra == 'llamacpp'
Requires-Dist: llama-cpp-python>=0.3; extra == 'llamacpp'
Provides-Extra: matrix
Requires-Dist: matrix-nio>=0.24; extra == 'matrix'
Provides-Extra: media
Requires-Dist: mss>=9; extra == 'media'
Requires-Dist: pillow>=11; extra == 'media'
Requires-Dist: playwright>=1.50; extra == 'media'
Provides-Extra: mlx
Requires-Dist: huggingface-hub>=0.20; extra == 'mlx'
Requires-Dist: mlx-lm>=0.10; extra == 'mlx'
Provides-Extra: office
Requires-Dist: openpyxl>=3.1; extra == 'office'
Requires-Dist: pypdf>=5; extra == 'office'
Requires-Dist: python-docx>=1.1; extra == 'office'
Requires-Dist: python-pptx>=1.0; extra == 'office'
Provides-Extra: perf
Requires-Dist: aiosqlite>=0.20; extra == 'perf'
Requires-Dist: uvloop>=0.21; (sys_platform != 'win32') and extra == 'perf'
Provides-Extra: server
Requires-Dist: fastapi>=0.115; extra == 'server'
Requires-Dist: websockets>=14; extra == 'server'
Provides-Extra: server-standard
Requires-Dist: fastapi>=0.115; extra == 'server-standard'
Requires-Dist: websockets>=14; extra == 'server-standard'
Provides-Extra: voice
Requires-Dist: edge-tts>=7; extra == 'voice'
Provides-Extra: whatsapp
Requires-Dist: neonize>=0.3.14; extra == 'whatsapp'
Description-Content-Type: text/markdown

# PyClaw

[![PyPI version](https://img.shields.io/pypi/v/openclaw-py.svg)](https://pypi.org/project/openclaw-py/)
[![Python](https://img.shields.io/pypi/pyversions/openclaw-py.svg)](https://pypi.org/project/openclaw-py/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Tests](https://github.com/chensaics/openclaw-py/actions/workflows/test.yml/badge.svg)](https://github.com/chensaics/openclaw-py/actions)

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

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

> **[Documentation](docs/README.md)** — 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

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

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

```bash
# 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](https://modelcontextprotocol.io). Config format is compatible with Claude Desktop and Cursor.

Add to `~/.pyclaw/pyclaw.json`:

```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

```json
{
  "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)

```bash
# 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

```bash
# 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

```bash
# 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](https://github.com/openclaw/openclaw) (originally built with TypeScript). PyClaw is a ground-up rewrite using Python + TypeScript, with additional features.

Thanks to:
- [OpenClaw](https://github.com/openclaw/openclaw) — original project inspiration
- [Next.js](https://nextjs.org) — React framework
- [Tauri](https://tauri.app) — Desktop apps
- [Expo](https://expo.dev) — Mobile apps

---

## License

[MIT](LICENSE) — Copyright (c) 2026 CHEN SAI

---

**[中文版 README](README_zh.md)**
