AIチュートリアル

Agent2API入門チュートリアル：デスクトップ版AIのログイン状態をOpenAI互換ゲートウェイに接続

本記事では、Agent2APIの仕組み、デスクトップ版・サーバー・Dockerの導入手順を解説し、アカウントの追加、ゲートウェイキーの作成、base_urlの設定、OpenAI互換インターフェースを使ったモデル呼び出しを実演します。

2026年10月19日約13分で読了

Agent2API入門：デスクトップ版AIのログイン状態をOpenAI互換ゲートウェイに接続

Agent2APIとは

Agent2APIは、複数のAIデスクトップクライアントにログイン済みのアカウントを統合し、統一されたOpenAI互換インターフェースを通じてモデル呼び出し機能を提供するローカルAI APIゲートウェイです。カスタムbase_urlに対応するクライアントであれば、http://127.0.0.1:3065/v1に接続できます。通常、上流API Keyは不要で、クライアントの変更も必要ありません。

Chat、Responses、Messagesの3種類のプロトコルに対応し、/v1/modelsモデル一覧インターフェースも提供します。ゲートウェイはローカルマシンまたはデプロイしたサーバー上で動作し、アカウントの利用枠は引き続き各アカウントに紐づきます。

主な機能

OpenAI互換インターフェース：/v1/chat/completions、/v1/responses、/v1/messagesに対応し、Messagesではcount_tokensも利用できます。
複数のプロバイダー：WorkBuddy、小浣熊、CatPaw、Qoder、Traeなど複数のプロバイダーを内蔵し、カスタムプロバイダーも設定できます。
アカウントのローテーション：アカウントを優先度順にキューへ登録し、429が発生した場合はアカウントを切り替えられます。利用制限のクールダウン中のアカウントは継続して使用されません。
認証情報の管理：一部のプロバイダーでは、Tokenの自動更新、期限間近の認証情報の一括更新、モデル一覧の更新に対応しています。
ネットワークとセキュリティ：アカウントごとに独立した外向きプロキシを設定でき、複数のゲートウェイKeyで権限を分配できます。
運用管理：リクエスト数、成功率、Token消費量、キャッシュヒット率、長期ヒートマップなどのレポートを提供します。
スケジュールタスク：自動チェックイン、認証情報の管理、モデル一覧の更新タスクを管理できます。

デプロイ方法を選択

アカウント管理画面：グローバルキュー、モデル別の制限クールダウン、有効期限と残高

Agent2APIには3つの形態があります。デスクトップ版は個人のPCでの利用に適しており、Windows、macOS、Linuxに対応し、トレイ常駐も可能です。サーバー版はGUIのないWindows ServerやLinux環境に適しています。Docker版は既存のコンテナ環境を利用するユーザー向けです。いずれの方法でも、実行時にNode.jsをインストールする必要はありません。

デスクトップ版：インストーラーでアプリを起動し、ゲートウェイはアプリのプロセス内で動作します。
サーバー版：システムサービスとしてインストールし、ブラウザーから管理パネルにアクセスできます。起動時の自動起動にも対応しています。
Docker：aimodcc/agent2api:latestイメージを使用し、amd64とarm64に対応しています。

インストールと初回設定

方法1：デスクトップ版

プロジェクトのLatest Releasesから、お使いのシステムに適したインストーラーをダウンロードします。起動後、「アカウント」ページで1つ以上のプロバイダーアカウントを追加します。デスクトップ版ゲートウェイは、デフォルトでローカルの3065ポートをリッスンします。

方法2：Linuxサーバー版

アカウント追加：プロバイダーとバージョンを選択し、Webログインを実行

tar -xzf agent2api-server-linux-amd64.tar.gz && cd agent2api-server-linux-amd64 && sudo bash install.sh

インストール完了後、ブラウザーでhttp://127.0.0.1:3065/にアクセスします。サービスがリモートホスト上で動作している場合は、アドレス内のホスト名をサーバーのIPアドレスまたはドメイン名に置き換えてください。

