5分でできる！PicoClawでClaude CodeをClaw化してみた

Posted at 2026-03-07

はじめに

Claude Codeはターミナルで動く強力なAIコーディングエージェントです。ただし、使えるのはターミナルの前にいるときに限られます。「外出先からTelegramで指示を飛ばしたい」「定期的にリポジトリの状態をチェックさせたい」と思ったことはないでしょうか。

PicoClawを使えば、Claude Codeを「Claw化」できます。TelegramやLINEから指示を送り、ファイル操作やコード生成を自律的に実行させる構成が手に入ります。やることは「バイナリをダウンロード → config.jsonを編集 → 起動」の3ステップだけ。5分もあれば動きます。

この記事では、PicoClawのclaude-cliプロバイダーを使います。Claude Codeをメッセージングアプリから呼び出せるエージェントにする手順を、コピペ可能な設定ファイル付きで解説します。

この記事でわかること

PicoClawのアーキテクチャと設計思想
Claude Codeをclaude-cliプロバイダーで接続する仕組み
TelegramからClaude Codeを操作する具体的なセットアップ手順
HEARTBEAT.mdによる自律タスクの定期実行
セキュリティ設計とサンドボックス機構

PicoClawとは

PicoClawは、Sipeed社が開発したGo製の超軽量AIエージェントランタイムです。OpenClawに着想を得たPython実装「NanoBot」（香港大学 Data Intelligence Lab）をさらにGoでゼロから書き直したものです。

特徴は、圧倒的な軽さです。以下はPicoClaw公式READMEの比較表に基づく数値です。

項目	OpenClaw	NanoBot	PicoClaw
言語	TypeScript	Python	Go
メモリ使用量	1GB超	100MB超	10MB未満（※）
起動時間（0.8GHzコア）	500秒超	30秒超	1秒未満
バイナリ形態	Node.js（≥22）必要	Pythonランタイム必要	シングルバイナリ
対応アーキ	x86_64, ARM64	x86_64, ARM64	x86_64, ARM64, ARM32, MIPS, RISC-V
最小ハードウェア	PC / サーバー	PC / サーバー	$10のRISC-Vボード

※ 10MB未満はPicoClawの初期コンセプト値です。最近のバージョンでは機能追加により10〜20MB程度になる場合があります。

OpenClawが「フル装備のプラットフォーム」、NanoBotが「学習用の最小フレームワーク」だとすれば、PicoClawは「有用なAIエージェントを動かすのに必要な最小限のハードウェアは何か」への回答です。$9.99のLicheeRV-NanoやRaspberry Pi Zero 2 Wでも動作します。

アーキテクチャ概要

PicoClawは4層のレイヤー構造を持っています。

各層の役割は以下の通りです。

チャンネル層: メッセージングプラットフォームとの接続を抽象化します。Telegram、LINE、Discord等13以上に対応しています。
Gateway層: 統一HTTPサーバー（デフォルト127.0.0.1:18790）として全チャンネルを処理します。個別ポートは不要です。
プロバイダー層: LLMバックエンドへのルーティングを担います。vendor/modelプレフィックスで自動選択されます。
ツール層: ToolRegistryがツールを管理します。RunToolLoop()がLLM呼び出しとツール実行を駆動します。

Claude CodeをClaw化する

PicoClawでClaude Codeを使う鍵はclaude-cliプロバイダーです。Claude Code CLIをサブプロセスとして起動し、PicoClawのエージェントループから制御する仕組みです。

claude-cliプロバイダーの動作

claude-cliプロバイダーはclaudeコマンドを以下のフラグ付きで起動します。

-p（プロンプトモード）
--output-format json
--dangerously-skip-permissions
--no-chrome

システムプロンプトは--system-promptフラグで渡します。ユーザーメッセージはstdin経由で渡されます。

これにより、Claude Code CLIのネイティブ能力をPicoClawから利用できます。ファイル操作、コード生成、テスト実行、Web検索などが対象です。

3層ツール構造

claude-cliプロバイダーを使う場合、3つのレイヤーのツールが利用可能になります。

層	ツール例	特徴
第1層: ビルトイン	`read_file`, `exec`, `web_search`, `spawn`	Go実装。サンドボックス付き
第2層: MCP	外部MCPサーバー経由のツール	`mcp_{server}_{tool}`形式で自動登録
第3層: Claude Code	`Read`, `Bash`, `Grep`, `WebSearch`等	Claude Code CLI内蔵のツール群

claude-cliプロバイダー経由の場合、第3層が主に使われます。PicoClawのビルトインツール定義はシステムプロンプトに注入される形で補完されます。

セットアップ手順

ここからは、PicoClawでClaude CodeをTelegramから操作する環境を構築していきます。

前提条件

Claude Code CLIがインストール済みで、claudeコマンドが使えること
Anthropic APIキーまたはClaude Codeの認証が済んでいること

