OpenClaw Python

Python implementation of OpenClaw — a self-hosted personal AI assistant gateway.

中文 README →

Note

🐍 OpenClaw is awesome — don't forget to use the Python version! 100% aligned.

📖 Setup & Config Guide: English → GUIDE.md · 中文 → GUIDE_CN.md

内容包括：安装、Telegram/飞书配置、权限设置、发文件排查、openclaw.json 全字段说明

⚠️ Beta Notice — This project is in active development and continuously aligned with the TypeScript OpenClaw reference. Bugs and rough edges exist; updates are frequent. Feedback and bug reports are welcome!

⚠️ 测试版声明 — 本项目持续对齐 TypeScript 版 OpenClaw，正在快速迭代中。欢迎反馈问题和需求！

Preview

Jarvis responding on Telegram and Feishu — powered by OpenClaw Python

What it does

A self-hosted AI gateway that connects your messaging channels to LLMs:

Feishu (Lark) — Full feature support: WebSocket real-time connection, streaming card output, media (image/file/voice), reactions, pairing, multi-account, Bitable, Wiki, Doc tools
Telegram — Fully operational with robust polling (conflict-free restart logic, health monitor, streaming progress, queue control)
Other channels — Discord, Slack, WhatsApp, Signal, IRC (code complete, runtime verification in progress)
Web UI — Chat, session management, config at http://localhost:18789
Cron scheduler — Autonomous scheduled tasks with flexible timing
Sub-agents — Spawn, registry, thread binding, Docker sandbox
Permission presets — Quick security level switching (Relaxed/Trusted/Standard/Strict)

🌟 LLM Provider Support (25+ Providers)

Full parity with TypeScript version, supporting multiple authentication methods:

Mainstream AI: Anthropic (Claude), OpenAI, Google Gemini, xAI (Grok), Mistral AI
Chinese Services: Kimi Coding (k2p5), MiniMax, Moonshot, Z.AI (GLM), Qwen, Qianfan (Baidu), Volcengine, BytePlus, Xiaomi
Aggregators & Proxies: OpenRouter, LiteLLM, Kilo Gateway, Vercel AI Gateway, Cloudflare AI Gateway, OpenCode Zen, Synthetic
Self-Hosted & Open Source: vLLM, Together AI, Hugging Face, Venice AI
Custom Providers: Any OpenAI/Anthropic-compatible endpoint

Authentication: API Keys (fully supported), OAuth/Portal flows (partial support)

Streaming: Full Anthropic Messages API streaming support with proper event handling

📖 See Provider Configuration Guide for complete details

Quick Start

Prerequisites

Python 3.11+ — Check with python3 --version
uv — Fast Python package manager
LLM API key — Gemini (recommended), Claude, or OpenAI

Install uv if you don't have it:

curl -LsSf https://astral.sh/uv/install.sh | sh

Installation

Clone both repositories as siblings (required structure):

# Create a workspace folder (any name works)
mkdir my-workspace && cd my-workspace

# Clone both repos
git clone https://github.com/openxjarvis/pi-mono-python.git
git clone https://github.com/openxjarvis/openclaw-python.git

# Install dependencies
cd openclaw-python
uv sync

Your folder structure should look like:

my-workspace/
├── openclaw-python/       ← main application
└── pi-mono-python/        ← required sibling (agent core)

First-Time Setup

Run the interactive setup wizard:

uv run openclaw onboard

The wizard will guide you through:

LLM Provider — Choose Gemini, Claude, OpenAI, etc.
API Keys — Enter your API key (saved to .env)
Channel Setup — Configure Telegram, Feishu, or skip
Gateway Port — Default is 18789
Workspace — Agent working directory

Start the Gateway

uv run openclaw start

OpenClaw is now running:

Web UI: http://localhost:18789
Telegram: Send a message to your bot
Feishu: Message your Feishu bot directly

Update to Latest Version

cd openclaw-python
git pull && uv sync

cd ../pi-mono-python
git pull && uv sync

