Metadata-Version: 2.4
Name: cheapclaw
Version: 1.0.0
Summary: CheapClaw multi-bot orchestration CLI
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: infiagent>=3.0.1
Requires-Dist: requests>=2.31.0
Requires-Dist: lark-oapi>=1.4.0
Requires-Dist: python-socks>=2.5.3

# CheapClaw

CheapClaw is a multi-bot orchestration app built on top of the `infiagent` SDK.

It is designed for a practical deployment shape:

- one shared LLM config can serve all bots
- users can start with a local web chat first
- then add Telegram / Feishu / other channels incrementally
- the supervisor decides whether a new message should reuse an old `task_id`, append to a running task, or fork a new one

## Quick start

### Install

After publishing to PyPI:

```bash
python -m pip install -U cheapclaw
```

For local development:

```bash
cd /Users/chenglin/Desktop/research/claw_dev/cheapclaw
python -m pip install -U -e .
```

### First run

```bash
cheapclaw config --interactive
cheapclaw up
```

Open:

```text
http://127.0.0.1:8787/dashboard
```

If you only have one `api_key` and one `base_url`, that is enough.  
Just fill them once during `cheapclaw config --interactive`; all bots will share that LLM config by default.

Full Chinese usage guide:

- [docs/CHEAPCLAW_CLI_TUTORIAL_ZH.md](/Users/chenglin/Desktop/research/claw_dev/cheapclaw/docs/CHEAPCLAW_CLI_TUTORIAL_ZH.md)

The core problem it solves is not "how to connect one more chat channel". The real problem is:

- a user sends a new request while several agents are already running
- sometimes the new message should continue an old task
- sometimes it should inject a new requirement into a running task
- sometimes it should start a parallel branch
- and the system needs to choose that path automatically without losing context

CheapClaw is built around that decision layer.

## Why CheapClaw exists

Compared with OpenClaw-like systems, the main motivation here is cost and long-horizon stability.

OpenClaw is impressive, but for many practical deployments it is expensive. CheapClaw uses `infiagent` as the execution substrate because `infiagent` already has several properties that matter for weaker models:

- short-step execution instead of giant long-context monologues
- resumable task memory keyed by `task_id`
- configurable fresh / resume behavior
- agent-system level composition
- SDK-level control over runtime, task state, and tool execution

That makes it much more suitable for small-model orchestration, especially when tasks are long and iterative.

## What is different

### 1. Instant message insertion into existing work

This is the main feature, not a side feature.

CheapClaw has a supervisor agent that decides how a new message should be routed:

- continue an old task by reusing the same `task_id`
- append a requirement to a currently running task without stopping it
- fork into a new task when the work is genuinely different

These are different operations and they are handled differently.

#### Continue an old task

If the work is still the same deliverable, CheapClaw can restart a new worker on the same `task_id`.

That matters because the old task keeps:

- workspace
- share context
- historical outputs
- prior task memory

So "modify the old report", "redo that script", "continue the previous result" does not have to become a brand new task.

#### Append to a running task

If a worker is still running, CheapClaw can inject a new requirement into that running task.

This does not require stopping the worker first. The requirement is appended and absorbed on the next safe loop boundary.

That is a different behavior from resuming an old task, and it is one of the main pain points CheapClaw is designed to solve.

### 2. Built on the InfiAgent SDK, not a closed custom runtime

CheapClaw is not a monolithic framework. It is an application built on the `infiagent` SDK.

That means it inherits several useful runtime capabilities:

- different thinking and execution models
- different models for different sub-agents
- mixed local models and provider models
- mixed API vendors in one overall system
- task-level runtime control through the SDK

In practice, this means you can build a system where:

- the supervisor uses one model
- the worker uses another
- a compression model is different again
- some parts use local inference and others use hosted APIs

This is configured at the agent-system level and in the model config.

### 3. Better behavior for weaker models

CheapClaw benefits from InfiAgent's short-step execution strategy.

For weak or small models, that matters a lot. With the same model, total cost can go either way depending on the exact task, but on long-running tasks the short-step strategy is often more stable and more cost-efficient than trying to force a weak model through a giant single planning loop.

Practical rule:

- the weaker the model, the shorter the step window should be
- do not set it below 10
- a good default is 20

### 4. Skills are not the only extension mechanism

CheapClaw supports normal skills, but it also treats full agent systems as a reusable extension layer.

In the default CheapClaw layout there are only two systems:

- `CheapClawSupervisor`
- `CheapClawWorkerGeneral`

But `infiagent` itself also ships with other agent systems, for example:

- `Researcher`
- `OpenCowork`

If you want to reuse them in this kind of setup, remove `human_in_loop` from their config first.

Using a full agent system as a reusable capability is sometimes better than a narrow skill:

- a skill is good for a compact workflow or tool pattern
- an agent system is good for a whole class of related tasks with a stronger internal role design

You can think of an agent system as a kind of "skill pro": broader coverage, more prompt budget, more specialization.

You can install an extra agent system from a zip archive:

```bash
cheapclaw bot-agent-system add /path/to/agent_system.zip --bot-id bot_1
cheapclaw bot-agent-system add /path/to/agent_system.zip --bot-id bot_1 --reload-after
cheapclaw bot-agent-system add /path/to/agent_system.zip --global
```

