opencode/picoclaw
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: rewrite README for embedded-first dual-flavor architecture

Browse source 
Restructure both English and Japanese READMEs to reflect the embedded
flavor as the primary setup (APK install → launch → wizard) and move
Termux instructions to a dedicated section. Update mermaid diagram to
show Go backend embedded within the APK, add ABI-split APK download
table, embedded/Termux build commands, and backend/loader modules to
project structure.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Kohei 2026-03-01 00:47:01 +09:00
parent db2373b40d
commit 69d82f060b
2 changed files with 224 additions and 142 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

183
README.ja.md
View file

@ -4,7 +4,7 @@
# ClawDroid # ClawDroid
Android 向け超軽量パーソナル AI アシスタント。Go バックエンドが Termux 上で動作し、ネイティブ Kotlin/Jetpack Compose アプリがチャット UI、音声アシスタント、デバイス自動操作を提供します。 Go バックエンドを内蔵した Android AI アシスタント。APK をインストールして起動するだけですぐに使えます。Kotlin/Jetpack Compose アプリがチャット UI、音声アシスタント、デバイス自動操作を提供します。上級者向けに [Termux 版](#termux-版)も利用可能です。
[PicoClaw](https://github.com/sipeed/picoclaw) からフォークしたプロジェクトです。 [PicoClaw](https://github.com/sipeed/picoclaw) からフォークしたプロジェクトです。
@ -12,17 +12,19 @@ Android 向け超軽量パーソナル AI アシスタント。Go バックエ
```mermaid ```mermaid
graph TB graph TB
subgraph android["Android アプリ (Kotlin)"] subgraph apk["Android APK"]
ChatUI["チャット UI<br/>(Compose)"] subgraph android["Kotlin アプリ"]
Overlay["アシスタント<br/>オーバーレイ"] ChatUI["チャット UI<br/>(Compose)"]
end Overlay["アシスタント<br/>オーバーレイ"]
end
subgraph backend["Go バックエンド (Termux)"] subgraph backend["Go バックエンド (組み込み)"]
Agent["エージェントループ"] Agent["エージェントループ"]
Tools["ツールループ<br/>(16以上)"] Tools["ツールループ<br/>(16以上)"]
LLM["LLM"] LLM["LLM"]
Services["MCP / Cron /<br/>Skills / Memory"] Services["MCP / Cron /<br/>Skills / Memory"]
Channels["チャンネル<br/>(Telegram, Discord, Slack, LINE 等)"] Channels["チャンネル<br/>(Telegram, Discord, Slack, LINE 等)"]
end
end end
ChatUI -- "WebSocket<br/>ws://127.0.0.1:18793" --> Agent ChatUI -- "WebSocket<br/>ws://127.0.0.1:18793" --> Agent
@ -33,86 +35,44 @@ graph TB
Agent --> Channels Agent --> Channels
``` ```
- **Go バックエンド** (`cmd/clawdroid/`): シングルバイナリ。エージェントループ、ツール実行、LLM 呼び出し、メッセージングチャンネル、Cron、ハートビート - **Go バックエンド**: APK 内にバンドルされたシングルバイナリ。エージェントループ、ツール実行、LLM 呼び出し、メッセージングチャンネル、Cron、ハートビート
- **Android アプリ** (`android/`): チャット UI、フローティングアシスタントオーバーレイ、アクセシビリティベースのデバイス制御、音声モード - **Android アプリ** (`android/`): チャット UI、フローティングアシスタントオーバーレイ、アクセシビリティベースのデバイス制御、音声モード
## クイックスタート ## クイックスタート
### 前提条件 ### 前提条件
- [Termux](https://termux.dev) がインストールされた Android デバイス - Android デバイス
- LLM API キー（OpenAI、Anthropic、Gemini 等） - LLM API キー（OpenAI、Anthropic、Gemini 等）
### 1. ダウンロード ### 1. ダウンロード
[GitHub Releases](https://github.com/KarakuriAgent/clawdroid/releases) から最新の Go バックエンドバイナリと Android アプリ APK をダウンロードします。 [GitHub Releases](https://github.com/KarakuriAgent/clawdroid/releases) から APK をダウンロードします。
デバイスのアーキテクチャに合ったバイナリを選択してください: デバイスのアーキテクチャに合った APK を選択してください:
| アーキテクチャ | バイナリ | | アーキテクチャ | APK |
|-------------|---------| |-------------|-----|
| 64-bit ARM（最近のデバイスの大半） | `clawdroid-linux-arm64` | | 64-bit ARM（最近のデバイスの大半） | `clawdroid-embedded-arm64-v8a-release.apk` |
| 32-bit ARM | `clawdroid-linux-arm` | | 32-bit ARM | `clawdroid-embedded-armeabi-v7a-release.apk` |
| x86_64（エミュレーター） | `clawdroid-embedded-x86_64-release.apk` |
| ユニバーサル（全アーキテクチャ） | `clawdroid-embedded-universal-release.apk` |
Termux で `uname -m` を実行するとアーキテクチャを確認できます。 ### 2. インストール & 起動
### 2. Go バックエンドのインストール APK をインストールしてアプリを起動します。Go バックエンドはバックグラウンドで自動的に起動します。
Termux で:
```bash
# バイナリを配置して実行権限を付与（arm64 の例）
cp ~/storage/downloads/clawdroid-linux-arm64 ~/.local/bin/clawdroid
chmod +x ~/.local/bin/clawdroid
```
### 3. 初期セットアップ ### 3. 初期セットアップ
```bash 初回起動時にセットアップウィザードが表示されます:
clawdroid onboard
```
`~/.clawdroid/config.json` とワークスペーステンプレートが作成されます。 - LLM モデルを `プロバイダー/モデル名` 形式（例: `openai/gpt-4o`）と API キーを設定
- 対応プロバイダーの一覧は「[対応 LLM プロバイダー](#対応-llm-プロバイダー)」を参照
設定ファイルを編集して API キーを追加: - すべての設定はアプリ内の設定画面から後で変更可能
```bash
vi ~/.clawdroid/config.json
```
### 4. Android アプリのインストール
ダウンロードした APK を同じデバイスにインストールします。
### 5. 実行
```bash
# ゲートウェイサーバーを起動（Android アプリ + メッセージングチャンネルに接続）
clawdroid gateway
# またはターミナルから直接対話
clawdroid agent
clawdroid agent -m "こんにちは！"
```
## CLI コマンド
| コマンド | 説明 |
|---------|------|
| `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` を付けると詳細ログが有効になります。
## 設定 ## 設定
設定ファイル: `~/.clawdroid/config.json` 組み込み版はアプリ内の設定 GUI で変更できます。Termux 版は `~/.clawdroid/config.json` を使用します。
すべての設定は `CLAWDROID_` プレフィックスの環境変数で上書きできます（例: `CLAWDROID_LLM_API_KEY`）。環境変数名は JSON パスを大文字・`_` 区切りにしたものです。 すべての設定は `CLAWDROID_` プレフィックスの環境変数で上書きできます（例: `CLAWDROID_LLM_API_KEY`）。環境変数名は JSON パスを大文字・`_` 区切りにしたものです。
@ -279,6 +239,78 @@ clawdroid agent -m "こんにちは！"
`base_url` で任意の OpenAI 互換エンドポイント（OpenRouter、ローカルプロキシ等）を指定できます。 `base_url` で任意の OpenAI 互換エンドポイント（OpenRouter、ローカルプロキシ等）を指定できます。
## Termux 版
### 概要
Termux 版は Go バックエンドを APK に内蔵せず、Termux 上で別プロセスとして実行する構成です。APK にバックエンドバイナリは含まれません。
### 前提条件
- [Termux](https://termux.dev) がインストールされた Android デバイス
- LLM API キー（OpenAI、Anthropic、Gemini 等）
### セットアップ
**1. Go バックエンドバイナリのダウンロード**
[GitHub Releases](https://github.com/KarakuriAgent/clawdroid/releases) からダウンロードします。デバイスのアーキテクチャに合ったバイナリを選択してください:
| アーキテクチャ | バイナリ |
|-------------|---------|
| 64-bit ARM（最近のデバイスの大半） | `clawdroid-linux-arm64` |
| 32-bit ARM | `clawdroid-linux-arm` |
Termux で `uname -m` を実行するとアーキテクチャを確認できます。
**2. バイナリのインストール**
```bash
cp ~/storage/downloads/clawdroid-linux-arm64 ~/.local/bin/clawdroid
chmod +x ~/.local/bin/clawdroid
```
**3. 初期セットアップの実行**
```bash
clawdroid onboard
```
`~/.clawdroid/config.json` とワークスペーステンプレートが作成されます。
**4. 設定**
```bash
vi ~/.clawdroid/config.json
```
LLM モデルと API キーを設定します。
**5. Termux 版 APK のインストール**
Termux フレーバーの APK（`clawdroid-termux-*.apk`）を同じデバイスにインストールします。
**6. バックエンドの起動**
```bash
clawdroid gateway
```
### CLI コマンド
| コマンド | 説明 |
|---------|------|
| `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` を付けると詳細ログが有効になります。
## ツール ## ツール
ClawDroid は 16 以上の組み込みツールを提供し、AI エージェントが自律的に使用します。 ClawDroid は 16 以上の組み込みツールを提供し、AI エージェントが自律的に使用します。
@ -481,7 +513,13 @@ Android Studio で `android/` を開くか、Gradle でビルド:
```bash ```bash
cd android cd android
./gradlew assembleDebug
# 組み込み版（Go バックエンドを APK に内蔵）
make build-android # Go バックエンドを jniLibs としてビルド
./gradlew assembleEmbeddedDebug
# Termux 版（バックエンドなし）
./gradlew assembleTermuxDebug
``` ```
パッケージ名: `io.clawdroid` パッケージ名: `io.clawdroid`
@ -507,6 +545,9 @@ clawdroid/
│ └── tools/ # 全ツール実装 │ └── tools/ # 全ツール実装
├── android/ ├── android/
│ ├── app/ # メインアプリ (AssistantService, AccessibilityService, DeviceController) │ ├── app/ # メインアプリ (AssistantService, AccessibilityService, DeviceController)
│ ├── backend/
│ │ ├── loader/ # 組み込みバックエンドローダー (GatewayProcessManager)
│ │ └── loader-noop/ # Termux フレーバー用 No-op ローダー
│ ├── core/ # 共有コア (data, domain, model, ui) │ ├── core/ # 共有コア (data, domain, model, ui)
│ └── feature/ # 機能モジュール (chat, settings) │ └── feature/ # 機能モジュール (chat, settings)
├── workspace/ # テンプレートファイル (IDENTITY.md, SOUL.md 等) ├── workspace/ # テンプレートファイル (IDENTITY.md, SOUL.md 等)

183
README.md
View file

@ -6,7 +6,7 @@
**[日本語版](README.ja.md)** **[日本語版](README.ja.md)**
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. Android AI assistant with an embedded Go backend. Install the APK, launch, and start chatting — no separate server setup needed. A Kotlin/Jetpack Compose app provides the chat UI, voice assistant, and device automation. For advanced users, a [Termux-based setup](#termux-version) is also available.
Forked from [PicoClaw](https://github.com/sipeed/picoclaw). Forked from [PicoClaw](https://github.com/sipeed/picoclaw).
@ -14,17 +14,19 @@ Forked from [PicoClaw](https://github.com/sipeed/picoclaw).
```mermaid ```mermaid
graph TB graph TB
subgraph android["Android App (Kotlin)"] subgraph apk["Android APK"]
ChatUI["Chat UI<br/>(Compose)"] subgraph android["Kotlin App"]
Overlay["Assistant<br/>Overlay"] ChatUI["Chat UI<br/>(Compose)"]
end Overlay["Assistant<br/>Overlay"]
end
subgraph backend["Go Backend (Termux)"] subgraph backend["Go Backend (embedded)"]
Agent["Agent Loop"] Agent["Agent Loop"]
Tools["Tool Loop<br/>(16+ tools)"] Tools["Tool Loop<br/>(16+ tools)"]
LLM["LLM"] LLM["LLM"]
Services["MCP / Cron /<br/>Skills / Memory"] Services["MCP / Cron /<br/>Skills / Memory"]
Channels["Channels<br/>(Telegram, Discord, Slack, LINE etc.)"] Channels["Channels<br/>(Telegram, Discord, Slack, LINE etc.)"]
end
end end
ChatUI -- "WebSocket<br/>ws://127.0.0.1:18793" --> Agent ChatUI -- "WebSocket<br/>ws://127.0.0.1:18793" --> Agent
@ -35,86 +37,44 @@ graph TB
Agent --> Channels Agent --> Channels
``` ```
- **Go backend** (`cmd/clawdroid/`): Single binary. Agent loop, tool execution, LLM calls, messaging channels, cron, heartbeat - **Go backend**: Single binary bundled inside the APK. Agent loop, tool execution, LLM calls, messaging channels, cron, heartbeat
- **Android app** (`android/`): Chat UI, floating assistant overlay, accessibility-based device control, voice mode - **Android app** (`android/`): Chat UI, floating assistant overlay, accessibility-based device control, voice mode
## Quick Start ## Quick Start
### Prerequisites ### Prerequisites
- Android device with [Termux](https://termux.dev) installed - Android device
- LLM API key (OpenAI, Anthropic, Gemini, etc.) - LLM API key (OpenAI, Anthropic, Gemini, etc.)
### 1. Download ### 1. Download
Download the latest Go backend binary and Android app APK from [GitHub Releases](https://github.com/KarakuriAgent/clawdroid/releases). Download the APK from [GitHub Releases](https://github.com/KarakuriAgent/clawdroid/releases).
Choose the binary matching your device architecture: Choose the APK matching your device architecture:
| Architecture | Binary | | Architecture | APK |
|-------------|--------| |-------------|-----|
| 64-bit ARM (most modern devices) | `clawdroid-linux-arm64` | | 64-bit ARM (most modern devices) | `clawdroid-embedded-arm64-v8a-release.apk` |
| 32-bit ARM | `clawdroid-linux-arm` | | 32-bit ARM | `clawdroid-embedded-armeabi-v7a-release.apk` |
| x86_64 (emulators) | `clawdroid-embedded-x86_64-release.apk` |
| Universal (all architectures) | `clawdroid-embedded-universal-release.apk` |
You can check your architecture in Termux with `uname -m`. ### 2. Install & Launch
### 2. Install the Go Backend Install the APK and open the app. The Go backend starts automatically in the background.
In Termux:
```bash
# Place the binary and make it executable (example for arm64)
cp ~/storage/downloads/clawdroid-linux-arm64 ~/.local/bin/clawdroid
chmod +x ~/.local/bin/clawdroid
```
### 3. Initial Setup ### 3. Initial Setup
```bash On first launch, a setup wizard guides you through the configuration:
clawdroid onboard
```
This creates `~/.clawdroid/config.json` and workspace templates. - Set your LLM model in `provider/model` format (e.g. `openai/gpt-4o`) and API key
- See [Supported LLM Providers](#supported-llm-providers) for the full list
Edit the config to add your API key: - All settings can be changed later from the in-app settings screen
```bash
vi ~/.clawdroid/config.json
```
### 4. Install the Android App
Install the downloaded APK on the same device.
### 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
| Command | Description |
|---------|-------------|
| `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 |
Use `--debug` / `-d` with `gateway` or `agent` for verbose logging.
## Configuration ## Configuration
Configuration file: `~/.clawdroid/config.json` The embedded version uses the in-app settings GUI. The Termux version uses `~/.clawdroid/config.json`.
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. 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.
@ -281,6 +241,78 @@ Uses [any-llm-go](https://github.com/mozilla-ai/any-llm-go) as a unified adapter
`base_url` can point to any OpenAI-compatible endpoint (OpenRouter, local proxies, etc.). `base_url` can point to any OpenAI-compatible endpoint (OpenRouter, local proxies, etc.).
## Termux Version
### Overview
The Termux version runs the Go backend as a separate process in Termux instead of embedding it in the APK. The APK does not include the backend binary.
### Prerequisites
- Android device with [Termux](https://termux.dev) installed
- LLM API key (OpenAI, Anthropic, Gemini, etc.)
### Setup
**1. Download the Go backend binary**
Download 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 binary**
```bash
cp ~/storage/downloads/clawdroid-linux-arm64 ~/.local/bin/clawdroid
chmod +x ~/.local/bin/clawdroid
```
**3. Run initial setup**
```bash
clawdroid onboard
```
This creates `~/.clawdroid/config.json` and workspace templates.
**4. Configure**
```bash
vi ~/.clawdroid/config.json
```
Add your LLM model and API key.
**5. Install the Termux APK**
Install the Termux-flavor APK (`clawdroid-termux-*.apk`) on the same device.
**6. Start the backend**
```bash
clawdroid gateway
```
### CLI Commands
| Command | Description |
|---------|-------------|
| `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 |
Use `--debug` / `-d` with `gateway` or `agent` for verbose logging.
## Tools ## Tools
ClawDroid provides 16+ built-in tools that the AI agent can use autonomously. ClawDroid provides 16+ built-in tools that the AI agent can use autonomously.
@ -483,7 +515,13 @@ Open `android/` in Android Studio or build with Gradle:
```bash ```bash
cd android cd android
./gradlew assembleDebug
# Embedded version (includes Go backend in APK)
make build-android # Build Go backend as jniLibs
./gradlew assembleEmbeddedDebug
# Termux version (no backend in APK)
./gradlew assembleTermuxDebug
``` ```
Package name: `io.clawdroid` Package name: `io.clawdroid`
@ -509,6 +547,9 @@ clawdroid/
│ └── tools/ # All tool implementations │ └── tools/ # All tool implementations
├── android/ ├── android/
│ ├── app/ # Main app (AssistantService, AccessibilityService, DeviceController) │ ├── app/ # Main app (AssistantService, AccessibilityService, DeviceController)
│ ├── backend/
│ │ ├── loader/ # Embedded backend loader (GatewayProcessManager)
│ │ └── loader-noop/ # No-op loader for Termux flavor
│ ├── core/ # Shared core (data, domain, model, ui) │ ├── core/ # Shared core (data, domain, model, ui)
│ └── feature/ # Feature modules (chat, settings) │ └── feature/ # Feature modules (chat, settings)
├── workspace/ # Template files (IDENTITY.md, SOUL.md, etc.) ├── workspace/ # Template files (IDENTITY.md, SOUL.md, etc.)