Agent Switchboard
내려받기

언어

고른 언어는 쿠키에 기억해 둡니다.

테마
가이드 문서

연결·프로젝트별 설정

기본 개념

Agent Switchboard에서는 세 가지를 나눠서 다룹니다.

  • 연결: 게이트웨이나 provider의 주소와 API 키입니다. 환경 설정 › 연결 · 인증에 한 번만 등록하면 여러 도구가 골라 쓸 수 있고, 같은 연결을 고른 도구끼리는 키를 공유합니다.
  • 도구: Codex, Claude Code, Pi 같은 코딩 에이전트 CLI입니다. 도구마다 연결 방식(API / 게이트웨이 또는 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 키·게이트웨이

  1. 사이드바 아래쪽 환경 설정을 열고 연결 · 인증으로 갑니다.
  2. 연결 추가를 누릅니다.
  3. provider 카탈로그에서 서비스를 고르거나 게이트웨이 주소를 입력하고, API 키를 넣어 저장합니다.

원격 주소는 HTTPS만 쓸 수 있습니다. HTTP는 같은 PC(loopback) 주소일 때만 허용합니다.

키는 운영체제 보안 저장소(Windows DPAPI, macOS Keychain, Linux Secret Service)에 연결별로 암호화해 보관하고, 한 번 저장하면 화면에 다시 보여 주지 않습니다. Codex, Claude Code, Pi 설정 파일에는 키 대신 Agent Switchboard의 credential helper 명령만 적습니다. 도구를 실행하면 helper가 보안 저장소에서 키를 꺼내 넘겨줍니다.

연결을 등록했다고 도구에 바로 적용되지는 않습니다. 아래 「도구에 적용하기」 순서를 따라 적용하세요.

구독 로그인(OAuth)

ChatGPT·Claude 구독처럼 도구에 직접 로그인해서 쓴다면 API 키가 필요 없습니다.

  1. 도구 설정 화면에서 OAuth / 기본 인증을 고릅니다.
  2. 기본 인증 적용을 누릅니다.
  3. 도구의 로그인 흐름으로 로그인합니다.

OAuth 토큰은 각 CLI가 자기 저장소에 보관하고 갱신합니다. Agent Switchboard는 토큰을 읽지도 복사하지도 않습니다.

여러 계정 쓰기

Codex·Claude Code·Pi·Qwen Code는 기본 인증에 계정을 여러 개 둘 수 있습니다. 도구의 계정 목록에서 계정을 만들어 로그인한 다음, 전역이나 프로젝트별로 쓸 계정을 고릅니다. Pi는 열린 터미널에서 /login, Qwen Code는 /auth로 로그인합니다. API·게이트웨이 연결에는 계정 선택이 적용되지 않습니다.

도구에 적용하기

전역 기본

  1. 왼쪽 레일의 전역 기본을 누릅니다. 프로젝트 홈의 전역 기본과 비교로도 열 수 있습니다.
  2. 도구 카드를 눌러 설정 화면을 엽니다.
  3. API / 게이트웨이 또는 OAuth / 기본 인증을 고릅니다.
  4. API 연결이면 등록해 둔 연결을 고르고, 검색할 수 있는 목록에서 모델을 고릅니다. 모델을 바꾸면 그 모델이 지원하는 추론 강도(Effort)와 토큰 한도도 함께 바뀝니다.
  5. 연결 테스트로 주소와 인증을 확인합니다.
  6. 저장 후 적용을 누릅니다. OpenCode는 설정 적용을 누릅니다.

연결 테스트와 적용 단계에서 고른 모델을 실제로 쓸 수 있는지 확인합니다. 쓸 수 없는 모델이면 적용을 멈추고 알려 줍니다. 그럴 때는 목록에서 쓸 수 있는 모델을 다시 고르세요.

프로젝트 폴더마다 다르게

Agent Switchboard에서 가장 중요한 기능입니다. 같은 PC에서도 폴더마다 에이전트, 모델, provider, 키를 다르게 쓸 수 있습니다.

  1. 왼쪽 레일에서 프로젝트를 고르면 프로젝트 홈이 열립니다.
  2. 도구 설정에서 도구 카드를 누릅니다. 목록에 없는 도구는 도구 버튼(이 폴더에 표시할 도구 추가)으로 더합니다.
  3. 전역 기본과 같은 방법으로 연결 방식·연결·모델·추론 강도를 고릅니다.
  4. 적용하면 이 폴더에서만 쓰는 설정이 됩니다.

프로젝트 홈에는 위에서부터 지금(실행 중·입력 대기·오류 세션), 도구 설정, 최근 세션이 있습니다. 도구 카드만 보면 그 폴더의 도구·연결·모델·추론 강도를 한눈에 알 수 있고, 전역 기본과 비교를 누르면 전역 값과 나란히 볼 수 있습니다.

폴더 전용 설정은 도구마다 아래 파일에 기록됩니다.

도구 폴더 설정 위치
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 메뉴 › 설정에서 이 폴더에 저장을 누르세요. 전역 기본값 따르기를 누르면 폴더 값이 지워지고 다시 전역 기본을 따릅니다. 이미 열려 있는 대화는 원래 엔진·모델·추론 강도를 그대로 씁니다.

트레이에서 빠르게 바꾸기

트레이(macOS는 메뉴 막대) 아이콘을 누르면 빠른 전환 패널이 열립니다. 메인 창을 열지 않고도 연결을 바꿀 수 있습니다.

  1. 도구를 고르고 API · 게이트웨이 또는 OAuth · 기본 인증을 고릅니다.
  2. 공급자를 고르면 저장된 연결로 모델 목록을 불러옵니다.
  3. 모델을 고르고 이 공급자로 전환을 누릅니다.

빠른 전환에서도 메인 창과 똑같이 백업하고, 연결을 테스트하고, 결과를 검증합니다.

설정 파일 보호

  • 처음 설정을 바꿀 때 원본을 백업하고, 그 뒤로도 바꿀 때마다 revision 백업을 남깁니다.
  • Agent Switchboard가 관리하는 항목만 바꾸고, 나머지 사용자 설정은 건드리지 않습니다.
  • 적용한 뒤에는 만든 파일을 다시 읽어 확인합니다. 확인에 실패하면 이번에 바뀐 내용을 이전 상태로 되돌립니다.
  • 최초 설정 복원을 누르면 Agent Switchboard가 처음 손대기 전의 파일로 돌아갑니다.
  • 저장된 키를 지울 때는 그 키를 쓰던 관리 연결을 먼저 도구 기본 인증으로 돌려 둡니다.

다음 단계