インストール・初回起動

対応環境

Agent Switchboard は次の 3 つの環境で動作します。

macOS 版は Apple Silicon 専用です。Intel Mac 用のファイルは提供していません。

インストールファイルはダウンロードページから入手します。ダウンロードページでは、いま使っている OS が最初に表示されます。

Windows

Setup と Portable の選択

• Setup（Agent-Switchboard-Setup-…exe）をおすすめします。インストール後、アプリ内で新しいバージョンをダウンロードしてインストールできます。
• Portable（Agent-Switchboard-Portable-…exe）はインストールせずに実行します。アプリ内での自動インストールには対応していません。新しいバージョンが出たら、ダウンロードページからファイルを再度ダウンロードする必要があります。

SmartScreen の警告

Windows 版のインストールファイルには、まだ Authenticode のコード署名がありません。そのため、ブラウザーでダウンロードしたときや初回実行時に、Windows SmartScreen が発行元を確認できないと警告することがあります。

1. ファイルを公式ダウンロードページ（switchboard.twentyoz.kr）から入手したことを確認します。
2. 警告ウィンドウで 詳細情報 を押し、続けて 実行 を押します。

インストール後にアプリ内で受け取るアップデートは、別途検証します。アプリに組み込まれた公開鍵でアップデートポリシーの署名とインストールファイルの SHA-512 ハッシュを確認した場合にのみインストールします。この検証は OS のコード署名の代わりにはなりません。

macOS

1. …-mac-arm64.dmg ファイルを開きます。
2. Agent Switchboard を「アプリケーション」フォルダーにドラッグします。
3. 「アプリケーション」フォルダーからアプリを起動します。

macOS 版の配布ファイルは、Developer ID 署名と Apple の公証（notarization）を経て公開しています。公開前には Gatekeeper の検証にも合格する必要があります。そのため、公式ダウンロードページから入手したファイルは通常のアプリと同じように開けます。

Linux

AppImage

AppImage はインストール不要で、実行権限を付与するだけで使えます。

chmod +x Agent-Switchboard-<버전>-linux-x86_64.AppImage
./Agent-Switchboard-<버전>-linux-x86_64.AppImage

.deb（Debian・Ubuntu 系）

sudo apt install ./Agent-Switchboard-<버전>-linux-amd64.deb

（ファイル名とコマンド中の <버전> はバージョン番号に置き換えてください。）

セキュアストレージ（keyring）

API キーは OS のセキュアストレージに暗号化して保管します。Linux では Secret Service などのデスクトップ keyring が必要です。keyring が使えない場合、キーを平文で保存することはせず、API キー接続の 저장 후 적용（保存して適用）の上に保存できない理由を表示します。keyring を有効にしてからアプリを再起動してください。スマートフォン連携も、セキュアストレージがないとオンにできません。

初回起動

アプリを初めて開くと、左側のレールと作業画面が表示されます。次の順に始めます。

1. プロジェクトフォルダーの登録: 左側のレールの下部にある 폴더 추가（フォルダーを追加）アイコンを押し、作業するフォルダーを選びます。フォルダーを選ぶと、そのフォルダーのプロジェクトホームが開きます。
2. 接続の登録: サイドバー下部の 환경 설정（環境設定）（ショートカット: Windows・Linux は Ctrl+,、macOS は ⌘,）を開き、연결 · 인증（接続・認証）で API キーやゲートウェイを登録します。サブスクリプションのログイン（OAuth）だけを使う場合は、この手順を省略してかまいません。
3. ツールへの適用: プロジェクトホームの 도구 설정（ツール設定）でツールを選び、接続とモデルを決めます。詳しくは接続・プロジェクト別設定を参照してください。
4. 実行: プロジェクトホームのヘッダーからツールを直接実行するか、レールのプロジェクトメニュー ⋯ → 새 세션（新しいセッション）でツールを選びます。既定の実行場所はアプリ内のターミナルタブです。

アプリ内の 도움말（ヘルプ）→ 처음 연결하기（はじめての接続）でも同じ手順を案内しています。

Agent Switchboard は、Codex や Claude Code などの各コーディングエージェント CLI を置き換えるものではありません。アプリはツールがインストールされているかを検出し、インストールされていないツールについては公式のインストール方法を案内します。

自動アップデート

確認のタイミング

• アプリ起動の約 2.5 秒後に新しいバージョンを確認します。
• アプリが起動している間は 15 分ごとに確認します。
• スリープから復帰すると、5 秒後に再度確認します。
• 上部のダウンロードアイコンから、いつでも手動で確認できます。

アップデートは公式サーバー（https://switchboard.twentyoz.kr/releases）から取得します。アカウントやアクセストークンは不要です。

新しいバージョンがあるとき

1. 업데이트 다운로드（アップデートをダウンロード）、이번 버전 건너뛰기（このバージョンをスキップ）、나중에（後で）のいずれかを選びます。
2. ダウンロードはバックグラウンドで進み、進捗率・サイズ・速度が表示されます。途中でキャンセルできます。
3. ダウンロードが終わっても自動ではインストールしません。재시작하여 설치（再起動してインストール）を押し、もう一度確認すると、アプリを終了してインストールします。

後で を選ぶと、現在の実行中は 4 時間通知しません。手動で確認すると、この保留とスキップしたバージョンも再び表示します。アップデートウィンドウでは、スキップしたバージョンまでの変更履歴を読めます。

OS 別の動作

インストールに失敗した場合は、アップデートウィンドウと再起動の確認ウィンドウに失敗の理由を表示します。解決方法はトラブルシューティングを参照してください。