Documentos de la guía
Conceptos básicos
Agent Switchboard trata por separado tres cosas.
- Conexión: la dirección y la clave de API de un gateway o provider. Se registra una sola vez en 환경 설정 › 연결 · 인증 (Preferencias › Conexiones y autenticación) y cualquier herramienta puede usarla. Las herramientas que eligen la misma conexión comparten la clave.
- Herramienta: una CLI de agente de programación, como Codex, Claude Code o Pi. En cada una eliges el tipo de conexión (
API / 게이트웨이[API / gateway] uOAuth / 기본 인증[OAuth / autenticación predeterminada]), el modelo y el esfuerzo de razonamiento. - Alcance: 전역 기본 (Predeterminado global) es lo que siguen todas las carpetas registradas. Si guardas algo distinto en una carpeta, ese valor solo se aplica a ella.
Una carpeta sin valores propios usa tal cual el predeterminado global. La primera vez que guardas en una carpeta, se crea su configuración propia a partir de los valores actuales. El provider, la autenticación, el modelo y el razonamiento definidos en la carpeta mandan sobre los globales.
Conexiones compatibles
| Herramienta | OAuth / autenticación predeterminada | API y gateways |
|---|---|---|
| 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 | Autenticación de providers de OpenCode; autenticación de las CLI de Claude Code, Codex y Kimi Code | Chat compatible con OpenAI, Anthropic Messages, catálogo de providers |
| Qwen Code | Autenticación de Qwen Code CLI | OpenAI Chat, Anthropic Messages, catálogo de providers |
| Cline CLI | ChatGPT OAuth, autenticación de Cline | Providers integrados por protocolo |
Droid, Crush y Kimi Code también tienen la conexión gestionada por la app. Con Antigravity (agy), Copilot CLI, Cursor CLI, Amp, Goose, Aider, Kilo CLI, Grok Build y Gemini CLI, la app solo comprueba la instalación y las ejecuta; la configuración y la autenticación las gestiona cada herramienta.
Registrar una conexión
Clave de API o gateway
- Abre Preferencias en la parte baja de la barra lateral y ve a Conexiones y autenticación.
- Pulsa 연결 추가 (Añadir conexión).
- Elige un servicio del catálogo de providers o escribe la dirección del gateway, pega la clave de API y guarda.
Las direcciones remotas tienen que ser HTTPS. HTTP solo se acepta para direcciones del propio PC (loopback).
Cada clave se guarda cifrada, por conexión, en el almacén seguro del sistema operativo (Windows DPAPI, macOS Keychain, Linux Secret Service), y una vez guardada no vuelve a mostrarse. En los archivos de configuración de Codex, Claude Code y Pi no se escribe la clave, sino el comando del credential helper de Agent Switchboard. Al lanzar la herramienta, el helper saca la clave del almacén seguro y se la pasa.
Registrar una conexión no la aplica todavía a ninguna herramienta. Para eso, sigue los pasos de «Asignar a una herramienta», más abajo.
Suscripción (OAuth)
Si inicias sesión directamente en la herramienta con tu suscripción a ChatGPT o Claude, no necesitas clave de API.
- En la configuración de la herramienta, elige
OAuth / 기본 인증(OAuth / autenticación predeterminada). - Pulsa 기본 인증 적용 (Aplicar autenticación predeterminada).
- Inicia sesión con el flujo de la propia herramienta.
Cada CLI guarda y renueva sus tokens OAuth en su propio almacenamiento. Agent Switchboard no los lee ni los copia.
Varias cuentas
Codex, Claude Code, Pi y Qwen Code admiten varias cuentas en la autenticación predeterminada. Crea la cuenta en la lista de cuentas de la herramienta, inicia sesión y luego elige qué cuenta usar, de forma global o por proyecto. En Pi se inicia sesión con /login desde una terminal abierta, y en Qwen Code con /auth. Las conexiones de API o gateway no usan esta selección de cuenta.
Asignar a una herramienta
Predeterminado global
- Pulsa 전역 기본 (Predeterminado global) en el rail izquierdo. También lo abres con 전역 기본과 비교 (Comparar con el predeterminado global) desde el inicio del proyecto.
- Pulsa la tarjeta de una herramienta para abrir su configuración.
- Elige
API / 게이트웨이(API / gateway) uOAuth / 기본 인증(OAuth / autenticación predeterminada). - Si es una conexión de API, elige una de las conexiones registradas y busca el modelo en la lista. Al cambiar de modelo, se ajustan con él el esfuerzo de razonamiento (effort) y el límite de tokens que admite.
- Comprueba la dirección y la autenticación con 연결 테스트 (Probar conexión).
- Pulsa 저장 후 적용 (Guardar y aplicar). En OpenCode, el botón es 설정 적용 (Aplicar configuración).
Tanto en la prueba como al aplicar, la app comprueba que el modelo elegido se pueda usar de verdad. Si no se puede, detiene la aplicación y te avisa. En ese caso, elige otro modelo disponible de la lista.
Una configuración distinta para cada carpeta
Es la función central de Agent Switchboard: en un mismo PC, cada carpeta puede usar su propio agente, modelo, provider y clave.
- Elige un proyecto en el rail izquierdo para abrir su inicio.
- En 도구 설정 (Configuración de herramientas), pulsa la tarjeta de una herramienta. Si la herramienta no aparece, añádela con el botón 도구 (Herramientas), que sirve para elegir qué herramientas se muestran en esta carpeta.
- Elige el tipo de conexión, la conexión, el modelo y el esfuerzo de razonamiento igual que en el predeterminado global.
- Al aplicar, esa configuración queda solo para esta carpeta.
El inicio del proyecto muestra, de arriba abajo, 지금 (Ahora: sesiones en ejecución, esperando entrada o con error), Configuración de herramientas y 최근 세션 (Sesiones recientes). Con un vistazo a las tarjetas sabes qué herramienta, conexión, modelo y esfuerzo de razonamiento usa la carpeta, y con Comparar con el predeterminado global los ves junto a los valores globales.
La configuración propia de la carpeta se guarda en estos archivos, según la herramienta.
| Herramienta | Dónde se guarda la configuración de la carpeta |
|---|---|
| Codex | Perfil propio de la carpeta en $CODEX_HOME (se elige automáticamente al ejecutar) |
| Claude Code | .claude/settings.local.json |
| Pi | .pi/settings.json |
| OpenCode | opencode.json |
| Qwen Code | .qwen/settings.json |
Cline CLI no crea archivo de configuración de proyecto; simplemente se ejecuta en la carpeta elegida. Las herramientas sin configuración por proyecto llevan la etiqueta 프로젝트 설정 미지원 (Sin configuración por proyecto) y usan la configuración global del PC.
Valores por defecto para conversaciones nuevas en Switcher
También puedes fijar por carpeta el agente, el modelo y el esfuerzo de razonamiento con los que se abren las conversaciones nuevas en Switcher. En el rail, abre el menú Switcher del proyecto › Configuración y pulsa 이 폴더에 저장 (Guardar en esta carpeta). Con 전역 기본값 따르기 (Usar el predeterminado global) se borran los valores de la carpeta y vuelve a mandar el global. Las conversaciones que ya estén abiertas conservan su motor, modelo y esfuerzo de razonamiento.
Cambios rápidos desde la bandeja
Pulsa el icono de la bandeja del sistema (la barra de menús en macOS) para abrir el panel de cambio rápido. Así cambias de conexión sin abrir la ventana principal.
- Elige una herramienta y luego
API · 게이트웨이(API · gateway) uOAuth · 기본 인증(OAuth · autenticación predeterminada). - Al elegir un proveedor, se carga la lista de modelos con la conexión guardada.
- Elige un modelo y pulsa 이 공급자로 전환 (Cambiar a este proveedor).
El cambio rápido hace lo mismo que la ventana principal: copia de seguridad, prueba de conexión y verificación del resultado.
Protección de los archivos de configuración
- La primera vez que se cambia la configuración se guarda una copia del original, y cada cambio posterior deja una copia de la revisión.
- Agent Switchboard solo toca los ajustes que gestiona; el resto de tu configuración queda intacto.
- Después de aplicar, la app vuelve a leer los archivos generados. Si la comprobación falla, deshace los cambios de esa aplicación.
- 최초 설정 복원 (Restaurar la configuración original) devuelve los archivos al estado en que estaban antes de que Agent Switchboard los tocara por primera vez.
- Antes de borrar una clave guardada, las conexiones gestionadas que la usaban pasan a la autenticación predeterminada de la herramienta.
Siguientes pasos
- Para seguir desde el teléfono, consulta Conectar el teléfono.
- Para trabajar desde una conversación o repartir el trabajo entre varias sesiones, consulta Switcher y orquestación.