EvoClaw Developer Guide

Installation

EvoClaw requires Python 3.9+ and a valid Tinker API key for cloud training. Install all dependencies with pip:

pip install evoclaw

Optional: Verify installation

import evoclaw
print(evoclaw.__version__)  # 0.2.1

Quick Start

The fastest way to get EvoClaw running is with the included example scripts. Three commands and your agent is live and evolving.

Step 1 — Configure OpenClaw gateway

Run the setup script for your chosen model. This configures OpenClaw to route through the EvoClaw proxy on port 30000.

# Recommended: Kimi-2.5 (~200B MoE)
evoclaw init

Step 2 — Set your Tinker API key

export TINKER_API_KEY="your_tinker_api_key_here"

Get your Tinker API key at thinkingmachines.ai/tinker. The key is free for development use.

Step 3 — Start EvoClaw

# Basic RL training mode
evoclaw start

You should see output like:

EvoClaw v0.2.1 starting...
   → Model:       moonshotai/Kimi-2.5
   → Proxy port:  30000
   → Tinker URL:  http://localhost:8080
   → Skills:      enabled (18 loaded)
   → Evolution:   enabled
   → Ready. Start chatting — your agent will begin evolving!

Prerequisites

• Python 3.9+ — EvoClaw uses modern async/await and type hints throughout
• OpenClaw — The agent framework EvoClaw wraps. See openclaw.ai
• Tinker API key — For cloud LoRA training. Free tier available at thinkingmachines.ai/tinker
• OpenAI-compatible judge endpoint — For PRM scoring (e.g. Azure OpenAI, any OpenAI-compatible API)
• Network access — That's it. No GPU, no local model server, no cluster.

System Architecture Overview

EvoClaw consists of five main components that work together asynchronously. They are fully decoupled — the proxy serves users while training runs in the background without blocking.

EvoClawProxy

The proxy is a FastAPI application that implements the OpenAI chat completions API. It sits between OpenClaw and your model, transparently intercepting every request.

from evoclaw import EvoClawConfig, EvoClawProxy
from evoclaw.buffer import ConversationBuffer
import asyncio

config = EvoClawConfig(proxy_port=30000)
buffer = ConversationBuffer(config)
proxy  = EvoClawProxy(config=config, buffer=buffer)

# Start the proxy server
asyncio.run(proxy.serve())

The proxy supports both streaming and non-streaming completions. Point your OpenClaw config to http://localhost:30000/v1.

ConversationBuffer

A thread-safe async FIFO queue. Every intercepted turn is added to the buffer. When the buffer reaches batch_size, it triggers a training cycle automatically.

from evoclaw.buffer import ConversationBuffer

buffer = ConversationBuffer(config)

# Add a turn manually (proxy does this automatically)
await buffer.add_turn(messages=messages, response=response)

# Check current size
print(buffer.size)   # e.g. 14 / 32

# Register a callback when buffer is ready
buffer.on_batch_ready(callback=trainer.train_step)

RewardModel (PRM)

The Process Reward Model scores every agent turn on a scale of 0.0 to 1.0. It calls a configurable judge endpoint — any OpenAI-compatible API works.

from evoclaw.reward_model import RewardModel

prm = RewardModel(config)

# Score a single turn
score = await prm.score(
    messages=conversation_history,
    response=agent_response
)
print(score)  # 0.82

EvoClawTrainer

The trainer listens to the buffer and submits LoRA training jobs to Tinker cloud when a batch is ready. After training, it calls the hot-swap API to update the live sampling server.

from evoclaw import EvoClawTrainer

trainer = EvoClawTrainer(config=config, buffer=buffer)

# Run the training loop (runs indefinitely)
await trainer.run()

# Or run a single step manually
await trainer.train_step(batch=buffer.flush())

The Skill System

Skills are short Markdown instructions (typically 2–5 sentences) that guide agent behavior. They are stored in a JSON skill bank and retrieved at inference time based on relevance to the current conversation.

The default skill bank (memory_data/conversation/conversation_skills.json) ships with 18 skills across 5 categories:

Skill Injection

At every turn, EvoClaw retrieves the top-K most relevant skills from the bank and injects them into the system prompt as a ### Agent Skills block. This happens before the model responds.

# Enable skill injection in config
config = EvoClawConfig(use_skills=True)

# The system prompt will be augmented like this:
"""
You are a helpful AI assistant.

### Agent Skills
- Write clean, documented, tested code.
- Validate all inputs before processing.
- Prefer iterative solutions over recursive ones.
"""

The injection is fully transparent — users never see the skill block, but the model does. The result is immediate behavior improvement without any retraining.

Skill Evolution

