AIチュートリアル

ai-phoneでローカルAI電話エージェントを構築・実行する

Apple Siliconにai-phoneをインストールし、音声モデルと言語モデルを設定して通話デーモンを実行する方法を解説します。SIP経由でローカルテストを行い、発信し、リレーモードで外部エージェントと連携する方法も紹介します。

2026年10月28日約11分で読了

ai-phoneとは？

ai-phoneは、コンピューター上で動作するAI電話エージェントです。着信の受け付け、発信、書面による指示に基づく会話、外部エージェントとの連携用のターン単位コマンドの提供が可能です。

現在のリリースはApple Silicon搭載のmacOS向けに設計されています。会話用の言語モデルがリモート上にある場合でも、音声認識と音声合成はMLXを通じてローカルで実行されます。ai-phoneをホストするコンピューターには対応Macが必要ですが、発信者は任意の電話機またはSIPクライアントを利用できます。

主な機能

着信と発信：セットアップ時にどちらか一方、または両方を有効にできます。
ローカル音声処理：音声認識と音声合成はMac上で実行されます。
柔軟な言語モデル：ローカルのMLXモデル、Claude CodeまたはCodexのサブスクリプション、あるいはOpenAI互換エンドポイントを利用できます。
SIPおよび電話接続：直接SIPアドレスでテストするか、SIPトランク、Telnyxアカウント、またはTwilioアカウントを接続して電話番号を利用できます。
コマンドライン自動化：プロンプトで通話を開始し、結果の文字起こしを受け取れます。
リレーモード：別のシェル対応エージェントに、会話の各ターンを制御させることができます。
音声の選択：同梱の英語音声を備えたPhonon、またはアメリカ英語とイギリス英語の音声や速度調整に対応したKokoroを利用できます。

ai-phoneが現在対応しているのは英語のみで、同時に処理できる通話は1件です。

要件

対応プラットフォーム

Apple Silicon搭載のMacが必要です。音声バックエンドがMLXに依存し、インストールにプラットフォーム固有の統合が含まれるため、Intel Mac、Linux、Windowsは現在対応していません。

メモリとストレージ

RAM 8 GB：セットアップで小型の2Bモデルが提示されます。
RAM 16 GB：デフォルトの4Bモデルに推奨されます。
RAM 32 GB：9Bモデルに推奨されます。
ストレージ：ダウンロードしたモデルの重みに数GBを確保してください。セットアップ時に空きディスク容量が確認されます。

ソフトウェアと電話接続

開始前にGit、Homebrew、uvをインストールしてください。インストーラーが必要なPythonパッケージとネイティブSIPライブラリを管理します。

通話には、直接接続用のSIPアドレスを使うか、自分のSIPトランク、Telnyxアカウント、またはTwilioアカウントを指定します。通信事業者の料金やサブスクリプションの制限が適用される場合があります。

ai-phoneをインストールする

リポジトリをクローンし、そのディレクトリに移動してインストーラーを実行し、対話式セットアップを起動します。

git clone https://github.com/oxnw/ai-phone.git
cd ai-phone
./scripts/install.sh
uv run ai-phone setup

セットアップでは、着信、発信、またはその両方を利用するかどうかを尋ねられます。続いて、言語モデル、電話回線、音声を設定します。ローカルモデルの場合、検出されたメモリ容量に基づいて推奨オプションが提示され、必要な重みがダウンロードされます。

標準の対話式プロンプトが端末でうまく動作しない場合は、プレーンモードを使用してください。

uv run ai-phone setup --plain

電話デーモンを起動する

セットアップ後、リポジトリのディレクトリからデーモンを起動します。

uv run ai-phone run

着信を受けたい間は、このプロセスを実行したままにしてください。発信専用で使う場合は、通話を開始する前に起動し、終了したらCtrl-Cで停止します。

セットアップではバックグラウンドサービスはインストールされません。セットアップ後、またはコンピューターの再起動後に、デーモンを自分で起動する必要があります。

発信する

デーモンを実行したまま、リポジトリ内で別の端末を開きます。callに宛先番号とタスクを説明するプロンプトを指定します。

uv run ai-phone call +15555550100 --json \
  --prompt "Ask whether they have a table for two at eight tonight."

+15555550100を発信先の番号に置き換えてください。通話が終了すると、コマンドから文字起こしが返されます。すべての発信通話は、AIであることの告知から始まります。

着信の場合は、セットアップ時に保存した挨拶と指示が使われます。

無料のローカルSIPテストを実行する

通信事業者への発信を行わずに、ローカルでテストできます。セットアップを実行して着信を有効にし、SIPアドレスを選択したうえで、デフォルト名agentをそのまま使用します。ai-phoneデーモンを実行した状態で、次のコマンドを実行します。

pjsua --local-port 5070 sip:agent@127.0.0.1

これにより、ローカルSIPクライアントがループバックアドレス上のエージェントに接続されます。電話プロバイダーを設定する前に、着信の基本的な流れを検証できます。

リレーモードで通話を制御する

リレーモードは、シェルにアクセスできる外部エージェント向けです。会話全体に対してai-phoneに1つのプロンプトを渡す代わりに、外部エージェントが通話を開始し、話し、聞き、各応答の後に次の操作を判断できます。

リレー通話を開始する

uv run ai-phone call +15555550100 --relay --json

ターンごとに話して聞く

uv run ai-phone say "Hi, I'd like to book a table for two." --json
uv run ai-phone listen --json
uv run ai-phone say "Eight o'clock, please." --json

会話を終了する

uv run ai-phone hangup --say "Thank you. Goodbye." --json

--jsonを使う各コマンドは、標準出力に1つのJSONオブジェクトを書き込みます。callコマンドは標準エラー出力にも進行状況イベントを書き込むため、連携処理ではこれらのストリームを分けて処理してください。

アクティブな通話がない場合、listen --jsonは着信を待ち、リレーモードで処理します。応答されないリレーターンは、デフォルトで25秒後にタイムアウトします。通話ID、トランスクリプトの取得、設定可能なタイムアウト、終了コードについては、エージェントコマンドリファレンスを参照してください。

モデルと音声を選択する

音声認識

ai-phoneは、MLXを介してローカルでParakeetを使用し、音声を認識します。

会話モデル

言語モデルには、ローカルのMLXモデル、Claude CodeまたはCodexのサブスクリプション、あるいはOpenAI互換エンドポイントを使用できます。セットアップで選択したオプションを設定できます。

音声合成

Phononには英語音声が付属しています。Kokoroでは、話速を調整できるアメリカ英語音声とイギリス英語音声を利用できます。

リモートの言語モデルを使用する場合、そのモデルには通話テキスト、指示、会話履歴が送信されます。外部エージェントがクラウドプロバイダーを使用する場合、そのプロバイダーにも提供されたトランスクリプトが送信される可能性があります。音声認識と音声合成は引き続きローカルで行われますが、電話音声はSIPおよびRTP経由で送信されます。

高度な設定のヒント

要件が変わったらセットアップを再実行する

音声、モデル、着信・発信の有効化、または発信者IDを変更するには、セットアップを再実行します。

uv run ai-phone setup

設定を変更したら、デーモンを再起動して新しい設定を反映してください。

キャリアを追加する前にローカルSIPから始める

まずループバックSIPテストでエージェントを検証します。ローカル通話が機能したら、通常の電話番号が必要な場合にSIPトランク、Telnyx、またはTwilioを設定してください。ネットワーク関連の問題については、プロジェクトのNATチェックリストを確認してください。

利用可能なメモリに合ったモデルを選択する

自動的に最大のモデルを選ぶのではなく、セットアップがRAMに基づいて推奨するモデルに従ってください。2Bオプションはメモリの少ないシステム向けで、デフォルトの4Bおよびより大きな9Bモデルには、より多くのメモリが必要です。

現在のレイテンシーとテスト状況を考慮する

READMEによると、最新のローカル実行では、メモリに大きな負荷がかかった状態で最初に聞こえる応答の中央値が1.50秒となり、プロジェクトの1秒目標を達成できませんでした。ローカル通話テストと割り込みテストは実施済みですが、実キャリアおよびエンドツーエンドのエージェント受け入れテストは未完了です。デプロイ準備状況を評価する際は、公開済みの測定結果とレイテンシー履歴を確認してください。

詳細なリファレンスを利用する

回線、転送、発信者ID、モデル、CLIコマンドについては使用ガイド。
利用可能な設定については設定例。
コンポーネントと通話フローについてはアーキテクチャガイド。
ネットワーク設定についてはNATチェックリスト。

ライセンスに関する考慮事項

ai-phoneはAGPL-3.0-or-laterの下でライセンスされています。付属するPJSIPインターフェースファイルはGPLv2-or-laterを使用しています。ソフトウェアを配布または統合する前に、プロジェクトのライセンスに関する注意事項を確認してください。

まとめ

ai-phoneは、Apple Silicon MacでAI電話エージェントを実行するための実用的なコマンドラインワークフローを提供します。インストール後、モデルとSIP回線を設定し、デーモンを起動してから、キャリア経由の通話を行う前にローカルでテストしてください。自動化では、リレーモードにより、JSONを生成するシェルコマンドを通じて、外部エージェントがターンごとに構造化された制御を行えます。