winds.from.oz 技術メモ

PicoClawを最初に動かすまでのメモ

Posted:

PicoClawを最初に動かすまでのメモ

PicoClaw は設定項目が多いが、最初は全部を理解しなくても動かせる。

この記事では、次の流れだけに絞る。

  1. PicoClaw を用意する
  2. ~/.picoclaw/config.json を作る
  3. モデルを 1 つ設定する
  4. 必要なら Slack を 1 つつなぐ
  5. picoclaw gateway を起動する
  6. DM またはメンションで疎通確認する

1. PicoClaw を用意する

ソースから使うなら、まずリポジトリを取得してビルドする。

git clone https://github.com/sipeed/picoclaw.git
cd picoclaw
make deps
make build

インストール済みの picoclaw バイナリを使うなら、この段階は省略できる。

2. 初期ファイルを作る

最初に設定ファイルと workspace を作る。

picoclaw onboard

これで通常は次が作られる。

  • ~/.picoclaw/config.json
  • ~/.picoclaw/workspace/

workspace 配下には、AGENT.md や USER.md、skills/ などのベースファイルが入る。

3. 最小の config.json を書く

最初は API で使うモデルを 1 つだけ定義すれば十分だ。

{
  "agents": {
    "defaults": {
      "workspace": "~/.picoclaw/workspace",
      "restrict_to_workspace": true,
      "model_name": "gpt-5.4"
    }
  },
  "model_list": [
    {
      "model_name": "gpt-5.4",
      "model": "openai/gpt-5.4",
      "api_key": "sk-your-openai-key",
      "api_base": "https://api.openai.com/v1"
    }
  ]
}

ここで大事なのは次の3つ。

  • model_list にモデルを定義する
  • agents.defaults.model_name を合わせる
  • restrict_to_workspace: true を維持する

4. CLI で先に動作確認する

チャネル連携の前に、まずは CLI だけで 1 回動かす方が切り分けしやすい。

picoclaw agent -m "こんにちは"

ここで返答があれば、少なくともモデル設定と PicoClaw 本体の流れは通っている。

チャネル連携まで一気に進めるより、先にここを通しておく方が安全だと思う。

5. Slack をつなぐ場合の最小例

Slack をつなぐなら、channel_list.slack を追加する。PicoClaw 0.2.8 では Slack token は settings 配下に置く。

{
  "agents": {
    "defaults": {
      "workspace": "~/.picoclaw/workspace",
      "restrict_to_workspace": true,
      "model_name": "gpt-5.4"
    }
  },
  "model_list": [
    {
      "model_name": "gpt-5.4",
      "model": "openai/gpt-5.4",
      "api_key": "sk-your-openai-key",
      "api_base": "https://api.openai.com/v1"
    }
  ],
  "channel_list": {
    "slack": {
      "enabled": true,
      "type": "slack",
      "allow_from": [
        "U0123456789"
      ],
      "reasoning_channel_id": "",
      "settings": {
        "bot_token": "xoxb-YOUR-BOT-TOKEN",
        "app_token": "xapp-YOUR-APP-TOKEN"
      }
    }
  }
}

最初は次だけ守ればよい。

  • bot_token と app_token の両方を入れる
  • token は channel_list.slack.settings 配下に置く
  • allow_from に自分の Slack User ID を入れる
  • 実トークンや実 ID は記事やメモに貼らない

Slack App の作り方や権限は、別記事の設定メモ側に詳しくまとめてある。

DM を使う場合は、Slack App 側で App Home の Messages tab も有効にする。PicoClaw 用 manifest では次の設定にする。

{
  "features": {
    "app_home": {
      "home_tab_enabled": false,
      "messages_tab_enabled": true,
      "messages_tab_read_only_enabled": false
    }
  }
}

あわせて Bot OAuth scopes に chat:write と im:history、event subscription に message.im が必要。messages_tab_enabled が無い、または messages_tab_read_only_enabled が true の場合、Slack UI からアプリへ DM を送れないことがある。

6. Gateway を起動する

チャネル連携は gateway を起動して使う。

picoclaw gateway

ログを詳しく見たいなら次でよい。

picoclaw gateway --debug

7. 起動時に見るポイント

Slack 連携なら、ログに次が出るかをまず見る。

  • Starting Slack channel (Socket Mode)
  • Slack bot connected
  • Slack channel started (Socket Mode)

ここまで出ていれば、Slack 接続自体は通っていると考えてよい。

systemd 常駐化している場合は、まず service と health endpoint を見る。

systemctl status picoclaw-gateway.service --no-pager -l
curl -fsS http://127.0.0.1:18790/health

/ready は PicoClaw の内部判定により 503 になることがあるため、Slack の token 疎通は Slack API でも切り分ける。

bot=$(jq -r '.channel_list.slack.settings.bot_token' ~/.picoclaw/config.json)
app=$(jq -r '.channel_list.slack.settings.app_token' ~/.picoclaw/config.json)
curl -fsS -H "Authorization: Bearer ${bot}" https://slack.com/api/auth.test
curl -fsS -X POST -H "Authorization: Bearer ${app}" https://slack.com/api/apps.connections.open

8. 最初の疎通確認

Slack 側では、まず DM かメンションで短い文を送る。

9. うまくいかないときの見方

最初に見るポイントは次の順が分かりやすい。

  1. picoclaw agent -m "こんにちは" が通るか
  2. picoclaw gateway --debug のログに接続成功が出るか
  3. channel_list.slack.settings に token が入っているか
  4. allow_from に自分の ID が入っているか
  5. Slack App 側の Socket Mode、App Home Messages tab、権限が正しいか

CLI で失敗するなら Slack ではなく PicoClaw 本体の問題、CLI は通るのに Slack だけ失敗するならチャネル設定の問題と切り分けやすい。

10. 最初は小さく始める

最初から全部盛りにしない方がよい。

おすすめの順番は次のとおり。

  1. モデル 1 個だけ設定する
  2. CLI で応答確認する
  3. Slack などチャネルを 1 つだけ有効化する
  4. allow_from で自分だけに制限する
  5. 慣れてきたらスキルや Web 検索を増やす

この流れなら、どこで壊れたかが追いやすい。

関連記事