From 69d82f060b8385c57d0c52ba555fa242c2c68090 Mon Sep 17 00:00:00 2001 From: Kohei Date: Sun, 1 Mar 2026 00:47:01 +0900 Subject: [PATCH] docs: rewrite README for embedded-first dual-flavor architecture MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- README.ja.md | 183 +++++++++++++++++++++++++++++++-------------------- README.md | 183 +++++++++++++++++++++++++++++++-------------------- 2 files changed, 224 insertions(+), 142 deletions(-) diff --git a/README.ja.md b/README.ja.md index d28f05dc2..e863018c3 100644 --- a/README.ja.md +++ b/README.ja.md @@ -4,7 +4,7 @@ # 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) からフォークしたプロジェクトです。 @@ -12,17 +12,19 @@ Android 向け超軽量パーソナル AI アシスタント。Go バックエ ```mermaid graph TB - subgraph android["Android アプリ (Kotlin)"] - ChatUI["チャット UI
(Compose)"] - Overlay["アシスタント
オーバーレイ"] - end + subgraph apk["Android APK"] + subgraph android["Kotlin アプリ"] + ChatUI["チャット UI
(Compose)"] + Overlay["アシスタント
オーバーレイ"] + end - subgraph backend["Go バックエンド (Termux)"] - Agent["エージェントループ"] - Tools["ツールループ
(16以上)"] - LLM["LLM"] - Services["MCP / Cron /
Skills / Memory"] - Channels["チャンネル
(Telegram, Discord, Slack, LINE 等)"] + subgraph backend["Go バックエンド (組み込み)"] + Agent["エージェントループ"] + Tools["ツールループ
(16以上)"] + LLM["LLM"] + Services["MCP / Cron /
Skills / Memory"] + Channels["チャンネル
(Telegram, Discord, Slack, LINE 等)"] + end end ChatUI -- "WebSocket
ws://127.0.0.1:18793" --> Agent @@ -33,86 +35,44 @@ graph TB Agent --> Channels ``` -- **Go バックエンド** (`cmd/clawdroid/`): シングルバイナリ。エージェントループ、ツール実行、LLM 呼び出し、メッセージングチャンネル、Cron、ハートビート +- **Go バックエンド**: APK 内にバンドルされたシングルバイナリ。エージェントループ、ツール実行、LLM 呼び出し、メッセージングチャンネル、Cron、ハートビート - **Android アプリ** (`android/`): チャット UI、フローティングアシスタントオーバーレイ、アクセシビリティベースのデバイス制御、音声モード ## クイックスタート ### 前提条件 -- [Termux](https://termux.dev) がインストールされた Android デバイス +- Android デバイス - LLM API キー（OpenAI、Anthropic、Gemini 等） ### 1. ダウンロード -[GitHub Releases](https://github.com/KarakuriAgent/clawdroid/releases) から最新の Go バックエンドバイナリと Android アプリ APK をダウンロードします。 +[GitHub Releases](https://github.com/KarakuriAgent/clawdroid/releases) から APK をダウンロードします。 -デバイスのアーキテクチャに合ったバイナリを選択してください: +デバイスのアーキテクチャに合った APK を選択してください: -| アーキテクチャ | バイナリ | -|-------------|---------| -| 64-bit ARM（最近のデバイスの大半） | `clawdroid-linux-arm64` | -| 32-bit ARM | `clawdroid-linux-arm` | +| アーキテクチャ | APK | +|-------------|-----| +| 64-bit ARM（最近のデバイスの大半） | `clawdroid-embedded-arm64-v8a-release.apk` | +| 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 バックエンドのインストール - -Termux で: - -```bash -# バイナリを配置して実行権限を付与（arm64 の例） -cp ~/storage/downloads/clawdroid-linux-arm64 ~/.local/bin/clawdroid -chmod +x ~/.local/bin/clawdroid -``` +APK をインストールしてアプリを起動します。Go バックエンドはバックグラウンドで自動的に起動します。 ### 3. 初期セットアップ -```bash -clawdroid onboard -``` +初回起動時にセットアップウィザードが表示されます: -`~/.clawdroid/config.json` とワークスペーステンプレートが作成されます。 - -設定ファイルを編集して 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` を付けると詳細ログが有効になります。 +- LLM モデルを `プロバイダー/モデル名` 形式（例: `openai/gpt-4o`）と API キーを設定 +- 対応プロバイダーの一覧は「[対応 LLM プロバイダー](#対応-llm-プロバイダー)」を参照 +- すべての設定はアプリ内の設定画面から後で変更可能 ## 設定 -設定ファイル: `~/.clawdroid/config.json` +組み込み版はアプリ内の設定 GUI で変更できます。Termux 版は `~/.clawdroid/config.json` を使用します。 すべての設定は `CLAWDROID_` プレフィックスの環境変数で上書きできます（例: `CLAWDROID_LLM_API_KEY`）。環境変数名は JSON パスを大文字・`_` 区切りにしたものです。 @@ -279,6 +239,78 @@ clawdroid agent -m "こんにちは！" `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 エージェントが自律的に使用します。 @@ -481,7 +513,13 @@ Android Studio で `android/` を開くか、Gradle でビルド: ```bash cd android -./gradlew assembleDebug + +# 組み込み版（Go バックエンドを APK に内蔵） +make build-android # Go バックエンドを jniLibs としてビルド +./gradlew assembleEmbeddedDebug + +# Termux 版（バックエンドなし） +./gradlew assembleTermuxDebug ``` パッケージ名: `io.clawdroid` @@ -507,6 +545,9 @@ clawdroid/ │ └── tools/ # 全ツール実装 ├── android/ │ ├── app/ # メインアプリ (AssistantService, AccessibilityService, DeviceController) +│ ├── backend/ +│ │ ├── loader/ # 組み込みバックエンドローダー (GatewayProcessManager) +│ │ └── loader-noop/ # Termux フレーバー用 No-op ローダー │ ├── core/ # 共有コア (data, domain, model, ui) │ └── feature/ # 機能モジュール (chat, settings) ├── workspace/ # テンプレートファイル (IDENTITY.md, SOUL.md 等) diff --git a/README.md b/README.md index 420a95494..430567b34 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ **[日本語版](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). @@ -14,17 +14,19 @@ Forked from [PicoClaw](https://github.com/sipeed/picoclaw). ```mermaid graph TB - subgraph android["Android App (Kotlin)"] - ChatUI["Chat UI
(Compose)"] - Overlay["Assistant
Overlay"] - end + subgraph apk["Android APK"] + subgraph android["Kotlin App"] + ChatUI["Chat UI
(Compose)"] + Overlay["Assistant
Overlay"] + end - subgraph backend["Go Backend (Termux)"] - Agent["Agent Loop"] - Tools["Tool Loop
(16+ tools)"] - LLM["LLM"] - Services["MCP / Cron /
Skills / Memory"] - Channels["Channels
(Telegram, Discord, Slack, LINE etc.)"] + subgraph backend["Go Backend (embedded)"] + Agent["Agent Loop"] + Tools["Tool Loop
(16+ tools)"] + LLM["LLM"] + Services["MCP / Cron /
Skills / Memory"] + Channels["Channels
(Telegram, Discord, Slack, LINE etc.)"] + end end ChatUI -- "WebSocket
ws://127.0.0.1:18793" --> Agent @@ -35,86 +37,44 @@ graph TB 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 ## Quick Start ### Prerequisites -- Android device with [Termux](https://termux.dev) installed +- Android device - 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). +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 | -|-------------|--------| -| 64-bit ARM (most modern devices) | `clawdroid-linux-arm64` | -| 32-bit ARM | `clawdroid-linux-arm` | +| Architecture | APK | +|-------------|-----| +| 64-bit ARM (most modern devices) | `clawdroid-embedded-arm64-v8a-release.apk` | +| 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 - -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 -``` +Install the APK and open the app. The Go backend starts automatically in the background. ### 3. Initial Setup -```bash -clawdroid onboard -``` +On first launch, a setup wizard guides you through the configuration: -This creates `~/.clawdroid/config.json` and workspace templates. - -Edit the config to add your API key: - -```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. +- 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 +- All settings can be changed later from the in-app settings screen ## 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. @@ -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.). +## 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 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 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` @@ -509,6 +547,9 @@ clawdroid/ │ └── tools/ # All tool implementations ├── android/ │ ├── 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) │ └── feature/ # Feature modules (chat, settings) ├── workspace/ # Template files (IDENTITY.md, SOUL.md, etc.)