어댑터와 모델 관리

이 가이드에서는 모델 제공업체를 연결하고 에이전트가 무엇으로 실행될지 선택하는 방법을 설명합니다.

여기서 다루는 모든 내용은 한 페이지에 있습니다: 설정 → 서버 → 모델 제공업체. 하위 사이드바 항목은 “모델 제공업체”, 페이지 제목은 “어댑터”입니다.

어댑터란 무엇인가

어댑터는 에이전트 턴을 실행하는 _러너_입니다. 두 개뿐이며 목록은 고정되어 있으므로 세 번째를 추가할 수는 없습니다.

어댑터	CLI	전송 방식
Control Center (built-in)	없음	프로세스 내 에이전트 루프, HTTP로 프로바이더와 통신
Claude Code	`claude`	`claude -p --output-format stream-json`

Cursor, Codex, Anthropic, OpenAI 등은 내장 어댑터 위의 프로바이더이며 별도의 CLI가 아닙니다. 여러분이 추가할 수 있는 것은 또 다른 프로바이더, 즉 OpenAI 또는 Anthropic 호환 엔드포인트입니다. 이 내용은 다음 섹션에서 다룹니다.

모델 제공업체 연결

내장 어댑터는 실행하려면 연결된 프로바이더가 최소 하나 필요합니다. 카탈로그에는 열네 개가 함께 제공됩니다.

설정 → 서버 → 모델 제공업체로 이동합니다
프로바이더 및 모델까지 스크롤합니다
사용할 프로바이더를 찾아 연결합니다:

프로바이더	연결 방법
Anthropic	API 키. Claude Pro/Max 구독은 Anthropic API 로그인이 아니므로 해당 플랜에는 Claude Code 어댑터를 사용하세요
OpenAI, Codex, Cursor	브라우저 OAuth 로그인 또는 API 키. Codex는 CLI 실행이 아니라 Codex Responses 백엔드를 통한 ChatGPT Plus/Pro입니다
Kimi Code	브라우저 OAuth만 지원합니다(기기 코드 흐름). 정액제 플랜이라 토큰당 요금이 없습니다
OpenRouter, Google Gemini, DeepSeek, Mistral, xAI, z.ai, z.ai GLM Coding Plan, Moonshot (Kimi API)	API 키

확인: 해당 행의 배지가 연결됨으로 바뀌고, 펼치면 그 프로바이더가 제공하는 모델이 각각 백만 토큰당 가격과 컨텍스트 윈도와 함께 나열됩니다.

OAuth 토큰은 서버 자체의 자격 증명 저장소에 저장되고 만료되기 전에 갱신됩니다. 프로바이더 자격 증명은 호스트 전역이며, 하나의 워크스페이스에 국한되지 않고 설치된 모든 워크스페이스가 공유합니다.

사용자 지정 프로바이더 추가

Ollama, LM Studio, vLLM 또는 프라이빗 배포에 사용합니다.

프로바이더 및 모델의 사용자 지정 프로바이더에서 프로바이더 추가를 누릅니다
이름을 입력하고 API 유형(OpenAI 호환 또는 Anthropic 호환)을 고른 뒤 Base URL(예: http://localhost:11434/v1)을 지정합니다
엔드포인트에 필요하면 API 키를 추가한 다음 프로바이더 추가를 누릅니다

사용자 지정 프로바이더는 같은 목록에 나타나며, 내장 프로바이더에는 없는 삭제 버튼이 함께 있습니다.

에이전트가 사용할 모델 선택

설정 → 워크스페이스 → 에이전트로 이동해 에이전트를 선택합니다
설정 탭에서 어댑터를 선택합니다
옆의 드롭다운에서 모델을 선택합니다

내장 어댑터의 경우 드롭다운은 연결된 모든 프로바이더의 자체 카탈로그에서 실시간으로 구성됩니다. 저장된 자격 증명이 없는 프로바이더는 모델을 하나도 제공하지 않으므로, 드롭다운이 비어 있다는 것은 거의 항상 “사용 가능한 것이 없음”이 아니라 “아직 연결된 것이 없음”을 뜻합니다.

내장 어댑터의 모델 id는 provider/model 형식으로 한정되며, |로 구분된 폴백 체인을 가질 수 있습니다. 폴백이 사용되면 비용은 요청한 모델이 아니라 실제로 그 턴을 처리한 모델을 기준으로 책정됩니다.

모든 워크스페이스는 다섯 개의 에이전트(CEO와 qa, architect, engineer, librarian)를 어댑터도 모델도 없이 시드합니다. 디스패치는 이 페이지의 기본 러너 설정이 아니라 **Control Center (built-in)**으로 폴백합니다. 기본 러너는 디스패치 경로가 전혀 읽지 않는 클라이언트 환경설정이기 때문입니다. 해당 실행의 실행 로그에는 cc-harness가 기록되므로 트랜스크립트에 실제로 실행된 것이 무엇인지 남습니다.

모델도 없으면 내장 루프는 Anthropic에 기본 모델을 요청합니다. 따라서 완전히 설정하지 않은 에이전트는 Anthropic 계정을 연결했다면 실행되고, 그렇지 않으면 No credential for provider "anthropic" 오류로 실패합니다.

온보딩의 어댑터 단계를 마치면, 그 시점에 존재하는 모든 워크스페이스에서 어댑터나 모델이 아직 없는 모든 에이전트(CEO와 전문가 에이전트)에 선택한 조합이 소급 적용됩니다. 나중에 만든 워크스페이스는 여전히 다섯 에이전트를 모두 미설정 상태로 시드합니다. 사용할 모든 에이전트에 어댑터와 모델을 명시적으로 설정하세요.

러너 CLI 설치

내장 어댑터는 설치가 필요하지 않습니다. Claude Code의 경우 해당 도구 자체의 패키지 관리자를 사용해 CLI를 서버 호스트에 설치합니다. 예:

npm install -g @anthropic-ai/claude-code

그런 다음 페이지 상단의 새로 고침을 누릅니다. 감지된 각 행에는 확인된 버전과 경로, 그리고 JSON 모드와 모델 선택을 지원하는지 여부를 나타내는 칩이 표시됩니다.

외부 CLI는 서버 호스트에서 자체 구성에 자체 자격 증명을 보관합니다. Control Center는 이를 관리하지 않습니다.

워크스페이스가 사용할 수 있는 프로바이더 제한

프로바이더 거버넌스는 워크스페이스 단위이며 마지막 일치가 우선하는 방식으로 평가됩니다.

프로바이더 및 모델에서 프로바이더 행의 허용 스위치를 끕니다

그러면 활성 워크스페이스에 해당 프로바이더에 대한 deny 문이 기록되고, 그 워크스페이스의 카탈로그에서 해당 모델이 빠집니다. 스위치를 다시 켜면 그 문이 제거됩니다.

문제 해결

러너가 찾을 수 없음으로 표시됩니다

CLI가 서버 호스트의 PATH에 있는지, 내 머신에만 있는 것은 아닌지 확인합니다
GUI로 실행한 데스크톱 앱은 최소한의 PATH로 서버를 실행하므로, 셸 전용 경로에 설치된 CLI는 인식되지 않을 수 있습니다
설치한 뒤 새로 고침을 누릅니다

모델 드롭다운이 비어 있습니다

어댑터가 내장 어댑터이고 연결된 프로바이더가 없습니다 — 프로바이더 및 모델에서 하나를 연결하세요
또는 프로바이더는 연결되어 있지만 이 워크스페이스의 거버넌스 스위치로 거부된 경우입니다

모델은 실행되는데 가격이 알 수 없음으로 표시됩니다

실시간 모델 목록에는 id가 있지만, 가격과 컨텍스트는 models.dev에서 옵니다. 새로 나온 모델이거나 사용자 지정 프로바이더의 모델은 아직 카탈로그 항목이 없습니다.