Pi Agent Desktop ユーザーガイド

次の手順に従って、アプリをインストールし、モデルを構成し、最初の会話を開始します。

ダウンロードしてインストールする

次の ダウンロードページを開いてください。このサイトではお使いのシステムに合うパッケージが目立つように表示されます。v0.4.1 のデスクトップパッケージには Pi Coding Agent 1.2.0 と Herdr v0.8.2 が含まれています。通常の使用では Pi CLI を別途インストールする必要はありません。

macOS

Apple Silicon (M シリーズ) の場合は arm64 を、Intel Mac の場合は x64 を選択します。 DMG を開き、アプリを [アプリケーション] にドラッグします。

Windows

Windows 10および11のx64に対応しています。現在のインストーラーは未署名のベータ版です。EXEを実行し、セットアップウィザードに従ってください。

Linux

Linux x64 は AppImage として使用できます。実行可能にしてから、ファイル マネージャーまたはアプリケーション メニューから開きます。

macOS にインストール

  1. Mac に Apple Silicon または Intel DMG をダウンロードします。
  2. DMG を開き、Pi Agent Desktop をアプリケーション フォルダーにドラッグします。
  3. アプリケーションから開きます。実稼働ビルドは Apple によって署名され、公証されています。

Windows にインストール

  1. 無署名の Windows x64 ベータ インストーラーをダウンロードして実行します。
  2. セットアップウィザードに従ってください。
  3. インストーラーはまだコード署名されていません。SmartScreen に「発行元不明」と表示された場合は、ファイルの配布元が GitHub Releasesであることを確認し、「詳細情報」→「実行」を選択してください。

Linux にインストール

  1. Linux x64 AppImage をダウンロードします。
  2. ファイルのプロパティでプログラムとして実行できるようにするか、実行します。 chmod +x Pi-Agent-Desktop-*.AppImage.
  3. AppImage を開きます。 Linux 更新は現在手動です。
最初の起動: プロジェクト フォルダーを選択し、[設定] → [モデル] を開き、モデルを構成します。 Pi CLI を使用したことがない場合でも開始できます。

メインワークスペースの紹介

メインワークスペース
メインワークスペースv0.4.0

左: プロジェクトとセッション

  • プロジェクトフォルダーを選択または切り替えます
  • 新しいセッションを作成する
  • セッションの検索、切り替え、名前変更、または削除
  • 一番下にある「設定」を開きます

中央:会話

  • プロンプトを送信し、応答をストリーミングで表示
  • 推論とツール呼び出しの結果を検査する
  • モデル、推論レベル、ツールのプリセットを選択します
  • ファイルをドラッグ、ペースト、添付するか、プロジェクト ファイルを参照します。 @

右: ファイル、プロセス、Herdr、ブラウザ

  • 現在のプロジェクト内のファイルを参照する
  • 複数のファイルをタブで開く
  • コード、Markdown、図、ドキュメントのプレビュー
  • 管理対象プロセスと編集されたログを検査および制御する
  • Herdr ペインの出力を確認し、必要に応じてキーボード制御を行います
  • エージェントと共有されている実際のページを開く
  • 分割線をドラッグしてパネルのサイズを変更します

最初のセッションを開始

  1. 左側のサイドバーでプロジェクト フォルダーを選択します。
  2. 「New session」を選択します。
  3. 利用可能なモデルがコンポーザーの下で選択されていることを確認してください。
  4. 「このプロジェクトについて説明する」または「ログイン ページを見つける」などの目標を説明します。

チャットや一時的な作業の場合は、空のフォルダーを選択できます。エージェントは、関連するツールを承認した場合にのみ、プロジェクト ファイルの読み取りまたは変更を行うことができます。

長いセッションは切り捨てられません。 アプリは最初に直近20件の会話を表示します。上端に近づくと古いメッセージを先読みします。「Load earlier messages」を選んで読み込むこともできます。履歴全体は引き続きお使いのマシンに保存されます。

自動タイトルと最新のメッセージに戻る

新しいセッションで最初の意味のあるメッセージが送信された後、アプリはバックグラウンドで現在のモデルを使用して最大 40 文字のタイトルを生成し、サイドバーをリアルタイムで更新します。リクエストがセッション履歴に入ることはなく、通常の応答もブロックされません。モデルが使用できない場合、メッセージの先頭でローカル フォールバックが提供されます。

  • 「Settings → General → Conversation」で新規セッションの自動タイトルをオン/オフにできます。
  • 手動名は常に優先され、自動タイトルによって上書きされることはありません。
  • スラッシュコマンド、空白のテキスト、1文字だけのメッセージ、画像のみのメッセージではタイトルは生成されません。
  • 上にスクロールした後、フローティングの「下にスクロール」ボタンを使用して最新のコンテンツに戻り、ストリーミング中の自動フォローを再度有効にします。

インターフェース言語を変更する

