Agent Switchboard
내려받기
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 대화의 기본 에이전트·모델·추론 강도도 폴더별로 정할 수 있습니다. 레일 프로젝트의 Switcher 메뉴 › 설정에서 이 폴더에 저장을 누릅니다. 전역 기본값 따르기를 누르면 폴더 값을 지우고 전역 기본을 다시 따릅니다. 이미 열린 대화는 기존 엔진·모델·추론 강도를 유지합니다.

트레이에서 빠르게 바꾸기

트레이(macOS는 메뉴 막대) 아이콘을 누르면 빠른 전환 패널이 열립니다.

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

빠른 전환도 메인 창과 같은 백업·연결 테스트·검증 과정을 거칩니다.

설정 파일 보호

  • 설정을 바꾸기 전에 원본을 처음 한 번 백업하고, 바꿀 때마다 revision 백업을 남깁니다.
  • Agent Switchboard는 자기가 관리하는 항목만 바꾸고 나머지 사용자 설정은 보존합니다.
  • 적용 뒤 생성한 파일을 다시 읽어 검증합니다. 검증에 실패하면 이번 적용으로 바뀐 내용을 이전 상태로 되돌립니다.
  • 최초 설정 복원은 Agent Switchboard가 처음 수정하기 전의 파일 상태로 되돌립니다.
  • 저장된 키를 삭제하면 관리 연결을 먼저 도구 기본 인증으로 전환합니다.

다음 단계