Step 1: PicoClawのインストール

GitHub Releasesからプレビルドバイナリをダウンロードします。

# macOS (Apple Silicon)
curl -L https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw-darwin-arm64 -o picoclaw
chmod +x picoclaw
sudo mv picoclaw /usr/local/bin/

# macOS (Intel)
curl -L https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw-darwin-amd64 -o picoclaw
chmod +x picoclaw
sudo mv picoclaw /usr/local/bin/

# Linux (x86_64)
curl -L https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw-linux-amd64 -o picoclaw
chmod +x picoclaw
sudo mv picoclaw /usr/local/bin/

インストールを確認します。

picoclaw --version

Step 2: 初期セットアップ

onboardコマンドで設定ファイルとワークスペースを生成します。

picoclaw onboard

以下のファイルとディレクトリが作成されます。

~/.picoclaw/
├── config.json          # メイン設定ファイル
└── workspace/
    ├── sessions/        # 会話履歴
    ├── memory/          # 長期記憶（MEMORY.md）
    ├── state/           # 状態管理
    ├── cron/            # スケジュールジョブ
    ├── skills/          # カスタムスキル
    ├── AGENTS.md        # エージェント行動指針
    ├── HEARTBEAT.md     # 定期タスク定義
    ├── IDENTITY.md      # エージェントID
    ├── SOUL.md          # 人格設定
    ├── TOOLS.md         # ツール使用ガイド
    └── USER.md          # ユーザー設定

Step 3: config.jsonの設定

~/.picoclaw/config.jsonを以下のように編集します。ポイントはmodel_listにclaude-cli/claude-codeを指定する点です。

~/.picoclaw/config.json

{
  "agents": {
    "defaults": {
      "workspace": "~/.picoclaw/workspace",
      "restrict_to_workspace": true,
      "model_name": "claude-code",
      "max_tokens": 32768,
      "max_tool_iterations": 50
    }
  },
  "model_list": [
    {
      "model_name": "claude-code",
      "model": "claude-cli/claude-code",
      "workspace": "~/my-project"
    }
  ],
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "YOUR_TELEGRAM_BOT_TOKEN",
      "allow_from": ["YOUR_TELEGRAM_USER_ID"]
    }
  },
  "tools": {
    "exec": {
      "enable_deny_patterns": true
    }
  },
  "heartbeat": {
    "enabled": true,
    "interval": 30
  },
  "gateway": {
    "host": "127.0.0.1",
    "port": 18790
  }
}

allow_fromには自分のTelegram User IDを設定してください。空配列[]にすると誰でもBotを操作できる状態になります。

model_listのworkspaceには、Claude Codeに操作させたいプロジェクトディレクトリのパスを指定します。

Step 4: Telegram Botの作成

Telegramで@BotFatherを開く
/newbotコマンドを送信
Bot名とユーザー名を入力
発行されたトークンをconfig.jsonのchannels.telegram.tokenに設定

自分のUser IDは@userinfobotにメッセージを送ると確認できます。

Step 5: CLIモードで動作確認

Gatewayを起動する前に、CLIモードで動作確認します。

picoclaw agent -m "Hello, what can you do?"

Claude Codeが応答すれば、プロバイダーの設定は正しいです。

Step 6: Gatewayの起動

picoclaw gateway

PicoClawのTelegramチャンネルはlong polling（getUpdates）方式で動作します。Webhook設定やngrokは不要です。picoclaw gatewayを起動するだけでBotがメッセージを受信し始めます。

LINE等のWebhookベースのチャンネルを使う場合は、ngrok等でWebhook URLを公開する必要があります。例: https://<ドメイン>/webhook/line。Telegramではこの手順は不要です。

Step 7: 動作確認

Telegramで作成したBotにメッセージを送信します。

このプロジェクトのディレクトリ構成を教えて

Claude Codeがワークスペース内のファイルを探索し、結果をTelegram経由で返せば成功です。

ハートビートで自律タスク

PicoClawには「ハートビート」機能があります。HEARTBEAT.mdに書いたタスクを、設定間隔ごとに自動実行する仕組みです。デフォルトは30分間隔です。

HEARTBEAT.mdの記述例

~/.picoclaw/workspace/HEARTBEAT.md

# 定期タスク

## リポジトリ状態チェック
- ~/my-project の git status を確認する
- コミットされていない変更があれば報告する

## テスト実行
- ~/my-project でテストスイートを実行する
- 失敗したテストがあれば内容を報告する

## 依存関係の更新確認
- package.json の依存関係に既知の脆弱性がないか確認する

ハートビートの間隔はconfig.jsonのheartbeat.interval（分単位、最小5分）で設定します。

