ericwang915/pythonclaw

PythonClaw

A personal AI agent you own — in pure Python. pip install and talk to it from your terminal, a web dashboard, or Telegram / Discord / WhatsApp.It remembers what matters, learns new skills on demand, and runs tasks on a schedule.

The Python reimagining of OpenClaw — no Node.js, no Rust, no C extensions. Just Python.

Quick Start · Local with Ollama · Docker · Providers · Skills · Config · Library

---

Why PythonClaw

• 🐍 Pure Python, zero build step — one pip install, no Node/Rust/C toolchain. Import it as a library, not just a CLI.
• 🔌 Any model, or none — DeepSeek, Claude, Gemini, Kimi, GLM… or 100% local with Ollama: no API key, nothing leaves your machine.
• 📡 One agent, everywhere — the same brain answers from your CLI, a browser dashboard, and group chats, each with isolated memory.
• 🧩 It grows itself — pulls from a 13K-skill marketplace, and can write and install a brand-new skill at runtime when none fits.

Quick Start

pip install pythonclaw

pythonclaw onboard    # pick a provider, paste an API key (or choose Ollama — no key)
pythonclaw start      # daemon + web dashboard at http://localhost:7788
pythonclaw chat       # or just chat in the terminal

Prefer to stay fully offline? One line, no key:

LLM_PROVIDER=ollama pythonclaw chat      # needs a local Ollama running

---

What’s inside

---

CLI Reference

First Run

$ pythonclaw start

  ╔══════════════════════════════════════╗
  ║       PythonClaw — Setup Wizard      ║
  ╚══════════════════════════════════════╝

  Choose your LLM provider:

    1. DeepSeek
    2. Grok (xAI)
    3. Claude (Anthropic)
    4. Gemini (Google)
    5. Kimi (Moonshot)
    6. GLM (Zhipu / ChatGLM)
    7. Ollama (100% local — no API key)

  Enter number (1-7): 1
  → DeepSeek

  API Key: ********
  → Key set (sk-****)

  Validating... ✔ Valid!
  ✔ Setup complete!

[PythonClaw] Daemon started (PID 12345).
[PythonClaw] Dashboard: http://localhost:7788

---

Architecture

┌──────────────────────────────────────────────────────────────┐
│                         PythonClaw                            │
├──────────┬────────────┬───────────┬──────────────────────────┤
│ CLI      │ Daemon     │ Sessions  │      Core                │
│          │            │           │                          │
│ onboard  │ start /    │ Store(MD) │ Agent                    │
│ chat     │ stop /     │ Manager   │ ├─ Memory (Markdown)     │
│ skill …  │ status     │ Locks +   │ ├─ RAG (Hybrid)          │
│          │            │ Semaphore │ ├─ Skills (3-tier)        │
│ Web UI ◄─┤ Channels   │           │ ├─ Compaction            │
│ Voice In │ Telegram   │ Per-group │ ├─ Soul + Persona        │
│          │ Discord    │ Isolation │ ├─ Group Context          │
│          │ WhatsApp   │           │ └─ Tool Execution        │
├──────────┴────────────┴───────────┴──────────────────────────┤
│               LLM Provider Abstraction Layer                 │
│ DeepSeek │ Grok │ Claude │ Gemini │ Kimi │ GLM │ Ollama │ …  │
├──────────────────────────────────────────────────────────────┤
│              ClawHub Marketplace (clawhub.com)               │
└──────────────────────────────────────────────────────────────┘

---

Web Dashboard

Start with pythonclaw start and open http://localhost:7788.

• Dashboard — agent status, soul/persona preview, tool list
• Chat — real-time chat with voice input (Deepgram)
• Skill Catalog — browse installed skills by category
• Marketplace — search and install skills from ClawHub
• Configuration — edit LLM provider, API keys, and settings in-browser

---

Configuration

All configuration lives in pythonclaw.json (auto-created by pythonclaw onboard). See pythonclaw.example.json for the full template.

{
  "llm": {
    "provider": "grok",
    "grok": { "apiKey": "xai-...", "model": "grok-3" }
  },
  "tavily":   { "apiKey": "" },
  "deepgram": { "apiKey": "" },
  "web":      { "host": "127.0.0.1", "port": 7788 },
  "channels": {
    "telegram": { "token": "" },
    "discord":  { "token": "" },
    "whatsapp": { "phoneNumberId": "", "token": "", "verifyToken": "pythonclaw_verify" }
  },
  "isolation":   { "perGroup": false },
  "concurrency": { "maxAgents": 4 }
}

Environment variables (e.g. DEEPSEEK_API_KEY, TAVILY_API_KEY, LLM_PROVIDER) override JSON values.

Security: the dashboard has full agent access, so web.host defaults to 127.0.0.1 (loopback only). Expose it deliberately — set web.host to 0.0.0.0 (or PYTHONCLAW_WEB_HOST=0.0.0.0 in containers) only behind your own auth/tunnel.

---

Supported LLM Providers

custom works with OpenAI, OpenRouter, LM Studio, vLLM, llama.cpp server — anything speaking the chat-completions protocol (set llm.custom.baseUrl).