# Restart the gateway
uv run openclaw restart

Dependencies: pi-mono-python

openclaw-python depends on pi-mono-python — a companion repo that provides the core agent and LLM infrastructure as local packages:

Package	Provides
`pi-ai`	Unified LLM streaming layer (Gemini, Anthropic, OpenAI, …)
`pi-agent`	Agent loop, tool execution, session state
`pi-coding-agent`	Coding agent with file/bash/search tools
`pi-tui`	Terminal UI rendering engine

Both repos must be cloned as siblings inside the same parent directory (any name works):

my-workspace/
├── openclaw-python/       ← this repo
└── pi-mono-python/        ← required sibling

Feishu (Lark) — Full Feature Support

飞书是目前功能最完整的渠道，支持所有功能：

Feature	Status
WebSocket long-connection	✅
Streaming card output (实时流式卡片)	✅
Image / File / Voice message	✅
Message reactions (reaction ACK)	✅
Pairing / allowlist / DM policy	✅
Multi-account	✅
Bitable (多维表格) tools	✅
Wiki / Doc read & write	✅
Mention / group chat	✅

Telegram — Optimized

Conflict-free polling (fixes self-inflicted 409 loop from dual-start bug)
PTB internal retry loop handles transient conflicts automatically
Health monitor with get_me() checks every 60s
Update offset persistence across restarts
Deduplication for all update types
Streaming progress — DMs show reasoning steps; groups show live preview bubble
Queue control — /stop to abort, /queue to change behavior (interrupt/steer/followup/collect)
3-minute auto-timeout — Prevents stuck runs

Configuration

Quick Configuration

The easiest way to configure OpenClaw is through the interactive wizard:

uv run openclaw onboard

Manual Configuration

Edit ~/.openclaw/openclaw.json for advanced settings:

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "YOUR_BOT_TOKEN",
      "dmPolicy": "pairing"
    },
    "feishu": {
      "appId": "YOUR_APP_ID",
      "appSecret": "YOUR_APP_SECRET",
      "useWebSocket": true
    }
  },
  "tools": {
    "exec": {
      "security": "full",
      "ask": "on-miss"
    }
  }
}

Essential CLI Commands

# Gateway management
uv run openclaw start         # Start the gateway
uv run openclaw stop          # Stop the gateway
uv run openclaw restart       # Restart the gateway
uv run openclaw status        # Check gateway status

# User management (for pairing mode)
uv run openclaw pairing list              # List pairing requests
uv run openclaw pairing approve <user_id> # Approve a user
uv run openclaw pairing deny <user_id>    # Deny a user

# Security presets
uv run openclaw security preset           # View/switch permission levels
uv run openclaw security preset trusted   # Set to trusted mode

# Configuration
uv run openclaw onboard                   # Run setup wizard again
uv run openclaw config show               # Show current config

For complete CLI reference and detailed configuration, see GUIDE.md.

Permissions & Troubleshooting

If the agent says it "can't do" something, the cause is usually a permission config — not a code bug.

OpenClaw has several independent permission layers. Check these before debugging code:

1. Channel Access — Who can talk to the bot

Controls who can send direct messages to your bot. Configured per channel in ~/.openclaw/openclaw.json:

Policy	Behavior	Use Case
`pairing` (default)	New users must request access and be approved via CLI	Recommended for personal bots
`allowlist`	Only pre-approved users can interact	Team/group usage
`open`	Any user can interact immediately	Public bots (use with caution)
`disabled`	No DM access allowed	Channel-only mode

Example:

{ "channels": { "telegram": { "dmPolicy": "pairing" } } }

Approve users in pairing mode:

# List pending requests
uv run openclaw pairing list

# Approve a user
uv run openclaw pairing approve <user_id>

2. Bash Execution — What shell commands the agent can run

Controls whether the agent can execute shell commands. Configured in ~/.openclaw/openclaw.json:

Setting	Effect	Example Commands
`deny`	Cannot run any shell commands	Agent can only read/write files
`allowlist`	Only whitelisted binaries allowed	`python`, `git`, `ffmpeg`, etc.
`full`	Can run any command	Recommended for trusted environments

Example configuration:

{
  "tools": {
    "exec": {
      "security": "full",
      "ask": "on-miss",
      "safe_bins": ["python", "ffmpeg", "git", "node", "npm"]
    }
  }
}

Note: The exec.security setting only affects the bash tool. File read/write operations are always available regardless of this setting.

Quick preset switching:

# View current permission level
uv run openclaw security preset

# Switch to trusted mode (recommended for personal use)
uv run openclaw security preset trusted

Available presets: relaxed · trusted · standard · strict

3. Feishu App Scopes — What Feishu API features work

If a Feishu tool fails with "Access denied" or "scope required", you need to enable that scope in the Feishu Developer Console:

Scope	Required for
`im:message`, `im:message:send_as_bot`	Basic messaging (required)
`im:message.reaction:write`	Typing indicator reactions
`task:task:write`	Creating / updating tasks
`calendar:calendar.event:write`	Creating calendar events
`bitable:app`	Bitable (spreadsheet) tools
`docx:document`, `wiki:wiki`	Doc / Wiki read & write
`drive:drive`	Cloud drive file access

After enabling new scopes, you must publish a new app version in the Feishu console for changes to take effect.

Common Permission Issues

Symptom	Likely Cause	Fix
Agent says "I cannot run commands"	`exec.security: deny`	Set to `allowlist` or `full`
Agent can't generate files with scripts	`exec.security: deny` blocks bash	Agent can still use `write_file` for text; enable bash for scripts
Feishu task/calendar tools fail	Missing API scope	Enable scope in Feishu console and republish
Bot doesn't respond to new users	DM policy is `pairing`	Approve via `uv run openclaw pairing approve` or set `dmPolicy: open`
Agent can write files but can't run Python	`exec.security: allowlist` missing `python`	Add `python` to `safe_bins`
Bot stuck / unresponsive after complex task	Agent run looping or timed out	Send `/stop` (auto-timeout after 3 min)

Quick fix: Run uv run openclaw security preset to see current permission level and switch to a preset (Trusted recommended for personal use).

See GUIDE.md for full configuration reference.

Status

Continuously aligned with the TypeScript OpenClaw reference.

Channels

Channel	Status	Notes
Telegram	✅ Production ready	Fully tested and operational
Feishu (Lark)	✅ Production ready	Full feature support
Ollama (local models)	✅ Production ready	Tested locally
Discord / Slack / WhatsApp / Signal / IRC	🔧 Runtime verification in progress	Code complete

AI Providers

Provider	Status	Models / Notes
Google Gemini	✅ Production	Gemini 2.5 Pro, Gemini 2.0 Flash, Gemini 1.5 Pro/Flash
Anthropic Claude	✅ Production	Claude 3.5 Sonnet, Claude 3.5 Haiku, Claude 3 Opus
OpenAI	✅ Production	GPT-4o, o1, o3-mini
DeepSeek	✅ Production	DeepSeek-V3, DeepSeek-R1
Ollama (local models)	✅ Production	Llama 3.3, Mistral, Qwen, CodeLlama (local)
AWS Bedrock	✅ Production	Claude 3.x, Llama 3.3, Mistral
Mistral AI	✅ Implemented	Mistral Large, Mistral Medium
xAI (Grok)	✅ Implemented	Grok series models
Kimi (Moonshot)	✅ Implemented	Kimi Coding (k2p5)
MiniMax	✅ Implemented	MiniMax series
Moonshot	✅ Implemented	Moonshot series
Zhipu AI (GLM)	✅ Implemented	GLM-4, ChatGLM series
Qwen (Alibaba)	✅ Implemented	Qwen series models
Qianfan (Baidu)	✅ Implemented	ERNIE (Wenxin) series
Volcengine	✅ Implemented	Doubao series
BytePlus	✅ Implemented	ByteDance international
Xiaomi AI	✅ Implemented	Xiaomi LLM
OpenRouter	✅ Implemented	Multi-provider aggregator
LiteLLM	✅ Implemented	Unified interface proxy
Together AI	✅ Implemented	Open-source model hosting
Hugging Face	✅ Implemented	Inference API
vLLM	✅ Implemented	Self-hosted inference engine
Venice AI	✅ Implemented	Privacy-first AI platform
Kilo Gateway	✅ Implemented	API gateway
Vercel AI Gateway	✅ Implemented	Vercel AI SDK
Cloudflare AI Gateway	✅ Implemented	Cloudflare Workers AI
OpenCode Zen	✅ Implemented	Coding-focused
Synthetic	✅ Implemented	Synthetic data generation
Custom endpoints	✅ Implemented	Any OpenAI/Anthropic-compatible endpoint

