メンバー限定 ─ 導入ガイド

voice-agent 導入編
受け取ってから、声で開発が始まるまで

zip を開いてから、自分のPCに向かって喋ると Claude Code が動く状態になるまでの全手順。

この回のゴール

見終わったら、自分のPCに向かって喋ると Claude Code が動く状態になっている。

最初に言う2つ（脱落率がいちばん下がる）

  1. Anthropic の APIキーは要らない — ターミナルで claude が動く状態なら、その資格情報をそのまま使う
  2. OpenAI のキーが無くても、動くところまでは確認できる — 音声だけが無効になる作り。お金を使う前に「自分のPCで動くか」を確かめられる

STEP 0受け取り方とアップデート

メンバーシップ版買い切り版
受け取る場所Discord の 📦配布物note の販売記事
更新在籍中ずっと最新版が届く購入時点の版（以後の更新は含まない）
質問Discord の質問部屋個別サポートなし
解約・期限解約後も受け取った版はそのまま使える期限なし
ライセンスを1回だけ、はっきり言う 受け取った本人が使う・改変するのは自由。ただし再配布・転載・販売はできない（改変したものも同じ）。
免責：これは声での指示で Claude Code にファイルの読み書きとコマンド実行をさせるもの。 重要なデータはバックアップを取り、git で管理されたフォルダで使うこと。

STEP 1前提を確認する（動かない環境がある）

環境状態
macOS 14 以降全機能（想定している環境）
Windows 11 / Linux（x64・arm64）会話と開発作業は動く。PC操作と doctor の macOS権限2項目は使えない
Windows on ARM / Alpine Linux⚠ 非対応（sqlite-vec のバイナリが無く、サーバが起動しない）

必要なもの（1つずつコマンドで確認して見せる）：

ネイティブのコンパイルは走らない（依存はすべてビルド済み）。

STEP 2OpenAI の APIキーを取る

  1. 「Create new secret key」を押す
  2. 作った直後の1回しか全体を見られない。その場でコピーする
  3. 支払い方法の登録が要る
  4. gpt-realtime が使えないと言われたら、組織の本人確認（Verify Organization）
★必ず言う このキーを、AIのチャット欄に貼って「設定して」とお願いしないこと。 自分の手で .env に書く。

STEP 3入れる（4コマンド）

corepack enable              # pnpm を使えるようにする
pnpm install
cp .env.example .env         # ここに OPENAI_API_KEY を書く
pnpm run doctor              # 足りないものを日本語で教えてくれる
★実際に見せる pnpm doctor は pnpm 内蔵のコマンドに取られて何も出ない。 わざと叩いて何も出ないところを見せるのが、いちばん伝わる説明。正解は pnpm run doctor。

STEP 4macOS の権限3種を通す

アクセシビリティ／オートメーション／画面収録。実際に許可ダイアログを出して見せる。

いちばん大事な注意 許可は「起動したアプリごと」に付く。 ターミナルから起動する場合と、常駐させる場合で別に許可が要る。「さっき許可したのに」はだいたいこれ。

ターミナルが Microphone の一覧に出てこないとき：

# 対象を必ず指定する
tccutil reset Microphone com.apple.Terminal     # iTerm2 なら com.googlecode.iterm2

# → Cmd+Q で完全終了（ウィンドウを閉じるだけではダメ）
# → 再起動すると許可ダイアログが出る
⚠ 注意 bundle-id を付けずに叩くと、Mac の全アプリのマイク許可が消える。Zoom や Slack も含めて。通話中は絶対にやらない。

STEP 5起動して、最初の会話

pnpm dev                     # → http://localhost:5173

ブラウザが開いてマイクが開き、会話係が挨拶を返す。再読み込み直後は一度画面に触る必要がある（ここで「マイクが動かない」と思う人が出る）。

最初に試してもらう3つ：

  1. 「こんにちは」— 声が返ってくればOK
  2. 「READMEを要約して」— Claude Code に渡る
  3. 確認が出たら「はい」— 声で許可が通ることの確認

STEP 6覚えておく操作（この6つだけ）

言うこと起きること
中断途中でやめる
作業画面を見せて3Dの作業画面へ
軽いモデルにして会話係を軽量モデルへ（単価が約3分の1）
編集は自動にしてそのプロジェクトだけファイル編集の確認をなくす（コマンド実行の確認は残る）
確認ありに戻して元に戻す
英語表示にして表記が英語に

割り込める：読み上げている最中に話しかければ、その場で止まって聞いてくれる。

作業が始まらないとき 「見送りました」の表示が出ていないかを見る。 相槌だけ・短すぎる・こちらの読み上げを拾っただけ、のときはわざと始めない作りになっている。

STEP 7自分のプロジェクトで使う

方法① 既定の作業対象を変える

# .env
VOICE_AGENT_WORKSPACE=/path/to/your/repo

方法② 声で場所を指して開く

複数を同時に開ける（「packages/web も開いて」）。画面に半透明のターミナルが並び、話しかけている相手だけ縁が光る。

声で開ける範囲を決める

設定範囲
near作業フォルダとその隣だけ（いちばん安全。ここから始めるのがおすすめ）
home（既定）ホーム配下。~/.ssh などの隠しフォルダは開けない
anywhere制限なし

今どの範囲かは、サーバの起動ログに毎回出る。

STEP 8お金の見方

pnpm loop:report            # logs/ を読んで、速さと費用をまとめる
1つだけ覚えてほしいこと サーバを起動したまま使い続けるほど安くなる（プロンプトキャッシュ）。 こまめに落として立ち上げ直すほど高くつく。直感と逆。

高いと感じたら、まず会話係を軽量モデルに（ヘッダーから／声で「軽いモデルにして」）。
単価を確かめていないモデルは費用を — と出す（0として黙って足し込まない）。

STEP 9任意の追加設定（時間が無ければ飛ばしてよい）

(a) 手元の資料を引けるようにする

pnpm rag:index              # docs/ を読み直して data/knowledge.db を作る
⚠ 注意して言う 索引にした資料の本文は data/knowledge.db に平文で入る。 人に見せたくない資料を入れたまま、そのフォルダを渡さないこと。

(b) アバターを変える

既定は計器表示（声に反応して波形と発光が動く）。VRMを使うなら packages/web/public/avatar.vrm に置いて avatar.kind を "vrm" に。 置いただけでは切り替わらない（「置く」と「使う」を分けてある）。声で「アニメのほうにして」でも切り替わる。

STEP 10困ったとき

pnpm run doctor             # まずこれ。足りない設定・権限を日本語で出す
症状見るところ
声が出ない・つながらない.env の OPENAI_API_KEY。gpt-realtime が使えるアカウントか
マイクが使えないブラウザのマイク許可。再読み込み直後は一度画面に触る
作業が始まらない「見送りました」の表示が出ていないか
ポートが使われている8787（サーバ）と 5173（画面）
pnpm doctor が何も出さないpnpm run doctor と打つ

お金を使わずに切り分ける

pnpm sim "READMEを要約して"        # 音声抜きで対話（Claude Code は実物）
pnpm sim --fake "テストを実行して"  # エージェントも偽物。API もトークンも使わない
pnpm dev:fake                       # 偽エージェントで画面を起動

--fake は API もトークンも使わない。何度でも回してよいので、「声が悪いのか、その下が悪いのか」を切り分けるときに使う。

⚠ pnpm dev を起動したまま pnpm e2e を叩かない（本物のサーバを使い回して壊れる）。

まとめ ＋ 次回予告

前提確認 → APIキー → インストール → macOS権限 → 起動 → 最初の会話 → 自分のプロジェクト → 費用の見方。

次回は、実際にこれでアプリを開発していくところ。今日は「動く状態にする」まで。次は「使い倒す」側。