方法3：Windows Server

Expand-Archive agent2api-server-windows-amd64.zip -DestinationPath C:\agent2api-pkg
cd C:\agent2api-pkg
.\install-service.ps1

上記のコマンドは、管理者権限のPowerShellで実行してください。インストールスクリプトによって、サービスがシステムに登録されます。

方法4：Docker

モデル管理画面：プロバイダー別のモデル一覧、倍率、コンテキスト、マッピング

docker run -d --name agent2api --restart unless-stopped -p 3065:3065 -v ./data:/data aimodcc/agent2api:latest

ここでの./data:/dataは、設定とアカウントデータを永続化するために使用します。コンテナの起動後、http://127.0.0.1:3065/を開いて初期化を完了します。

管理者とゲートウェイKeyの初期設定

管理パネルを開き、管理者アカウントを登録します。
「ゲートウェイKey」ページに移動し、クライアント呼び出し用のKeyを作成します。
「アカウント」ページに移動し、プロバイダーとバージョンを選択して、画面の手順に従ってWebログインまたはログイン状態のインポートを完了します。
アカウントの状態、有効期限、残高が正常であることを確認します。
「モデル管理」ページに移動し、利用可能なモデルとモデルマッピングを確認します。

ゲートウェイKeyを設定していない場合、プロジェクトはデフォルトでAPIリクエストを拒否します。ゲートウェイKeyを公開コード、ログ、信頼できないクライアントに公開しないでください。

アカウントとモデルの設定

レポート概要：統計カード、Topアカウント／プロバイダー、モデルとプロバイダーの利用量ドーナツグラフ

アカウント管理ページでは、アカウントの有効期限、残高、グローバルキュー、モデル別の利用制限クールダウン状態を確認できます。複数のアカウントを追加すると、システムは優先度に基づいてスケジューリングします。あるアカウントで429が発生した場合やクールダウン状態になった場合は、別の利用可能なアカウントに切り替えられます。

アカウント管理画面：グローバルキュー、モデル別の制限クールダウン、有効期限と残高

モデル管理ページでは、プロバイダー別にモデル一覧、倍率、コンテキスト情報、マッピング関係を確認できます。モデル一覧をオンラインで自動取得できるプロバイダーは定期的に更新され、一部のプラットフォームではフォールバック用の内蔵静的リストも利用できます。

初回API呼び出し

カスタムAPIアドレスに対応するクライアントで、Base URLを次のように設定します。

http://127.0.0.1:3065/v1

API Keyには、先ほど作成したゲートウェイKeyを入力します。例としてsk-localを使用できますが、実際の呼び出しでは管理パネルで生成したKeyを使用してください。

レポートトレンド：キャッシュヒット率とToken消費量の二軸トレンド、日別Token棒グラフ

まず、ゲートウェイのヘルス状態を確認します。

curl http://127.0.0.1:3065/health

次に、モデル一覧を確認します。

curl http://127.0.0.1:3065/v1/models \
  -H "Authorization: Bearer YOUR_GATEWAY_KEY"

Chat Completionsインターフェースの呼び出し例：

curl http://127.0.0.1:3065/v1/chat/completions \
  -H "Authorization: Bearer YOUR_GATEWAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "messages": [
      {"role": "user", "content": "こんにちは。あなた自身について紹介してください。"}
    ]
  }'

チェックインセンター画面：チェックイン概要と毎日のチェックイン分類

YOUR_GATEWAY_KEYをゲートウェイKeyに、YOUR_MODEL_IDを/v1/modelsが返すモデルIDに置き換えてください。ResponsesとMessagesのプロトコルも同じゲートウェイアドレスを使用します。具体的なリクエストフィールドは、対応するクライアントまたはプロトコルの形式に従ってください。

複数アカウント、プロキシ、スケジュールタスク

複数アカウントのローテーション

同じプロバイダーに複数のアカウントを追加すると、グローバル優先度キューと429時のフォールバック機構によって可用性を高められます。アカウントの利用枠、有効期限、利用シーンに応じて適切な優先度を設定し、クールダウン中のアカウントを定期的に確認することをおすすめします。

外向きプロキシ

プロジェクトでは、アカウントごとに独立した出口を設定できます。この機能は、アカウントごとに外向きネットワークを管理する必要がある場面に適しています。ただし、プロキシの可用性、コンプライアンス、アカウントのリスク管理については、利用者自身が評価する必要があります。

スケジュールタスク

タスク管理ページでは、自動チェックイン、認証情報の管理、モデル一覧の更新を一元管理し、タスクの有効／無効と実行間隔を設定できます。プロバイダーによって対応機能が異なる点に注意してください。たとえば、一部のプラットフォームではTokenの更新、チェックイン、残高照会に対応していません。

レポートと利用量の確認

レポートページでは、リクエスト数、成功率、Token総量、人気モデル、アカウントランキングを確認でき、プロバイダー別の利用量分布も確認できます。トレンドページには、24時間のキャッシュヒット率、Token消費量、日別の統計データが表示されます。

レポート概要：統計カード、Topアカウント／プロバイダー、モデルとプロバイダーの利用量ドーナツグラフ

レポートトレンド：キャッシュヒット率とToken消費量の二軸トレンド、日別Token棒グラフ

プロバイダーが残高または利用量の照会に対応している場合は、アカウントページで関連情報を直接確認できます。チェックインセンターでは、チェックイン概要と毎日のチェックイン分類を確認できます。

開発とビルドに関する注意

ソースコードからデスクトップ版をビルドする場合、Rust 1.77以上、Tauri 2ツールチェーン、Node.js 18.17以上が必要です。Node.jsはフロントエンドのビルドとTauriスクリプトにのみ使用され、パッケージ化されたデスクトップ版の実行時にはNode.jsに依存しません。

npm run tauri:install
npm run tauri:dev
npm run tauri:build
npm run build:icon

ここで、tauri:dev は開発モードとホットリロードに使用し、tauri:build はデスクトップ版インストーラーのビルドに使用します。macOS の DMG は macOS 上でのみビルドでき、Windows からのクロスコンパイルはできません。正式な成果物はプロジェクトの CI ワークフローによって生成されます。

認証情報の安全性と利用範囲

Agent2API は学習および情報交換のみを目的としています。非公式クライアントとして、ユーザー自身のアカウントのログイン状態を再利用するため、上流サービスの利用規約に違反する可能性があります。アカウントのレート制限、リスク管理措置、凍結、停止などのリスクは、利用者自身が負うものとします。

プロジェクトは accessToken、refreshToken などのアカウント認証情報を平文でローカルの設定ディレクトリに保存します。デフォルトの保存場所は ~/.agent2api/ です。エクスポートしたファイルにも平文の認証情報が含まれる可能性があるため、設定を公開リポジトリにコミットしたり、オンラインストレージにアップロードしたり、他人と共有したりしないでください。

README では、プロジェクトを商用目的で利用すること、再配布によって利益を得ること、アカウントを大量に運用すること、上流サービスの課金やクォータ制限を回避すること、その他の法令に違反する活動に利用することを明確に禁止しています。運用環境や商用環境では、上流サービスの公式チャネルと公式 API を利用してください。利用前にプロジェクトの LICENSE および利用声明をお読みください。

まとめ

Agent2API は、複数のデスクトップクライアントのアカウントを、1 つのローカルな OpenAI 互換ゲートウェイに統合します。デプロイ、アカウントの追加、ゲートウェイ Key の作成が完了すれば、統一された base_url を使用して、カスタム API アドレスに対応するツールから接続できます。複数アカウントのローテーション、モデル管理、プロキシ、スケジュールタスク、レポート機能は、さらに高度なローカル管理に適しています。利用時は認証情報を適切に保護し、上流サービスの利用規約とプロジェクトの追加利用声明を厳守してください。