指南文档
连接与按项目设置
基本概念
Agent Switchboard 将以下三者分开管理。
- 连接：网关或 provider 的地址和 API 密钥。只需在 환경 설정 › 연결 · 인증（偏好设置 › 连接与认证）中注册一次，多个工具即可选择使用同一个连接。使用同一连接的工具共享密钥。
- 工具：Codex、Claude Code、Pi 等编程智能体 CLI。每个工具分别设置连接方式（
API / 게이트웨이（API / 网关）或OAuth / 기본 인증（OAuth / 默认认证））、模型和推理强度。 - 范围：전역 기본（全局默认）是所有已注册文件夹都遵循的值。在某个文件夹中单独保存后，只有该文件夹使用专用值。
文件夹没有单独设置时，直接使用全局默认。在文件夹中首次保存时，会以当前值为初始值创建该文件夹的专用设置。文件夹专用的 provider、认证、模型和推理设置优先于全局设置。
支持的连接
| 工具 | OAuth / 默认认证 | API 与网关 |
|---|---|---|
| Codex | ChatGPT OAuth | OpenAI Responses, LiteLLM Responses, GLM via LiteLLM |
| Claude Code | Claude OAuth | Anthropic API, LiteLLM, GLM, OpenRouter, DeepSeek Anthropic Messages |
| Pi | ChatGPT OAuth, Claude OAuth | OpenAI, Anthropic, LiteLLM, Z.ai, OpenRouter, Gemini, xAI, DeepSeek, Groq, Together, Mistral, Cerebras |
| OpenCode | OpenCode provider 认证，Claude Code、Codex、Kimi Code CLI 认证 | OpenAI 兼容 Chat, Anthropic Messages, provider 目录 |
| Qwen Code | Qwen Code CLI 认证 | OpenAI Chat, Anthropic Messages, provider 目录 |
| Cline CLI | ChatGPT OAuth, Cline 认证 | 按协议内置的 provider |
Droid、Crush、Kimi Code 也支持连接管理。Antigravity（agy）、Copilot CLI、Cursor CLI、Amp、Goose、Aider、Kilo CLI、Grok Build、Gemini CLI 仅支持安装检测和运行，这些工具的设置和认证由各工具自行管理。
注册连接
API 密钥与网关
- 打开侧边栏下方的 환경 설정（偏好设置），进入 연결 · 인증（连接与认证）。
- 点击 연결 추가（添加连接）。
- 在 provider 目录中选择服务或输入网关地址，填入 API 密钥后保存。
远程地址只接受 HTTPS。HTTP 仅允许本机（loopback）地址。
密钥按连接分别加密保存在操作系统的安全存储（Windows DPAPI、macOS Keychain、Linux Secret Service）中。已保存的密钥不会再次显示在界面上。Codex、Claude Code、Pi 的设置文件中只记录 Agent Switchboard 的 credential helper 命令，而不是密钥。工具运行时，由 helper 从安全存储中取出密钥并传递。
仅注册连接并不会应用到工具。需要按下一节的步骤应用到工具。
订阅登录（OAuth）
使用 ChatGPT、Claude 订阅等工具自带的登录时，不需要 API 密钥。
- 在工具设置画面中选择
OAuth / 기본 인증（OAuth / 默认认证）。 - 点击 기본 인증 적용（应用默认认证）。
- 按工具的登录流程完成登录。
OAuth 令牌由各 CLI 在自己的存储中直接保管和刷新。Agent Switchboard 不会读取或复制令牌。
使用多个账号
Codex、Claude Code、Pi、Qwen Code 的默认认证可以使用多个账号。在工具的账号列表中创建账号并登录后，在全局或按项目选择账号。Pi 在打开的终端中通过 /login 登录，Qwen Code 通过 /auth 登录。账号选择不适用于 API 与网关连接。
应用到工具
全局默认
- 点击左侧侧栏中的 전역 기본（全局默认）。也可以通过项目首页的 전역 기본과 비교（与全局默认比较）打开。
- 点击工具卡片，打开设置画面。
- 选择
API / 게이트웨이（API / 网关）或OAuth / 기본 인증（OAuth / 默认认证）。 - 如果是 API 连接，选择已注册的连接，并在可搜索的列表中选择模型。更换模型时，该模型支持的推理强度（effort）和 Token 上限也会一并反映。
- 通过 연결 테스트（连接测试）确认地址和认证。
- 点击 저장 후 적용（保存并应用）。OpenCode 则点击 설정 적용（应用设置）。
连接测试和应用时，会确认所选模型是否确实可用。模型不可用时会停止应用并提示。此时请在列表中直接选择可用的模型。
每个项目文件夹使用不同设置
这是 Agent Switchboard 的核心功能。即使在同一台 PC 上，每个文件夹也可以使用不同的智能体、模型、provider 和密钥。
- 在左侧侧栏中选择项目，打开项目首页。
- 在 도구 설정（工具设置）中点击工具卡片。列表中没有的工具，可以通过 도구（工具）按钮（添加在此文件夹中显示的工具）添加。
- 按与全局默认相同的方法选择连接方式、连接、模型和推理强度。
- 应用后即成为此文件夹的专用设置。
项目首页从上到下依次显示 지금（当前：运行中、等待输入、出错的会话）、工具设置、최근 세션（最近会话）。在工具卡片上可以一目了然地确认该文件夹的工具、连接、模型和推理强度。通过 与全局默认比较 可以与全局值并排查看。
文件夹专用设置按工具写入以下文件。
| 工具 | 文件夹设置位置 |
|---|---|
| Codex | $CODEX_HOME 中的文件夹专用配置文件（运行时自动选择） |
| Claude Code | .claude/settings.local.json |
| Pi | .pi/settings.json |
| OpenCode | opencode.json |
| Qwen Code | .qwen/settings.json |
Cline CLI 不创建项目设置文件，而是在所选文件夹中运行。不支持项目设置的工具会显示为 프로젝트 설정 미지원（不支持项目设置），并使用 PC 的全局设置。
Switcher 新对话的默认值
Switcher 对话的默认智能体、模型和推理强度也可以按文件夹设置。在侧栏项目的 Switcher 菜单 › 설정（设置）中点击 이 폴더에 저장（保存到此文件夹）。点击 전역 기본값 따르기（遵循全局默认值）会删除文件夹的值，重新遵循全局默认。已经打开的对话保留原有的引擎、模型和推理强度。
在托盘中快速切换
点击托盘（macOS 为菜单栏）图标，会打开快速切换面板。
- 选择工具，再选择
API · 게이트웨이（API · 网关）或OAuth · 기본 인증（OAuth · 默认认证）。 - 选择供应商后，会用已保存的连接加载模型列表。
- 选择模型，然后点击 이 공급자로 전환（切换到此供应商）。
快速切换同样会经过与主窗口相同的备份、连接测试和验证流程。
设置文件保护
- 修改设置前，首次会备份一次原文件，之后每次修改都会保留 revision 备份。
- Agent Switchboard 只修改自己管理的项目，保留其余的用户设置。
- 应用后重新读取生成的文件进行验证。验证失败时，将本次应用所做的修改恢复到之前的状态。
- 최초 설정 복원（恢复初始设置）会恢复到 Agent Switchboard 首次修改之前的文件状态。
- 删除已保存的密钥时，会先将受管理的连接切换为工具的默认认证。
下一步
- 如需在手机上继续，请参阅连接手机。
- 关于对话界面和指挥多个会话，请参阅 Switcher 与编排。