When a turn receives a reward score below 0.3, EvoClaw automatically triggers skill evolution:

1. The full conversation trajectory is sent to the evolution LLM (configured via azure_openai_deployment)
2. The LLM analyzes what the agent did wrong and what it should have done differently
3. A new, targeted skill is generated and appended to the skill bank as a JSON entry
4. The new skill is immediately available for injection in future turns

# Enable evolution in config
config = EvoClawConfig(
    use_skills=True,
    enable_skill_evolution=True,
    azure_openai_deployment="gpt-5.2",
    azure_openai_endpoint="https://YOUR-RESOURCE.openai.azure.com/",
)

Writing Custom Skills

You can add your own skills directly to the JSON bank. Each skill has a simple structure:

{
  "id": "skill_019",
  "category": "coding",
  "title": "Always write type hints in Python",
  "content": "When writing Python functions, always include type hints for all parameters and the return value. Use Optional[T] for values that may be None. Example: def process(data: list[str]) -> dict[str, int]:",
  "tags": ["python", "typing", "best-practices"],
  "enabled": true
}

EvoClawConfig Reference

All settings are passed as a single EvoClawConfig dataclass instance. Both EvoClawProxy and EvoClawTrainer accept the same config object.

Learning Modes

Mode 1: Reinforcement Learning (GRPO)

Uses Group Relative Policy Optimization to update the model policy based on scored conversation turns. Best when you have clear task completion signals from the environment.

config = EvoClawConfig(
    loss_fn="importance_sampling",  # or "ppo", "cispo"
    use_prm=True,
)

Mode 2: On-Policy Distillation (OPD)

Leverages richer natural-language supervision from a teacher model. Best with a strong teacher (e.g. GPT-5) providing detailed feedback. Faster convergence and denser signal than pure RL.

config = EvoClawConfig(
    loss_fn="importance_sampling",
    use_prm=True,
    prm_model="gpt-5.2",  # Strong teacher
    prm_url="https://api.openai.com/v1",
)

Supported Models

Deployment Guide

Production setup with systemd

# /etc/systemd/system/evoclaw.service
[Unit]
Description=EvoClaw Self-Evolving Agent
After=network.target

[Service]
User=ubuntu
WorkingDirectory=/opt/evoclaw
Environment="TINKER_API_KEY=your_key_here"
ExecStart=/usr/bin/evoclaw start
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Environment variables

Troubleshooting

Proxy not starting

Make sure port 30000 is available. Change it with proxy_port in your config. Check that FastAPI and uvicorn are installed correctly.

Training not triggering

The trainer only fires when the buffer reaches batch_size (default 32). For testing, reduce it: EvoClawConfig(batch_size=4). Also verify your Tinker API key is set correctly.

PRM scoring failing

Verify prm_url is reachable and your API key (prm_api_key or OPENAI_API_KEY) is valid. You can test with use_prm=False for initial setup.

Skill evolution not triggering

Evolution only fires when enable_skill_evolution=True AND reward is below evolution_threshold (default 0.3). Check that azure_openai_deployment is set.

Frequently Asked Questions

Does EvoClaw work without a GPU?

Yes. The entire training pipeline runs on Tinker cloud. Your machine only needs network access. This is one of EvoClaw's core design principles.

How is EvoClaw different from MetaClaw?

EvoClaw builds on MetaClaw's concept but adds a proper Python package structure, full documentation, an interactive website, a streaming proxy, more default skills, better error handling, and a pip-installable setup. See the full comparison.

Can I use EvoClaw with models other than Kimi-2.5?

Yes. Any model supported by Tinker cloud can be used. Set model_name to the Tinker model identifier. Qwen3-4B is a good lightweight option.

Is my conversation data sent anywhere?

Training batches are sent to Tinker cloud for LoRA fine-tuning. The PRM judge endpoint receives conversation turns for scoring. No data is sent to EvoClaw's servers — EvoClaw is entirely open-source and runs on your infrastructure.

Can I disable training and just use skill injection?

Yes. Set use_skills=True and simply don't start the EvoClawTrainer. The proxy and skill injection will work independently.

Changelog

LoRA Training

EvoClaw supports cloud-based LoRA fine-tuning via Tinker. No GPU required — training runs entirely on Tinker's infrastructure.

Supported Models

Setup

Get a Tinker API key at thinkingmachines.ai/tinker, then run:

evoclaw init

Select your model and paste your Tinker API key when prompted. Config is saved to ~/.evoclaw/config.json.

How It Works

Start Training

evoclaw start

Config Reference

{
  "tinker_api_key": "your_key_here",
  "model": "moonshotai/Kimi-K2.5",
  "lora_rank": 32,
  "train_every_n": 10,
  "auto_train": true
}