diff --git a/README.ja.md b/README.ja.md index e4245cf96..70f9fca45 100644 --- a/README.ja.md +++ b/README.ja.md @@ -1,769 +1,525 @@ -
-ClawDroid +# ClawDroid -

ClawDroid: Go で書かれた超効率 AI アシスタント

+Android 向け超軽量パーソナル AI アシスタント。Go バックエンドが Termux 上で動作し、ネイティブ Kotlin/Jetpack Compose アプリがチャット UI、音声アシスタント、デバイス自動操作を提供します。 -

$10 ハードウェア · 10MB RAM · 1秒起動 · 皮皮虾，我们走！

-

+[PicoClaw](https://github.com/pico-claw/picoclaw) からフォークしたプロジェクトです。 -

-Go -Hardware -License -

+## アーキテクチャ -**日本語** | [English](README.md) - -
- - ---- - -🦐 ClawDroid は [nanobot](https://github.com/HKUDS/nanobot) にインスパイアされた超軽量パーソナル AI アシスタントです。Go でゼロからリファクタリングされ、AI エージェント自身がアーキテクチャの移行とコード最適化を推進するセルフブートストラッピングプロセスで構築されました。 - -⚡️ $10 のハードウェアで 10MB 未満の RAM で動作：OpenClaw より 99% 少ないメモリ、Mac mini より 98% 安い！ - - - - - - -
-

- -

- 		-

- -

-
- -## 📢 ニュース -2026-02-09 🎉 ClawDroid リリース！$10 ハードウェアで 10MB 未満の RAM で動く AI エージェントを 1 日で構築。🦐 皮皮虾，我们走！ - -## ✨ 特徴 - -🪶 **超軽量**: メモリフットプリント 10MB 未満 — Clawdbot のコア機能より 99% 小さい。 - -💰 **最小コスト**: $10 ハードウェアで動作 — Mac mini より 98% 安い。 - -⚡️ **超高速**: 起動時間 400 倍高速、0.6GHz シングルコアでも 1 秒で起動。 - -🌍 **真のポータビリティ**: RISC-V、ARM、x86 対応の単一バイナリ。ワンクリックで Go！ - -🤖 **AI ブートストラップ**: 自律的な Go ネイティブ実装 — コアの 95% が AI 生成、人間によるレビュー付き。 - -| | OpenClaw | NanoBot | **ClawDroid** | -| --- | --- | --- |--- | -| **言語** | TypeScript | Python | **Go** | -| **RAM** | >1GB |>100MB| **< 10MB** | -| **起動時間**
(0.8GHz コア) | >500秒 | >30秒 | **<1秒** | -| **コスト** | Mac Mini 599$ | 大半の Linux SBC
~50$ |**あらゆる Linux ボード**
**最安 10$** | -ClawDroid - - -## 🦾 デモンストレーション -### 🛠️ スタンダードアシスタントワークフロー - - - - - - - - - - - - - - - - -

🧩 フルスタックエンジニア

🗂️ ログ＆計画管理

🔎 Web 検索＆学習

開発 · デプロイ · スケールスケジュール · 自動化 · メモリ発見 · インサイト · トレンド
- -### 🐜 革新的な省フットプリントデプロイ -ClawDroid はほぼすべての Linux デバイスにデプロイできます！ - -- $9.9 [LicheeRV-Nano](https://www.aliexpress.com/item/1005006519668532.html) E(Ethernet) または W(WiFi6) バージョン、最小ホームアシスタントに -- $30~50 [NanoKVM](https://www.aliexpress.com/item/1005007369816019.html) または $100 [NanoKVM-Pro](https://www.aliexpress.com/item/1005010048471263.html) サーバー自動メンテナンスに -- $50 [MaixCAM](https://www.aliexpress.com/item/1005008053333693.html) または $100 [MaixCAM2](https://www.kickstarter.com/projects/zepan/maixcam2-build-your-next-gen-4k-ai-camera) スマート監視に - -https://private-user-images.githubusercontent.com/83055338/547056448-e7b031ff-d6f5-4468-bcca-5726b6fecb5c.mp4 - -🌟 もっと多くのデプロイ事例が待っています！ - -## 📦 インストール - -### コンパイル済みバイナリでインストール - -[リリースページ](https://github.com/KarakuriAgent/clawdroid/releases) からお使いのプラットフォーム用のファームウェアをダウンロードしてください。 - -### ソースからインストール（最新機能、開発向け推奨） - -```bash -git clone https://github.com/KarakuriAgent/clawdroid.git - -cd clawdroid -make deps - -# ビルド（インストール不要） -make build - -# 複数プラットフォーム向けビルド -make build-all - -# ビルドとインストール -make install +``` +┌──────────────────────────────────┐ +│ Android アプリ (Kotlin) │ +│ ┌───────────┐ ┌───────────────┐ │ +│ │ チャット │ │ アシスタント │ │ +│ │ UI │ │ オーバーレイ │ │ +│ │ (Compose) │ │ │ │ +│ └─────┬─────┘ └───────┬──────┘ │ +│ │ WebSocket │ │ +│ └───────┬────────┘ │ +└────────────────┼─────────────────┘ + │ ws://127.0.0.1:18793 +┌────────────────┼─────────────────┐ +│ Go バックエンド (Termux) │ +│ ┌────────┐ ┌─────────────────┐ │ +│ │エージェント│ │ ツールループ │ │ +│ │ ループ │ │ (16以上) │ │ +│ └───┬────┘ └────────┬────────┘ │ +│ │ ┌──────────┤ │ +│ ┌───┴──┐ │ ┌────────┴─────────┐ │ +│ │ LLM │ │ │ MCP / Cron / │ │ +│ └──────┘ │ │ Skills / Memory │ │ +│ ┌────────┴─┴──────────────────┐ │ +│ │ チャンネル (Telegram, │ │ +│ │ Discord, Slack, LINE 等) │ │ +│ └─────────────────────────────┘ │ +└──────────────────────────────────┘ ``` -## 🐳 Docker Compose +- **Go バックエンド** (`cmd/clawdroid/`): シングルバイナリ。エージェントループ、ツール実行、LLM 呼び出し、メッセージングチャンネル、Cron、ハートビート +- **Android アプリ** (`android/`): チャット UI、フローティングアシスタントオーバーレイ、アクセシビリティベースのデバイス制御、音声モード -Docker Compose を使えば、ローカルにインストールせずに ClawDroid を実行できます。 +## クイックスタート + +### 前提条件 + +- [Termux](https://termux.dev) がインストールされた Android デバイス +- LLM API キー（OpenAI、Anthropic、Gemini 等） + +### 1. ダウンロード + +[GitHub Releases](https://github.com/KarakuriAgent/clawdroid/releases) から最新の Go バックエンドバイナリと Android アプリ APK をダウンロードします。 + +デバイスのアーキテクチャに合ったバイナリを選択してください: + +| アーキテクチャ | バイナリ | +|-------------|---------| +| 64-bit ARM（最近のデバイスの大半） | `clawdroid-linux-arm64` | +| 32-bit ARM | `clawdroid-linux-arm` | + +Termux で `uname -m` を実行するとアーキテクチャを確認できます。 + +### 2. Go バックエンドのインストール + +Termux で: ```bash -# 1. リポジトリをクローン -git clone https://github.com/KarakuriAgent/clawdroid.git -cd clawdroid - -# 2. API キーを設定 -cp config/config.example.json config/config.json -vim config/config.json # DISCORD_BOT_TOKEN, プロバイダーの API キーを設定 - -# 3. ビルドと起動 -docker compose --profile gateway up -d - -# 4. ログ確認 -docker compose logs -f clawdroid-gateway - -# 5. 停止 -docker compose --profile gateway down +# バイナリを配置して実行権限を付与（arm64 の例） +cp ~/storage/downloads/clawdroid-linux-arm64 ~/.local/bin/clawdroid +chmod +x ~/.local/bin/clawdroid ``` -### Agent モード（ワンショット） - -```bash -# 質問を投げる -docker compose run --rm clawdroid-agent -m "What is 2+2?" - -# インタラクティブモード -docker compose run --rm clawdroid-agent -``` - -### リビルド - -```bash -docker compose --profile gateway build --no-cache -docker compose --profile gateway up -d -``` - -### 🚀 クイックスタート（ネイティブ） - -> [!TIP] -> `~/.clawdroid/config.json` に API キーを設定してください。 -> API キーの取得先: [OpenRouter](https://openrouter.ai/keys) (LLM) · [Zhipu](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) (LLM) -> Web 検索は **任意** です - 無料の [Brave Search API](https://brave.com/search/api) (月 2000 クエリ無料) - -**1. 初期化** +### 3. 初期セットアップ ```bash clawdroid onboard ``` -**2. 設定** (`~/.clawdroid/config.json`) +`~/.clawdroid/config.json` とワークスペーステンプレートが作成されます。 -```json -{ - "agents": { - "defaults": { - "workspace": "~/.clawdroid/workspace", - "model": "glm-4.7", - "max_tokens": 8192, - "temperature": 0.7, - "max_tool_iterations": 20 - } - }, - "providers": { - "openrouter": { - "api_key": "xxx", - "api_base": "https://openrouter.ai/api/v1" - } - }, - "tools": { - "web": { - "search": { - "api_key": "YOUR_BRAVE_API_KEY", - "max_results": 5 - } - } - }, - "heartbeat": { - "enabled": true, - "interval": 30 - } -} -``` - -**3. API キーの取得** - -- **LLM プロバイダー**: [OpenRouter](https://openrouter.ai/keys) · [Zhipu](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) · [Anthropic](https://console.anthropic.com) · [OpenAI](https://platform.openai.com) · [Gemini](https://aistudio.google.com/api-keys) -- **Web 検索**（任意）: [Brave Search](https://brave.com/search/api) - 無料枠あり（月 2000 リクエスト） - -> **注意**: 完全な設定テンプレートは `config.example.json` を参照してください。 - -**3. チャット** +設定ファイルを編集して API キーを追加: ```bash -clawdroid agent -m "What is 2+2?" +vi ~/.clawdroid/config.json ``` -これだけです！2 分で AI アシスタントが動きます。 +### 4. Android アプリのインストール ---- +ダウンロードした APK を同じデバイスにインストールします。 -## 💬 チャットアプリ - -Telegram、Discord、QQ、DingTalk、LINE で ClawDroid と会話できます - -| チャネル | セットアップ | -|---------|------------| -| **Telegram** | 簡単（トークンのみ） | -| **Discord** | 簡単（Bot トークン + Intents） | -| **QQ** | 簡単（AppID + AppSecret） | -| **DingTalk** | 普通（アプリ認証情報） | -| **LINE** | 普通（認証情報 + Webhook URL） | - -
-Telegram（推奨） - -**1. Bot を作成** - -- Telegram を開き、`@BotFather` を検索 -- `/newbot` を送信、プロンプトに従う -- トークンをコピー - -**2. 設定** - -```json -{ - "channels": { - "telegram": { - "enabled": true, - "token": "YOUR_BOT_TOKEN", - "allowFrom": ["YOUR_USER_ID"] - } - } -} -``` - -> ユーザー ID は Telegram の `@userinfobot` から取得できます。 - -**3. 起動** +### 5. 実行 ```bash +# ゲートウェイサーバーを起動（Android アプリ + メッセージングチャンネルに接続） clawdroid gateway -``` -
- -
-Discord - -**1. Bot を作成** -- https://discord.com/developers/applications にアクセス -- アプリケーションを作成 → Bot → Add Bot -- Bot トークンをコピー - -**2. Intents を有効化** -- Bot の設定画面で **MESSAGE CONTENT INTENT** を有効化 -- （任意）**SERVER MEMBERS INTENT** も有効化 - -**3. ユーザー ID を取得** -- Discord 設定 → 詳細設定 → **開発者モード** を有効化 -- 自分のアバターを右クリック → **ユーザーIDをコピー** - -**4. 設定** - -```json -{ - "channels": { - "discord": { - "enabled": true, - "token": "YOUR_BOT_TOKEN", - "allowFrom": ["YOUR_USER_ID"] - } - } -} +# またはターミナルから直接対話 +clawdroid agent +clawdroid agent -m "こんにちは！" ``` -**5. Bot を招待** -- OAuth2 → URL Generator -- Scopes: `bot` -- Bot Permissions: `Send Messages`, `Read Message History` -- 生成された招待 URL を開き、サーバーに Bot を追加 - -**6. 起動** - -```bash -clawdroid gateway -``` - -
- -
-QQ - -**1. Bot を作成** - -- [QQ オープンプラットフォーム](https://q.qq.com/#) にアクセス -- アプリケーションを作成 → **AppID** と **AppSecret** を取得 - -**2. 設定** - -```json -{ - "channels": { - "qq": { - "enabled": true, - "app_id": "YOUR_APP_ID", - "app_secret": "YOUR_APP_SECRET", - "allow_from": [] - } - } -} -``` - -> `allow_from` を空にすると全ユーザーを許可、QQ番号を指定してアクセス制限可能。 - -**3. 起動** - -```bash -clawdroid gateway -``` - -
- -
-DingTalk - -**1. Bot を作成** - -- [オープンプラットフォーム](https://open.dingtalk.com/) にアクセス -- 内部アプリを作成 -- Client ID と Client Secret をコピー - -**2. 設定** - -```json -{ - "channels": { - "dingtalk": { - "enabled": true, - "client_id": "YOUR_CLIENT_ID", - "client_secret": "YOUR_CLIENT_SECRET", - "allow_from": [] - } - } -} -``` - -> `allow_from` を空にすると全ユーザーを許可、ユーザーIDを指定してアクセス制限可能。 - -**3. 起動** - -```bash -clawdroid gateway -``` - -
- -
-LINE - -**1. LINE 公式アカウントを作成** - -- [LINE Developers Console](https://developers.line.biz/) にアクセス -- プロバイダーを作成 → Messaging API チャネルを作成 -- **チャネルシークレット** と **チャネルアクセストークン** をコピー - -**2. 設定** - -```json -{ - "channels": { - "line": { - "enabled": true, - "channel_secret": "YOUR_CHANNEL_SECRET", - "channel_access_token": "YOUR_CHANNEL_ACCESS_TOKEN", - "webhook_host": "0.0.0.0", - "webhook_port": 18791, - "webhook_path": "/webhook/line", - "allow_from": [] - } - } -} -``` - -**3. Webhook URL を設定** - -LINE の Webhook には HTTPS が必要です。リバースプロキシまたはトンネルを使用してください: - -```bash -# ngrok の例 -ngrok http 18791 -``` - -LINE Developers Console で Webhook URL を `https://あなたのドメイン/webhook/line` に設定し、**Webhook の利用** を有効にしてください。 - -**4. 起動** - -```bash -clawdroid gateway -``` - -> グループチャットでは @メンション時のみ応答します。返信は元メッセージを引用する形式です。 - -> **Docker Compose**: `clawdroid-gateway` サービスに `ports: ["18791:18791"]` を追加して Webhook ポートを公開してください。 - -
- -## ⚙️ 設定 - -設定ファイル: `~/.clawdroid/config.json` - -### ワークスペース構成 - -ClawDroid は設定されたワークスペース（デフォルト: `~/.clawdroid/workspace`）にデータを保存します： - -``` -~/.clawdroid/workspace/ -├── sessions/ # 会話セッションと履歴 -├── memory/ # 長期メモリ（MEMORY.md） -├── state/ # 永続状態（最後のチャネルなど） -├── cron/ # スケジュールジョブデータベース -├── skills/ # カスタムスキル -├── AGENTS.md # エージェントの行動ガイド -├── HEARTBEAT.md # 定期タスクプロンプト（30分ごとに確認） -├── IDENTITY.md # エージェントのアイデンティティ -├── SOUL.md # エージェントのソウル -├── TOOLS.md # ツールの説明 -└── USER.md # ユーザー設定 -``` - -### 🔒 セキュリティサンドボックス - -ClawDroid はデフォルトでサンドボックス環境で実行されます。エージェントは設定されたワークスペース内のファイルにのみアクセスし、コマンドを実行できます。 - -#### デフォルト設定 - -```json -{ - "agents": { - "defaults": { - "workspace": "~/.clawdroid/workspace", - "restrict_to_workspace": true - } - } -} -``` - -| オプション | デフォルト | 説明 | -|-----------|-----------|------| -| `workspace` | `~/.clawdroid/workspace` | エージェントの作業ディレクトリ | -| `restrict_to_workspace` | `true` | ファイル/コマンドアクセスをワークスペースに制限 | - -#### 保護対象ツール - -`restrict_to_workspace: true` の場合、以下のツールがサンドボックス化されます： - -| ツール | 機能 | 制限 | -|-------|------|------| -| `read_file` | ファイル読み込み | ワークスペース内のファイルのみ | -| `write_file` | ファイル書き込み | ワークスペース内のファイルのみ | -| `list_dir` | ディレクトリ一覧 | ワークスペース内のディレクトリのみ | -| `edit_file` | ファイル編集 | ワークスペース内のファイルのみ | -| `append_file` | ファイル追記 | ワークスペース内のファイルのみ | -| `exec` | コマンド実行 | コマンドパスはワークスペース内である必要あり | - -#### exec ツールの追加保護 - -`restrict_to_workspace: false` でも、`exec` ツールは以下の危険なコマンドをブロックします： - -- `rm -rf`, `del /f`, `rmdir /s` — 一括削除 -- `format`, `mkfs`, `diskpart` — ディスクフォーマット -- `dd if=` — ディスクイメージング -- `/dev/sd[a-z]` への書き込み — 直接ディスク書き込み -- `shutdown`, `reboot`, `poweroff` — システムシャットダウン -- フォークボム `:(){ :|:& };:` - -#### エラー例 - -``` -[ERROR] tool: Tool execution failed -{tool=exec, error=Command blocked by safety guard (path outside working dir)} -``` - -``` -[ERROR] tool: Tool execution failed -{tool=exec, error=Command blocked by safety guard (dangerous pattern detected)} -``` - -#### 制限の無効化（セキュリティリスク） - -エージェントにワークスペース外のパスへのアクセスが必要な場合： - -**方法1: 設定ファイル** -```json -{ - "agents": { - "defaults": { - "restrict_to_workspace": false - } - } -} -``` - -**方法2: 環境変数** -```bash -export CLAWDROID_AGENTS_DEFAULTS_RESTRICT_TO_WORKSPACE=false -``` - -> ⚠️ **警告**: この制限を無効にすると、エージェントはシステム上の任意のパスにアクセスできるようになります。制御された環境でのみ慎重に使用してください。 - -#### セキュリティ境界の一貫性 - -`restrict_to_workspace` 設定は、すべての実行パスで一貫して適用されます： - -| 実行パス | セキュリティ境界 | -|---------|-----------------| -| メインエージェント | `restrict_to_workspace` ✅ | -| サブエージェント / Spawn | 同じ制限を継承 ✅ | -| ハートビートタスク | 同じ制限を継承 ✅ | - -すべてのパスで同じワークスペース制限が適用されます — サブエージェントやスケジュールタスクを通じてセキュリティ境界をバイパスする方法はありません。 - -### ハートビート（定期タスク） - -ClawDroid は自動的に定期タスクを実行できます。ワークスペースに `HEARTBEAT.md` ファイルを作成します： - -```markdown -# 定期タスク - -- 重要なメールをチェック -- 今後の予定を確認 -- 天気予報をチェック -``` - -エージェントは30分ごと（設定可能）にこのファイルを読み込み、利用可能なツールを使ってタスクを実行します。 - -#### spawn で非同期タスク実行 - -時間のかかるタスク（Web検索、API呼び出し）には `spawn` ツールを使って**サブエージェント**を作成します： - -```markdown -# 定期タスク - -## クイックタスク（直接応答） -- 現在時刻を報告 - -## 長時間タスク（spawn で非同期） -- AIニュースを検索して要約 -- メールをチェックして重要なメッセージを報告 -``` - -**主な特徴:** - -| 機能 | 説明 | -|------|------| -| **spawn** | 非同期サブエージェントを作成、ハートビートをブロックしない | -| **独立コンテキスト** | サブエージェントは独自のコンテキストを持ち、セッション履歴なし | -| **message ツール** | サブエージェントは message ツールで直接ユーザーと通信 | -| **非ブロッキング** | spawn 後、ハートビートは次のタスクへ継続 | - -#### サブエージェントの通信方法 - -``` -ハートビート発動 - ↓ -エージェントが HEARTBEAT.md を読む - ↓ -長いタスク: spawn サブエージェント - ↓ ↓ -次のタスクへ継続 サブエージェントが独立して動作 - ↓ ↓ -全タスク完了 message ツールを使用 - ↓ ↓ -HEARTBEAT_OK 応答 ユーザーが直接結果を受け取る -``` - -サブエージェントはツール（message、web_search など）にアクセスでき、メインエージェントを経由せずにユーザーと通信できます。 - -**設定:** - -```json -{ - "heartbeat": { - "enabled": true, - "interval": 30 - } -} -``` - -| オプション | デフォルト | 説明 | -|-----------|-----------|------| -| `enabled` | `true` | ハートビートの有効/無効 | -| `interval` | `30` | チェック間隔（分）、最小5分 | - -**環境変数:** -- `CLAWDROID_HEARTBEAT_ENABLED=false` で無効化 -- `CLAWDROID_HEARTBEAT_INTERVAL=60` で間隔変更 - -### 基本設定 - -1. **設定ファイルの作成:** - - ```bash - cp config.example.json config/config.json - ``` - -2. **設定の編集:** - - ```json - { - "providers": { - "openrouter": { - "api_key": "sk-or-v1-..." - } - }, - "channels": { - "discord": { - "enabled": true, - "token": "YOUR_DISCORD_BOT_TOKEN" - } - } - } - ``` - -3. **実行** - - ```bash - clawdroid agent -m "Hello" - ``` - - -
-完全な設定例 - -```json -{ - "agents": { - "defaults": { - "model": "anthropic/claude-opus-4-5" - } - }, - "providers": { - "openrouter": { - "apiKey": "sk-or-v1-xxx" - }, - "groq": { - "apiKey": "gsk_xxx" - } - }, - "channels": { - "telegram": { - "enabled": true, - "token": "123456:ABC...", - "allowFrom": ["123456789"] - }, - "discord": { - "enabled": true, - "token": "", - "allow_from": [""] - }, - "whatsapp": { - "enabled": false - }, - "feishu": { - "enabled": false, - "appId": "cli_xxx", - "appSecret": "xxx", - "encryptKey": "", - "verificationToken": "", - "allowFrom": [] - } - }, - "tools": { - "web": { - "search": { - "apiKey": "BSA..." - } - } - }, - "heartbeat": { - "enabled": true, - "interval": 30 - } -} -``` - -
- -## CLI リファレンス +## CLI コマンド | コマンド | 説明 | |---------|------| -| `clawdroid onboard` | 設定＆ワークスペースの初期化 | -| `clawdroid agent -m "..."` | エージェントとチャット | -| `clawdroid agent` | インタラクティブチャットモード | -| `clawdroid gateway` | ゲートウェイを起動 | -| `clawdroid status` | ステータスを表示 | +| `clawdroid gateway` | フルサーバー起動（チャンネル、Cron、ハートビート、HTTP ゲートウェイ） | +| `clawdroid agent` | 対話型 REPL モード | +| `clawdroid agent -m "..."` | 単発メッセージ送信 | +| `clawdroid onboard` | 初回セットアップウィザード | +| `clawdroid status` | 設定と接続状態の表示 | +| `clawdroid cron list\|add\|remove\|enable\|disable` | スケジュールタスクの管理 | +| `clawdroid skills list\|show\|remove` | スキルの管理 | +| `clawdroid version` | バージョン情報の表示 | -## 🤝 コントリビュート＆ロードマップ +`gateway` または `agent` に `--debug` / `-d` を付けると詳細ログが有効になります。 -PR 歓迎！コードベースは意図的に小さく読みやすくしています。🤗 +## 設定 -Discord: https://discord.gg/V4sAZ9XWpN +設定ファイル: `~/.clawdroid/config.json` -ClawDroid +すべての設定は `CLAWDROID_` プレフィックスの環境変数で上書きできます（例: `CLAWDROID_LLM_API_KEY`）。環境変数名は JSON パスを大文字・`_` 区切りにしたものです。 +### LLM (`llm`) -## 🐛 トラブルシューティング +| キー | デフォルト | 環境変数 | 説明 | +|-----|----------|---------|------| +| `model` | `zhipu/glm-4.7` | `CLAWDROID_LLM_MODEL` | `プロバイダー/モデル名` 形式で指定 | +| `api_key` | *(空)* | `CLAWDROID_LLM_API_KEY` | LLM プロバイダーの API キー | +| `base_url` | *(空)* | `CLAWDROID_LLM_BASE_URL` | カスタム API エンドポイント（OpenAI 互換） | -### Web 検索で「API 配置问题」と表示される +### エージェント (`agents.defaults`) -検索 API キーをまだ設定していない場合、これは正常です。ClawDroid は手動検索用の便利なリンクを提供します。 +| キー | デフォルト | 環境変数 | 説明 | +|-----|----------|---------|------| +| `workspace` | `~/.clawdroid/workspace` | `CLAWDROID_AGENTS_DEFAULTS_WORKSPACE` | ワークスペースのパス | +| `data_dir` | `~/.clawdroid/data` | `CLAWDROID_AGENTS_DEFAULTS_DATA_DIR` | データディレクトリ（メモリ、スキル、cron 等） | +| `restrict_to_workspace` | `true` | `CLAWDROID_AGENTS_DEFAULTS_RESTRICT_TO_WORKSPACE` | ファイル操作をワークスペース内に制限 | +| `max_tokens` | `8192` | `CLAWDROID_AGENTS_DEFAULTS_MAX_TOKENS` | LLM 呼び出しあたりの最大出力トークン数 | +| `context_window` | `128000` | `CLAWDROID_AGENTS_DEFAULTS_CONTEXT_WINDOW` | コンテキストウィンドウサイズ（トークン） | +| `temperature` | `0` | `CLAWDROID_AGENTS_DEFAULTS_TEMPERATURE` | LLM のサンプリング温度 | +| `max_tool_iterations` | `20` | `CLAWDROID_AGENTS_DEFAULTS_MAX_TOOL_ITERATIONS` | 1リクエストあたりのツール呼び出し最大ループ数 | -Web 検索を有効にするには： -1. [https://brave.com/search/api](https://brave.com/search/api) で無料の API キーを取得（月 2000 クエリ無料） -2. `~/.clawdroid/config.json` に追加： - ```json - { - "tools": { - "web": { - "search": { - "api_key": "YOUR_BRAVE_API_KEY", - "max_results": 5 - } - } - } - } - ``` +### ゲートウェイ (`gateway`) -### コンテンツフィルタリングエラーが出る +| キー | デフォルト | 環境変数 | 説明 | +|-----|----------|---------|------| +| `host` | `127.0.0.1` | `CLAWDROID_GATEWAY_HOST` | HTTP ゲートウェイのバインドアドレス | +| `port` | `18790` | `CLAWDROID_GATEWAY_PORT` | HTTP ゲートウェイのポート | -一部のプロバイダー（Zhipu など）にはコンテンツフィルタリングがあります。クエリを言い換えるか、別のモデルを使用してください。 +### チャンネル (`channels`) -### Telegram Bot で「Conflict: terminated by other getUpdates」と表示される +#### WebSocket (`channels.websocket`) -別のインスタンスが実行中の場合に発生します。`clawdroid gateway` が 1 つだけ実行されていることを確認してください。 +| キー | デフォルト | 環境変数 | 説明 | +|-----|----------|---------|------| +| `enabled` | `true` | `CLAWDROID_CHANNELS_WEBSOCKET_ENABLED` | WebSocket チャンネルを有効化（Android アプリ接続用） | +| `host` | `127.0.0.1` | `CLAWDROID_CHANNELS_WEBSOCKET_HOST` | バインドアドレス | +| `port` | `18793` | `CLAWDROID_CHANNELS_WEBSOCKET_PORT` | ポート | +| `path` | `/ws` | `CLAWDROID_CHANNELS_WEBSOCKET_PATH` | WebSocket パス | +| `allow_from` | `[]` | `CLAWDROID_CHANNELS_WEBSOCKET_ALLOW_FROM` | 許可するユーザー ID（空 = 全員許可） | ---- +#### Telegram (`channels.telegram`) -## 📝 API キー比較 +| キー | デフォルト | 環境変数 | 説明 | +|-----|----------|---------|------| +| `enabled` | `false` | `CLAWDROID_CHANNELS_TELEGRAM_ENABLED` | Telegram ボットを有効化 | +| `token` | *(空)* | `CLAWDROID_CHANNELS_TELEGRAM_TOKEN` | BotFather から取得したボットトークン | +| `proxy` | *(空)* | `CLAWDROID_CHANNELS_TELEGRAM_PROXY` | SOCKS5/HTTP プロキシ URL | +| `allow_from` | `[]` | `CLAWDROID_CHANNELS_TELEGRAM_ALLOW_FROM` | 許可するユーザー/チャット ID | -| サービス | 無料枠 | ユースケース | -|---------|--------|------------| -| **OpenRouter** | 月 200K トークン | 複数モデル（Claude, GPT-4 など） | -| **Zhipu** | 月 200K トークン | 中国ユーザー向け最適 | -| **Brave Search** | 月 2000 クエリ | Web 検索機能 | -| **Groq** | 無料枠あり | 高速推論（Llama, Mixtral） | +#### Discord (`channels.discord`) + +| キー | デフォルト | 環境変数 | 説明 | +|-----|----------|---------|------| +| `enabled` | `false` | `CLAWDROID_CHANNELS_DISCORD_ENABLED` | Discord ボットを有効化 | +| `token` | *(空)* | `CLAWDROID_CHANNELS_DISCORD_TOKEN` | ボットトークン | +| `allow_from` | `[]` | `CLAWDROID_CHANNELS_DISCORD_ALLOW_FROM` | 許可するユーザー ID | + +#### Slack (`channels.slack`) + +| キー | デフォルト | 環境変数 | 説明 | +|-----|----------|---------|------| +| `enabled` | `false` | `CLAWDROID_CHANNELS_SLACK_ENABLED` | Slack ボットを有効化 | +| `bot_token` | *(空)* | `CLAWDROID_CHANNELS_SLACK_BOT_TOKEN` | ボットトークン（`xoxb-...`） | +| `app_token` | *(空)* | `CLAWDROID_CHANNELS_SLACK_APP_TOKEN` | Socket Mode 用アプリレベルトークン（`xapp-...`） | +| `allow_from` | `[]` | `CLAWDROID_CHANNELS_SLACK_ALLOW_FROM` | 許可するユーザー ID | + +#### WhatsApp (`channels.whatsapp`) + +| キー | デフォルト | 環境変数 | 説明 | +|-----|----------|---------|------| +| `enabled` | `false` | `CLAWDROID_CHANNELS_WHATSAPP_ENABLED` | WhatsApp ブリッジを有効化 | +| `bridge_url` | `ws://localhost:3001` | `CLAWDROID_CHANNELS_WHATSAPP_BRIDGE_URL` | ブリッジの WebSocket URL | +| `allow_from` | `[]` | `CLAWDROID_CHANNELS_WHATSAPP_ALLOW_FROM` | 許可する電話番号/ID | + +#### LINE (`channels.line`) + +| キー | デフォルト | 環境変数 | 説明 | +|-----|----------|---------|------| +| `enabled` | `false` | `CLAWDROID_CHANNELS_LINE_ENABLED` | LINE ボットを有効化 | +| `channel_secret` | *(空)* | `CLAWDROID_CHANNELS_LINE_CHANNEL_SECRET` | チャンネルシークレット | +| `channel_access_token` | *(空)* | `CLAWDROID_CHANNELS_LINE_CHANNEL_ACCESS_TOKEN` | チャンネルアクセストークン | +| `webhook_host` | `127.0.0.1` | `CLAWDROID_CHANNELS_LINE_WEBHOOK_HOST` | Webhook サーバーのバインドアドレス | +| `webhook_port` | `18791` | `CLAWDROID_CHANNELS_LINE_WEBHOOK_PORT` | Webhook サーバーのポート | +| `webhook_path` | `/webhook/line` | `CLAWDROID_CHANNELS_LINE_WEBHOOK_PATH` | Webhook パス | +| `allow_from` | `[]` | `CLAWDROID_CHANNELS_LINE_ALLOW_FROM` | 許可するユーザー ID | + +### ツール (`tools`) + +| キー | デフォルト | 環境変数 | 説明 | +|-----|----------|---------|------| +| `exec.enabled` | `false` | `CLAWDROID_TOOLS_EXEC_ENABLED` | シェルコマンド実行（安全のためデフォルト無効） | +| `android.enabled` | `true` | `CLAWDROID_TOOLS_ANDROID_ENABLED` | Android デバイス自動操作 | +| `memory.enabled` | `true` | `CLAWDROID_TOOLS_MEMORY_ENABLED` | 長期メモリとデイリーノート | + +#### Web 検索 (`tools.web`) + +| キー | デフォルト | 環境変数 | 説明 | +|-----|----------|---------|------| +| `brave.enabled` | `false` | `CLAWDROID_TOOLS_WEB_BRAVE_ENABLED` | Brave Search API を有効化 | +| `brave.api_key` | *(空)* | `CLAWDROID_TOOLS_WEB_BRAVE_API_KEY` | Brave API キー | +| `brave.max_results` | `5` | `CLAWDROID_TOOLS_WEB_BRAVE_MAX_RESULTS` | 検索結果の最大件数 | +| `duckduckgo.enabled` | `true` | `CLAWDROID_TOOLS_WEB_DUCKDUCKGO_ENABLED` | DuckDuckGo 検索を有効化（API キー不要） | +| `duckduckgo.max_results` | `5` | `CLAWDROID_TOOLS_WEB_DUCKDUCKGO_MAX_RESULTS` | 検索結果の最大件数 | + +#### MCP サーバー (`tools.mcp`) + +サーバー名をキーとしたエントリで定義。Stdio と HTTP の 2 種類のトランスポートに対応。 + +**Stdio トランスポート:** + +| キー | 説明 | +|-----|------| +| `command` | サーバーの起動コマンド | +| `args` | コマンド引数 | +| `env` | プロセスの環境変数 | + +**HTTP トランスポート:** + +| キー | 説明 | +|-----|------| +| `url` | サーバー URL | +| `headers` | HTTP ヘッダー（例: Authorization） | + +**共通:** + +| キー | デフォルト | 説明 | +|-----|----------|------| +| `description` | *(空)* | 人間が読める説明 | +| `enabled` | `false` | このサーバーを有効化 | +| `idle_timeout` | `300` | アイドル時に停止するまでの秒数 | + +### ハートビート (`heartbeat`) + +| キー | デフォルト | 環境変数 | 説明 | +|-----|----------|---------|------| +| `enabled` | `true` | `CLAWDROID_HEARTBEAT_ENABLED` | 定期ハートビートを有効化 | +| `interval` | `30` | `CLAWDROID_HEARTBEAT_INTERVAL` | 間隔（分、最小 5） | + +### レート制限 (`rate_limits`) + +| キー | デフォルト | 環境変数 | 説明 | +|-----|----------|---------|------| +| `max_tool_calls_per_minute` | `60` | `CLAWDROID_RATE_LIMITS_MAX_TOOL_CALLS_PER_MINUTE` | 1分あたりのツール呼び出し上限（0 = 無制限） | +| `max_requests_per_minute` | `30` | `CLAWDROID_RATE_LIMITS_MAX_REQUESTS_PER_MINUTE` | 1分あたりの LLM リクエスト上限（0 = 無制限） | + +## 対応 LLM プロバイダー + +[any-llm-go](https://github.com/mozilla-ai/any-llm-go) を統一アダプターとして使用。 + +| プロバイダー | モデル指定形式 | 例 | +|------------|-------------|---| +| OpenAI | `openai/model` | `openai/gpt-4o` | +| Anthropic | `anthropic/model` または `claude/model` | `anthropic/claude-3-5-sonnet` | +| Google Gemini | `gemini/model` または `google/model` | `gemini/gemini-2.0-flash` | +| DeepSeek | `deepseek/model` | `deepseek/deepseek-chat` | +| Groq | `groq/model` | `groq/llama-3.3-70b` | +| Mistral | `mistral/model` | `mistral/mistral-large-latest` | +| Ollama | `ollama/model` | `ollama/llama3` | +| LlamaCpp | `llamacpp/model` | `llamacpp/local` | +| Llamafile | `llamafile/model` | `llamafile/local` | +| ZhiPu | `zhipu/model` | `zhipu/glm-4.7` | + +`base_url` で任意の OpenAI 互換エンドポイント（OpenRouter、ローカルプロキシ等）を指定できます。 + +## ツール + +ClawDroid は 16 以上の組み込みツールを提供し、AI エージェントが自律的に使用します。 + +### ファイル操作 + +| ツール | 説明 | +|-------|------| +| `read_file` | ファイル内容の読み取り | +| `write_file` | ファイルへの書き込み | +| `edit_file` | 検索置換による編集 | +| `append_file` | ファイルへの追記 | +| `copy_file` | ファイルのコピー | +| `list_dir` | ディレクトリ内容の一覧 | + +`restrict_to_workspace` 有効時はワークスペース内のみに制限されます。 + +### Android デバイス自動操作 + +| アクション | 説明 | +|-----------|------| +| `screenshot` | 画面キャプチャ（JPEG） | +| `get_ui_tree` | アクセシビリティツリーの取得 | +| `tap` | 座標をタップ | +| `swipe` | スワイプ操作 | +| `text` | テキスト入力 | +| `keyevent` | キーイベント送信（戻る、ホーム等） | +| `search_apps` | インストール済みアプリの検索 | +| `launch_app` | パッケージ名でアプリを起動 | +| `app_info` | アプリ情報の取得 | +| `broadcast` | Android ブロードキャストの送信 | +| `intent` | Android インテントの送信 | + +UI 自動操作（`screenshot`、`tap`、`swipe` 等）はアシスタントオーバーレイからのみ利用可能です。メインのチャット UI からは使用できません。 + +### Web + +| ツール | 説明 | +|-------|------| +| `web_search` | Web 検索（Brave API または DuckDuckGo） | +| `web_fetch` | URL からテキストを取得・抽出 | + +### エージェント・タスク管理 + +| ツール | 説明 | +|-------|------| +| `subagent` | 同期的なサブタスク委譲 | +| `spawn` | 非同期的なサブタスク委譲 | +| `cron` | タスクのスケジュール（単発、繰り返し、cron 式） | +| `memory` | 長期メモリとデイリーノート | +| `message` | クロスチャンネルメッセージング | +| `skill` | スキルの一覧表示・読み込み | +| `exec` | シェルコマンド実行（デフォルト無効） | +| `exit` | アシスタント/音声セッションの終了 | + +### MCP（Model Context Protocol） + +外部 MCP サーバーをツールプロバイダーとして接続できます。 + +```json +{ + "tools": { + "mcp": { + "my-local-server": { + "command": "npx", + "args": ["-y", "@example/mcp-server"], + "description": "ローカル MCP サーバー", + "enabled": true + }, + "my-remote-server": { + "url": "https://mcp.example.com/mcp", + "headers": { "Authorization": "Bearer token" }, + "description": "リモート MCP サーバー", + "enabled": true, + "idle_timeout": 300 + } + } + } +} +``` + +**stdio**（ローカルプロセス）と **HTTP/Streamable**（リモート）の両方のトランスポートに対応。アイドル状態のサーバーは 5 分後に自動停止します（`idle_timeout` で変更可能）。 + +## Android アプリ + +### 機能 + +- **チャット UI** - Jetpack Compose で構築されたフルチャットインターフェース +- **フローティングアシスタントオーバーレイ** - 常時アクセス可能なピルバー型オーバーレイ（`SYSTEM_ALERT_WINDOW`） +- **音声モード** - 継続的な音声会話ループ（聞く → 送信 → 思考 → 話す） +- **Google アシスタントの代替** - `android.intent.action.ASSIST` として登録。ホームボタン長押しで起動 +- **デバイス自動操作** - AccessibilityService ベースのタップ、スワイプ、テキスト入力、スクリーンショット +- **カメラ撮影** - 音声モード中に写真を撮影し視覚的コンテキストとして利用 +- **メッセージ永続化** - Room データベースによるチャット履歴の保存 + +### パーミッション + +| パーミッション | 用途 | +|-------------|------| +| `INTERNET` | LLM API 呼び出し、Web ツール | +| `SYSTEM_ALERT_WINDOW` | フローティングアシスタントオーバーレイ | +| `RECORD_AUDIO` | 音声モード（音声認識） | +| `CAMERA` | 写真撮影 | +| `QUERY_ALL_PACKAGES` | アプリ検索・起動 | +| `POST_NOTIFICATIONS` | フォアグラウンドサービスの通知 | + +### 音声モード + +音声モードは継続的な会話ループで動作します: + +1. **聞き取り** - Android SpeechRecognizer が音声をキャプチャ +2. **送信** - 文字起こしされたテキストを Go バックエンドに送信 +3. **思考** - エージェントが処理しツールを呼び出す +4. **読み上げ** - TextToSpeech でレスポンスを読み上げ + +レスポンスは短く（1〜3 文）、自然な話し言葉で返されます。30 秒間無音が続くと自動的にタイムアウトします。 + +## メッセージングチャンネル + +複数のメッセージングプラットフォームから同時にアクセスできます。 + +| チャンネル | トランスポート | 設定 | +|-----------|-------------|------| +| WebSocket | ローカル WebSocket | デフォルト有効、`127.0.0.1:18793` | +| Telegram | Bot API | Bot トークンが必要 | +| Discord | Bot API | Bot トークンが必要 | +| Slack | Socket Mode | Bot トークン + App トークンが必要 | +| WhatsApp | Bridge WebSocket | ブリッジ URL が必要 | +| LINE | Webhook | チャンネルシークレット + アクセストークンが必要 | + +各チャンネルは `allow_from` でアクセスを許可するユーザーを制限できます。 + +## メモリシステム + +- **長期メモリ** (`memory/MEMORY.md`) - 永続的なナレッジベース。エージェントが重要な情報を保存します。 +- **デイリーノート** (`memory/YYYYMM/YYYYMMDD.md`) - 日ごとのジャーナル。直近 3 日分がシステムプロンプトに含まれます。 + +## ハートビート + +有効時、ワークスペースの `HEARTBEAT.md` に基づいてエージェントが定期的にチェックインします。デフォルト間隔: 30 分。リマインダーやバックグラウンドタスクなどのプロアクティブなアクションをトリガーできます。 + +## スキル + +スキルは `SKILL.md` ファイルとして定義され、3 つのディレクトリから読み込まれます: + +1. ワークスペーススキル (`~/.clawdroid/data/skills/`) +2. グローバルスキル (`~/.clawdroid/skills/`) +3. ビルトインスキル + +```bash +clawdroid skills list # インストール済みスキルの一覧 +clawdroid skills show # スキルの詳細表示 +clawdroid skills remove # スキルの削除 +``` + +## ワークスペースファイル + +ワークスペース (`~/.clawdroid/data/`) にはエージェントの振る舞いを定義するテンプレートファイルが含まれます: + +| ファイル | 用途 | +|--------|------| +| `IDENTITY.md` | ボット名、バージョン、機能 | +| `SOUL.md` | 性格と価値観 | +| `AGENT.md` | 運用ガイドライン | +| `USER.md` | ユーザーの好みとコンテキスト | +| `HEARTBEAT.md` | ハートビートチェックのテンプレート | + +## ソースからビルド + +### Go バックエンド + +Go バックエンドは Termux 上で直接修正・ビルドできます。PC 等の別の開発環境がなくても、Android デバイス上でコードを変更して拡張することが可能です。 + +```bash +# Termux に Go をインストール +pkg install golang make git + +# クローンしてビルド +git clone https://github.com/KarakuriAgent/clawdroid.git +cd clawdroid +make build && make install +``` + +| Make ターゲット | 説明 | +|---------------|------| +| `make build` | 現在のプラットフォーム向けにビルド | +| `make build-all` | linux/amd64, arm64, arm 向けにビルド | +| `make install` | `~/.local/bin` にインストール | +| `make test` | テスト実行 | +| `make check` | deps + fmt + vet + test | +| `make clean` | ビルド成果物を削除 | +| `make uninstall` | バイナリを削除 | +| `make uninstall-all` | バイナリ + 全データ (`~/.clawdroid/`) を削除 | + +静的バイナリ（CGO_ENABLED=0）。ビルドターゲット: `linux/amd64`、`linux/arm64`、`linux/arm`。 + +### Android アプリ + +Android Studio で `android/` を開くか、Gradle でビルド: + +```bash +cd android +./gradlew assembleDebug +``` + +パッケージ名: `io.clawdroid` + +## プロジェクト構成 + +``` +clawdroid/ +├── cmd/clawdroid/ # Go CLI エントリーポイント +├── pkg/ +│ ├── agent/ # エージェントループ、コンテキストビルダー、メモリ、セッション、音声プロンプト +│ ├── bus/ # メッセージバス（受信/送信チャンネル） +│ ├── channels/ # メッセージングチャンネルアダプター +│ ├── config/ # 設定の読み込みと構造体 +│ ├── cron/ # スケジュールタスクサービス +│ ├── gateway/ # HTTP ゲートウェイサーバー +│ ├── heartbeat/ # 定期ハートビートサービス +│ ├── logger/ # 構造化ロギング +│ ├── mcp/ # MCP クライアントマネージャー +│ ├── providers/ # LLM プロバイダーアダプター (any-llm-go) +│ ├── skills/ # スキルローダー (SKILL.md) +│ ├── state/ # 状態の永続化 +│ └── tools/ # 全ツール実装 +├── android/ +│ ├── app/ # メインアプリ (AssistantService, AccessibilityService, DeviceController) +│ ├── core/ # 共有コア (data, domain, model, ui) +│ └── feature/ # 機能モジュール (chat, settings) +├── workspace/ # テンプレートファイル (IDENTITY.md, SOUL.md 等) +├── config/ # config.example.json +├── Makefile +├── go.mod +└── .goreleaser.yaml +``` + +## ライセンス + +MIT License。Copyright (c) 2026 PicoClaw contributors。 + +[PicoClaw](https://github.com/pico-claw/picoclaw) からフォーク。 diff --git a/README.md b/README.md index 897cc8f79..f686ab8ed 100644 --- a/README.md +++ b/README.md @@ -1,858 +1,524 @@ -
- ClawDroid +# ClawDroid -

ClawDroid: Ultra-Efficient AI Assistant in Go

+Ultra-lightweight personal AI assistant for Android. A Go backend runs in Termux while a native Kotlin/Jetpack Compose app provides the chat UI, voice assistant, and device automation. -

$10 Hardware · 10MB RAM · 1s Boot · 皮皮虾，我们走！

+Forked from [PicoClaw](https://github.com/pico-claw/picoclaw). -

- Go - Hardware - License -
- Website - Twitter -

+## Architecture - [中文](README.zh.md) | [日本語](README.ja.md) | **English** -
- ---- - -🦐 ClawDroid is an ultra-lightweight personal AI Assistant inspired by [nanobot](https://github.com/HKUDS/nanobot), refactored from the ground up in Go through a self-bootstrapping process, where the AI agent itself drove the entire architectural migration and code optimization. - -⚡️ Runs on $10 hardware with <10MB RAM: That's 99% less memory than OpenClaw and 98% cheaper than a Mac mini! - - - - - - -
-

- -

- 		-

- -

-
- -> [!CAUTION] -> **🚨 SECURITY & OFFICIAL CHANNELS / 安全声明** -> -> * **NO CRYPTO:** ClawDroid has **NO** official token/coin. All claims on `pump.fun` or other trading platforms are **SCAMS**. -> * **OFFICIAL DOMAIN:** The **ONLY** official website is **[clawdroid.io](https://clawdroid.io)**, and company website is **[sipeed.com](https://sipeed.com)** -> * **Warning:** Many `.ai/.org/.com/.net/...` domains are registered by third parties. -> * **Warning:** clawdroid is in early development now and may have unresolved network security issues. Do not deploy to production environments before the v1.0 release. -> * **Note:** clawdroid has recently merged a lot of PRs, which may result in a larger memory footprint (10–20MB) in the latest versions. We plan to prioritize resource optimization as soon as the current feature set reaches a stable state. - - -## 📢 News -2026-02-16 🎉 ClawDroid hit 12K stars in one week! Thank you all for your support! ClawDroid is growing faster than we ever imagined. Given the high volume of PRs, we urgently need community maintainers. Our volunteer roles and roadmap are officially posted [here](doc/clawdroid_community_roadmap_260216.md) —we can’t wait to have you on board! - -2026-02-13 🎉 ClawDroid hit 5000 stars in 4days! Thank you for the community! There are so many PRs&issues come in (during Chinese New Year holidays), we are finalizing the Project Roadmap and setting up the Developer Group to accelerate ClawDroid's development. -🚀 Call to Action: Please submit your feature requests in GitHub Discussions. We will review and prioritize them during our upcoming weekly meeting. - -2026-02-09 🎉 ClawDroid Launched! Built in 1 day to bring AI Agents to $10 hardware with <10MB RAM. 🦐 ClawDroid，Let's Go！ - -## ✨ Features - -🪶 **Ultra-Lightweight**: <10MB Memory footprint — 99% smaller than Clawdbot - core functionality. - -💰 **Minimal Cost**: Efficient enough to run on $10 Hardware — 98% cheaper than a Mac mini. - -⚡️ **Lightning Fast**: 400X Faster startup time, boot in 1 second even in 0.6GHz single core. - -🌍 **True Portability**: Single self-contained binary across RISC-V, ARM, and x86, One-click to Go! - -🤖 **AI-Bootstrapped**: Autonomous Go-native implementation — 95% Agent-generated core with human-in-the-loop refinement. - -| | OpenClaw | NanoBot | **ClawDroid** | -| ----------------------------- | ------------- | ------------------------ | ----------------------------------------- | -| **Language** | TypeScript | Python | **Go** | -| **RAM** | >1GB | >100MB | **< 10MB** | -| **Startup**
(0.8GHz core) | >500s | >30s | **<1s** | -| **Cost** | Mac Mini 599$ | Most Linux SBC
~50$ | **Any Linux Board**
**As low as 10$** | - -ClawDroid - -## 🦾 Demonstration - -### 🛠️ Standard Assistant Workflows - - - - - - - - - - - - - - - - - -

🧩 Full-Stack Engineer

🗂️ Logging & Planning Management

🔎 Web Search & Learning

Develop • Deploy • ScaleSchedule • Automate • MemoryDiscovery • Insights • Trends
- -### 🐜 Innovative Low-Footprint Deploy - -ClawDroid can be deployed on almost any Linux device! - -- $9.9 [LicheeRV-Nano](https://www.aliexpress.com/item/1005006519668532.html) E(Ethernet) or W(WiFi6) version, for Minimal Home Assistant -- $30~50 [NanoKVM](https://www.aliexpress.com/item/1005007369816019.html), or $100 [NanoKVM-Pro](https://www.aliexpress.com/item/1005010048471263.html) for Automated Server Maintenance -- $50 [MaixCAM](https://www.aliexpress.com/item/1005008053333693.html) or $100 [MaixCAM2](https://www.kickstarter.com/projects/zepan/maixcam2-build-your-next-gen-4k-ai-camera) for Smart Monitoring - - - -🌟 More Deployment Cases Await！ - -## 📦 Install - -### Install with precompiled binary - -Download the firmware for your platform from the [release](https://github.com/KarakuriAgent/clawdroid/releases) page. - -### Install from source (latest features, recommended for development) - -```bash -git clone https://github.com/KarakuriAgent/clawdroid.git - -cd clawdroid -make deps - -# Build, no need to install -make build - -# Build for multiple platforms -make build-all - -# Build And Install -make install +``` +┌─────────────────────────────────┐ +│ Android App (Kotlin) │ +│ ┌───────────┐ ┌──────────────┐ │ +│ │ Chat UI │ │ Assistant │ │ +│ │ (Compose) │ │ Overlay │ │ +│ └─────┬─────┘ └──────┬──────┘ │ +│ │ WebSocket │ │ +│ └───────┬───────┘ │ +└────────────────┼────────────────┘ + │ ws://127.0.0.1:18793 +┌────────────────┼────────────────┐ +│ Go Backend (Termux) │ +│ ┌────────┐ ┌────────────────┐ │ +│ │ Agent │ │ Tool Loop │ │ +│ │ Loop │ │ (16+ tools) │ │ +│ └───┬────┘ └───────┬────────┘ │ +│ │ ┌─────────┤ │ +│ ┌───┴──┐ │ ┌───────┴────────┐ │ +│ │ LLM │ │ │ MCP / Cron / │ │ +│ └──────┘ │ │ Skills / Memory │ │ +│ ┌────────┴─┴────────────────┐ │ +│ │ Channels (Telegram, │ │ +│ │ Discord, Slack, LINE etc.)│ │ +│ └───────────────────────────┘ │ +└─────────────────────────────────┘ ``` -## 🐳 Docker Compose +- **Go backend** (`cmd/clawdroid/`): Single binary. Agent loop, tool execution, LLM calls, messaging channels, cron, heartbeat +- **Android app** (`android/`): Chat UI, floating assistant overlay, accessibility-based device control, voice mode -You can also run ClawDroid using Docker Compose without installing anything locally. +## Quick Start + +### Prerequisites + +- Android device with [Termux](https://termux.dev) installed +- LLM API key (OpenAI, Anthropic, Gemini, etc.) + +### 1. Download + +Download the latest Go backend binary and Android app APK from [GitHub Releases](https://github.com/KarakuriAgent/clawdroid/releases). + +Choose the binary matching your device architecture: + +| Architecture | Binary | +|-------------|--------| +| 64-bit ARM (most modern devices) | `clawdroid-linux-arm64` | +| 32-bit ARM | `clawdroid-linux-arm` | + +You can check your architecture in Termux with `uname -m`. + +### 2. Install the Go Backend + +In Termux: ```bash -# 1. Clone this repo -git clone https://github.com/KarakuriAgent/clawdroid.git -cd clawdroid - -# 2. Set your API keys -cp config/config.example.json config/config.json -vim config/config.json # Set DISCORD_BOT_TOKEN, API keys, etc. - -# 3. Build & Start -docker compose --profile gateway up -d - -# 4. Check logs -docker compose logs -f clawdroid-gateway - -# 5. Stop -docker compose --profile gateway down +# Place the binary and make it executable (example for arm64) +cp ~/storage/downloads/clawdroid-linux-arm64 ~/.local/bin/clawdroid +chmod +x ~/.local/bin/clawdroid ``` -### Agent Mode (One-shot) - -```bash -# Ask a question -docker compose run --rm clawdroid-agent -m "What is 2+2?" - -# Interactive mode -docker compose run --rm clawdroid-agent -``` - -### Rebuild - -```bash -docker compose --profile gateway build --no-cache -docker compose --profile gateway up -d -``` - -### 🚀 Quick Start - -> [!TIP] -> Set your API key in `~/.clawdroid/config.json`. -> Get API keys: [OpenRouter](https://openrouter.ai/keys) (LLM) · [Zhipu](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) (LLM) -> Web search is **optional** - get free [Brave Search API](https://brave.com/search/api) (2000 free queries/month) or use built-in auto fallback. - -**1. Initialize** +### 3. Initial Setup ```bash clawdroid onboard ``` -**2. Configure** (`~/.clawdroid/config.json`) +This creates `~/.clawdroid/config.json` and workspace templates. -```json -{ - "agents": { - "defaults": { - "workspace": "~/.clawdroid/workspace", - "model": "glm-4.7", - "max_tokens": 8192, - "temperature": 0.7, - "max_tool_iterations": 20 - } - }, - "providers": { - "openrouter": { - "api_key": "xxx", - "api_base": "https://openrouter.ai/api/v1" - } - }, - "tools": { - "web": { - "brave": { - "enabled": false, - "api_key": "YOUR_BRAVE_API_KEY", - "max_results": 5 - }, - "duckduckgo": { - "enabled": true, - "max_results": 5 - } - } - } -} -``` - -**3. Get API Keys** - -* **LLM Provider**: [OpenRouter](https://openrouter.ai/keys) · [Zhipu](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) · [Anthropic](https://console.anthropic.com) · [OpenAI](https://platform.openai.com) · [Gemini](https://aistudio.google.com/api-keys) -* **Web Search** (optional): [Brave Search](https://brave.com/search/api) - Free tier available (2000 requests/month) - -> **Note**: See `config.example.json` for a complete configuration template. - -**4. Chat** +Edit the config to add your API key: ```bash -clawdroid agent -m "What is 2+2?" +vi ~/.clawdroid/config.json ``` -That's it! You have a working AI assistant in 2 minutes. +### 4. Install the Android App ---- +Install the downloaded APK on the same device. -## 💬 Chat Apps - -Talk to your clawdroid through Telegram, Discord, DingTalk, or LINE - -| Channel | Setup | -| ------------ | ---------------------------------- | -| **Telegram** | Easy (just a token) | -| **Discord** | Easy (bot token + intents) | -| **QQ** | Easy (AppID + AppSecret) | -| **DingTalk** | Medium (app credentials) | -| **LINE** | Medium (credentials + webhook URL) | - -
-Telegram (Recommended) - -**1. Create a bot** - -* Open Telegram, search `@BotFather` -* Send `/newbot`, follow prompts -* Copy the token - -**2. Configure** - -```json -{ - "channels": { - "telegram": { - "enabled": true, - "token": "YOUR_BOT_TOKEN", - "allowFrom": ["YOUR_USER_ID"] - } - } -} -``` - -> Get your user ID from `@userinfobot` on Telegram. - -**3. Run** +### 5. Run ```bash +# Start the gateway server (connects to Android app + messaging channels) clawdroid gateway + +# Or interact directly from the terminal +clawdroid agent +clawdroid agent -m "Hello!" ``` -
+## CLI Commands -
-Discord - -**1. Create a bot** - -* Go to -* Create an application → Bot → Add Bot -* Copy the bot token - -**2. Enable intents** - -* In the Bot settings, enable **MESSAGE CONTENT INTENT** -* (Optional) Enable **SERVER MEMBERS INTENT** if you plan to use allow lists based on member data - -**3. Get your User ID** - -* Discord Settings → Advanced → enable **Developer Mode** -* Right-click your avatar → **Copy User ID** - -**4. Configure** - -```json -{ - "channels": { - "discord": { - "enabled": true, - "token": "YOUR_BOT_TOKEN", - "allowFrom": ["YOUR_USER_ID"] - } - } -} -``` - -**5. Invite the bot** - -* OAuth2 → URL Generator -* Scopes: `bot` -* Bot Permissions: `Send Messages`, `Read Message History` -* Open the generated invite URL and add the bot to your server - -**6. Run** - -```bash -clawdroid gateway -``` - -
- -
-QQ - -**1. Create a bot** - -- Go to [QQ Open Platform](https://q.qq.com/#) -- Create an application → Get **AppID** and **AppSecret** - -**2. Configure** - -```json -{ - "channels": { - "qq": { - "enabled": true, - "app_id": "YOUR_APP_ID", - "app_secret": "YOUR_APP_SECRET", - "allow_from": [] - } - } -} -``` - -> Set `allow_from` to empty to allow all users, or specify QQ numbers to restrict access. - -**3. Run** - -```bash -clawdroid gateway -``` - -
- -
-DingTalk - -**1. Create a bot** - -* Go to [Open Platform](https://open.dingtalk.com/) -* Create an internal app -* Copy Client ID and Client Secret - -**2. Configure** - -```json -{ - "channels": { - "dingtalk": { - "enabled": true, - "client_id": "YOUR_CLIENT_ID", - "client_secret": "YOUR_CLIENT_SECRET", - "allow_from": [] - } - } -} -``` - -> Set `allow_from` to empty to allow all users, or specify QQ numbers to restrict access. - -**3. Run** - -```bash -clawdroid gateway -``` - -
- -
-LINE - -**1. Create a LINE Official Account** - -- Go to [LINE Developers Console](https://developers.line.biz/) -- Create a provider → Create a Messaging API channel -- Copy **Channel Secret** and **Channel Access Token** - -**2. Configure** - -```json -{ - "channels": { - "line": { - "enabled": true, - "channel_secret": "YOUR_CHANNEL_SECRET", - "channel_access_token": "YOUR_CHANNEL_ACCESS_TOKEN", - "webhook_host": "0.0.0.0", - "webhook_port": 18791, - "webhook_path": "/webhook/line", - "allow_from": [] - } - } -} -``` - -**3. Set up Webhook URL** - -LINE requires HTTPS for webhooks. Use a reverse proxy or tunnel: - -```bash -# Example with ngrok -ngrok http 18791 -``` - -Then set the Webhook URL in LINE Developers Console to `https://your-domain/webhook/line` and enable **Use webhook**. - -**4. Run** - -```bash -clawdroid gateway -``` - -> In group chats, the bot responds only when @mentioned. Replies quote the original message. - -> **Docker Compose**: Add `ports: ["18791:18791"]` to the `clawdroid-gateway` service to expose the webhook port. - -
- -## ClawdChat Join the Agent Social Network - -Connect Clawdroid to the Agent Social Network simply by sending a single message via the CLI or any integrated Chat App. - -**Read `https://clawdchat.ai/skill.md` and follow the instructions to join [ClawdChat.ai](https://clawdchat.ai)** - -## ⚙️ Configuration - -Config file: `~/.clawdroid/config.json` - -### Workspace Layout - -ClawDroid stores data in your configured workspace (default: `~/.clawdroid/workspace`): - -``` -~/.clawdroid/workspace/ -├── sessions/ # Conversation sessions and history -├── memory/ # Long-term memory (MEMORY.md) -├── state/ # Persistent state (last channel, etc.) -├── cron/ # Scheduled jobs database -├── skills/ # Custom skills -├── AGENTS.md # Agent behavior guide -├── HEARTBEAT.md # Periodic task prompts (checked every 30 min) -├── IDENTITY.md # Agent identity -├── SOUL.md # Agent soul -├── TOOLS.md # Tool descriptions -└── USER.md # User preferences -``` - -### 🔒 Security Sandbox - -ClawDroid runs in a sandboxed environment by default. The agent can only access files and execute commands within the configured workspace. - -#### Default Configuration - -```json -{ - "agents": { - "defaults": { - "workspace": "~/.clawdroid/workspace", - "restrict_to_workspace": true - } - } -} -``` - -| Option | Default | Description | -|--------|---------|-------------| -| `workspace` | `~/.clawdroid/workspace` | Working directory for the agent | -| `restrict_to_workspace` | `true` | Restrict file/command access to workspace | - -#### Protected Tools - -When `restrict_to_workspace: true`, the following tools are sandboxed: - -| Tool | Function | Restriction | -|------|----------|-------------| -| `read_file` | Read files | Only files within workspace | -| `write_file` | Write files | Only files within workspace | -| `list_dir` | List directories | Only directories within workspace | -| `edit_file` | Edit files | Only files within workspace | -| `append_file` | Append to files | Only files within workspace | -| `exec` | Execute commands | Command paths must be within workspace | - -#### Additional Exec Protection - -Even with `restrict_to_workspace: false`, the `exec` tool blocks these dangerous commands: - -* `rm -rf`, `del /f`, `rmdir /s` — Bulk deletion -* `format`, `mkfs`, `diskpart` — Disk formatting -* `dd if=` — Disk imaging -* Writing to `/dev/sd[a-z]` — Direct disk writes -* `shutdown`, `reboot`, `poweroff` — System shutdown -* Fork bomb `:(){ :|:& };:` - -#### Error Examples - -``` -[ERROR] tool: Tool execution failed -{tool=exec, error=Command blocked by safety guard (path outside working dir)} -``` - -``` -[ERROR] tool: Tool execution failed -{tool=exec, error=Command blocked by safety guard (dangerous pattern detected)} -``` - -#### Disabling Restrictions (Security Risk) - -If you need the agent to access paths outside the workspace: - -**Method 1: Config file** - -```json -{ - "agents": { - "defaults": { - "restrict_to_workspace": false - } - } -} -``` - -**Method 2: Environment variable** - -```bash -export CLAWDROID_AGENTS_DEFAULTS_RESTRICT_TO_WORKSPACE=false -``` - -> ⚠️ **Warning**: Disabling this restriction allows the agent to access any path on your system. Use with caution in controlled environments only. - -#### Security Boundary Consistency - -The `restrict_to_workspace` setting applies consistently across all execution paths: - -| Execution Path | Security Boundary | -|----------------|-------------------| -| Main Agent | `restrict_to_workspace` ✅ | -| Subagent / Spawn | Inherits same restriction ✅ | -| Heartbeat tasks | Inherits same restriction ✅ | - -All paths share the same workspace restriction — there's no way to bypass the security boundary through subagents or scheduled tasks. - -### Heartbeat (Periodic Tasks) - -ClawDroid can perform periodic tasks automatically. Create a `HEARTBEAT.md` file in your workspace: - -```markdown -# Periodic Tasks - -- Check my email for important messages -- Review my calendar for upcoming events -- Check the weather forecast -``` - -The agent will read this file every 30 minutes (configurable) and execute any tasks using available tools. - -#### Async Tasks with Spawn - -For long-running tasks (web search, API calls), use the `spawn` tool to create a **subagent**: - -```markdown -# Periodic Tasks - -## Quick Tasks (respond directly) -- Report current time - -## Long Tasks (use spawn for async) -- Search the web for AI news and summarize -- Check email and report important messages -``` - -**Key behaviors:** - -| Feature | Description | +| Command | Description | |---------|-------------| -| **spawn** | Creates async subagent, doesn't block heartbeat | -| **Independent context** | Subagent has its own context, no session history | -| **message tool** | Subagent communicates with user directly via message tool | -| **Non-blocking** | After spawning, heartbeat continues to next task | +| `clawdroid gateway` | Start the full server (channels, cron, heartbeat, HTTP gateway) | +| `clawdroid agent` | Interactive REPL mode | +| `clawdroid agent -m "..."` | Send a single message | +| `clawdroid onboard` | First-time setup wizard | +| `clawdroid status` | Show config and connection status | +| `clawdroid cron list\|add\|remove\|enable\|disable` | Manage scheduled tasks | +| `clawdroid skills list\|show\|remove` | Manage skills | +| `clawdroid version` | Print version info | -#### How Subagent Communication Works +Use `--debug` / `-d` with `gateway` or `agent` for verbose logging. -``` -Heartbeat triggers - ↓ -Agent reads HEARTBEAT.md - ↓ -For long task: spawn subagent - ↓ ↓ -Continue to next task Subagent works independently - ↓ ↓ -All tasks done Subagent uses "message" tool - ↓ ↓ -Respond HEARTBEAT_OK User receives result directly -``` +## Configuration -The subagent has access to tools (message, web_search, etc.) and can communicate with the user independently without going through the main agent. +Configuration file: `~/.clawdroid/config.json` -**Configuration:** +All settings can be overridden by environment variables with the `CLAWDROID_` prefix (e.g. `CLAWDROID_LLM_API_KEY`). The env var name corresponds to the JSON path in uppercase with `_` separators. + +### LLM (`llm`) + +| Key | Default | Env | Description | +|-----|---------|-----|-------------| +| `model` | `zhipu/glm-4.7` | `CLAWDROID_LLM_MODEL` | LLM model in `provider/model` format | +| `api_key` | *(empty)* | `CLAWDROID_LLM_API_KEY` | API key for the LLM provider | +| `base_url` | *(empty)* | `CLAWDROID_LLM_BASE_URL` | Custom API endpoint (OpenAI-compatible) | + +### Agent Defaults (`agents.defaults`) + +| Key | Default | Env | Description | +|-----|---------|-----|-------------| +| `workspace` | `~/.clawdroid/workspace` | `CLAWDROID_AGENTS_DEFAULTS_WORKSPACE` | Workspace directory path | +| `data_dir` | `~/.clawdroid/data` | `CLAWDROID_AGENTS_DEFAULTS_DATA_DIR` | Data directory (memory, skills, cron, etc.) | +| `restrict_to_workspace` | `true` | `CLAWDROID_AGENTS_DEFAULTS_RESTRICT_TO_WORKSPACE` | Restrict file operations to workspace | +| `max_tokens` | `8192` | `CLAWDROID_AGENTS_DEFAULTS_MAX_TOKENS` | Max output tokens per LLM call | +| `context_window` | `128000` | `CLAWDROID_AGENTS_DEFAULTS_CONTEXT_WINDOW` | Context window size (tokens) | +| `temperature` | `0` | `CLAWDROID_AGENTS_DEFAULTS_TEMPERATURE` | LLM sampling temperature | +| `max_tool_iterations` | `20` | `CLAWDROID_AGENTS_DEFAULTS_MAX_TOOL_ITERATIONS` | Max tool call loops per request | + +### Gateway (`gateway`) + +| Key | Default | Env | Description | +|-----|---------|-----|-------------| +| `host` | `127.0.0.1` | `CLAWDROID_GATEWAY_HOST` | HTTP gateway bind address | +| `port` | `18790` | `CLAWDROID_GATEWAY_PORT` | HTTP gateway port | + +### Channels (`channels`) + +#### WebSocket (`channels.websocket`) + +| Key | Default | Env | Description | +|-----|---------|-----|-------------| +| `enabled` | `true` | `CLAWDROID_CHANNELS_WEBSOCKET_ENABLED` | Enable WebSocket channel (Android app connection) | +| `host` | `127.0.0.1` | `CLAWDROID_CHANNELS_WEBSOCKET_HOST` | Bind address | +| `port` | `18793` | `CLAWDROID_CHANNELS_WEBSOCKET_PORT` | Port | +| `path` | `/ws` | `CLAWDROID_CHANNELS_WEBSOCKET_PATH` | WebSocket path | +| `allow_from` | `[]` | `CLAWDROID_CHANNELS_WEBSOCKET_ALLOW_FROM` | Allowed user IDs (empty = all) | + +#### Telegram (`channels.telegram`) + +| Key | Default | Env | Description | +|-----|---------|-----|-------------| +| `enabled` | `false` | `CLAWDROID_CHANNELS_TELEGRAM_ENABLED` | Enable Telegram bot | +| `token` | *(empty)* | `CLAWDROID_CHANNELS_TELEGRAM_TOKEN` | Bot token from BotFather | +| `proxy` | *(empty)* | `CLAWDROID_CHANNELS_TELEGRAM_PROXY` | SOCKS5/HTTP proxy URL | +| `allow_from` | `[]` | `CLAWDROID_CHANNELS_TELEGRAM_ALLOW_FROM` | Allowed user/chat IDs | + +#### Discord (`channels.discord`) + +| Key | Default | Env | Description | +|-----|---------|-----|-------------| +| `enabled` | `false` | `CLAWDROID_CHANNELS_DISCORD_ENABLED` | Enable Discord bot | +| `token` | *(empty)* | `CLAWDROID_CHANNELS_DISCORD_TOKEN` | Bot token | +| `allow_from` | `[]` | `CLAWDROID_CHANNELS_DISCORD_ALLOW_FROM` | Allowed user IDs | + +#### Slack (`channels.slack`) + +| Key | Default | Env | Description | +|-----|---------|-----|-------------| +| `enabled` | `false` | `CLAWDROID_CHANNELS_SLACK_ENABLED` | Enable Slack bot | +| `bot_token` | *(empty)* | `CLAWDROID_CHANNELS_SLACK_BOT_TOKEN` | Bot token (`xoxb-...`) | +| `app_token` | *(empty)* | `CLAWDROID_CHANNELS_SLACK_APP_TOKEN` | App-level token (`xapp-...`) for Socket Mode | +| `allow_from` | `[]` | `CLAWDROID_CHANNELS_SLACK_ALLOW_FROM` | Allowed user IDs | + +#### WhatsApp (`channels.whatsapp`) + +| Key | Default | Env | Description | +|-----|---------|-----|-------------| +| `enabled` | `false` | `CLAWDROID_CHANNELS_WHATSAPP_ENABLED` | Enable WhatsApp bridge | +| `bridge_url` | `ws://localhost:3001` | `CLAWDROID_CHANNELS_WHATSAPP_BRIDGE_URL` | Bridge WebSocket URL | +| `allow_from` | `[]` | `CLAWDROID_CHANNELS_WHATSAPP_ALLOW_FROM` | Allowed phone numbers/IDs | + +#### LINE (`channels.line`) + +| Key | Default | Env | Description | +|-----|---------|-----|-------------| +| `enabled` | `false` | `CLAWDROID_CHANNELS_LINE_ENABLED` | Enable LINE bot | +| `channel_secret` | *(empty)* | `CLAWDROID_CHANNELS_LINE_CHANNEL_SECRET` | Channel secret | +| `channel_access_token` | *(empty)* | `CLAWDROID_CHANNELS_LINE_CHANNEL_ACCESS_TOKEN` | Channel access token | +| `webhook_host` | `127.0.0.1` | `CLAWDROID_CHANNELS_LINE_WEBHOOK_HOST` | Webhook server bind address | +| `webhook_port` | `18791` | `CLAWDROID_CHANNELS_LINE_WEBHOOK_PORT` | Webhook server port | +| `webhook_path` | `/webhook/line` | `CLAWDROID_CHANNELS_LINE_WEBHOOK_PATH` | Webhook path | +| `allow_from` | `[]` | `CLAWDROID_CHANNELS_LINE_ALLOW_FROM` | Allowed user IDs | + +### Tools (`tools`) + +| Key | Default | Env | Description | +|-----|---------|-----|-------------| +| `exec.enabled` | `false` | `CLAWDROID_TOOLS_EXEC_ENABLED` | Shell command execution (disabled for safety) | +| `android.enabled` | `true` | `CLAWDROID_TOOLS_ANDROID_ENABLED` | Android device automation | +| `memory.enabled` | `true` | `CLAWDROID_TOOLS_MEMORY_ENABLED` | Long-term memory and daily notes | + +#### Web Search (`tools.web`) + +| Key | Default | Env | Description | +|-----|---------|-----|-------------| +| `brave.enabled` | `false` | `CLAWDROID_TOOLS_WEB_BRAVE_ENABLED` | Enable Brave Search API | +| `brave.api_key` | *(empty)* | `CLAWDROID_TOOLS_WEB_BRAVE_API_KEY` | Brave API key | +| `brave.max_results` | `5` | `CLAWDROID_TOOLS_WEB_BRAVE_MAX_RESULTS` | Max search results | +| `duckduckgo.enabled` | `true` | `CLAWDROID_TOOLS_WEB_DUCKDUCKGO_ENABLED` | Enable DuckDuckGo search (no API key needed) | +| `duckduckgo.max_results` | `5` | `CLAWDROID_TOOLS_WEB_DUCKDUCKGO_MAX_RESULTS` | Max search results | + +#### MCP Servers (`tools.mcp`) + +Each entry is keyed by server name. Stdio and HTTP transports are supported. + +**Stdio transport:** + +| Key | Description | +|-----|-------------| +| `command` | Command to launch the server | +| `args` | Command arguments | +| `env` | Environment variables for the process | + +**HTTP transport:** + +| Key | Description | +|-----|-------------| +| `url` | Server URL | +| `headers` | HTTP headers (e.g. Authorization) | + +**Common:** + +| Key | Default | Description | +|-----|---------|-------------| +| `description` | *(empty)* | Human-readable description | +| `enabled` | `false` | Enable this server | +| `idle_timeout` | `300` | Seconds before idle shutdown | + +### Heartbeat (`heartbeat`) + +| Key | Default | Env | Description | +|-----|---------|-----|-------------| +| `enabled` | `true` | `CLAWDROID_HEARTBEAT_ENABLED` | Enable periodic heartbeat | +| `interval` | `30` | `CLAWDROID_HEARTBEAT_INTERVAL` | Interval in minutes (min 5) | + +### Rate Limits (`rate_limits`) + +| Key | Default | Env | Description | +|-----|---------|-----|-------------| +| `max_tool_calls_per_minute` | `60` | `CLAWDROID_RATE_LIMITS_MAX_TOOL_CALLS_PER_MINUTE` | Max tool calls per minute (0 = unlimited) | +| `max_requests_per_minute` | `30` | `CLAWDROID_RATE_LIMITS_MAX_REQUESTS_PER_MINUTE` | Max LLM requests per minute (0 = unlimited) | + +## Supported LLM Providers + +Uses [any-llm-go](https://github.com/mozilla-ai/any-llm-go) as a unified adapter. + +| Provider | Model Format | Example | +|----------|-------------|---------| +| OpenAI | `openai/model` | `openai/gpt-4o` | +| Anthropic | `anthropic/model` or `claude/model` | `anthropic/claude-3-5-sonnet` | +| Google Gemini | `gemini/model` or `google/model` | `gemini/gemini-2.0-flash` | +| DeepSeek | `deepseek/model` | `deepseek/deepseek-chat` | +| Groq | `groq/model` | `groq/llama-3.3-70b` | +| Mistral | `mistral/model` | `mistral/mistral-large-latest` | +| Ollama | `ollama/model` | `ollama/llama3` | +| LlamaCpp | `llamacpp/model` | `llamacpp/local` | +| Llamafile | `llamafile/model` | `llamafile/local` | +| ZhiPu | `zhipu/model` | `zhipu/glm-4.7` | + +`base_url` can point to any OpenAI-compatible endpoint (OpenRouter, local proxies, etc.). + +## Tools + +ClawDroid provides 16+ built-in tools that the AI agent can use autonomously. + +### File Operations + +| Tool | Description | +|------|-------------| +| `read_file` | Read file contents | +| `write_file` | Write content to a file | +| `edit_file` | Search-and-replace editing | +| `append_file` | Append content to a file | +| `copy_file` | Copy files | +| `list_dir` | List directory contents | + +File operations respect `restrict_to_workspace` when enabled. + +### Android Device Automation + +| Action | Description | +|--------|-------------| +| `screenshot` | Capture screen as JPEG | +| `get_ui_tree` | Dump accessibility tree | +| `tap` | Tap at coordinates | +| `swipe` | Swipe gesture | +| `text` | Input text | +| `keyevent` | Send key event (back, home, etc.) | +| `search_apps` | Search installed apps | +| `launch_app` | Launch app by package name | +| `app_info` | Get app details | +| `broadcast` | Send Android broadcast | +| `intent` | Send Android intent | + +UI automation actions (`screenshot`, `tap`, `swipe`, etc.) are only available from the assistant overlay, not the main chat UI. + +### Web + +| Tool | Description | +|------|-------------| +| `web_search` | Search the web (Brave API or DuckDuckGo) | +| `web_fetch` | Fetch and extract text from a URL | + +### Agent & Task Management + +| Tool | Description | +|------|-------------| +| `subagent` | Synchronous sub-task delegation | +| `spawn` | Asynchronous sub-task delegation | +| `cron` | Schedule tasks (one-time, recurring, cron expressions) | +| `memory` | Long-term memory and daily notes | +| `message` | Cross-channel messaging | +| `skill` | List and read skills | +| `exec` | Shell command execution (disabled by default) | +| `exit` | End assistant/voice session | + +### MCP (Model Context Protocol) + +ClawDroid can connect to external MCP servers as tool providers. ```json { - "heartbeat": { - "enabled": true, - "interval": 30 - } -} -``` - -| Option | Default | Description | -|--------|---------|-------------| -| `enabled` | `true` | Enable/disable heartbeat | -| `interval` | `30` | Check interval in minutes (min: 5) | - -**Environment variables:** - -* `CLAWDROID_HEARTBEAT_ENABLED=false` to disable -* `CLAWDROID_HEARTBEAT_INTERVAL=60` to change interval - -### Providers - -> [!NOTE] -> Groq provides free voice transcription via Whisper. If configured, Telegram voice messages will be automatically transcribed. - -| Provider | Purpose | Get API Key | -| -------------------------- | --------------------------------------- | ------------------------------------------------------ | -| `gemini` | LLM (Gemini direct) | [aistudio.google.com](https://aistudio.google.com) | -| `zhipu` | LLM (Zhipu direct) | [bigmodel.cn](bigmodel.cn) | -| `openrouter(To be tested)` | LLM (recommended, access to all models) | [openrouter.ai](https://openrouter.ai) | -| `anthropic(To be tested)` | LLM (Claude direct) | [console.anthropic.com](https://console.anthropic.com) | -| `openai(To be tested)` | LLM (GPT direct) | [platform.openai.com](https://platform.openai.com) | -| `deepseek(To be tested)` | LLM (DeepSeek direct) | [platform.deepseek.com](https://platform.deepseek.com) | -| `groq` | LLM + **Voice transcription** (Whisper) | [console.groq.com](https://console.groq.com) | - -
-Zhipu - -**1. Get API key and base URL** - -* Get [API key](https://bigmodel.cn/usercenter/proj-mgmt/apikeys) - -**2. Configure** - -```json -{ - "agents": { - "defaults": { - "workspace": "~/.clawdroid/workspace", - "model": "glm-4.7", - "max_tokens": 8192, - "temperature": 0.7, - "max_tool_iterations": 20 - } - }, - "providers": { - "zhipu": { - "api_key": "Your API Key", - "api_base": "https://open.bigmodel.cn/api/paas/v4" + "tools": { + "mcp": { + "my-local-server": { + "command": "npx", + "args": ["-y", "@example/mcp-server"], + "description": "Local MCP server", + "enabled": true + }, + "my-remote-server": { + "url": "https://mcp.example.com/mcp", + "headers": { "Authorization": "Bearer token" }, + "description": "Remote MCP server", + "enabled": true, + "idle_timeout": 300 + } } } } ``` -**3. Run** +Supports both **stdio** (local process) and **HTTP/Streamable** (remote) transports. Idle servers are automatically stopped after 5 minutes (configurable). + +## Android App + +### Features + +- **Chat UI** - Full chat interface built with Jetpack Compose +- **Floating Assistant Overlay** - Always-accessible pill bar overlay (`SYSTEM_ALERT_WINDOW`) +- **Voice Mode** - Continuous voice conversation loop (listen -> send -> think -> speak) +- **Replace Google Assistant** - Registered as `android.intent.action.ASSIST`; long-press home to activate +- **Device Automation** - AccessibilityService-based tap, swipe, text input, screenshot capture +- **Camera Capture** - Take photos during voice mode for visual context +- **Message Persistence** - Local Room database for chat history + +### Permissions + +| Permission | Purpose | +|-----------|---------| +| `INTERNET` | LLM API calls, web tools | +| `SYSTEM_ALERT_WINDOW` | Floating assistant overlay | +| `RECORD_AUDIO` | Voice mode (STT) | +| `CAMERA` | Photo capture | +| `QUERY_ALL_PACKAGES` | App search and launch | +| `POST_NOTIFICATIONS` | Foreground service notification | + +### Voice Mode + +Voice mode runs a continuous conversation loop: + +1. **Listening** - Android SpeechRecognizer captures speech +2. **Sending** - Transcribed text sent to Go backend +3. **Thinking** - Agent processes and calls tools +4. **Speaking** - Response read aloud via TextToSpeech + +Responses are kept short (1-3 sentences) with natural spoken language. 30-second silence timeout. + +## Messaging Channels + +ClawDroid can be reached through multiple messaging platforms simultaneously. + +| Channel | Transport | Configuration | +|---------|-----------|---------------| +| WebSocket | Local WebSocket | Default on, `127.0.0.1:18793` | +| Telegram | Bot API | Bot token required | +| Discord | Bot API | Bot token required | +| Slack | Socket Mode | Bot token + App token required | +| WhatsApp | Bridge WebSocket | Bridge URL required | +| LINE | Webhook | Channel secret + access token required | + +Each channel supports `allow_from` access control to restrict which users can interact. + +## Memory System + +- **Long-term memory** (`memory/MEMORY.md`) - Persistent knowledge base. The agent stores important facts here. +- **Daily notes** (`memory/YYYYMM/YYYYMMDD.md`) - Daily journal entries. The last 3 days are included in the system prompt. + +## Heartbeat + +When enabled, the agent periodically checks in based on `HEARTBEAT.md` in the workspace. Default interval: 30 minutes. The heartbeat can trigger proactive actions like reminders or background tasks. + +## Skills + +Skills are defined as `SKILL.md` files and loaded from three directories: + +1. Workspace skills (`~/.clawdroid/data/skills/`) +2. Global skills (`~/.clawdroid/skills/`) +3. Built-in skills ```bash -clawdroid agent -m "Hello" +clawdroid skills list # List installed skills +clawdroid skills show # Show skill details +clawdroid skills remove # Remove a skill ``` -
+## Workspace Files -
-Full config example +The workspace (`~/.clawdroid/data/`) contains template files that shape the agent's behavior: -```json -{ - "agents": { - "defaults": { - "model": "anthropic/claude-opus-4-5" - } - }, - "providers": { - "openrouter": { - "api_key": "sk-or-v1-xxx" - }, - "groq": { - "api_key": "gsk_xxx" - } - }, - "channels": { - "telegram": { - "enabled": true, - "token": "123456:ABC...", - "allow_from": ["123456789"] - }, - "discord": { - "enabled": true, - "token": "", - "allow_from": [""] - }, - "whatsapp": { - "enabled": false - }, - "feishu": { - "enabled": false, - "app_id": "cli_xxx", - "app_secret": "xxx", - "encrypt_key": "", - "verification_token": "", - "allow_from": [] - }, - "qq": { - "enabled": false, - "app_id": "", - "app_secret": "", - "allow_from": [] - } - }, - "tools": { - "web": { - "brave": { - "enabled": false, - "api_key": "BSA...", - "max_results": 5 - }, - "duckduckgo": { - "enabled": true, - "max_results": 5 - } - } - }, - "heartbeat": { - "enabled": true, - "interval": 30 - } -} +| File | Purpose | +|------|---------| +| `IDENTITY.md` | Bot name, version, capabilities | +| `SOUL.md` | Personality and values | +| `AGENT.md` | Operational guidelines | +| `USER.md` | User preferences and context | +| `HEARTBEAT.md` | Heartbeat check template | + +## Build from Source + +### Go Backend + +The Go backend can be built and modified directly on Android within Termux. This means you can customize, extend, and rebuild on the device itself without a separate development machine. + +```bash +# Install Go in Termux +pkg install golang make git + +# Clone and build +git clone https://github.com/KarakuriAgent/clawdroid.git +cd clawdroid +make build && make install ``` -
+| Make Target | Description | +|-------------|-------------| +| `make build` | Build for current platform | +| `make build-all` | Build for linux/amd64, arm64, arm | +| `make install` | Install to `~/.local/bin` | +| `make test` | Run tests | +| `make check` | deps + fmt + vet + test | +| `make clean` | Remove build artifacts | +| `make uninstall` | Remove binary | +| `make uninstall-all` | Remove binary + all data (`~/.clawdroid/`) | -## CLI Reference +Static binaries (CGO_ENABLED=0). Build targets: `linux/amd64`, `linux/arm64`, `linux/arm`. -| Command | Description | -| ------------------------- | ----------------------------- | -| `clawdroid onboard` | Initialize config & workspace | -| `clawdroid agent -m "..."` | Chat with the agent | -| `clawdroid agent` | Interactive chat mode | -| `clawdroid gateway` | Start the gateway | -| `clawdroid status` | Show status | -| `clawdroid cron list` | List all scheduled jobs | -| `clawdroid cron add ...` | Add a scheduled job | +### Android App -### Scheduled Tasks / Reminders +Open `android/` in Android Studio or build with Gradle: -ClawDroid supports scheduled reminders and recurring tasks through the `cron` tool: - -* **One-time reminders**: "Remind me in 10 minutes" → triggers once after 10min -* **Recurring tasks**: "Remind me every 2 hours" → triggers every 2 hours -* **Cron expressions**: "Remind me at 9am daily" → uses cron expression - -Jobs are stored in `~/.clawdroid/workspace/cron/` and processed automatically. - -## 🤝 Contribute & Roadmap - -PRs welcome! The codebase is intentionally small and readable. 🤗 - -Roadmap coming soon... - -Developer group building, Entry Requirement: At least 1 Merged PR. - -User Groups: - -discord: - -ClawDroid - -## 🐛 Troubleshooting - -### Web search says "API 配置问题" - -This is normal if you haven't configured a search API key yet. ClawDroid will provide helpful links for manual searching. - -To enable web search: - -1. **Option 1 (Recommended)**: Get a free API key at [https://brave.com/search/api](https://brave.com/search/api) (2000 free queries/month) for the best results. -2. **Option 2 (No Credit Card)**: If you don't have a key, we automatically fall back to **DuckDuckGo** (no key required). - -Add the key to `~/.clawdroid/config.json` if using Brave: - -```json -{ - "tools": { - "web": { - "brave": { - "enabled": false, - "api_key": "YOUR_BRAVE_API_KEY", - "max_results": 5 - }, - "duckduckgo": { - "enabled": true, - "max_results": 5 - } - } - } -} +```bash +cd android +./gradlew assembleDebug ``` -### Getting content filtering errors +Package name: `io.clawdroid` -Some providers (like Zhipu) have content filtering. Try rephrasing your query or use a different model. +## Project Structure -### Telegram bot says "Conflict: terminated by other getUpdates" +``` +clawdroid/ +├── cmd/clawdroid/ # Go CLI entry point +├── pkg/ +│ ├── agent/ # Agent loop, context builder, memory, sessions, voice prompt +│ ├── bus/ # Message bus (inbound/outbound channels) +│ ├── channels/ # Messaging channel adapters +│ ├── config/ # Configuration loading and structs +│ ├── cron/ # Scheduled task service +│ ├── gateway/ # HTTP gateway server +│ ├── heartbeat/ # Periodic heartbeat service +│ ├── logger/ # Structured logging +│ ├── mcp/ # MCP client manager +│ ├── providers/ # LLM provider adapter (any-llm-go) +│ ├── skills/ # Skills loader (SKILL.md) +│ ├── state/ # State persistence +│ └── tools/ # All tool implementations +├── android/ +│ ├── app/ # Main app (AssistantService, AccessibilityService, DeviceController) +│ ├── core/ # Shared core (data, domain, model, ui) +│ └── feature/ # Feature modules (chat, settings) +├── workspace/ # Template files (IDENTITY.md, SOUL.md, etc.) +├── config/ # config.example.json +├── Makefile +├── go.mod +└── .goreleaser.yaml +``` -This happens when another instance of the bot is running. Make sure only one `clawdroid gateway` is running at a time. +## License ---- +MIT License. Copyright (c) 2026 PicoClaw contributors. -## 📝 API Key Comparison - -| Service | Free Tier | Use Case | -| ---------------- | ------------------- | ------------------------------------- | -| **OpenRouter** | 200K tokens/month | Multiple models (Claude, GPT-4, etc.) | -| **Zhipu** | 200K tokens/month | Best for Chinese users | -| **Brave Search** | 2000 queries/month | Web search functionality | -| **Groq** | Free tier available | Fast inference (Llama, Mixtral) | +Forked from [PicoClaw](https://github.com/pico-claw/picoclaw). diff --git a/README.zh.md b/README.zh.md deleted file mode 100644 index 62e27d417..000000000 --- a/README.zh.md +++ /dev/null @@ -1,721 +0,0 @@ -
-ClawDroid - -

ClawDroid: 基于Go语言的超高效 AI 助手

- -

10$硬件 · 10MB内存 · 1秒启动 · 皮皮虾，我们走！

- -

- Go - Hardware - License -
- Website - Twitter -

- - **中文** | [日本語](README.ja.md) | [English](README.md) -
- ---- - -🦐 **ClawDroid** 是一个受 [nanobot](https://github.com/HKUDS/nanobot) 启发的超轻量级个人 AI 助手。它采用 **Go 语言** 从零重构，经历了一个“自举”过程——即由 AI Agent 自身驱动了整个架构迁移和代码优化。 - -⚡️ **极致轻量**：可在 **10 美元** 的硬件上运行，内存占用 **<10MB**。这意味着比 OpenClaw 节省 99% 的内存，比 Mac mini 便宜 98%！ - - - - - - -
-

- -

-		 -

- -

-
- -注意：人手有限，中文文档可能略有滞后，请优先查看英文文档。 - -> [!CAUTION] -> **🚨 SECURITY & OFFICIAL CHANNELS / 安全声明** -> * **无加密货币 (NO CRYPTO):** ClawDroid **没有** 发行任何官方代币、Token 或虚拟货币。所有在 `pump.fun` 或其他交易平台上的相关声称均为 **诈骗**。 -> * **官方域名:** 唯一的官方网站是 **[clawdroid.io](https://clawdroid.io)**，公司官网是 **[sipeed.com](https://sipeed.com)**。 -> * **警惕:** 许多 `.ai/.org/.com/.net/...` 后缀的域名被第三方抢注，请勿轻信。 -> * **注意:** clawdroid正在初期的快速功能开发阶段，可能有尚未修复的网络安全问题，在1.0正式版发布前，请不要将其部署到生产环境中 -> * **注意:** clawdroid最近合并了大量PRs，近期版本可能内存占用较大(10~20MB)，我们将在功能较为收敛后进行资源占用优化. - - -## 📢 新闻 (News) -2026-02-16 🎉 ClawDroid 在一周内突破了12K star! 感谢大家的关注！ClawDroid 的成长速度超乎我们预期. 由于PR数量的快速膨胀，我们亟需社区开发者参与维护. 我们需要的志愿者角色和roadmap已经发布到了[这里](doc/clawdroid_community_roadmap_260216.md), 期待你的参与！ - -2026-02-13 🎉 **ClawDroid 在 4 天内突破 5000 Stars！** 感谢社区的支持！由于正值中国春节假期，PR 和 Issue 涌入较多，我们正在利用这段时间敲定 **项目路线图 (Roadmap)** 并组建 **开发者群组**，以便加速 ClawDroid 的开发。 -🚀 **行动号召：** 请在 GitHub Discussions 中提交您的功能请求 (Feature Requests)。我们将在接下来的周会上进行审查和优先级排序。 - -2026-02-09 🎉 **ClawDroid 正式发布！** 仅用 1 天构建，旨在将 AI Agent 带入 10 美元硬件与 <10MB 内存的世界。🦐 ClawDroid（皮皮虾），我们走！ - -## ✨ 特性 - -🪶 **超轻量级**: 核心功能内存占用 <10MB — 比 Clawdbot 小 99%。 - -💰 **极低成本**: 高效到足以在 10 美元的硬件上运行 — 比 Mac mini 便宜 98%。 - -⚡️ **闪电启动**: 启动速度快 400 倍，即使在 0.6GHz 单核处理器上也能在 1 秒内启动。 - -🌍 **真正可移植**: 跨 RISC-V、ARM 和 x86 架构的单二进制文件，一键运行！ - -🤖 **AI 自举**: 纯 Go 语言原生实现 — 95% 的核心代码由 Agent 生成，并经由“人机回环 (Human-in-the-loop)”微调。 - -| | OpenClaw | NanoBot | **ClawDroid** | -| --- | --- | --- | --- | -| **语言** | TypeScript | Python | **Go** | -| **RAM** | >1GB | >100MB | **< 10MB** | -| **启动时间**
(0.8GHz core) | >500s | >30s | **<1s** | -| **成本** | Mac Mini $599 | 大多数 Linux 开发板 ~$50 | **任意 Linux 开发板**
**低至 $10** | - -ClawDroid - -## 🦾 演示 - -### 🛠️ 标准助手工作流 - - - - - - - - - - - - - - - - - -

🧩 全栈工程师模式

🗂️ 日志与规划管理

🔎 网络搜索与学习

开发 • 部署 • 扩展日程 • 自动化 • 记忆发现 • 洞察 • 趋势
- -### 🐜 创新的低占用部署 - -ClawDroid 几乎可以部署在任何 Linux 设备上！ - -* $9.9 [LicheeRV-Nano](https://www.aliexpress.com/item/1005006519668532.html) E(网口) 或 W(WiFi6) 版本，用于极简家庭助手。 -* $30~50 [NanoKVM](https://www.aliexpress.com/item/1005007369816019.html)，或 $100 [NanoKVM-Pro](https://www.aliexpress.com/item/1005010048471263.html)，用于自动化服务器运维。 -* $50 [MaixCAM](https://www.aliexpress.com/item/1005008053333693.html) 或 $100 [MaixCAM2](https://www.kickstarter.com/projects/zepan/maixcam2-build-your-next-gen-4k-ai-camera)，用于智能监控。 - -[https://private-user-images.githubusercontent.com/83055338/547056448-e7b031ff-d6f5-4468-bcca-5726b6fecb5c.mp4](https://private-user-images.githubusercontent.com/83055338/547056448-e7b031ff-d6f5-4468-bcca-5726b6fecb5c.mp4) - -🌟 更多部署案例敬请期待！ - -## 📦 安装 - -### 使用预编译二进制文件安装 - -从 [Release 页面](https://github.com/KarakuriAgent/clawdroid/releases) 下载适用于您平台的固件。 - -### 从源码安装（获取最新特性，开发推荐） - -```bash -git clone https://github.com/KarakuriAgent/clawdroid.git - -cd clawdroid -make deps - -# 构建（无需安装） -make build - -# 为多平台构建 -make build-all - -# 构建并安装 -make install - -``` - -## 🐳 Docker Compose - -您也可以使用 Docker Compose 运行 ClawDroid，无需在本地安装任何环境。 - -```bash -# 1. 克隆仓库 -git clone https://github.com/KarakuriAgent/clawdroid.git -cd clawdroid - -# 2. 设置 API Key -cp config/config.example.json config/config.json -vim config/config.json # 设置 DISCORD_BOT_TOKEN, API keys 等 - -# 3. 构建并启动 -docker compose --profile gateway up -d - -# 4. 查看日志 -docker compose logs -f clawdroid-gateway - -# 5. 停止 -docker compose --profile gateway down - -``` - -### Agent 模式 (一次性运行) - -```bash -# 提问 -docker compose run --rm clawdroid-agent -m "2+2 等于几？" - -# 交互模式 -docker compose run --rm clawdroid-agent - -``` - -### 重新构建 - -```bash -docker compose --profile gateway build --no-cache -docker compose --profile gateway up -d - -``` - -### 🚀 快速开始 - -> [!TIP] -> 在 `~/.clawdroid/config.json` 中设置您的 API Key。 -> 获取 API Key: [OpenRouter](https://openrouter.ai/keys) (LLM) · [Zhipu (智谱)](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) (LLM) -> 网络搜索是 **可选的** - 获取免费的 [Brave Search API](https://brave.com/search/api) (每月 2000 次免费查询) - -**1. 初始化 (Initialize)** - -```bash -clawdroid onboard - -``` - -**2. 配置 (Configure)** (`~/.clawdroid/config.json`) - -```json -{ - "agents": { - "defaults": { - "workspace": "~/.clawdroid/workspace", - "model": "glm-4.7", - "max_tokens": 8192, - "temperature": 0.7, - "max_tool_iterations": 20 - } - }, - "providers": { - "openrouter": { - "api_key": "xxx", - "api_base": "https://openrouter.ai/api/v1" - } - }, - "tools": { - "web": { - "search": { - "api_key": "YOUR_BRAVE_API_KEY", - "max_results": 5 - } - } - } -} - -``` - -**3. 获取 API Key** - -* **LLM 提供商**: [OpenRouter](https://openrouter.ai/keys) · [Zhipu](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) · [Anthropic](https://console.anthropic.com) · [OpenAI](https://platform.openai.com) · [Gemini](https://aistudio.google.com/api-keys) -* **网络搜索** (可选): [Brave Search](https://brave.com/search/api) - 提供免费层级 (2000 请求/月) - -> **注意**: 完整的配置模板请参考 `config.example.json`。 - -**4. 对话 (Chat)** - -```bash -clawdroid agent -m "2+2 等于几？" - -``` - -就是这样！您在 2 分钟内就拥有了一个可工作的 AI 助手。 - ---- - -## 💬 聊天应用集成 (Chat Apps) - -通过 Telegram, Discord 或钉钉与您的 ClawDroid 对话。 - -| 渠道 | 设置难度 | -| --- | --- | -| **Telegram** | 简单 (仅需 token) | -| **Discord** | 简单 (bot token + intents) | -| **QQ** | 简单 (AppID + AppSecret) | -| **钉钉 (DingTalk)** | 中等 (app credentials) | - -
-Telegram (推荐) - -**1. 创建机器人** - -* 打开 Telegram，搜索 `@BotFather` -* 发送 `/newbot`，按照提示操作 -* 复制 token - -**2. 配置** - -```json -{ - "channels": { - "telegram": { - "enabled": true, - "token": "YOUR_BOT_TOKEN", - "allowFrom": ["YOUR_USER_ID"] - } - } -} - -``` - -> 从 Telegram 上的 `@userinfobot` 获取您的用户 ID。 - -**3. 运行** - -```bash -clawdroid gateway - -``` - -
- -
-Discord - -**1. 创建机器人** - -* 前往 [https://discord.com/developers/applications](https://discord.com/developers/applications) -* Create an application → Bot → Add Bot -* 复制 bot token - -**2. 开启 Intents** - -* 在 Bot 设置中，开启 **MESSAGE CONTENT INTENT** -* (可选) 如果计划基于成员数据使用白名单，开启 **SERVER MEMBERS INTENT** - -**3. 获取您的 User ID** - -* Discord 设置 → Advanced → 开启 **Developer Mode** -* 右键点击您的头像 → **Copy User ID** - -**4. 配置** - -```json -{ - "channels": { - "discord": { - "enabled": true, - "token": "YOUR_BOT_TOKEN", - "allowFrom": ["YOUR_USER_ID"] - } - } -} - -``` - -**5. 邀请机器人** - -* OAuth2 → URL Generator -* Scopes: `bot` -* Bot Permissions: `Send Messages`, `Read Message History` -* 打开生成的邀请 URL，将机器人添加到您的服务器 - -**6. 运行** - -```bash -clawdroid gateway - -``` - -
- -
-QQ - -**1. 创建机器人** - -* 前往 [QQ 开放平台](https://q.qq.com/#) -* 创建应用 → 获取 **AppID** 和 **AppSecret** - -**2. 配置** - -```json -{ - "channels": { - "qq": { - "enabled": true, - "app_id": "YOUR_APP_ID", - "app_secret": "YOUR_APP_SECRET", - "allow_from": [] - } - } -} - -``` - -> 将 `allow_from` 设为空以允许所有用户，或指定 QQ 号以限制访问。 - -**3. 运行** - -```bash -clawdroid gateway - -``` - -
- -
-钉钉 (DingTalk) - -**1. 创建机器人** - -* 前往 [开放平台](https://open.dingtalk.com/) -* 创建内部应用 -* 复制 Client ID 和 Client Secret - -**2. 配置** - -```json -{ - "channels": { - "dingtalk": { - "enabled": true, - "client_id": "YOUR_CLIENT_ID", - "client_secret": "YOUR_CLIENT_SECRET", - "allow_from": [] - } - } -} - -``` - -> 将 `allow_from` 设为空以允许所有用户，或指定 ID 以限制访问。 - -**3. 运行** - -```bash -clawdroid gateway - -``` - -
- -## ClawdChat 加入 Agent 社交网络 - -只需通过 CLI 或任何集成的聊天应用发送一条消息，即可将 ClawDroid 连接到 Agent 社交网络。 - -**阅读 `https://clawdchat.ai/skill.md` 并按照说明加入 [ClawdChat.ai**](https://clawdchat.ai) - -## ⚙️ 配置详解 - -配置文件路径: `~/.clawdroid/config.json` - -### 工作区布局 (Workspace Layout) - -ClawDroid 将数据存储在您配置的工作区中（默认：`~/.clawdroid/workspace`）： - -``` -~/.clawdroid/workspace/ -├── sessions/ # 对话会话和历史 -├── memory/ # 长期记忆 (MEMORY.md) -├── state/ # 持久化状态 (最后一次频道等) -├── cron/ # 定时任务数据库 -├── skills/ # 自定义技能 -├── AGENTS.md # Agent 行为指南 -├── HEARTBEAT.md # 周期性任务提示词 (每 30 分钟检查一次) -├── IDENTITY.md # Agent 身份设定 -├── SOUL.md # Agent 灵魂/性格 -├── TOOLS.md # 工具描述 -└── USER.md # 用户偏好 - -``` - -### 心跳 / 周期性任务 (Heartbeat) - -ClawDroid 可以自动执行周期性任务。在工作区创建 `HEARTBEAT.md` 文件： - -```markdown -# Periodic Tasks - -- Check my email for important messages -- Review my calendar for upcoming events -- Check the weather forecast - -``` - -Agent 将每隔 30 分钟（可配置）读取此文件，并使用可用工具执行任务。 - -#### 使用 Spawn 的异步任务 - -对于耗时较长的任务（网络搜索、API 调用），使用 `spawn` 工具创建一个 **子 Agent (subagent)**： - -```markdown -# Periodic Tasks - -## Quick Tasks (respond directly) -- Report current time - -## Long Tasks (use spawn for async) -- Search the web for AI news and summarize -- Check email and report important messages - -``` - -**关键行为：** - -| 特性 | 描述 | -| --- | --- | -| **spawn** | 创建异步子 Agent，不阻塞主心跳进程 | -| **独立上下文** | 子 Agent 拥有独立上下文，无会话历史 | -| **message tool** | 子 Agent 通过 message 工具直接与用户通信 | -| **非阻塞** | spawn 后，心跳继续处理下一个任务 | - -#### 子 Agent 通信原理 - -``` -心跳触发 (Heartbeat triggers) - ↓ -Agent 读取 HEARTBEAT.md - ↓ -对于长任务: spawn 子 Agent - ↓ ↓ -继续下一个任务 子 Agent 独立工作 - ↓ ↓ -所有任务完成 子 Agent 使用 "message" 工具 - ↓ ↓ -响应 HEARTBEAT_OK 用户直接收到结果 - -``` - -子 Agent 可以访问工具（message, web_search 等），并且无需通过主 Agent 即可独立与用户通信。 - -**配置：** - -```json -{ - "heartbeat": { - "enabled": true, - "interval": 30 - } -} - -``` - -| 选项 | 默认值 | 描述 | -| --- | --- | --- | -| `enabled` | `true` | 启用/禁用心跳 | -| `interval` | `30` | 检查间隔，单位分钟 (最小: 5) | - -**环境变量:** - -* `CLAWDROID_HEARTBEAT_ENABLED=false` 禁用 -* `CLAWDROID_HEARTBEAT_INTERVAL=60` 更改间隔 - -### 提供商 (Providers) - -> [!NOTE] -> Groq 通过 Whisper 提供免费的语音转录。如果配置了 Groq，Telegram 语音消息将被自动转录为文字。 - -| 提供商 | 用途 | 获取 API Key | -| --- | --- | --- | -| `gemini` | LLM (Gemini 直连) | [aistudio.google.com](https://aistudio.google.com) | -| `zhipu` | LLM (智谱直连) | [bigmodel.cn](bigmodel.cn) | -| `openrouter(待测试)` | LLM (推荐，可访问所有模型) | [openrouter.ai](https://openrouter.ai) | -| `anthropic(待测试)` | LLM (Claude 直连) | [console.anthropic.com](https://console.anthropic.com) | -| `openai(待测试)` | LLM (GPT 直连) | [platform.openai.com](https://platform.openai.com) | -| `deepseek(待测试)` | LLM (DeepSeek 直连) | [platform.deepseek.com](https://platform.deepseek.com) | -| `groq` | LLM + **语音转录** (Whisper) | [console.groq.com](https://console.groq.com) | - -
-智谱 (Zhipu) 配置示例 - -**1. 获取 API key 和 base URL** - -* 获取 [API key](https://bigmodel.cn/usercenter/proj-mgmt/apikeys) - -**2. 配置** - -```json -{ - "agents": { - "defaults": { - "workspace": "~/.clawdroid/workspace", - "model": "glm-4.7", - "max_tokens": 8192, - "temperature": 0.7, - "max_tool_iterations": 20 - } - }, - "providers": { - "zhipu": { - "api_key": "Your API Key", - "api_base": "https://open.bigmodel.cn/api/paas/v4" - }, - }, -} - -``` - -**3. 运行** - -```bash -clawdroid agent -m "你好" - -``` - -
- -
-完整配置示例 - -```json -{ - "agents": { - "defaults": { - "model": "anthropic/claude-opus-4-5" - } - }, - "providers": { - "openrouter": { - "api_key": "sk-or-v1-xxx" - }, - "groq": { - "api_key": "gsk_xxx" - } - }, - "channels": { - "telegram": { - "enabled": true, - "token": "123456:ABC...", - "allow_from": ["123456789"] - }, - "discord": { - "enabled": true, - "token": "", - "allow_from": [""] - }, - "whatsapp": { - "enabled": false - }, - "feishu": { - "enabled": false, - "app_id": "cli_xxx", - "app_secret": "xxx", - "encrypt_key": "", - "verification_token": "", - "allow_from": [] - }, - "qq": { - "enabled": false, - "app_id": "", - "app_secret": "", - "allow_from": [] - } - }, - "tools": { - "web": { - "search": { - "api_key": "BSA..." - } - } - }, - "heartbeat": { - "enabled": true, - "interval": 30 - } -} - -``` - -
- -## CLI 命令行参考 - -| 命令 | 描述 | -| --- | --- | -| `clawdroid onboard` | 初始化配置和工作区 | -| `clawdroid agent -m "..."` | 与 Agent 对话 | -| `clawdroid agent` | 交互式聊天模式 | -| `clawdroid gateway` | 启动网关 (Gateway) | -| `clawdroid status` | 显示状态 | -| `clawdroid cron list` | 列出所有定时任务 | -| `clawdroid cron add ...` | 添加定时任务 | - -### 定时任务 / 提醒 (Scheduled Tasks) - -ClawDroid 通过 `cron` 工具支持定时提醒和重复任务： - -* **一次性提醒**: "Remind me in 10 minutes" (10分钟后提醒我) → 10分钟后触发一次 -* **重复任务**: "Remind me every 2 hours" (每2小时提醒我) → 每2小时触发 -* **Cron 表达式**: "Remind me at 9am daily" (每天上午9点提醒我) → 使用 cron 表达式 - -任务存储在 `~/.clawdroid/workspace/cron/` 中并自动处理。 - -## 🤝 贡献与路线图 (Roadmap) - -欢迎提交 PR！代码库刻意保持小巧和可读。🤗 - -路线图即将发布... - -开发者群组正在组建中，入群门槛：至少合并过 1 个 PR。 - -用户群组： - -Discord: [https://discord.gg/V4sAZ9XWpN](https://discord.gg/V4sAZ9XWpN) - -ClawDroid - -## 🐛 疑难解答 (Troubleshooting) - -### 网络搜索提示 "API 配置问题" - -如果您尚未配置搜索 API Key，这是正常的。ClawDroid 会提供手动搜索的帮助链接。 - -启用网络搜索： - -1. 在 [https://brave.com/search/api](https://brave.com/search/api) 获取免费 API Key (每月 2000 次免费查询) -2. 添加到 `~/.clawdroid/config.json`: -```json -{ - "tools": { - "web": { - "search": { - "api_key": "YOUR_BRAVE_API_KEY", - "max_results": 5 - } - } - } -} - -``` - - - -### 遇到内容过滤错误 (Content Filtering Errors) - -某些提供商（如智谱）有严格的内容过滤。尝试改写您的问题或使用其他模型。 - -### Telegram bot 提示 "Conflict: terminated by other getUpdates" - -这表示有另一个机器人实例正在运行。请确保同一时间只有一个 `clawdroid gateway` 进程在运行。 - ---- - -## 📝 API Key 对比 - -| 服务 | 免费层级 | 适用场景 | -| --- | --- | --- | -| **OpenRouter** | 200K tokens/月 | 多模型聚合 (Claude, GPT-4 等) | -| **智谱 (Zhipu)** | 200K tokens/月 | 最适合中国用户 | -| **Brave Search** | 2000 次查询/月 | 网络搜索功能 | -| **Groq** | 提供免费层级 | 极速推理 (Llama, Mixtral) | \ No newline at end of file