長時間タスクはspawnツールで独立サブエージェントとして生成されます。サブエージェントは非同期で実行されます。完了時にmessageツールでユーザーに直接通知します。親のハートビートループはブロックされません。

セキュリティ設計

外部からClaude Codeを操作できる以上、セキュリティ設計は極めて重要です。PicoClawは複数のレイヤーで防御を行います。

PicoClawは現在活発に開発中です。公式READMEでもv1.0リリース前のプロダクション利用は非推奨とされています。検証目的での利用をおすすめします。

ワークスペースサンドボックス

restrict_to_workspace: true（デフォルト有効）を設定すると、全てのファイル操作とシェル実行がワークスペース内に制限されます。絶対パスによるワークスペース外アクセスは検知・ブロックされます。

危険コマンドブロッキング

enable_deny_patterns: true（デフォルト有効）を設定すると、40以上の正規表現パターンで危険なコマンドがブロックされます。

カテゴリ	ブロック例
ファイル破壊	`rm -rf`, `format`, `mkfs`, `dd if=`
システム操作	`shutdown`, `reboot`, `sudo`, `chmod`
インジェクション	`$()`, バッククォート展開, `\| sh`
パッケージ管理	`npm install -g`, `pip install --user`
リモート操作	`git push`, `git force`, `ssh`
危険なダウンロード	`curl \| sh`, `wget \| bash`

カスタムパターンの追加も可能です。

"exec": {
  "enable_deny_patterns": true,
  "custom_deny_patterns": ["\\bmy_dangerous_cmd\\b"],
  "custom_allow_patterns": ["\\bgit\\s+status\\b"]
}

チャンネルレベルのアクセス制御

各チャンネルのallow_fromにユーザーIDのホワイトリストを設定できます。自分のUser IDのみを許可すれば、第三者からのメッセージは無視されます。

クイックスタートまとめ

ゼロからTelegram経由でClaude Codeを動かすまでの全手順をまとめます。以下をそのまま実行すれば構築できます。

1. インストール

# macOS (Apple Silicon) の場合
curl -L https://github.com/sipeed/picoclaw/releases/latest/download/picoclaw-darwin-arm64 -o picoclaw
chmod +x picoclaw && sudo mv picoclaw /usr/local/bin/
picoclaw onboard

2. config.jsonを配置

以下を~/.picoclaw/config.jsonにコピーしてください。3箇所を自分の値に置き換えます。

~/.picoclaw/config.json

{
  "agents": {
    "defaults": {
      "workspace": "~/.picoclaw/workspace",
      "restrict_to_workspace": true,
      "model_name": "claude-code",
      "max_tokens": 32768,
      "max_tool_iterations": 50
    }
  },
  "model_list": [
    {
      "model_name": "claude-code",
      "model": "claude-cli/claude-code",
      "workspace": "~/my-project"
    }
  ],
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "<STEP3で取得するBotトークン>",
      "allow_from": ["<STEP3で取得するUser ID>"]
    }
  },
  "tools": {
    "exec": {
      "enable_deny_patterns": true
    }
  },
  "heartbeat": {
    "enabled": false
  },
  "gateway": {
    "host": "127.0.0.1",
    "port": 18790
  }
}

workspaceにはClaude Codeに操作させたいプロジェクトのパスを指定します。heartbeatは動作確認後にtrueに変更することをおすすめします。

3. Telegram Botを作成しトークンとUser IDを取得

1. @BotFather に /newbot を送信 → Botトークンを取得
2. @userinfobot にメッセージ送信 → User IDを取得
3. 取得した値を config.json に記入

4. CLIモードで動作確認

picoclaw agent -m "プロジェクトの構成を教えて"

5. Gatewayを起動

picoclaw gateway

Telegramはlong polling方式のため、これだけでBotが動き始めます。ngrokやWebhookの設定は不要です。

6. Telegramからメッセージを送信

Botにメッセージを送れば、Claude Codeが応答します。

まとめ

PicoClawのclaude-cliプロバイダーを使えば、Claude Codeをターミナルの外に連れ出せます。メモリ10〜20MB程度、起動1秒未満で動作します。TelegramやLINEからいつでもClaude Codeに指示を送れるようになります。

ポイントを整理します。

PicoClawはGo製のシングルバイナリで、ランタイム依存がない
claude-cli/claude-codeプロバイダーがClaude Code CLIをサブプロセスとして制御する
3層のツール構造（ビルトイン + MCP + Claude Codeネイティブ）で柔軟に拡張できる
HEARTBEAT.mdで定期的な自律タスクを実行できる
サンドボックスと危険コマンドブロッキングでセキュリティを確保している

今回はTelegramを例にしました。LINE、Discord、Slack等13以上のチャンネルに同じ仕組みで対応できます。自宅のRaspberry Piに常駐させれば、外出先からClaude Codeを呼び出せる開発環境が手に入ります。

参考リンク

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up