Run 100% local with Ollama

No API key, no cloud, your data never leaves the machine:

ollama pull llama3.1        # or qwen3, mistral, …
pip install pythonclaw

LLM_PROVIDER=ollama pythonclaw chat        # CLI
LLM_PROVIDER=ollama pythonclaw start       # daemon + web dashboard

Pick a different model with OLLAMA_MODEL=qwen3, or point at a remote Ollama with OLLAMA_BASE_URL=http://gpu-box:11434/v1.

Troubleshooting: “timeout” errors after binding your API key

Not every error containing the word timeout is an API/network timeout. A common case: a script the agent generated (or a downloaded skill) calls subprocess.Popen(cmd, timeout=N) — Popen has no timeout parameter, so Python raises TypeError: Popen.__init__() got an unexpected keyword argument 'timeout'. Your API key and connection are fine; the script just needs subprocess.run(cmd, timeout=N) instead. PythonClaw now detects this and attaches a hint to the tool output so the agent fixes the script on the next round.

If you hit a real network timeout (request hangs ~300 s, error mentions your provider host), check llm..baseUrl — a missing /v1 suffix is the most common cause — and verify the endpoint answers curl $BASEURL/models.

---

Docker

docker run -p 7788:7788 \
  -e LLM_PROVIDER=deepseek -e DEEPSEEK_API_KEY=sk-... \
  -v pythonclaw-data:/root/.pythonclaw \
  $(docker build -q .)

Or with compose (edit the environment block / use a .env file):

git clone https://github.com/ericwang915/PythonClaw.git && cd PythonClaw
docker compose up -d

Fully local stack: run Ollama on the host and set LLM_PROVIDER=ollama — the compose file already routes host.docker.internal for you.

---

Skills

Three-Tier Progressive Loading

---
name: code_runner
description: Execute Python code safely in an isolated subprocess.
---
# Code Runner

## Instructions
Run `python {skill_path}/run_code.py "expression"`

ClawHub Marketplace

Browse and install 13,000+ community skills from ClawHub — free, no API key required:

pythonclaw skill search "database backup"
pythonclaw skill install 

Also accessible from the web dashboard Marketplace tab.

---

Memory & RAG

Markdown Memory

~/.pythonclaw/context/memory/
├── MEMORY.md           # Curated long-term memory
└── 2026-02-23.md       # Daily append-only log

When per-group isolation is enabled ("isolation": { "perGroup": true } in config), each session (Telegram chat, Discord channel, etc.) gets its own memory/, persona/, and soul/ under ~/.pythonclaw/context/groups//, while global memories remain accessible via read-through fallback.

TOOLS.md — Local Notes

~/.pythonclaw/context/tools/
└── TOOLS.md              # Your environment-specific cheat sheet

Skills define how tools work. TOOLS.md stores your specifics — SSH hosts, device nicknames, project paths, preferred defaults, API endpoints. Keeping them apart means you can update skills without losing your notes, and share skills without leaking your infrastructure. Editable from the web dashboard.

Hybrid RAG Pipeline

Query → BM25 (sparse) + Embeddings (dense) → RRF Fusion → LLM Re-ranker → Top-K

---

Use as a Library

from pythonclaw import Agent
from pythonclaw.core.llm.openai_compatible import OpenAICompatibleProvider

provider = OpenAICompatibleProvider(
    api_key="sk-...",
    base_url="https://api.deepseek.com/v1",
    model_name="deepseek-chat",
)

agent = Agent(provider=provider)
print(agent.chat("What is the capital of France?"))

---

Project Structure

PythonClaw/
├── pythonclaw/
│   ├── main.py                # CLI entry (onboard/start/stop/status/chat/skill)
│   ├── onboard.py             # Interactive setup wizard
│   ├── daemon.py              # PID-based daemon lifecycle
│   ├── server.py              # Multi-channel daemon server
│   ├── core/
│   │   ├── agent.py           # Core reasoning loop
│   │   ├── tools.py           # Tool schemas and execution
│   │   ├── skill_loader.py    # Three-tier skill system
│   │   ├── skillhub.py        # ClawHub marketplace client
│   │   ├── persistent_agent.py
│   │   ├── compaction.py      # Context compaction
│   │   ├── llm/               # Provider adapters
│   │   ├── memory/            # Markdown memory
│   │   ├── knowledge/         # Knowledge-base RAG
│   │   └── retrieval/         # BM25 + dense + fusion + reranker
│   ├── channels/              # Telegram, Discord, WhatsApp
│   ├── scheduler/             # Cron jobs, heartbeat
│   ├── web/                   # FastAPI dashboard + static assets
│   └── templates/             # Built-in skill templates
├── context/                   # Runtime data (gitignored)
├── pyproject.toml
├── pythonclaw.example.json    # Configuration template
└── LICENSE

---

Development

git clone https://github.com/ericwang915/PythonClaw.git
cd PythonClaw
python -m venv .venv && source .venv/bin/activate
pip install -e .
pytest tests/ -v

---

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

---

Comparison with OpenClaw

---

License

MIT

---

If PythonClaw helps you, consider giving it a ⭐