安装与首次运行

支持环境

Agent Switchboard 可在以下三种环境中运行。

（文件名中的 <버전> 表示版本号。）

macOS 仅支持 Apple Silicon。不提供 Intel Mac 版本的文件。

安装文件请从下载页面获取。下载页面会优先显示您当前使用的操作系统。

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 哈希之后才会安装。此验证不能替代操作系统的代码签名。

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 密钥加密保存在操作系统的安全存储中。在 Linux 上需要 Secret Service 之类的桌面 keyring。如果无法使用 keyring，应用不会以明文保存密钥，而是在 API 密钥连接的 저장 후 적용（保存并应用）上方显示无法保存的原因。启用 keyring 后请重新启动应用。手机连接同样需要有安全存储才能开启。

首次运行

首次打开应用时，会看到左侧的侧栏（rail）和工作区。请按以下顺序开始。

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 小时内不会再次提醒。手动检查时，会重新显示这次暂缓的版本和已跳过的版本。在更新窗口中可以阅读截至所跳过版本的更新日志。

各操作系统的行为

如果安装失败，更新窗口和重启确认窗口会显示失败原因。解决方法请参阅问题排查。