Core Infrastructure

Component	Status
Gateway server + Web UI	✅ Production
Session management	✅ Production
Tool system	✅ Production
Skill system	✅ Production
Cron scheduler	✅ Production
Sub-agents (spawn, registry)	✅ Production
Docker sandbox	✅ Implemented
Context compaction	✅ Production

Development

# Run tests
uv run pytest

# Lint
uv run ruff check .
uv run ruff format .

# Build Web UI (if modifying frontend)
cd openclaw/web/ui-src
npm install && npm run build

Related Projects

OpenClaw TypeScript — github.com/badlogic/pi-mono — upstream reference implementation
pi-mono-python — github.com/openxjarvis/pi-mono-python — core agent infrastructure

License

MIT — see LICENSE for details.

Name		Name	Last commit message	Last commit date
.github		.github
archive		archive
assets		assets
extensions		extensions
git-hooks		git-hooks
openclaw		openclaw
scripts		scripts
skills		skills
ui/dist		ui/dist
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
Dockerfile		Dockerfile
GUIDE.md		GUIDE.md
GUIDE_CN.md		GUIDE_CN.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
README_CN.md		README_CN.md
RUN_TESTS.sh		RUN_TESTS.sh
VERSION.txt		VERSION.txt
docker-compose.yml		docker-compose.yml
openclaw.example.json		openclaw.example.json
pairing		pairing
pyproject.toml		pyproject.toml
pytest.ini		pytest.ini
uv.lock		uv.lock

Navigation Menu

Repository navigation

About

Repository files navigation

OpenClaw Python

🐍 OpenClaw is awesome — don't forget to use the Python version! 100% aligned.

Preview

What it does

🌟 LLM Provider Support (25+ Providers)

Quick Start

Prerequisites

Installation

First-Time Setup

Start the Gateway

Update to Latest Version

Dependencies: pi-mono-python

Feishu (Lark) — Full Feature Support

Telegram — Optimized

Configuration

Quick Configuration

Manual Configuration

Essential CLI Commands

Permissions & Troubleshooting

1. Channel Access — Who can talk to the bot

2. Bash Execution — What shell commands the agent can run

3. Feishu App Scopes — What Feishu API features work

Common Permission Issues

Status

Channels

AI Providers

Core Infrastructure

Development

Related Projects

License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

OpenClaw Python

🐍 OpenClaw is awesome — don't forget to use the Python version! 100% aligned.

Preview

What it does

🌟 LLM Provider Support (25+ Providers)

Quick Start

Prerequisites

Installation

First-Time Setup

Start the Gateway

Update to Latest Version

Dependencies: pi-mono-python

Feishu (Lark) — Full Feature Support

Telegram — Optimized

Configuration

Quick Configuration

Manual Configuration

Essential CLI Commands

Permissions & Troubleshooting

1. Channel Access — Who can talk to the bot

2. Bash Execution — What shell commands the agent can run

3. Feishu App Scopes — What Feishu API features work

Common Permission Issues

Status

Channels

AI Providers

Core Infrastructure

Development

Related Projects

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages