拍板 Paiban

拍板 取扱説明書

このマニュアルでは、板板（デバイス）、拍板 Hub（PC 版）、拍板ミニプログラム（WeChat）、クラウド中継のすべての機能を説明します。初めて使うときは 1〜4 章を順に読み、あとは必要なときに参照してください。

Hub とデバイスの画面は現在中国語です。探す必要のある項目には中国語の表記を「」で併記しています。

1. 拍板とは

Claude Code や Codex などの AI エージェントは、作業の途中で「このコマンドを実行していい？」「このファイルを変えていい？」とたびたび止まります。拍板はその質問を机の上の板板に届けます。板板は光ってあなたを見つめ、クリックで承認、傾けて拒否。作業が終わればうれしそうな顔で知らせてくれます。ターミナルを見張る必要はもうありません。

部品 内容 場所
板板 机の上の小さなデバイス：1.47 インチ画面、ボタン 1 つ、姿勢センサー、RGB ライト Waveshare ESP32-S3-LCD-1.47B + 3D プリントケース
拍板 Hub PC アプリ：各エージェントのイベントを受け取って板板に送り、あなたの決定を返す Windows（インストール不要の zip）
拍板ミニプログラム WeChat ミニプログラム：アカウント、板板の Wi-Fi 設定、リマインダー、ひとこと質問、PC の紐付け WeChat
クラウド中継 PC と板板が別のネットワークにあるときに転送 Azure 香港 
Claude Code / Codex / Qwen / Kimi / Gemini
        │ hooks（ローカル）
        ▼
   拍板 Hub（PC）── LAN / クラウド中継 ──▶ 板板
                                          ▲ Bluetooth
                                  拍板ミニプログラム

2. 用意するもの

3. インストール

最新版はプロジェクトサイトと Releases にあります。

3.1 ファームウェアの書き込み

初回はフルイメージ paiban-firmware-v*-merged.bin（16 MB、パーティションテーブル込み）：

pip install esptool
esptool.py --chip esp32s3 --baud 921600 write_flash 0x0 paiban-firmware-v0.5.1-merged.bin

以降のアップデートは -app.bin を 0x10000 に書き込みます。Wi-Fi、リマインダー、設定、アカウントの紐付けはそのまま残ります：

esptool.py --chip esp32s3 --baud 921600 write_flash 0x10000 paiban-firmware-v0.5.1-app.bin

PC がボードを認識しないときは、BOOT を押しながら USB を挿してダウンロードモードに入ります。書き込み後は RST を押すか挿し直してください。

3.2 Hub のインストール

  1. paiban-hub-v*-win-x64.zip をダウンロードし、決まった場所に展開します（例：D:\paiban-apps\PaibanHub）。
  2. PaibanHub.exe を起動。「PC が保護されました」と出たら「詳細情報 → 実行」（まだコード署名していません）。
  3. 初回起動でスタートメニューにショートカットが作られ、既定で Windows 起動時に自動起動します（設定で変更可）。

アップデート：Hub を終了（トレイアイコンを右クリック →「退出」）し、新しいバージョンでフォルダごと上書きして起動します。設定とログイン情報は %APPDATA%\拍板 Hub にあり、消えません。

3.3 ミニプログラム

正式公開までは、WeChat 開発者ツールでリポジトリの miniapp/ を読み込み、「プレビュー」でスマホから開きます。アカウントとクラウド中継にはクラウド開発が必要です（miniapp/README.ja.md を参照）。

4. 初期設定

  1. 板板の電源を入れる：画面に設定用の QR コードが出て、ライトが白くゆっくり点滅します。
  2. ミニプログラムで Wi-Fi 設定：「我的 → 添加设备」（デバイス追加）で板板の画面の QR を読み取る（または一覧から BANBAN-xxxx を選ぶ）。Wi-Fi 名とパスワードを入れ、まず「测试连接」（接続テスト）を押すと、板板が実際に接続を試し、パスワード違い・ネットワークが見つからない・電波が弱いなどを教えてくれます。
  3. PC を自動で見つける：同じ Wi-Fi なら Hub が 2 秒ごとに LAN でブロードキャストし、板板が自動で接続します。画面左上の点が緑になります。
  4. 見つからない場合、ルーターが端末間通信を遮断している可能性があります（ゲストネットワークなど）。ミニプログラムで PC のアドレスを手動にし、Hub の概要ページに表示されるアドレス（例 192.168.1.20:8765）を入力します。
  5. エージェントを接続：Hub の「接入 agent」で Claude Code などの「接入」（接続）を押します。
  6. 試す：Hub の概要ページ下の「测试审批」（承認テスト）。板板に承認が出るのでクリックして承認します。

5. エージェントの接続

Hub の「接入 agent」ページでワンクリック。Hub が各クライアントの設定ファイルに hooks を書き込みます。書き込む前に自動でバックアップし、「撤销」（取り消し）は拍板が書いた行だけを削除します。もとの設定には触れません。

クライアント 設定ファイル 承認 注意
Claude Code ~/.claude/settings.json 完全：板板での承認・拒否がそのまま有効。「PC に戻す」とターミナルでいつもどおり確認 バックグラウンド実行（claude -p）には確認画面がないため、起動前に環境変数 PAIBAN_HEADLESS_APPROVE=1 を設定すると、ファイル変更とコマンド実行が板板の承認に回ります
Codex ~/.codex/hooks.json 完全 接続後、Codex で /hooks と入力して拍板の hooks を一度信頼してください
Qwen Code ~/.qwen/settings.json 完全
Kimi Code ~/.kimi-code/config.toml ブロックのみ：板板で拒否すると止められます。承認後も Kimi 自身の確認が出ることがあります --yolo と組み合わせると快適。読み取り専用のコマンドは邪魔しません
Gemini CLI ~/.gemini/settings.json ブロックのみ Kimi と同じ

ほかのプログラムからも使えます：

# 通知を送る
curl -X POST http://127.0.0.1:8765/notify -d '{"title":"バックアップ完了","body":"12 GB","agent":"nightly"}'
# 承認を求めて結果を待つ：allow / deny / defer（defer = PC に戻した、またはタイムアウト）
curl -X POST http://127.0.0.1:8765/approve -d '{"agent":"deploy","summary":"本番に公開","detail":"v2.3.1","timeout":120}'

6. 板板の使い方

6.1 ボタン 1 つと姿勢

画面は横向き、USB 端子が右側です。ボタンは BOOT だけです。

画面 クリック ダブルクリック 長押し ジェスチャー
時計 / エージェント / デバイス 次のページ 前のページ おやすみモード（デバイスページ：設定 QR） 伏せる = おやすみモード；叩く・振る・持ち上げると板板が反応します（6.7）
承認待ち 承認 拒否 PC に戻す まず水平に置き、右に約 20° 傾けて 1 秒保つ = 承認、左 = 拒否
アカウント紐付けの確認 同意 拒否 — 右 = 同意、左 = 拒否
リマインダー 完了 — 10 分後に再通知 振る = 10 分後
通知 閉じる / 次へ すべて消す — —
回答 次のページ 閉じる — —
遊びモード 別の技 時計に戻る 時計に戻る 傾けると転がる、振ると目が回る、3 回叩くとハートの目

60 秒操作がないと画面が暗くなります（板板が眠そうになります）。承認やリマインダーが来ると明るくなります。電池駆動時はさらに省電力：30 秒で暗くなり、3 分で画面が消えます。ボタン・持ち上げる・叩く・承認ですぐに点きます（6.8）。

傾けて承認の誤動作対策：承認が表示されたら、まず板板が水平で静止した状態になってから傾きが有効になります。傾けたら（既定は約 20°）1 秒しっかり保ちます（途中で揺れたり、直前に振ったり叩いたりするとやり直し）。左右の傾きだけを認識し、前後（持ち上げて見るなど）は無視します。一度決めたら水平に戻すまで次は効きません。ミニプログラムの「设置 → 倾斜灵敏度」で、敏感（15°・0.8 秒）／標準（20°・1 秒）／鈍い（28°・1.3 秒）を選べます。傾きをオフにしてボタンだけにもできます。

6.2 4 つのページ

6.3 表情とライト

表情 意味 ライト
ぼんやり、ときどきまばたき 待機 うっすら青緑
目を細めてうなずく エージェントが作業中 青くゆっくり点滅
じっと期待のまなざし 承認待ち 琥珀色の速い点滅
汗をかく 承認がもうすぐタイムアウト 琥珀色の速い点滅
うれしい 作業完了 緑
涙 エラー 赤くゆっくり点滅
しょんぼり 拒否された —
寝ている おやすみモード / 画面が暗い 消灯
灰色の目に「？」 PC が見つからない —
— リマインダーが鳴っている 紫にゆっくり点滅

6.4 承認

6.5 通知・リマインダー・ひとこと質問

6.6 おやすみモード

時計ページで BOOT を長押し、板板を伏せる、またはミニプログラムでオン。ライトは消え、通知は表示されません。承認はいつもどおり表示されます（でないとエージェントが止まってしまうため）。

6.7 板板の気分

板板には気分があり、待機中の表情が一日中同じではなくなりました。

ミニプログラムのホームに今の気分が表示されます。ファームウェア 0.7、Hub 0.4 以降が必要です。

6.8 省電力（電池駆動）

ミニプログラム「设置 → 省电」（設定 → 省電力）で 3 段階：電池のとき省電力（既定）、常に省電力、省電力しない。

PC に接続中 省電力時
暗くする 60 秒操作なし 30 秒操作なし。CPU 80 MHz、10 フレーム/秒
画面オフ しない 3 分操作なし：バックライト・画面・ライトをオフ、Wi-Fi を深い省電力に（メッセージが数百ミリ秒遅れる）
復帰 ボタン、叩く、振る、持ち上げる。承認・リマインダー・通知・回答で自動 同じ

電池残量 3% 未満が 2 分続くと、電池保護のためディープスリープに入ります。充電後に BOOT を押すと復帰します。

7. PC 版 Hub

ウィンドウを閉じるとタスクトレイにしまわれます（設定で「閉じたら終了」にも変更可）。トレイアイコンは状態によって変わります（未起動 / デバイス待ち / デバイス接続中 / 承認待ち）。マウスを乗せると詳細、右クリックでテスト通知や終了ができます。

7.1 概要（「概览」）

7.2 エージェント接続（「接入 agent」）

5 章を参照。各カードに、コマンドが見つかったか、設定ファイルの場所、承認の種類、注意事項が出ます。「打开位置」でエクスプローラーで開きます。

7.3 アカウント（「账号」）

クラウド中継へのログイン / ログアウトと、アカウントのデバイス管理。9 章を参照。

7.4 アクティビティ（「动态」）

直近 500 件のイベント：エージェントのイベント、承認、デバイスの接続・切断、エラー。承認 / デバイス / 問題で絞り込めます。

7.5 設定（「设置」）

設定 既定値 内容
クラウド中継 オン ログイン時のみ有効。オフ = LAN のみ
中継サーバー 公式アドレス 通常は変更不要。変えると再ログインが必要
ポート 8765 エージェントの hooks と板板が使用。変えたら各クライアントを再書き込み
承認待ちの時間 90 秒 15〜570 秒。過ぎると PC に戻す
Kimi / Gemini を承認に回す オン オフ = 通知のみ
デバイスがないとき PC で承認 オフ オン = 板板がオフラインのとき Hub の画面に承認を表示
システム通知 オン ウィンドウが背面のとき承認を Windows 通知で知らせる
既定で答えるエージェント Claude Code ミニプログラムで選んでいないときに使います。未インストールなら最初にインストールされているもの
エージェントごとのコマンド claude -p、codex exec --skip-git-repo-check -、gemini、qwen、kimi --print 「ひとこと質問」用。質問は標準入力で渡し、答えは標準出力から取ります
外観 システムに合わせる ライト / ダーク
Windows 起動時に開始 オン トレイで起動
閉じたらトレイへ オン

8. ミニプログラム

ページ 機能
设备（デバイス） いまの板板の状態、承認待ち（スマホでも承認可）、エージェント一覧、最新の通知。デモボタン（PC なしで板板の反応を確認）、遊びモード、複数台の切り替え
提醒（リマインダー） リマインダーの追加・編集・削除。板板に書き込み
问一句（ひとこと質問） エージェントに質問、履歴
我的（マイページ） WeChat ログイン、アイコンとニックネーム、デバイス一覧（名前変更・切り替え・削除）、PC とクラウド中継、利用統計
設定（我的 → 设备设置） 明るさ、画面 180° 回転、タイムゾーン、遊びモード、傾けて承認、傾き方向の反転、伏せておやすみ、おやすみモード、「正位置」の校正、Wi-Fi、クラウド中継、ピンの再検出、再起動、工場出荷時リセット

ミニプログラムと板板は Bluetooth でつながるので、スマホは板板の近く（約 10 m 以内）に置いてください。

9. 別のネットワーク：クラウド中継

会社の PC と自宅の板板、テザリング中の PC、将来の 4G 版などはクラウド中継を使います。手順の詳細とセキュリティは クラウド中継ガイド を参照。概要：

  1. PC をログイン（PC ごとに 1 回）：Hub の「账号 → 登录」で QR コードを表示し、ミニプログラムの「我的 → 电脑与云端中转 → 扫码绑定电脑」で読み取ります。
  2. 板板を紐付け（デバイスごとに 1 回）：Hub のアカウントページの「绑定到账号」、またはミニプログラムで Wi-Fi 設定後に紐付け。板板の上で確認が必要です。
  3. 以降は自動で経路を選びます。同じ Wi-Fi なら LAN、そうでなければ中継。承認が二重に出ることはありません。
  4. ログアウト / 解除：Hub の「账号 → 登出」。スマホから PC や板板をリモートで解除できます。

中継サーバーは複数レプリカで動いています。サーバーの更新時は 1〜2 秒で別のレプリカに接続が移り、板板に切断は表示されず、その間の承認もあとで届きます。

10. アップデート・リセット・移行

11. トラブルシューティング

板板が「正在找拍板 Hub」（Hub を探しています）のまま - Hub は起動していますか（トレイにアイコンがあるか）。 - 同じ Wi-Fi ですか。ゲストネットワークや AP 分離はブロードキャストを遮断します → Hub のアドレスを手動入力。 - 初回は Windows ファイアウォールが PaibanHub のネットワーク利用を確認します。「プライベート ネットワーク」を許可してください。

エージェントが確認してくるのに板板が反応しない - 「接入 agent」でそのクライアントが接続済みになっていますか。Codex は /hooks で一度信頼が必要です。 - 板板がおやすみモード？（承認は表示されますがライトは点きません） - Hub の「动态」にイベントが出ていますか。出ていなければ「重新写入」。

Wi-Fi テストで「ネットワークが見つからない」：板板は 2.4 GHz のみ対応です。デュアルバンドルーターでは 2.4 GHz に別の名前を付けてください。

傾きの左右が逆：ミニプログラム「设置 → 倾斜方向反过来」（反転）、または「校准正放」（校正）。

「ひとこと質問」でコマンド失敗と出る：Hub の設定にあるそのエージェントのコマンドがターミナルで実行できるか確認してください（例：echo hi | claude -p）。

「ひとこと質問」が「思考中」のまま、またはログインしていないと出る：コマンドライン版の Claude Code / Codex はターミナルで一度ログインが必要です。デスクトップ版のログインは共有されません。

電池が「未检测到」（未検出）：電池なしなら正常。電池をつないでいるのにそう出る場合は「重新识别引脚」（ピンの再検出）。

クラウド中継について：クラウド中継ガイド · よくある質問 を参照。

12. データとプライバシー