Skip to content

Latest commit

 

History

History
360 lines (247 loc) · 39.4 KB

install.ja.md

File metadata and controls

360 lines (247 loc) · 39.4 KB

インストールとデプロイ

このページは 3 つの提供形態 —— デスクトップ(Windows / macOS / Linux)、サーバー(Windows / Linux、ヘッドレス)、Docker —— の完全なインストールと運用ガイドです。どれを選ぶか迷ったら、まず下の対応表をご覧ください。

どの形態も、導入後の管理(アカウント追加、ゲートウェイキーの作成、レポート閲覧)はブラウザーパネルで行います —— パネルはゲートウェイと同じポートで待ち受け、デスクトップ版だけはアプリウィンドウも持ちます。

简体中文 | English | 繁體中文 | 日本語 | 한국어 | Português (BR)

目次

どの形態を選ぶか

お使いのマシンに合う行を選んでください:

形態 成果物 インターフェース 説明
Windows デスクトップ(推奨) Agent2API_<バージョン>_x64-setup.exe アプリウィンドウ NSIS インストーラー。既定では C:\Program Files\Agent2API にインストールされ、セットアップ時に管理者権限が必要
macOS デスクトップ Agent2API_<バージョン>_universal.dmg アプリウィンドウ ユニバーサルバイナリ(Apple Silicon と Intel をそれぞれビルドして統合)。macOS 10.15 以上
Linux デスクトップ Agent2API_<バージョン>_amd64.deb または Agent2API_<バージョン>_amd64.AppImage アプリウィンドウ deb はシステムにインストール(webkit2gtk-4.1 / gtk3 に依存)。AppImage はインストール不要の単一ファイルで、どのディストリビューションでも動作
Windows サーバー(GUI なし) agent2api-server-windows-amd64.zip ブラウザーパネル コマンドラインでインストールし Windows サービスとして登録 —— サーバー を参照
Linux サーバー(GUI なし) agent2api-server-linux-<arch>.tar.gz ブラウザーパネル コマンドラインでインストールし systemd で常駐。同じパッケージはコンテナ内更新のペイロードも兼ねます
Docker aimodcc/agent2api:latest ブラウザーパネル amd64 / arm64 の 2 アーキテクチャ。詳しくは Docker デプロイ

どれを選ぶか: デスクトップがある(トレイ、起動時の自動起動、本機ログイン状態の取り込みが欲しい)→ デスクトップ版。 サーバーにグラフィカルインターフェースが無い(Windows Server / Linux サーバー)→ サーバーパッケージ。 すでに Docker を動かしている → イメージ。

デスクトップ版はグラフィカルセッションが必要で、ヘッドレスサーバーにはインストールできません。 サーバーパッケージは WebView / GTK に一切リンクせず、実行ファイル 1 つと ui/ ディレクトリだけで動きます。

デスクトップ(Windows / macOS / Linux)

デスクトップ(Windows / macOS / Linux)はインストール後そのまま起動するだけです。Node やその他のランタイムは不要で、ゲートウェイはアプリのプロセス内で動き、トレイに常駐します。

  1. 初回起動時に、アプリのプロセス内で本機ゲートウェイ(ポート 3065)が起動し、メインウィンドウが開きます。旧バージョンのデータディレクトリやデータファイルが見つかった場合は、移行を促すダイアログが表示されるので、案内に従って操作してください。
  2. 「アカウント」ページの「アカウントを追加」をクリックし、プロバイダーを選んでダイアログの案内どおりにログインまたは認証情報を入力します(Web ログイン / SMS 認証コード / 認証情報の貼り付け / 本機のログイン状態の取り込み)。
  3. OpenAI クライアントの base_url に http://127.0.0.1:3065/v1 を設定し、api_key は何でも構いません(例: sk-local。認証を有効にしていない場合、サーバー側は検証しません)。

ウィンドウを閉じても既定ではトレイに最小化されるだけで、ゲートウェイはバックグラウンドで転送を続けます。完全に終了するには、トレイアイコンを右クリックして「終了」を選んでください。

macOS での初回起動: dmg 内のアプリには Apple のコード署名も公証も施していません(署名には有料の Apple Developer アカウントが必要です。.github/workflows/build.yml の説明を参照)。そのため Gatekeeper が初回起動をブロックします。「システム設定 → プライバシーとセキュリティ」で一度手動で許可してください。

Linux デスクトップ: トレイは libayatana-appindicator3 に依存します(多くのデスクトップ環境には同梱)。アイコンが表示されない場合は libayatana-appindicator3-1 をインストールして再起動してください。AppImage は初回実行前に実行ビットが必要です(chmod +x。「インストーラーを開く」を選ぶと自動で付与されます)。更新方法: deb はシステムのインストーラー経由(インストール時に一度パスワードを求められます)、AppImage はファイルを差し替えるだけで更新完了です。

デスクトップ版の差異: AutoClaw と智谱清言の「本機のログイン状態を取り込む」は Windows でのみ利用できます(Windows の DPAPI 暗号文を読むため、macOS / Linux ではこのセクションごと非表示になります)。ほかのプロバイダー(小浣熊 / CatPaw / Cline)は HOME 配下の平文ファイルを読むため、3 プラットフォームすべてで使えます。トレイ、自動起動、LAN アクセス、Web パネルのホストは macOS / Linux でも同様に利用できます。

サーバー(Windows / Linux、ヘッドレス)

グラフィカルインターフェースの無いサーバー(Windows Server、Linux サーバー、クラウドインスタンス)向けです。成果物はいずれも同じ agent2api-server バイナリで、ウィンドウもトレイも無く、WebView / GTK にもリンクせず、実行時に Node などのランタイムも不要です。コマンドが行うのはインストールだけで、その後の管理(アカウント追加、キー作成、レポート閲覧)はすべてブラウザーパネルで行います。

サービスはシステムサービスとして常駐します: 起動時の自動開始、クラッシュ後の自動再起動、コンソールなしのバックグラウンド動作。

Windows Server

agent2api-server-windows-amd64.zip をダウンロードして展開し、管理者として PowerShell を開きます:

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

スクリプトは、プログラムを C:\Agent2API に、データを C:\ProgramData\Agent2API に配置し、Agent2API という名前の Windows サービス(LocalSystem、起動時に自動開始)を登録し、ファイアウォールの受信規則を追加してからサービスを開始します。

# 場所とポートのカスタマイズ
.\install-service.ps1 -InstallDir D:\apps\agent2api -DataDir D:\data\agent2api -Port 8080

# 日常の管理
Get-Service Agent2API
Restart-Service Agent2API
Stop-Service Agent2API

# アンインストール(データは保持)。-Purge を付けるとプログラムごと削除
.\install-service.ps1 -Uninstall

ワンクリック更新:標準の Windows サービスは「設定 → 更新」から更新できます。確認後、Windows x64 サーバーパッケージをダウンロードし、公式ハッシュを独立検証します。一時的な更新プロセスがサービスを停止し、ファイルの解放を待ってバックアップ・置換・再起動を行います。新版の起動確認後にページを再読み込みし、アカウント・設定・データは保持します。

旧インストールの接続 / 手動更新:新版を新しいディレクトリに展開し、管理者として install-service.ps1 を一度実行してください。既存のインストール先、データ先、ポート、環境設定、サービスアカウントを保持します。ポートなど明示的に渡した項目のみ変更し、ディレクトリ移行は別途行います。その後はパネルから更新できます。

プログラムの書き込みは SYSTEM と管理者のみ許可し、作業場所は <インストール先>\.service-update です。常駐サービスは追加しません。サービス環境の AGENT2API_WINDOWS_UPDATE=0 で入口を無効化できます。カスタムアカウント、ディレクトリリンク、ネットワークパス、外部ジョブ管理環境は手動更新のままです。置換失敗時は旧ファイルへ復元し、新版起動失敗時はログとバックアップを残してデータベースを自動で巻き戻しません。

Windows 固有の落とし穴はスクリプト側で対処済み: サービスの作業ディレクトリは exe のあるフォルダーではなく C:\Windows\system32 です —— UI ディレクトリは exe のパスから特定するので影響ありません。データディレクトリはサービス登録の AGENT2API_PROXY_HOME に明示的に書き込みます(未設定だと LocalSystem の C:\Windows\system32\config\systemprofile の下に落ちて、まず見つけられません)。 サービスにはコンソールが無いため、ログはファイル C:\ProgramData\Agent2API\logs\server.log にも出力されます。

Linux(systemd)

tar -xzf agent2api-server-linux-amd64.tar.gz
cd agent2api-server-linux-amd64      # 展開後のディレクトリ名に合わせてください
sudo bash install.sh

スクリプトは agent2api システムアカウント(ログイン不可)を作成し、プログラムを /opt/agent2api、データを /var/lib/agent2api、設定を /etc/agent2api/agent2api.env に配置し、systemd ユニットを enable + start します。

# アップグレード(データと設定は保持。旧バイナリは .bak に退避)
sudo bash install.sh --upgrade

# アンインストール(データは保持)。--purge を付けるとデータと設定ごと削除
sudo bash install.sh --uninstall

# 日常の管理
systemctl status agent2api
systemctl restart agent2api
journalctl -u agent2api -f

起動時の自動開始、クラッシュ後の自動再起動(Restart=always)、SIGTERM での優雅な停止(処理中のリクエストを待ってから終了するため、SSE の長時間接続が切れません)はすべて設定済みです。/etc/agent2api/agent2api.env を編集したら systemctl restart agent2api で反映します。

systemd ワンクリック更新:標準インストールには権限を制限した更新プログラムが含まれます。パネルで更新を確認すると、ダウンロード、公式チェックサムの独立検証、バックアップと置換、再起動、新版サービスの確認まで実行します。アカウントと設定は保持され、ゲートウェイは一般ユーザーのまま、プログラムファイルは root 所有のままです。

旧インストールでは、この機能を含む新サーバーパッケージを取得し、そのディレクトリで一度 sudo bash install.sh --upgrade を実行して更新コンポーネントを導入してください。カスタムサービスアカウントやパスは上書きしません。従来の手順で更新してください。AGENT2API_SYSTEMD_UPDATE=0 でパネルの入口を無効化でき、agent2api-updater.socket を無効にすると更新コンポーネントも停止します。AGENT2API_SELF_UPDATE は引き続き Docker 専用です。

更新プログラムはローカル socket を使用し、ネットワークポートは公開しません。既定で公式インデックスから公開リポジトリを検証します。固定リポジトリや独立検証用プロキシは、管理者が /etc/agent2api/updater.env に AGENT2API_UPDATER_REPO=owner/repo または HTTPS_PROXY を設定できます。置換失敗時は旧ファイルに復元します。新版の起動を確認できない場合は /opt/agent2api/.before-update-* に復旧ファイルを残して失敗を通知し、データベースは自動で巻き戻しません。

インストール後

どちらのプラットフォームも同じです —— ブラウザーで開きます:

http://<サーバーIP>:3065/
  1. 初回アクセスでは管理者アカウントの登録へ案内されます(環境変数での事前設定も可能。下記参照)
  2. ログイン後、「ゲートウェイキー」ページで API キーを作成します
  3. クライアントの base_url を http://<サーバーIP>:3065/v1 に、api_key を作成したキーに設定します

⚠️ キーを作成するまで /v1/* はサービスを拒否します(fail-closed)。これは意図的な挙動です。サーバー形態は 0.0.0.0 にバインドするため、キー無しで上流のクォータをネットワーク全体に開放するのは受け入れられません。

無人デプロイ

管理者とゲートウェイキーはいずれも環境変数で事前設定でき、ブラウザーでの手作業を省略できます:

変数 説明
AGENT2API_ADMIN_USER + AGENT2API_ADMIN_PASSWORD 管理者を事前設定(パスワードは平文で記入、起動時に bcrypt へ変換)。AGENT2API_ADMIN_PASSWORD_HASH でハッシュを直接指定することもできます
AGENT2API_PROXY_API_KEY ゲートウェイキーを 1 本事前設定し、「パネルで最初の 1 本を作る」手順を省略
AGENT2API_PROXY_HOME データディレクトリ
AGENT2API_HOST / AGENT2API_PROXY_PORT リッスンアドレス(既定 0.0.0.0)/ ポート(既定 3065)
AGENT2API_PANEL_PORT パネルを別ポートに分離: 管理プレーンがそのポートで待ち受け、メインポートは /v1/* のみを提供
AGENT2API_ALLOW_NO_KEY 1 で fail-closed を無効化(純粋な内部ネットワーク限定)
AGENT2API_LOG_FILE ログファイルのパス。既定は {データディレクトリ}/logs/server.log
AGENT2API_VERBOSE 1 で debug ログを有効化

Linux では /etc/agent2api/agent2api.env に、Windows ではサービスのレジストリキー HKLM\SYSTEM\CurrentControlSet\Services\Agent2API\Environment に記述します(install-service.ps1 が基本項目を書き込み、再実行時は既存の設定を保持し、引数で明示した項目だけを変更します)。

アカウントは事前設定できません: アカウントには QR スキャン / SMS コード / 認証情報の貼り付けが必要で、これは上流プロトコルが決めるため回避できません。大量展開では、設定済みのデータディレクトリをまるごとコピーしてください(SQLite データベースと account.key が同じディレクトリにあり、アカウントも一緒に移ります)。

Docker

イメージタグ:latest は最新の正式版、beta は最新の beta プレリリースを追従します。3.3.0-beta.3 のような完全なバージョン番号で固定することもできます。beta を使うには、以下のコマンドまたは Compose 設定の aimodcc/agent2api:latest を aimodcc/agent2api:beta に変更し、更新時は docker compose pull && docker compose up -d を実行してください。beta の公開で latest は変更されず、手動の開発ビルドは dev のみ更新します。同じイメージは GitHub Container Registry にも公開しています。イメージ名を ghcr.io/aimod-cc/agent2api に置き換えてください(タグ規則は同じです)。

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

ブラウザーで http://<ホスト>:3065 を開くと、初回は管理者アカウントの登録へ案内されます。ログイン後、「ゲートウェイキー」ページでクライアント用の API キーを作成してください —— http://<ホスト>:3065/v1 が OpenAI 互換エンドポイントです(キーを作成するまで転送は拒否されます)。すべての状態(SQLite データベース / 設定 / ログ)は ./data ボリューム 1 つに収まります。

compose を使う場合(amd64 / arm64 のイメージがあります):

services:
  agent2api:
    image: aimodcc/agent2api:latest
    container_name: agent2api
    restart: unless-stopped
    ports:
      - "3065:3065"
    volumes:
      - ./data:/data

環境変数(すべて任意):

変数 説明
AGENT2API_ADMIN_USER + AGENT2API_ADMIN_PASSWORD 管理者アカウントとパスワードを事前設定(パスワードは平文で指定、起動時に自動でハッシュ化)。未設定ならパネルで登録
AGENT2API_PANEL_PORT パネルを別ポートに分離: 設定するとパネル(UI + /api/*)がそのポートだけで待ち受け、公開側はメインポートのみをマッピングして管理面を内部に留められます(パネルポートはループバックに束縛。127.0.0.1:3066:3066 のように記述)
AGENT2API_HOST / AGENT2API_PROXY_PORT リッスンアドレス(既定 0.0.0.0)/ ポート(既定 3065)
AGENT2API_ALLOW_NO_KEY 1 で fail-closed を無効化(キー未設定でも /v1 を許可。純粋な内部ネットワーク限定)
AGENT2API_CAPTCHA_ENABLED ログインページの人間確認ウィジェット: 既定 1(有効)、0 で無効
AGENT2API_SELF_UPDATE コンテナ内の更新入口: 既定 1(有効。パネルから「ダウンロードして更新」可能)。0 で無効化し手動更新のみに
AGENT2API_IMAGE_CACHE_MB 生成画像のダウンロード用メモリキャッシュ上限(MiB、既定 128、範囲 8〜4096)。不正 / 範囲外は既定値にフォールバック
AGENT2API_IMAGE_COMPRESS_CACHE_MB セッション画像の圧縮結果メモリキャッシュ上限(MiB、既定 128、範囲 8〜4096、扱いは同じ)
WORKBUDDY_UPDATE_REPO + WORKBUDDY_UPDATE_API_BASE 上級: 「更新確認 / 更新ダウンロード」を自前のソースに差し替えます。前者はリポジトリを変更(既定は上流の aimod-cc/Agent2API。fork 後は変更可)、後者は API ルートを変更(既定 https://api.github.com。GitHub と同じ形の release JSON を返す必要があります)。自前ソース設定後、ダウンロードの許可リストはそのソース自身のホストのみを追加で許可します(スキームはソースに従う: http:// を設定すれば平文ダウンロードも許可。ローカル演習 / 内部ミラー向け)

ソースからビルドする場合: 本リポジトリをクローンして docker compose up -d --build(イメージにはゲートウェイとパネルのみが入り、Rust ツールチェーンは含まれません)。

メモリ使用量

イメージ内のゲートウェイ(Linux ターゲット)には jemalloc アロケーターを組み込んでいます。長時間の稼働やマルチアカウントの並行転送では、システム標準のアロケーターよりメモリ断片化が起きにくく、RSS がじわじわ増えにくくなります —— 小メモリのマシンが最もよく押し潰されたり OOM になったりする箇所です。

小メモリのマシンでは、コンテナにメモリ上限を設定することをおすすめします。超過するとカーネルがプロセスを終了し、restart: unless-stopped が起動し直します。「1 回再起動する」形になり、ホスト(や同居する他サービス)を巻き込みません。

# docker run
docker run -d --name agent2api --restart unless-stopped --memory=1g \
  -p 3065:3065 -v ./data:/data \
  aimodcc/agent2api:latest

compose の場合はサービスに mem_limit: 1g を 1 行追加します(docker-compose.yml にコメント例があります)。swarm や docker compose --compatibility では deploy.resources.limits.memory を使います。1g はあくまで出発点で、実際の並行数に合わせて調整してください。

常駐メモリを使う 2 つの画像キャッシュ上限は、どちらも環境変数で小さくできます(既定は各 128 MiB): AGENT2API_IMAGE_CACHE_MB(生成画像のダウンロードキャッシュ)、AGENT2API_IMAGE_COMPRESS_CACHE_MB(セッション画像の圧縮結果キャッシュ)。不正 / 範囲外の値は既定値にフォールバックし、起動を妨げることはありません。

MALLOC_ARENA_MAX=2 のような glibc アロケーターの調整は、jemalloc を組み込んでいない形態(旧イメージ、自前ビルドのサーバー、デスクトップ)にのみ意味があります。本イメージでは設定不要です。

Web パネルでの機能差(「本機デスクトップクライアントが無い」ことに起因): Web ログイン(WorkBuddy / Qoder / Cline)、SMS 認証コード、認証情報の貼り付けは完全に利用できます。本機へのコールバックが必要な Web ログイン(AutoClaw / CatPaw / Accio / CodeArts / Trae)と「本機ログイン状態の取り込み」は利用できないため、認証情報の貼り付けをお使いください。デスクトップ版で「Web 管理パネルも公開する」を有効にしてブラウザーから開いた場合も同じ差になります —— 同一の画面、同一の判定です。

コンテナ内アップデート(任意)

パネルの「ソフトウェア更新」ページから、コンテナ内でそのまま「ダウンロードして更新」できます。公式 Release の agent2api-server-linux-<arch>.tar.gz(.sha256 を検証)を取得 → 実行ファイルと ui/ を差し替え → プロセスが正常終了し、restart ポリシーが同じコンテナを起動し直します。AGENT2API_SELF_UPDATE で制御します(Dockerfile では既定 1)。0 にすると手動アップグレードのみになります。

同じ agent2api-server-linux-<arch>.tar.gz は Linux サーバー のインストールパッケージでもあります: 中の agent2api-server と ui/ がこの更新経路が名前で取得する項目で、さらに install.sh / agent2api.service / agent2api.env.example も同梱されています。更新経路が読むのは前の 2 つだけ(残りは読んで捨てます。selfupdate::extract_bundle を参照)なので、1 つの成果物が 2 つの用途を兼ねます —— コンテナ内では展開して差し替え、ベアメタルでは展開して install.sh を実行。

トレードオフに注意してください: コンテナ内更新の後は、イメージタグと実際に動作しているバージョンがずれます(docker inspect は古いタグを表示したままです)。docker compose pull && up -d でコンテナを再作成すると、イメージに焼き込まれたバージョンに戻ります。バージョンを固定したい場合はこの入口を有効にしないでください。

動作確認とクライアント接続

ゲートウェイが起動したら、curl で接続を確認します(model には GET /v1/models に実在する名前を入れてください):

curl http://127.0.0.1:3065/health
curl http://127.0.0.1:3065/v1/models

curl http://127.0.0.1:3065/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{"model":"deepseek-v4.1-flash","messages":[{"role":"user","content":"你好"}],"stream":true}'

クライアントからの呼び出し例(Python SDK):

from openai import OpenAI

client = OpenAI(base_url="http://127.0.0.1:3065/v1", api_key="sk-local")
resp = client.chat.completions.create(
    model="deepseek-v4.1-flash",     # 一覧にあるどのプロバイダーのものでも可 — GET /v1/models を参照
    messages=[{"role": "user", "content": "你好"}],
)
print(resp.choices[0].message.content)

ブラウザー上のページ(自作の Web UI など)から fetch で直結するとクロスオリジンのプリフライトで拒否されます —— ゲートウェイは既定で CORS に応答せず、プリフライトは API キー検証に到達して 401 になります。解決策: ① 設定ページの「セキュリティ → ゲートウェイのクロスオリジンアクセス」を有効に(オリジン *。任意の Web ページから本機ゲートウェイを叩けてしまうため「ゲートウェイキー」も併せて設定してください); ② ページをゲートウェイと同一オリジンに —— ローカルの静的サーバーでページを配信し /v1 を 127.0.0.1:3065 にリバースプロキシします。

LAN アクセス

既定では 127.0.0.1 のみをリッスンします。「設定 → 一般 → LAN アクセス」を有効にするとすべてのネットワークアダプターで待ち受け、LAN 内の機器は API アドレスを本機の IP に向けるだけで(画面に完全なアドレスが表示されます)アカウント群を共有できます。セキュリティのため、有効化の前にパネル管理者の登録が必要です。管理 API は管理者セッションまたはゲートウェイキーを要求し、有効なキーが無い場合は転送 API も拒否します(有効化の流れで「既定」キーが自動追加されます)。Web パネルの LAN 公開も任意で選べます(既定は非公開)。変更は再起動後に有効です。

デスクトップ版(Windows / macOS)のインストーラーには Web パネルの ui/ も同梱されています。「Web 管理パネルも公開する」を有効にすると、LAN 内の機器がブラウザーで同じアドレスを開くだけで管理画面になります —— Docker 版と同一の画面です。デスクトップウィンドウ自体は Web ログインを通りません(ログインページが無いため)。本機の最初のゲートウェイキーを資格情報として使うので、このスイッチを入れるのにデスクトップ側で追加のログインは不要です。Web ログインページは、ブラウザーからパネルを開いたときにだけ表示されます。

モバイル

モバイルには 3 つの形態があります。用途で選んでください:

形態 インストール方法 向いている用途
ブラウザー / PWA スマートフォンのブラウザーで /m を開く。「ホーム画面に追加」も可 ちょっと見たい、何も入れたくない、iPhone ならこれが最短
Android APK Agent2API-<バージョン>.apk をインストール アイコンが欲しい、全画面、複数サーバーの管理
iOS IPA Agent2API-<バージョン>.ipa をインストール(未署名・自己再署名が必要) アイコンが欲しい、全画面

いずれも同じ UI コードです。違いは「誰がページを配信するか」: PWA はゲートウェイが配信し(「Web 管理パネルも公開する」が必須)、APK / IPA は UI をパッケージに同梱します(オフラインでも UI が起動でき、そのスイッチは不要)。

前提条件(形態別)

デスクトップ(Windows / macOS / Linux): 2 つのスイッチを両方オンにする必要があります。

  1. 「設定 → 一般 → LAN アクセス」— LAN 内の機器からゲートウェイへアクセスできるようにします。有効化の流れでパネル管理者の登録が求められ、「既定」という名前のキーが自動追加されます。
  2. 「設定 → 一般 → LAN アクセス → Web 管理パネルも公開する」— ui/ 静的フォルダーを配信します。ブラウザー / PWA 形態では必須(/m はゲートウェイが配信するため、このスイッチがオフだと 404)。APK / IPA では不要(UI はパッケージ内)ですが、1 番目のスイッチは必要です — でないとゲートウェイは 127.0.0.1 だけをリッスンし、スマートフォンから到達できません。

どちらも再起動後に有効になります。

サーバー / Docker: 追加のスイッチは不要です — どちらの形態も既定で全アダプターをリッスンし、ui/ を配信します(Dockerfile に AGENT2API_UI_DIR=/app/ui が固定で書かれています)。コンテナまたはサービスのポートが LAN から到達可能であれば十分です。AGENT2API_HOST=127.0.0.1 を手動で設定した場合は 0.0.0.0 に変更してください。AGENT2API_UI_DIR が存在しないディレクトリを指す場合、パネルは 404 になりますが API は動作し続けます。

スマートフォンで開く(ブラウザー / PWA)

http://<ゲートウェイが動作するマシンの LAN IP>:3065/m

デスクトップ版では上記の設定画面に表示されるアドレス(例: 192.168.1.23)の末尾 /v1 を /m に置き換えます。Docker / サーバーではホストの LAN IP とマッピングされたポートを使います。

初回アクセス時はログインページへリダイレクトされ、パネル管理者でサインインすると自動的にモバイル UI へ戻ります。管理者が未登録の場合は、ログインページで作成を求められます。

APK をインストール(Android)

初回起動時は「サーバー」画面になります。手順は 3 つだけ:

  1. 「追加」をタップし、ゲートウェイの IP またはドメイン:ポート を入力(例: 192.168.1.23:3065)。プロトコルは http:// または https:// が使えます(省略時は http)。ポートを省略すると http は 3065、https は標準の 443 になります;
  2. 「接続して保存」をタップ — まず疎通確認を行うので、アドレスの誤りや LAN アクセス未有効はその場で分かります;
  3. ログインページが表示されます。このゲートウェイの管理者アカウントとパスワードを入力(管理者が未登録なら「管理者アカウントを作成」になります)。

複数サーバー: もう一度「追加」するだけです。ログイン状態はサーバーごとに個別に保存されるため、切り替えても再ログインは不要、戻しても同様です。入口は「設定 → サーバー」で、一覧の行をタップすると切り替わります。ログインページの下部にも「別のサーバーに切り替える」 があるので、ログアウト後(またはログアウトされた後)に、一覧へ行くためだけにログインし直す必要はありません。

APK の既知の制限:

  • プロトコルを書かない場合は http:// の LAN アドレスに平文で接続します。リスクは「同一 LAN 内で盗聴可能」で、ゲートウェイ自体は管理者ログインを要求します。解消したい場合はゲートウェイに TLS を設定し(リバースプロキシやトンネルでも可)、App に https:// アドレスを入力してください — プロトコルはそのまま保持され、証明書が無効なら疎通確認が即座に失敗します。
  • UI は APK のバージョンに従い、ゲートウェイの更新には追随しません。ゲートウェイ更新で新しい画面が増えた場合、それを見るには新しい APK が必要です(データの変化は影響を受けません)。

IPA のインストール(iOS)

Release の Agent2API-<バージョン>.ipa は既定で未署名です — Apple は開発者が自由にインストール可能なアプリを配布することを許していないため、未署名パッケージは自分の Apple ID で一度再署名する必要があります。3 つの経路があります:

方法 必要なもの 有効期間
AltStore / SideStore / Sideloadly PC(初回のみ)+ 無料の Apple ID 7 日、その後再署名
Apple Developer Program 年 $99、自分の証明書とプロビジョニングプロファイル 1 年
App Store / TestFlight 年 $99 + 審査 長期

サイドロードの手順: .ipa を AltStore(または SideStore)にドロップし、Apple ID で再署名してインストールします。無料アカウントの制限は「同時に 3 アプリまで」「7 日ごとに再署名」です。

iPhone でゲートウェイを眺めたいだけなら、Safari で /m を開いて「ホーム画面に追加」するだけで十分です — IPA は不要で、再署名の手間も省けます。

IPA の既知の制限:

  • アプリ内更新はリンクを開くだけ: iOS はアプリが実行コードをダウンロードしてインストールすることを許さないため、設定の「ソフトウェア更新」は Release ページを開く「ダウンロード」ボタンになります(Android のように直接ダウンロードはしません)。PWA 形態は Service Worker で更新されるので、再読み込みすれば済みます。
  • 平文 http:// のゲートウェイ: Info.plist で ATS の平文制限を緩和し、ローカルネットワークの用途も宣言済みです。初回接続時に「ローカルネットワークへのアクセスを許可」のダイアログが出るので、必ず許可してください — 拒否するとすべてのリクエストが理由も表示されず失敗します。
  • それ以外は APK と同じです: UI はパッケージのバージョンに従い、既定のプロトコルは http です。

ホーム画面に追加(ブラウザー / PWA)

任意 — アドレスバーのない全画面になります。モバイル UI の「設定 → アプリとしてインストール」に入口があります:

  • Android / Chrome: 設定ページの「ホーム画面に追加」をタップ(システムのインストールダイアログが開きます)。メニュー → 「ホーム画面に追加」/「アプリをインストール」でも可
  • iOS / Safari: Safari にはインストール API がないため、設定ページに手順を明記しています — 共有 → 「ホーム画面に追加」

ホーム画面のアイコンから開くと、モバイルのホームページに直接移動します。すでに独立ウィンドウで動作している場合、設定ページには「インストール済み」と表示されます。

新しいバージョンがあると、画面下部に「再起動して更新」のバーが浮かびます。ゲートウェイ更新後の新しい UI はすでにダウンロード済みで、ワンタップで切り替わります(無視しても現在の利用に影響はなく、次回起動時に反映されます)。

ネイティブアプリ / ストアパッケージが無い理由: モバイル UI は常に別のマシンで動作するゲートウェイに接続します(ゲートウェイはそのマシンのクライアントログインを読み、設定ファイルを書き込む必要があり、スマートフォンでは動作できません)。本質は「HTTP サービスへのリモートアクセス」であり、ブラウザーが最適な媒体です — 同一オリジン認証、インストール不要、ゲートウェイと一緒にアップグレードされます。PWA 形式では全画面表示とホーム画面アイコンが追加され、ネイティブアプリと同じ操作感になります。

Service Worker(オフラインシェル)は https または localhost でのみ動作します: LAN アクセスは http://<IP> のため、ブラウザーは SW を提供せず、オフライン時にモバイル UI は開けません。これはブラウザーのセキュリティ制限であり、機能不足ではありません — 通常利用時はゲートウェイがオンラインなので影響ありません。

できること / できないこと

できる できない(デスクトップ版で操作)
レポート、アカウント状態、残高、リクエストログ、実行ログの閲覧 アカウント追加(QR / トークン貼り付け / ログイン状態のインポート)
アカウントの有効化/無効化、資格情報の更新、削除 アカウントの資格情報・プロキシ・レート制限ルールの編集
ワンタップチェックイン、チェックイン履歴の閲覧 新規特典とプランの個別受け取り
モデルの有効化/無効化、プロバイダー別の絞り込み モデルマッピング、推論レベル、ケイパビリティフラグの編集
ゲートウェイキーのコピー、キーの有効化/無効化 キーの新規作成、プロバイダー/モデルの許可リスト設定
手動 HTTP / SOCKS5 プロキシの追加・編集・削除、Clash Verge エンドポイントの同期、有効化/無効化、接続テスト —(プロキシのサブスクリプションと内蔵カーネルは提供終了)
スケジュールタスクの有効化/無効化、間隔の変更 ポート、ルーティング、リトライ、タイムアウト、データ保持の変更
アシスタントのクイック照会(残高 / 重複モデル / 本日の使用量 / レート制限中のアカウント) アシスタントの自由対話とツール呼び出し
Agent テイクオーバーの状態確認、復元 クライアント設定の書き換え(スマートフォンからはローカルファイルを読めません)

デスクトップ版のサイドバー下部に「スマートフォンで開く」という入口があり、同じページに移動します。