diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 0000000..d632da5 --- /dev/null +++ b/.dockerignore @@ -0,0 +1,10 @@ +.git +.gitignore +build/ +.picoclaw/ +config/ +.env +.env.example +*.md +LICENSE +assets/ diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..c450b6e --- /dev/null +++ b/.env.example @@ -0,0 +1,17 @@ +# ── LLM Provider ────────────────────────── +# Uncomment and set the API key for your provider +# OPENROUTER_API_KEY=sk-or-v1-xxx +# ZHIPU_API_KEY=xxx +# ANTHROPIC_API_KEY=sk-ant-xxx +# OPENAI_API_KEY=sk-xxx +# GEMINI_API_KEY=xxx + +# ── Chat Channel ────────────────────────── +# TELEGRAM_BOT_TOKEN=123456:ABC... +# DISCORD_BOT_TOKEN=xxx + +# ── Web Search (optional) ──────────────── +# BRAVE_SEARCH_API_KEY=BSA... + +# ── Timezone ────────────────────────────── +TZ=Asia/Tokyo diff --git a/.github/workflows/docker-build.yml b/.github/workflows/docker-build.yml new file mode 100644 index 0000000..be35508 --- /dev/null +++ b/.github/workflows/docker-build.yml @@ -0,0 +1,65 @@ +name: 🐳 Build & Push Docker Image + +on: + push: + branches: [main] + tags: ["v*"] + pull_request: + branches: [main] + +env: + REGISTRY: ghcr.io + IMAGE_NAME: ${{ github.repository_owner }}/picoclaw + +jobs: + build: + name: 🏗️ Build Docker Image + runs-on: ubuntu-latest + permissions: + contents: read + packages: write + + steps: + # ── Checkout ────────────────────────────── + - name: 📥 Checkout repository + uses: actions/checkout@v4 + + # ── Docker Buildx ───────────────────────── + - name: 🔧 Set up Docker Buildx + uses: docker/setup-buildx-action@v3 + + # ── Login to GHCR ───────────────────────── + - name: 🔑 Login to GitHub Container Registry + if: github.event_name != 'pull_request' + uses: docker/login-action@v3 + with: + registry: ${{ env.REGISTRY }} + username: ${{ github.actor }} + password: ${{ secrets.GITHUB_TOKEN }} + + # ── Metadata (tags & labels) ────────────── + - name: 🏷️ Extract Docker metadata + id: meta + uses: docker/metadata-action@v5 + with: + images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }} + tags: | + type=ref,event=branch + type=ref,event=pr + type=semver,pattern={{version}} + type=semver,pattern={{major}}.{{minor}} + type=sha,prefix= + type=raw,value=latest,enable={{is_default_branch}} + type=raw,value={{date 'YYYYMMDD-HHmmss'}},enable={{is_default_branch}} + + # ── Build & Push ────────────────────────── + - name: 🚀 Build and push Docker image + uses: docker/build-push-action@v6 + with: + context: . + push: ${{ github.event_name != 'pull_request' }} + tags: ${{ steps.meta.outputs.tags }} + labels: ${{ steps.meta.outputs.labels }} + cache-from: type=gha + cache-to: type=gha,mode=max + platforms: linux/amd64,linux/arm64 diff --git a/.gitignore b/.gitignore index 6ad4d78..19c154d 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,7 @@ # Binaries +# Go build artifacts bin/ +build/ *.exe *.dll *.so @@ -10,12 +12,20 @@ bin/ /picoclaw-test # Picoclaw specific + +# PicoClaw .picoclaw/ config.json sessions/ build/ # Coverage + +# Secrets & Config (keep templates, ignore actual secrets) +.env +config/config.json + +# Test coverage.txt coverage.html diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000..068f64c --- /dev/null +++ b/Dockerfile @@ -0,0 +1,36 @@ +# ============================================================ +# Stage 1: Build the picoclaw binary +# ============================================================ +FROM golang:1.24-alpine AS builder + +RUN apk add --no-cache git make + +WORKDIR /src + +# Cache dependencies +COPY go.mod go.sum ./ +RUN go mod download + +# Copy source and build +COPY . . +RUN make build + +# ============================================================ +# Stage 2: Minimal runtime image +# ============================================================ +FROM alpine:3.21 + +RUN apk add --no-cache ca-certificates tzdata + +# Copy binary +COPY --from=builder /src/build/picoclaw /usr/local/bin/picoclaw + +# Copy builtin skills +COPY --from=builder /src/skills /opt/picoclaw/skills + +# Create picoclaw home directory +RUN mkdir -p /root/.picoclaw/workspace/skills && \ + cp -r /opt/picoclaw/skills/* /root/.picoclaw/workspace/skills/ 2>/dev/null || true + +ENTRYPOINT ["picoclaw"] +CMD ["gateway"] diff --git a/README.ja.md b/README.ja.md new file mode 100644 index 0000000..daeee50 --- /dev/null +++ b/README.ja.md @@ -0,0 +1,456 @@ +
+PicoClaw + +

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

