指南文档
三个基本概念
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 与编排。