開く設定→一般→インターフェース言語

英語、簡体字中国語、または繁体字中国語を選択します。台湾、香港、マカオ、 zh-Hant システムのロケールが英語以外の場合は、既存のユーザー選択を維持しつつ、初期言語を繁体字中国語にします。ネイティブダイアログ、ファイルのコンテキストメニュー、ブラウザーの確認画面、トレイのメニュー、アプリケーションメニューも選択した言語に従います。

Windows / Linuxのメニューバー: アプリとの一体感を高めるため、上部メニューバーは初期状態で非表示です。既存のコマンドとショートカットは引き続き使えます。一時的に表示するには Alt キーを押します。macOS では引き続きシステムのメニューバーを使用します。

チャットのサイズ、会話の幅、モデルの返信の幅を調整する

開く設定→一般→会話

  • [小]、[標準]、[大]、または [特大] チャット テキストを選択します。変更はすぐに適用され、再起動しても維持されます。
  • 快適な幅は 760px のままです。 Expanded は最大 960px のウィンドウに適応します。
  • モデルの返信幅は返信バブルを個別に制御します。Comfort は元の読み取り幅を維持しますが、Fill 会話列では段落、表、およびコード ブロックが利用可能なチャット列スペースを使用できるようにします。
  • モデルの応答幅は、外部の会話幅とは別のものです。フルモードは、右側のパネルが開いているときに使用可能なスペースを縮小します。
  • メッセージ、プロセスの詳細、およびコンポーザーは、幅の広いウィンドウと最小幅のウィンドウの両方で、位置合わせされたコンテンツ境界を共有します。

プロンプトキャッシュウォーミングを設定する

プロンプト キャッシュ ウォーミングは、オフ、ツールの長時間実行中、およびアイドル モード中に提供されます。長いツール呼び出し中またはアイドル時間中にモデル プロンプト キャッシュをアクティブに保つことができますが、モデル トークンが使用される場合があります。設定はPi CLIと共有されます。すぐに更新できなかったアクティブなセッションを再度開きます。

添付ファイルを送信し、ローカルファイルへのリンクを使用

  • ドラッグ アンド ドロップ、貼り付け、またはコンポーザーの横にある添付ボタンを使用して、画像または任意のファイルを追加します。画像以外の添付ファイルはファイル カードとして表示されます。
  • 大きなスクリーンショットと Retina PNG は、ドラフトに入る前に 2048 ピクセルの最長エッジと約 512 KiB JPEG にサイズ変更されるため、一般的なスクリーンショットは保持され、再起動後に回復できます。
  • テキストなしでも添付ファイルを送信できます。Agentが応答をストリーミング中のとき、添付ファイル付きメッセージをSteer / Follow-upキューに追加することもできます。
  • 送信が失敗した場合、添付ファイルとテキストは、送信中に入力された内容を上書きすることなく、現在の下書きに結合されます。
  • Markdown メッセージは、Windows、POSIX、および UNC ローカル パスを認識します。リポジトリの相対パスはアプリ内で開きますが、絶対パスはシステム ファイル マネージャーで表示できます。
  • ローカル ファイル リンクを右クリックして開き、デフォルトのアプリまたはプログラムから開くを選択し、コピーを保存したり、パスやテキストの内容をコピーしたり、フォルダー内で表示したりできます。
  • プロジェクトファイルを参照するために @ を入力すると、アプリは必要に応じて最大 300 件の候補を参照・検索します。ホームディレクトリをワークスペースにしている場合、 AppData または Library は初期状態では非表示ですが、名前を直接入力すればアクセスできます。
  • ファイル検索ツールが利用できないか、タイムアウトするか、失敗した場合、UI はフォールバック状態を表示し、入力をブロックしたり不完全な結果を黙って返したりする代わりに、現在のディレクトリの候補を保持します。
思考ブロックの設定: 思考ブロックを展開または折りたたむと、アプリは現在のセッションでその状態を記憶します。新しいブロックには直近の状態が引き継がれ、他のセッションとは分離されます。
コンテンツのプレゼンテーション: Mermaid フェンスは、ストリーミング後にデフォルトでレンダリングされたダイアグラムを表示し、ソース ビューと障害フォールバックが保持されます。複数行の通知とスペースのない長いテキストは完全に折り返されます。リスト内の数式を表示するとインデントが保持されるため、後の見出し、表、太字のテキストが数式として誤って解析されません。

内蔵ブラウザーを使用

開くワークスペースの右側→ブラウザ

内蔵ブラウザーでは実際のChromiumページを表示します。タブ、プロファイル、ログイン状態を保ったまま、ユーザーとAgentが同じページを操作でき、いつでも操作を引き継げます。

閲覧する

  • 複数のタブを作成、切り替え、閉じる
  • 一時的または永続的なプロファイルを選択してください
  • サインインしてアップロード、ダウンロード、プロキシを使用

Agentと作業する

  • ブラウザの読み取りにより、ナビゲーション、ページのスナップショット、スクリーンショットが可能になります
  • ブラウザーの操作により、クリック、入力、およびキーボード操作が可能になります
  • ユーザーとAgentはページを共有し、いつでも操作を引き継げます

許可と確認

  • コーディング権限によりブラウザーアクセスが自動的に有効になることはありません
  • メインウィンドウの初回使用時にセッション許可を求めます
  • 送信、アップロード、ダウンロード、外部プロトコルは引き続きポリシーに従って制御されます
内蔵ブラウザ
内蔵ブラウザv0.4.0

ブラウザの権限を管理する

[設定] → [ブラウザ] を開いて、個々のセッションのグローバルなデフォルトと永続的なポリシーを管理します。承認ダイアログからの許可は現在のセッションに対して一時的なものであり、いつでも取り消すことができます。

アドバンストブラウザモード

詳細モードでは、信頼できる入力、ネットワーク検査、JavaScript ナレッジ ストア、および専用プロファイルでの確認済み書き込み要求のリプレイが追加されます。この切り替えは現在のアプリ起動中にのみ持続し、エージェント ツールは Cookie 値を受信したり返したりしません。

プライベートネットワーク保護: 現在の保護は明示的にベストエフォート型です。管理されたネットワーク サンドボックスがない場合、Strict モードは、警告なしに保護を弱めるのではなく、要求を拒否します。

Herdr Agent Fleetを使用

開く設定→Herdr

Pi Agent Desktop は Herdr v0.8.2 / プロトコル 20 を使ってローカルの Agent フリートを管理します。Pi は herdr_* ツールを元の会話から使用できます。タイトルバーにはフリートの状態が表示され、右側の Herdr ターミナルでは監視、問題の調査、明示的な操作の引き継ぎができます。

Herdr エージェント フリート
Herdr エージェント フリートv0.4.0

Herdr ランタイムを準備する

  1. macOS、Linux、または Windows x64 で、[設定] → [開発者ツール] を開き、Herdr を見つけます。整合性が検証された v0.8.2 ランタイムがバンドルされているため、ネットワークから個別にダウンロードすることなく、プライベート ランタイムをインストール、更新、修復、または削除できます。
  2. [設定] → Herdr を開き、統合を有効にし、アタッチまたは管理モードを選択し、Herdr セッション名を入力し、オプションで自動接続を有効にします。
  3. Attach は、自分で起動および停止するシステム Herdr サーバーに接続します。 Pi Desktop はそれを決して止めません。管理対象は、制限内で Pi Desktop のプライベート サーバーを起動、監視、再起動します。
  4. Herdr が無効になった場合、モードが変更された場合、ランタイムが削除された場合、またはアプリが終了した場合、マネージドはプライベート サーバーを停止します。外部 Herdr を引き継いだり終了したりすることはありません。

会話からエージェントを管理する

  • 24 個の herdr_* ツールは、フリートの照会、ワークスペース・タブ・ペインの作成と管理、Agent の起動と指示、待機、キー入力、状態の説明、プロセス診断、出力待ちに対応します。
  • タイトルバーの状態はワークスペース、タブ、ペイン、Agentごとにまとめられ、スタート画面と進行中のセッションの両方で、待機中、作業中、ブロック中、完了、不明を表示します。
  • 対応するAgent CLI: pi, claude, codex, gemini, omp, opencode, copilot, kimi, droid, grok, qwen、そして agy.
  • 管理モードでは、許可リストに登録された固定の場所でのみ共通のエージェント CLI が検出され、許可されたエージェント コマンドのみがランチャー オーバーレイに配置されます。ログイン シェルの実行、シェル プロファイルの読み取り、ネットワークからのインストール、ホーム ディレクトリの再帰的スキャンは決して行われません。
  • missing-locally これは、デスクトップがサポートされているローカル ディレクトリで CLI を見つけられなかったことのみを意味します。アタッチ モードでは、外部 Herdr セッションは引き続き正式な起動結果を返します。
  • Pi セッションと Herdr セッションは独立しています。 Herdr プロンプトは、Pi セッション履歴または圧縮概要には書き込まれません。

ターミナルを監視し、操作を引き継ぐ

  • 右側のHerdrターミナルは、ANSI出力、自動サイズ調整、読み取り専用での監視、明示的なキーボード操作の引き継ぎ、入力制限、再接続、上限付きバッファーに対応します。
  • ターミナル ビューを閉じても、Herdr ペインやエージェントは閉じられません。ビューを閉じると端末制御を解放するかどうかを選択できます。
  • ワークスペース、ペイン、またはエージェントを閉じるには、ローカルの確認が必要です。 Herdr v0.8.2 ではエージェントのみを停止できないため、Close Agent はそのペインとその内部のすべてのプロセスを明示的に閉じます。
  • Windows x64 では、ネイティブ ジョブ オブジェクトには端末の子プロセスが含まれており、アプリまたは端末の障害後に制限付きクリーンアップが提供されます。
プラットフォームのサポート: Herdr は、macOS arm64 / x64、Linux x64、および Windows x64 をサポートします。 Windows ARM64、Windows サーバー、および 32 ビット Windows はサポートされていません。
セキュリティ境界: Herdr エンドポイント、プロトコル、および Unix ソケットは、制限され編集されたデータを使用して厳密に検証されます。マネージド プロセスと同様に、Herdr はコンテナーやセキュリティ サンドボックスではなくライフサイクル制御を提供します。

管理されたバックグラウンドプロセスを実行する

有効にする設定→一般→管理されたプロセス

管理対象のバックグラウンドプロセスを使うと、Agent は開発サーバー、ファイル監視プロセス、モック API などを、シェルの &, nohupや外部ターミナルは不要です。短いコマンドには、セッションで選択した Bash、または Windows の PowerShell を使用します。

プロセスを起動して確認

  1. 信頼できるプロジェクト フォルダーを選択し、[設定] → [一般] で [管理されたバックグラウンド プロセスを有効にする] をオンにします。この機能はデフォルトではオフになっています。
  2. Agent に開発サーバーや監視ビルドなど長時間実行するタスクの開始を依頼すると、 process_* ツールが使われます。
  3. 右側でプロセスを開いて、所有者、状態、準備状況、編集されたログ、ループバック エンドポイント、および終了理由を検査します。
  4. 利用可能なエンドポイントの「Open in Browser」を選ぶと、内蔵Browserでデバッグできます。プロセスの権限とBrowserの許可は別々に管理されます。

プロセスとログを制御する

  • 行単位で標準入力を送信したり、プロセスを停止、強制停止、再起動したりできます。ログの検索、コピー、エクスポートも可能です。
  • 開始に時間のかかるタスクは、出力全体を読み直さずログカーソルから処理を続けます。ログバッファには上限があり、一般的な秘密情報は伏せられます。
  • 各プロセスは、それを開始したエージェント セッションにのみ属します。再起動すると新しい実行 ID が作成され、古い操作は拒否されます。
  • エージェントはユーザーの停止を自動的にバイパスできません。クラッシュ リーパーは、ホストまたはアプリの障害後に、限定されたプロセス ツリーのクリーンアップを実行します。
プラットフォームのサポート: 管理対象プロセスは、macOS、Linux、および Windows 11 x64 をサポートします。他のデスクトップ機能は Windows 10 でも引き続き利用できますが、管理対象プロセスは利用できません。 Windows ARM64、Windows サーバー、および 32 ビット Windows はサポートされていません。
セキュリティサンドボックスではありません: 管理対象プロセスはライフサイクルを制御します。子プロセスは Agent シェルと同じローカルファイル、ネットワーク、環境へのアクセス権を持ちます。プロジェクトサービスは既定で次のアドレスにバインドしてください: 127.0.0.1 デフォルトでは;共通の LAN バインドには確認が必要です。

Windows PowerShell に対応

Windows で Agent のコマンドに PowerShell 5.1 または 7 を使用できます。新規セッションの既定シェルを選択でき、既存のセッションは従来の選択を維持します。

  1. Windows で「設定 → 一般 → Agent の既定のシェル」を開き、PowerShell または Bash を選択します。新規セッションの既定は PowerShell です。この設定は、その後作成するセッションだけに適用されます。
  2. 利用可能な場合は PowerShell 7 を優先し、Windows PowerShell 5.1 にも対応します。「開発者ツール」で必要に応じて実行ファイルを指定し、インストールやパス変更後に状態を更新してください。
既存のセッションはシェルとツールの許可を維持します。既定値を変更しても、ツールなしのセッションにコマンド実行権限は追加されません。Bash と PowerShell はローカルユーザーの権限で動作し、セキュリティサンドボックスではありません。

長すぎる PowerShell コマンドは分割してください。Windows の長さ制限を超える場合、切り詰めて実行することなく、実行前に明示的なエラーを返します。

モデルの構成

開く設定→モデル

Pi Agent Desktop v0.4.1 には Pi Coding Agent 1.2.0 が含まれていますが、モデル クレジットは含まれていません。既存のモデル プロバイダー アカウントに接続するか、プロバイダーからの API キーを入力します。モデル設定は、英語、簡体字中国語、繁体字中国語をサポートしています。

APIキーを使用

  1. 「設定」→「モデル」を開き、「プロバイダーの追加」を選択します。
  2. モデルプロバイダーを選択します。
  3. プロキシまたは互換エンドポイントの場合は、ベース URL を入力します。プロバイダーのデフォルトを使用するには、空白のままにします。
  4. API キーを貼り付けて保存します。アプリはエージェント ホスト モデルの状態を同期します。
  5. モデルを選択します。「Test」が使える場合は、接続を確認してください。
  6. 設定を閉じて、会話コンポーザーの下のモデルを選択します。

Base URLは現在のAPIキープロバイダーのエンドポイントを上書きします。ページ下部の「Save」を選ぶと、APIキーとともに反映されます。モデル一覧の更新には全段階でタイムアウトが設定されています。サービスの作成や一覧の最終反映が停止しても、アプリは待機を終了し、キャッシュ済みモデルを保持します。

表示するモデルを制御する

  1. [設定] → [モデル] を開き、接続されたサブスクリプションまたは API キー プロバイダーを選択します。
  2. 有効な数を確認します。プロバイダの機種が多い場合は、機種名またはIDで検索してください。
  3. モデルを個別に切り替えるか、プロバイダーの「Enable all」または「Disable all」を選びます。
  4. 選択内容が保存されるまで待ち、会話画面のモデル選択欄に戻ります。

選択内容はPiの設定に保存され、既存の思考レベル設定との互換性も保たれますが、既存セッションで使用中のモデルは変更されません。有効なモデルがない設定は保存できません。

モデルディレクトリを更新する

  1. 会話コンポーザーの下にあるモデル セレクターを開きます。
  2. 「Refresh model directory」を選択して、設定済みプロバイダーから最新のモデル一覧を取得します。
  3. 更新が完了するまで待ちます。オフライン、タイムアウト、一部プロバイダーの失敗は状態表示または警告で通知されます。

起動時は不要なネットワーク要求を行わず、ローカルにキャッシュされたモデル一覧を優先します。更新に失敗しても既存のモデル一覧は消去されず、キャッシュを引き続き利用できます。

OAuthを使用

  1. OAuth をサポートするプロバイダーを選択します。
  2. 「Sign in」を選び、ブラウザーで認証を完了します。
  3. アプリに戻り、プロバイダーが接続済みとして表示されていることを確認します。サインインまたはサインアウトすると、モデルの状態が自動的に同期されます。

互換性のあるカスタムサービスを使用

OpenAI、Anthropic、または Google API と互換性のあるセルフホスト サービスの場合は、カスタム プロバイダーを追加し、そのベース URL、API タイプ、API キー、およびモデル情報を入力します。これは、標準のプロバイダーがニーズを満たさない場合にのみ使用してください。

接続に失敗しましたか? API キーが完了していること、アカウントにクレジットがあること、ネットワークがプロバイダーに接続できることを確認してください。次に、モデル カードのテスト アクションを使用して、プロバイダー エラーを確認します。認証情報は保存されたがモデルの同期に失敗した場合、アプリは認証情報を保持しながら明確な警告を表示します。

モデル設定の復旧

Pi 1.2.0 ではスキーマ検証に失敗すると models.json 全体が無効となり、すべてのカスタムプロバイダーとモデルの上書き設定が適用されません。Desktop はデスクトップとチャネルの両セッションで送信を一時停止します。
  1. 「設定 → モデル」で指摘された項目を修正します。画面で編集できない項目は ~/.pi/agent/models.json を手動で編集してください。行コメントと末尾のカンマに対応しています。
  2. ディスクから設定を再読み込みし、セッションを再読み込みしてから送信してください。復旧後は選択モデルと Auto ルーティングを確認してください。

OpenRouter は現在のアカウント権限に基づいてモデル一覧を更新します。Desktop と Pi CLI は ~/.pi/agent/ のキャッシュを共有します。アカウント変更やオフライン起動の後は、接続して一覧を更新し、古い情報や別アカウントの情報を置き換えてください。

Auto モデルルーティング

高速モデルと高性能モデルを設定すると、Auto が思考レベルやタスクの複雑さに応じて新しい質問ごとにモデルを選択し、実際に回答したモデルを表示します。

Auto モデルルーティング
Auto モデルルーティングv0.4.0
  1. 「設定 → モデル → 自動ルーティング」で Auto を有効にし、両方のモデルとそれぞれの思考レベルを選択します。保存後、入力欄の下で Auto を選びます。
  2. 思考レベルで振り分けるか、判定モデルでタスクの複雑さを判断できます。判定リクエストには追加の時間と使用量がかかり、判定に失敗した場合は高性能モデルを使用します。
  3. ツールの続行では選択済みのモデルを使います。自動再試行時にもう一方の設定済みモデルを試すことができ、実際のモデルごとに使用量を確認できます。
  4. ルーティングの変更は、新規セッション、再読み込みしたセッション、または Auto を選び直した後に反映されます。

MCP サービス

stdio または Streamable HTTP でローカルやリモートのツールに接続。設定画面で構成のインポート、OAuth ログイン、接続テスト、リソースのプレビューができます。

MCP エイリアス、ツール検索、Codemode のネスト呼び出しに一貫した権限チェックを適用します。アップグレード後も、既存のセッションとチャネルの許可範囲は変わりません。
MCP サービス
MCP サービスv0.4.0
  1. 「設定 → MCP」を開き、「グローバル」または「現在のプロジェクト」を選択して、サーバーを追加するか JSON 設定をインポートします。
  2. stdio コマンドまたは Streamable HTTP URL を設定します。必要に応じて OAuth やプロバイダーの認証情報への参照を使用し、接続をテストします。
  3. ツール、リソース、リソーステンプレートを閲覧し、サービスの詳細画面でリソースをプレビューしたり再接続したりできます。
  4. 同名のグローバル設定はプロジェクト設定で上書きされます。拡張機能の登録元と適用待ちの変更は個別に表示されます。
  5. MCP 設定を保存してもツールへの権限は付与されません。現在のセッションのツールメニューで許可してください。入れ子の呼び出しにも同じ権限が適用されます。

画像生成と判定モデル

Codemode で画像生成、コンテンツ分類、はい/いいえの判定、採点ができます。生成した画像は会話を再度開いた後も閲覧できます。

  1. 「設定 → モデル」で利用可能な画像モデルまたは判定モデルを設定し、セッションのツールメニューで Codemode を有効にします。「フルアクセス」には Codemode とツール検索が含まれます。
  2. Agent に画像生成やコンテンツの分類を依頼できます。画像入力に対応した判定モデルはスクリーンショットも評価できます。これらは補助モデルで、チャットモデルの選択メニューとは別に扱われます。
  3. OpenAI の判定機能には API キーが必要です。ChatGPT のサブスクリプションログインでは利用できません。API キーで TypeSafe / Jev を追加すると jev-latest を利用できます。
  4. プロバイダーの詳細画面で画像モデルや判定モデルをテストできます。テストには料金が発生する場合があります。呼び出しはキャンセル可能で、入力、結果、状態、使用量がセッション履歴に残ります。

ツールと実行履歴

セッションの分岐に対応した実行ツリーで、直接呼び出しと入れ子の呼び出しを確認。セッションを再度開いた後や圧縮後でも、状態、所要時間、入力、完全な結果を参照できます。

  1. セッションのツールメニューで、モデルに見せる入口、入れ子の検索で見つかるツール、実行権限を個別に管理します。権限の変更はランタイムに同期されます。
  2. 大きな結果と一時出力は保存され、ページ単位で読めます。セッションを再度開いた後や圧縮後でも、Agent は tool_history_get で元の内容を取得できます。
  3. 中断後も完了済みの子呼び出しは保持され、未確認の結果は中断または結果不明と表示されます。復旧時に操作が自動で再実行されることはありません。

モデルの詳細設定

  • 「設定 → モデル → モデルの詳細設定」で、自動コンテキスト圧縮、返信用の予約トークン、最近の内容の保持量、モデル別の設定を調整できます。
  • Agent とプロバイダーの再試行回数、待機時間、リクエストのタイムアウト、および自動、SSE、WebSocket、キャッシュ付き WebSocket の通信方式を設定できます。
  • モデル編集で、思考レベル別のサンプリング設定、画像とリクエストの入力制限、モデル ID 別の設定を利用できます。対応モデルでは Max 推論レベルを選択できます。
  • 詳細設定は Pi CLI と共有されます。既存のセッションを再読み込みすると反映されます。信頼済みプロジェクトの設定がグローバル値を上書きする場合があります。保存時に外部の変更を検出し、競合を減らします。

Skillsの設定

開くプロジェクトを選択してください→設定→Skills

このセクションでは設定を扱います。各Skillの機能と使い方は、それぞれのドキュメントを参照してください。

Skillsの設定
Skillsの設定v0.4.0
  1. プロジェクトを選択し、「設定」→「スキル」を開きます。
  2. インストール済みのSkillを選び、スイッチでモデルに表示するかどうかを設定します。
  3. 追加するには「Add skill」を選び、名前で検索して「Global」または「Current project」を選択し、インストールします。
  4. カスタム指示が必要な場合にのみコンテンツを編集し、変更を保存します。
インストールの再試行: 通常のインストールでは、npm のデフォルトの同時実行性とキャッシュが使用されます。ネットワーク エラー、タイムアウト、または npm キャッシュ ロックの失敗が発生した場合、アプリは一時的に分離されたキャッシュを使用して自動的に 1 回再試行します。
ヒント: 複数のプロジェクトで使うSkillには「Global」を、リポジトリ固有のSkillには「Current project」を選びます。

プラグインの設定

開くプロジェクトを選択してください→設定→プラグイン

Pluginsページでは、取得元、インストール範囲、有効・無効を設定できます。

  1. プロジェクトを選択し、「設定」→「プラグイン」を開きます。
  2. 「Add plugin」を選び、npmパッケージ、Gitリポジトリ、またはローカルの絶対パスを入力します。
  3. 「グローバル」または「現在のプロジェクト」を選択してインストールします。
  4. インストールされているリストからプラグインを有効化、無効化、更新、または削除します。
  5. プラグイン設定を変更した後、現在のセッションをリロードします。
重要: プラグインはコードを実行できます。信頼できるソースからのみインストールしてください。

メッセージングチャネルの設定

開く設定→メッセージングチャネル

チャンネルを選択してください。 Feishu / Lark には公式 QR 作成フローが推奨されますが、既存のカスタム アプリは引き続きサポートされます。

添付ファイルを正しいターンに関連付けます。キャンセルや拡張機能による処理が後続の Desktop ターンに影響したり、前のアシスタントの返信を再送したりする問題を修正しました。

チャンネル構成
WeChat「Connect WeChat」を選び、QRコードをスキャンしてスマートフォンで承認します。
TelegramBotFather で作成したボット トークンを入力します。
Feishu / Lark推奨される QR フローを通じて新しいボットを作成するか、既存のアプリのアプリ ID とアプリ シークレットを入力します。

QRコードでFeishu / Larkボットを作成

  1. 「Connect Feishu / Lark」を選び、「Scan to create」(推奨)を選択します。
  2. アカウントの地域としてFeishu ChinaまたはLarkを選択します。
  3. QR コードを生成し、対応するクライアントでスキャンして、正式な認証を完了します。
  4. アプリがボットを作成し、必要な権限を設定して認証情報を保存し、本人確認後に接続を開始します。
安全な初期設定: App SecretはAgent Host内だけで扱われ、OSの暗号化機能を使って保存されます。UIに表示されることはありません。初期状態では、スキャンしたユーザーのみがダイレクトメッセージを送信できます。グループ、コマンド、Agentツールは明示的に有効化するまで無効です。

既存のFeishu / Larkアプリを接続

[既存のアプリ] を選択し、Feishu または Lark を選択して、アプリ ID とアプリ シークレットを入力します。 QR フローは既存のアプリの App Secret を読み取ることはありません。

アカウント設定を完了する

  1. アカウントを保存し、必要に応じてデフォルトのプロジェクト ディレクトリとアクセス ポリシーを構成します。
  2. アカウントを起動し、状態が「Running」であることを確認します。
  3. 「Test connection」を使用します。メッセージの会話を現在のデスクトップセッションとコンテキスト共有する場合のみ、セッションに紐付けてください。

開発者ツールの設定

開く設定→開発者ツール

必要なツールはアプリが自動で検出します。通常は「Missing」または「Unavailable」と表示された項目だけ対応が必要です。

開発者ツールの設定
開発者ツールの設定v0.4.0
  1. 「Rescan」を選択すると、各ツールの状態、取得元、バージョンを確認できます。
  2. インストールされているツールは [自動] のままにしておきます。検出が間違っている場合は、「選択」を使用してパスを選択します。
  3. 不足しているツールに管理対象バージョンがある場合は「Install」を選択します。管理対象ファイルが壊れている場合は「Repair」を使用します。

Windows では、Git Bash は、同じ場所に配置された Git バージョンとともにインストール レイアウトから認識されるため、Windows ディレクトリ用のカスタム Git およびバージョン管理された PortableGit フォルダーは正しく動作します。

利用可能な場合は PowerShell 7 を優先し、Windows PowerShell 5.1 にも対応します。「開発者ツール」で必要に応じて実行ファイルを指定し、インストールやパス変更後に状態を更新してください。

Herdr ランタイムを管理する

macOS、Linux、および Windows x64 パッケージには、整合性が検証された Herdr v0.8.2 が含まれています。開発者ツールでは、バンドルされインストールされているバージョンとプライベート ディスクの使用状況が表示され、Herdr を個別にダウンロードしなくても、バンドルされたコピーからプライベート ランタイムをインストール、更新、修復、または削除できます。

Herdr バージョンは、Pi Desktop アップデートとともに提供されます。プライベート ランタイムを削除しても、Herdr セッションやアプリ内にバンドルされているリカバリ コピーは削除されません。

すべてを揃える必要はありません: 健全なツールは放っておいてください。管理ツールは Pi Desktop のプライベート ディレクトリに残り、システム PATH を変更しません。

更新、バックグラウンド動作、ローカルデータ

アップデートをチェックする

「設定」→「情報」で安定版の更新を確認できます。macOS と Windows ではアプリ内で更新をダウンロードしてインストールできます。Linux AppImage では新しいバージョンを手動でダウンロードします。

メッセージ チャネルをオンラインに維持する

「設定」→「一般」で閉じるときにトレイに最小化するを有効にします。メイン ウィンドウを閉じると、チャネルは実行されたままになります。トレイから [終了] を選択すると、アプリが完全に停止します。

ローカルデータ

Desktop のツール権限と実行記録はアプリのデータディレクトリに保存されます。完全なバックアップには、~/.pi/agent/ とともに tool-executions のログとコンテンツファイルも保存してください。

  • セッションと Pi の設定は初期状態でローカルの ~/.pi/agent/ に保存されます。
  • 既存の Pi CLI ユーザーは、現在のセッションと構成を再利用できます。
  • モデル リクエストは引き続き選択したモデル プロバイダーに送られるため、そのプロバイダーのプライバシー ポリシーを確認してください。
  • メッセージング資格情報はオペレーティング システムの安全なストレージで暗号化され、[設定] に再度表示されることはありません。

よくある質問

設定済みの MCP ツールを Agent が使えないのはなぜですか?

MCP 設定を保存してもツールへの権限は付与されません。現在のセッションのツールメニューで許可してください。入れ子の呼び出しにも同じ権限が適用されます。

Auto を有効にするには?

「設定 → モデル → 自動ルーティング」で Auto を有効にし、両方のモデルとそれぞれの思考レベルを選択します。保存後、入力欄の下で Auto を選びます。

Node.js または Pi CLI をインストールする必要がありますか?

いいえ。デスクトップ パッケージには Pi Coding Agent ランタイムが含まれています。スキル、プラグイン、またはエージェントのコマンドに追加のツールが必要な場合にのみ、「設定」→「開発者ツール」を確認してください。

SkillsとPluginsで最初にプロジェクトを選択する必要があるのはなぜですか?

SkillsとPluginsはプロジェクトごとにインストールできます。そのため、アプリには現在のプロジェクトフォルダーが必要です。メインのサイドバーでプロジェクトを選び、Settingsを開き直してください。

モデルを設定したのにメッセージを送信できないのはなぜですか?

入力欄の下でモデルが選択されていることを確認し、APIキー、アカウント残高、ネットワーク接続を確認してください。プロバイダーカードの「Test」を使うと、具体的なエラーを確認できます。

モデル設定の復旧

長いセッションを開いたとき、最近のメッセージしか表示されないのはなぜですか?

初回読み込みを短縮するため、アプリは直近20件の会話から表示します。上にスクロールするか「Load earlier messages」を選んで続きを読み込んでください。ページ分割や遅延読み込みによって、ローカルに保存された履歴が削除・切り詰められることはありません。

Codingツールを許可したのにAgentがブラウザーを使えないのはなぜですか?

ブラウザーの読み取りと対話では、別個の許可が使用されます。コーディング権限は、ブラウザの読み取り/対話を暗黙的に有効にするものではありません。メイン ウィンドウの認証ダイアログを確認するか、[設定] → [ブラウザ] でポリシーを調整します。

管理対象のバックグラウンドプロセスを有効にできないのはなぜですか?

Confirm that the platform is supported and a trusted project folder is selected. Windows には Windows 11 x64 が必要です。 UI がヘルパー、所有者 ID、またはクラッシュ リーパーの問題を報告した場合は、再起動または再インストールのガイダンスに従い、必要に応じて診断をエクスポートします。

Herdrが見つからない、または接続できないのはなぜですか?

Herdr は、macOS arm64 / x64、Linux x64、および Windows x64 をサポートします。 Windows ARM64、Windows サーバー、および 32 ビット Windows はサポートされていません。 [設定] → [開発者ツール] でバンドルされた Herdr v0.8.2 をインストールまたは修復し、[設定] → Herdr でモード、セッション名、および接続ステータスを確認します。

WindowsまたはLinuxで上部メニューバーが表示されないのはなぜですか?

v0.2.3ではアプリとの一体感を高めるため、上部メニューバーを初期状態で非表示にしました。コマンドとショートカットに変更はありません。表示するには Alt 一時的に表示できます。macOSのメニューバーは引き続き画面上部に表示されます。

チャンネルのペアリングを承認したのに返信がないのはなぜですか?

最初のメッセージはペアリングを開始するために使われ、Agentには送信されません。承認後、同じユーザーから新しいメッセージを送ってもらってください。

ウィンドウを閉じるとメッセージングチャンネルがオフラインになるのはなぜですか?

「設定」→「一般」で閉じるときにトレイに最小化するを有効にします。トレイまたはアプリケーション メニューから [終了] を選択すると、すべてのチャネルが停止します。

Windows SmartScreenが表示されたらどうすればよいですか?

Windows インストーラーはまだコード署名されていません。配布元が GitHub Releasesであることを確認し、「詳細情報」→「実行」を選択してください。

Linux はサポートされていますか?

はい。Linux x64ではAppImageを利用できます。Linux ARM64版はまだなく、AppImageの更新は現在手動です。

問題を報告するにはどうすればよいですか?

アプリのバージョン、OS、エラーメッセージを記録し、次のページから問題を報告してください: GitHub Issue。 API キー、トークン、アプリ シークレット、またはその他の資格情報を含めないでください。