+ +

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

+

+ +

+Go +Hardware +License +

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

+ +

+ 		+

+ +

+
+ +## 📢 ニュース +2026-02-09 🎉 PicoClaw リリース！$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 | **PicoClaw** | +| --- | --- | --- |--- | +| **言語** | TypeScript | Python | **Go** | +| **RAM** | >1GB |>100MB| **< 10MB** | +| **起動時間**
(0.8GHz コア) | >500秒 | >30秒 | **<1秒** | +| **コスト** | Mac Mini 599$ | 大半の Linux SBC
~50$ |**あらゆる Linux ボード**
**最安 10$** | +PicoClaw + + +## 🦾 デモンストレーション +### 🛠️ スタンダードアシスタントワークフロー + + + + + + + + + + + + + + + + +

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

🗂️ ログ＆計画管理

🔎 Web 検索＆学習

開発 · デプロイ · スケールスケジュール · 自動化 · メモリ発見 · インサイト · トレンド
+ +### 🐜 革新的な省フットプリントデプロイ +PicoClaw はほぼすべての 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/sipeed/picoclaw/releases) からお使いのプラットフォーム用のファームウェアをダウンロードしてください。 + +### ソースからインストール（最新機能、開発向け推奨） + +```bash +git clone https://github.com/sipeed/picoclaw.git + +cd picoclaw +make deps + +# ビルド（インストール不要） +make build + +# 複数プラットフォーム向けビルド +make build-all + +# ビルドとインストール +make install +``` + +## 🐳 Docker Compose + +Docker Compose を使えば、ローカルにインストールせずに PicoClaw を実行できます。 + +```bash +# 1. リポジトリをクローン +git clone https://github.com/sipeed/picoclaw.git +cd picoclaw + +# 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 picoclaw-gateway + +# 5. 停止 +docker compose --profile gateway down +``` + +### Agent モード（ワンショット） + +```bash +# 質問を投げる +docker compose run --rm picoclaw-agent -m "What is 2+2?" + +# インタラクティブモード +docker compose run --rm picoclaw-agent +``` + +### リビルド + +```bash +docker compose --profile gateway build --no-cache +docker compose --profile gateway up -d +``` + +### 🚀 クイックスタート（ネイティブ） + +> [!TIP] +> `~/.picoclaw/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. 初期化** + +```bash +picoclaw onboard +``` + +**2. 設定** (`~/.picoclaw/config.json`) + +```json +{ + "agents": { + "defaults": { + "workspace": "~/.picoclaw/workspace", + "model": "glm-4.7", + "max_tokens": 8192, + "temperature": 0.7, + "max_tool_iterations": 20 + } + }, + "providers": { + "openrouter": { + "api_key": "xxx", + "api_base": "https://open.bigmodel.cn/api/paas/v4" + } + }, + "tools": { + "web": { + "search": { + "api_key": "YOUR_BRAVE_API_KEY", + "max_results": 5 + } + } + } +} +``` + +**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. チャット** + +```bash +picoclaw agent -m "What is 2+2?" +``` + +これだけです！2 分で AI アシスタントが動きます。 + +--- + +## 💬 チャットアプリ + +Telegram で PicoClaw と会話できます + +| チャネル | セットアップ | +|---------|------------| +| **Telegram** | 簡単（トークンのみ） | +| **Discord** | 簡単（Bot トークン + Intents） | + +
+Telegram（推奨） + +**1. Bot を作成** + +- Telegram を開き、`@BotFather` を検索 +- `/newbot` を送信、プロンプトに従う +- トークンをコピー + +**2. 設定** + +```json +{ + "channels": { + "telegram": { + "enabled": true, + "token": "YOUR_BOT_TOKEN", + "allowFrom": ["YOUR_USER_ID"] + } + } +} +``` + +> ユーザー ID は Telegram の `@userinfobot` から取得できます。 + +**3. 起動** + +```bash +picoclaw 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"] + } + } +} +``` + +**5. Bot を招待** +- OAuth2 → URL Generator +- Scopes: `bot` +- Bot Permissions: `Send Messages`, `Read Message History` +- 生成された招待 URL を開き、サーバーに Bot を追加 + +**6. 起動** + +```bash +picoclaw gateway +``` + +
+ +## 設定 (Configuration) + +PicoClaw は設定に `config.json` を使用します。 + +1. **設定ファイルの作成:** + + サンプル設定ファイルをコピーします: + + ```bash + cp config.example.json config/config.json + ``` + +2. **設定の編集:** + + `config/config.json` を開き、APIキーや設定を記述します。 + + ```json + { + "providers": { + "openrouter": { + "api_key": "sk-or-v1-..." + } + }, + "channels": { + "discord": { + "enabled": true, + "token": "YOUR_DISCORD_BOT_TOKEN" + } + } + } + ``` + +**3. 実行** + +```bash +picoclaw 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..." + } + } + } +} +``` + +
+ +## CLI リファレンス + +| コマンド | 説明 | +|---------|------| +| `picoclaw onboard` | 設定＆ワークスペースの初期化 | +| `picoclaw agent -m "..."` | エージェントとチャット | +| `picoclaw agent` | インタラクティブチャットモード | +| `picoclaw gateway` | ゲートウェイを起動 | +| `picoclaw status` | ステータスを表示 | + +## 🤝 コントリビュート＆ロードマップ + +PR 歓迎！コードベースは意図的に小さく読みやすくしています。🤗 + +Discord: https://discord.gg/V4sAZ9XWpN + +PicoClaw + + +## 🐛 トラブルシューティング + +### Web 検索で「API 配置问题」と表示される + +検索 API キーをまだ設定していない場合、これは正常です。PicoClaw は手動検索用の便利なリンクを提供します。 + +Web 検索を有効にするには： +1. [https://brave.com/search/api](https://brave.com/search/api) で無料の API キーを取得（月 2000 クエリ無料） +2. `~/.picoclaw/config.json` に追加： + ```json + { + "tools": { + "web": { + "search": { + "api_key": "YOUR_BRAVE_API_KEY", + "max_results": 5 + } + } + } + } + ``` + +### コンテンツフィルタリングエラーが出る + +一部のプロバイダー（Zhipu など）にはコンテンツフィルタリングがあります。クエリを言い換えるか、別のモデルを使用してください。 + +### Telegram Bot で「Conflict: terminated by other getUpdates」と表示される + +別のインスタンスが実行中の場合に発生します。`picoclaw gateway` が 1 つだけ実行されていることを確認してください。 + +--- + +## 📝 API キー比較 + +| サービス | 無料枠 | ユースケース | +|---------|--------|------------| +| **OpenRouter** | 月 200K トークン | 複数モデル（Claude, GPT-4 など） | +| **Zhipu** | 月 200K トークン | 中国ユーザー向け最適 | +| **Brave Search** | 月 2000 クエリ | Web 検索機能 | +| **Groq** | 無料枠あり | 高速推論（Llama, Mixtral） | diff --git a/README.md b/README.md index 2e4d8df..1a8b819 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,8 @@ License