Notes:

- `--bot-id` installs only into one bot runtime
- `--reload-after` will restart that bot immediately after install
- `--global` installs into shared project assets; bots pick it up after `cheapclaw prepare` or `cheapclaw reload-bot --prepare-first`

## Architecture

CheapClaw has three layers:

1. Channel adapters
2. A supervisor agent
3. Worker tasks running on InfiAgent

The supervisor does not do the real work. It decides:

- direct reply
- reuse old `task_id`
- append to running task
- start a new task
- restart / fresh / reset when needed

Workers do the execution.

## Current capabilities

- local web chat (`localweb`)
- Telegram integration
- Feishu integration through long connection mode
- WhatsApp Cloud API integration
- Discord integration
- QQ integration through OneBot v11 bridge
- WeChat integration through OneBot v11 bridge
- dashboard and panel view
- conversation-to-task binding
- task completion observation
- watchdog observation
- task-level visible skill filtering
- task-level message append
- task-level restart on the same `task_id`
- file sending for Telegram

## Skills behavior

CheapClaw uses task-level visible-skill filtering for worker agents.

By default, workers only see:

- `docx`
- `pptx`
- `xlsx`
- `find-skills`

The supervisor can expose more skills to a worker when needed.

This is implemented by filtering what the model sees in `<available_skills>`, not by breaking the global skill installation mechanism. That means normal skill installation still works.

## Install and run

Use the CLI workflow directly. You do not need to run `cheapclaw_service.py` manually for normal usage.

### 1) Install

Published package:

```bash
python -m pip install -U cheapclaw
```

Local development:

```bash
cd /Users/chenglin/Desktop/research/claw_dev/cheapclaw
python -m pip install -e .
```

### 2) Initialize and configure

```bash
cheapclaw config --interactive
```

You can set context compression thresholds in manifest `context` (for example `user_history_compress_threshold_tokens`).  
These values are synced into each bot app config during `prepare/up`.

If you press Enter on path prompts, defaults are:
- manifest: `~/cheapclaw/fleet.manifest.json`
- runtime root: `~/cheapclaw/runtime`
- fleet config: `~/cheapclaw/runtime/fleet.generated.json`
- llm config: `~/cheapclaw/runtime/config/llm_config.yaml`

If you only have one provider:

- fill `llm.base_url`
- fill `llm.api_key`
- fill `llm.model`

That single LLM config will be reused by all bots unless you intentionally split it later.

### 3) Start all enabled bots (and web console)

```bash
cheapclaw up
```

Open dashboard:
- `http://127.0.0.1:8787/dashboard`

### 4) Daily operations

```bash
cheapclaw status
cheapclaw logs --bot-id bot_1
cheapclaw add-bot
cheapclaw reload-bot --bot-id bot_1 --prepare-first
```

### 5) Stop

```bash
cheapclaw stop
```

Current behavior:
- `cheapclaw stop` stops all bots and stops fleet web console by default.
- `cheapclaw stop --no-web-console` stops bots only.
- If manifest is missing, `cheapclaw stop` falls back to process-scan stop mode (stops all running CheapClaw bot loops and fleet web console processes started from this repo).

### Command quick reference

- `cheapclaw config --interactive`
- `cheapclaw up`
- `cheapclaw status`
- `cheapclaw logs --bot-id <bot_id>`
- `cheapclaw add-bot`
- `cheapclaw start-bot --bot-id <bot_id>`
- `cheapclaw stop-bot --bot-id <bot_id>`
- `cheapclaw reload-bot --bot-id <bot_id> --prepare-first`
- `cheapclaw stop`
- `cheapclaw web-status`
- `cheapclaw web-start`
- `cheapclaw web-stop`

## Channel credentials

### Telegram

- `bot_token`

### Feishu

- `app_id`
- `app_secret`
- `verify_token`
- optional: `encrypt_key`

CheapClaw uses Feishu long connection mode, so it does not require a public webhook endpoint.

### WhatsApp Cloud API

- `access_token`
- `phone_number_id`
- `verify_token`

### Discord

- `bot_token`
- optional: `intents` (default `37377`)
- optional: `require_mention_in_guild` (default `true`)

### QQ / WeChat（OneBot v11 bridge）

- `onebot_api_base` (e.g. `http://127.0.0.1:5700`)
- optional: `onebot_access_token`
- optional: `onebot_post_secret`
- optional: `onebot_self_id`

## Repository layout

- `cheapclaw_service.py`: main service entry
- `tool_runtime_helpers.py`: panel, task, and runtime helpers
- `assets/agent_library/`: supervisor and worker systems
- `assets/config/`: example config files
- `tools_library/`: CheapClaw-specific tools
- `skills/`: CheapClaw-specific skills
- `web/`: dashboard

## Notes for separate release

CheapClaw is intended to live in its own repository.

The framework-level changes that made it possible are mostly SDK and runtime improvements in `infiagent`, especially:

- SDK task control
- task snapshotting
- fresh / resume support
- tool hooks
- context hooks
- skill visibility filtering

If you publish `infiagent` to PyPI, CheapClaw can then be shipped as a clean separate application repo on top of that package.
