ガイド文書
動作環境
Agent Switchboard は次の 3 つの環境で使えます。
| OS | アーキテクチャ | インストールファイル |
|---|---|---|
| Windows | x64 | Agent-Switchboard-Setup-<버전>-x64.exe, Agent-Switchboard-Portable-<버전>-x64.exe |
| macOS | Apple Silicon(arm64) | Agent-Switchboard-<버전>-mac-arm64.dmg, ZIP |
| Linux | x64 | Agent-Switchboard-<버전>-linux-x86_64.AppImage, Agent-Switchboard-<버전>-linux-amd64.deb |
macOS 版は Apple Silicon 専用です。Intel Mac 用のファイルは提供していません。
インストールファイルはダウンロードページから入手できます。お使いの OS に合ったファイルが最初に表示されます。
Windows
Setup と Portable のどちらを選ぶか
- おすすめは Setup(
Agent-Switchboard-Setup-…exe)です。インストールしておけば、新しいバージョンをアプリ内でダウンロードしてインストールできます。 - Portable(
Agent-Switchboard-Portable-…exe)はインストールせずに起動できます。その代わりアプリ内でアップデートをインストールできないため、新しいバージョンが出たらダウンロードページからファイルを入手し直す必要があります。
SmartScreen の警告
Windows 版のインストールファイルには、まだ Authenticode のコード署名がありません。そのため、ファイルのダウンロード時や初回起動時に、Windows SmartScreen が「発行元を確認できません」と警告することがあります。
- ファイルを公式ダウンロードページ(
switchboard.twentyoz.kr)から入手したことを確認します。 - 警告ウィンドウで 詳細情報 を押し、続けて 実行 を押します。
インストール後にアプリ内で受け取るアップデートは、別途検証します。アプリに組み込まれた公開鍵でアップデートポリシーの署名とインストールファイルの SHA-512 ハッシュを確かめ、検証に通った場合だけインストールします。ただし、この検証は OS のコード署名の代わりにはなりません。
macOS
…-mac-arm64.dmgファイルを開きます。- Agent Switchboard を「アプリケーション」フォルダーにドラッグします。
- 「アプリケーション」フォルダーからアプリを起動します。
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 を有効にしてから、アプリを再起動してください。スマートフォン連携も、セキュアストレージがないとオンにできません。
初めて起動したら
アプリを初めて開くと、左側のレールと作業画面が表示されます。次の順に進めれば使い始められます。
- プロジェクトフォルダーを登録する: 左側のレールの下にある 폴더 추가(フォルダーを追加)アイコンを押し、作業するフォルダーを選びます。選んだフォルダーのプロジェクトホームが開きます。
- 接続を登録する: サイドバー下部の 환경 설정(環境設定。ショートカットは Windows・Linux が
Ctrl+,、macOS が⌘,)を開き、연결 · 인증(接続・認証)で API キーやゲートウェイを登録します。サブスクリプションのログイン(OAuth)だけを使う場合は、この手順は飛ばしてかまいません。 - ツールに適用する: プロジェクトホームの 도구 설정(ツール設定)でツールを選び、接続とモデルを決めます。詳しくは接続・プロジェクト別設定をご覧ください。
- 起動する: プロジェクトホームのヘッダーからツールを直接起動するか、レールのプロジェクトメニュー
⋯ → 새 세션(新しいセッション)でツールを選びます。既定では、アプリ内のターミナルタブで起動します。
同じ手順は、アプリ内の 도움말(ヘルプ)→ 처음 연결하기(はじめての接続)でも確認できます。
Agent Switchboard は、Codex や Claude Code などのコーディングエージェント CLI そのものを置き換えるものではありません。アプリはツールがインストールされているかを確認し、見つからないツールについては公式のインストール方法を案内します。
自動アップデート
確認のタイミング
- アプリの起動から約 2.5 秒後に、新しいバージョンを確認します。
- アプリの起動中は、15 分ごとに確認します。
- スリープから復帰すると、5 秒後にもう一度確認します。
- 上部のダウンロードアイコンを押せば、いつでも手動で確認できます。
アップデートは公式サーバー(https://switchboard.twentyoz.kr/releases)から取得します。アカウントやアクセストークンは必要ありません。
新しいバージョンがあるとき
- 업데이트 다운로드(アップデートをダウンロード)、이번 버전 건너뛰기(このバージョンをスキップ)、나중에(後で)のいずれかを選びます。
- ダウンロードはバックグラウンドで進み、進捗率・サイズ・速度が表示されます。途中でキャンセルすることもできます。
- ダウンロードが終わっても、すぐにはインストールしません。재시작하여 설치(再起動してインストール)を押し、もう一度確認すると、アプリを終了してインストールします。
後で を選ぶと、その起動中は 4 時間通知しません。手動で確認すると、後回しにしたバージョンやスキップしたバージョンも改めて表示します。スキップしたバージョンまでの変更履歴は、アップデートウィンドウで読めます。
OS ごとの動作
| インストール形式 | アプリ内での自動インストール |
|---|---|
| Windows Setup | 対応 |
| Windows Portable | 非対応。ダウンロードページから新しいファイルを入手します |
| macOS(署名済みアプリ) | 対応。インストールの検証が終わってから終了します。エラーや 120 秒のタイムアウトが起きた場合は再試行できます |
| Linux AppImage | 対応。既存のアプリが終了してから新しいバージョンを起動します |
| Linux .deb | 対応。インストール時に管理者権限のダイアログが表示されます |
インストールに失敗した場合は、アップデートウィンドウと再起動の確認ウィンドウに理由が表示されます。対処法はトラブルシューティングをご覧ください。