+[日本語](README.ja.md) | **English** + --- @@ -118,6 +120,46 @@ make build-all make install ``` +## 🐳 Docker Compose + +You can also run PicoClaw using Docker Compose without installing anything locally. + +```bash +# 1. Clone this repo +git clone https://github.com/sipeed/picoclaw.git +cd picoclaw + +# 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 picoclaw-gateway + +# 5. Stop +docker compose --profile gateway down +``` + +### Agent Mode (One-shot) + +```bash +# Ask a question +docker compose run --rm picoclaw-agent -m "What is 2+2?" + +# Interactive mode +docker compose run --rm picoclaw-agent +``` + +### Rebuild + +```bash +docker compose --profile gateway build --no-cache +docker compose --profile gateway up -d +``` + ### 🚀 Quick Start > [!TIP] diff --git a/config.example.json b/config/config.example.json similarity index 100% rename from config.example.json rename to config/config.example.json diff --git a/config/config.openrouter.json b/config/config.openrouter.json new file mode 100644 index 0000000..4aca883 --- /dev/null +++ b/config/config.openrouter.json @@ -0,0 +1,86 @@ +{ + "agents": { + "defaults": { + "workspace": "~/.picoclaw/workspace", + "model": "arcee-ai/trinity-large-preview:free", + "max_tokens": 8192, + "temperature": 0.7, + "max_tool_iterations": 20 + } + }, + "channels": { + "telegram": { + "enabled": false, + "token": "YOUR_TELEGRAM_BOT_TOKEN", + "allow_from": [ + "YOUR_USER_ID" + ] + }, + "discord": { + "enabled": true, + "token": "YOUR_DISCORD_BOT_TOKEN", + "allow_from": [] + }, + "maixcam": { + "enabled": false, + "host": "0.0.0.0", + "port": 18790, + "allow_from": [] + }, + "whatsapp": { + "enabled": false, + "bridge_url": "ws://localhost:3001", + "allow_from": [] + }, + "feishu": { + "enabled": false, + "app_id": "", + "app_secret": "", + "encrypt_key": "", + "verification_token": "", + "allow_from": [] + } + }, + "providers": { + "anthropic": { + "api_key": "", + "api_base": "" + }, + "openai": { + "api_key": "", + "api_base": "" + }, + "openrouter": { + "api_key": "sk-or-v1-xxx", + "api_base": "" + }, + "groq": { + "api_key": "gsk_xxx", + "api_base": "" + }, + "zhipu": { + "api_key": "YOUR_ZHIPU_API_KEY", + "api_base": "" + }, + "gemini": { + "api_key": "", + "api_base": "" + }, + "vllm": { + "api_key": "", + "api_base": "" + } + }, + "tools": { + "web": { + "search": { + "api_key": "YOUR_BRAVE_API_KEY", + "max_results": 5 + } + } + }, + "gateway": { + "host": "0.0.0.0", + "port": 18790 + } +} \ No newline at end of file diff --git a/docker-compose.yml b/docker-compose.yml new file mode 100644 index 0000000..4876962 --- /dev/null +++ b/docker-compose.yml @@ -0,0 +1,40 @@ +services: + # ───────────────────────────────────────────── + # PicoClaw Agent (one-shot query) + # docker compose run --rm picoclaw-agent -m "Hello" + # ───────────────────────────────────────────── + picoclaw-agent: + build: + context: . + dockerfile: Dockerfile + container_name: picoclaw-agent + profiles: + - agent + volumes: + - ./config/config.json:/root/.picoclaw/config.json:ro + - picoclaw-workspace:/root/.picoclaw/workspace + entrypoint: ["picoclaw", "agent"] + stdin_open: true + tty: true + + # ───────────────────────────────────────────── + # PicoClaw Gateway (Long-running Bot) + # docker compose up picoclaw-gateway + # ───────────────────────────────────────────── + picoclaw-gateway: + build: + context: . + dockerfile: Dockerfile + container_name: picoclaw-gateway + restart: unless-stopped + profiles: + - gateway + volumes: + # Configuration file + - ./config/config.json:/root/.picoclaw/config.json:ro + # Persistent workspace (sessions, memory, logs) + - picoclaw-workspace:/root/.picoclaw/workspace + command: ["gateway"] + +volumes: + picoclaw-workspace: