메인 콘텐츠로 건너뛰기
Capriole AI API 키 하나로 OpenCode에서 GPT-6.2 Astra, Claude Fable 5.1, Opus 5.5, Gemini 4 Carbon 모델을 공식 API 가격보다 최대 92% 저렴하게 사용할 수 있습니다.

OpenCode란

OpenCode는 터미널 인터페이스, 데스크톱 앱, IDE 확장으로 제공되는 오픈 소스 AI 코딩 에이전트입니다. 이 구성은 Capriole AI를 하나의 사용자 지정 제공자로 추가합니다. 제공자의 각 모델은 Capriole AI가 해당 모델 계열에 제공하는 API 프로토콜을 사용합니다.

사전 준비

시작하기 전에 다음이 있는지 확인하세요.
  • Capriole AI 계정(여기에서 가입)
  • Premium 플랜(월 USD 9, 무제한 웹 채팅 포함) 또는 Team 플랜. API 키를 만들려면 둘 중 하나가 필요합니다(구독하기)
  • Capriole AI API 키(키 받기)

설치

OpenCode 2와 OpenCode 1은 모두 opencode 명령을 사용하므로 한 번에 하나만 설치할 수 있습니다. 공식 설치 스크립트로 OpenCode 2를 설치하세요.
또는 npm으로 설치하세요.
OpenCode 1에서 옮기려면 opencode upgrade --major를 실행하세요. https://opencode.ai/install 스크립트와 opencode-ai npm 패키지는 여전히 OpenCode 1을 설치합니다. 설치를 확인하세요.

구성

모델 검증

OpenCode 2.2.5 버전은 OpenCode 2 구성으로 지원 모델 섹션의 모든 모델에서 Capriole AI를 통한 파일 읽기와 최종 답변 검사를 통과합니다. OpenCode 1.19.3 버전은 OpenCode 1 구성으로 파일 읽기, 파일 쓰기, 최종 답변 검사를 통과합니다.

OpenCode 2

~/.config/opencode/opencode.json을 만들거나 업데이트하세요.
각 설정의 역할은 다음과 같습니다.
  • package: "@opencode/ai/providers/openai-compatible"은 제공자의 기본 패키지이므로 Gemini, Grok, GLM, Kimi는 Chat Completions를 사용합니다.
  • 각 GPT 모델은 package를 Responses API를 사용하는 @opencode/ai/providers/openai-compatible/responses로 재정의합니다. 각 Claude 모델은 Anthropic Messages를 사용하는 @opencode/ai/providers/anthropic-compatible로 재정의합니다.
  • env는 키를 담은 환경 변수를 지정합니다. Authorization 헤더는 모든 패키지에서 키를 Bearer 토큰으로 보냅니다.
  • reasoningEffort는 각 GPT 모델의 기본 추론 강도를 정합니다. 이 설정이 없으면 GPT 모델은 추론 없이 답합니다.
  • baseURL에는 모든 패키지에서 /v1이 포함됩니다. limit은 OpenCode에 각 모델의 컨텍스트 창과 출력 한도를 알려 줍니다.
  • agents.title은 OpenCode가 세션 제목에 사용하는 모델을 정합니다.

OpenCode 1

OpenCode 1은 OpenCode 2 형식을 읽지 않지만, OpenCode 2는 이 형식도 읽으므로 업그레이드한 뒤에도 OpenCode 1 설정을 그대로 쓸 수 있습니다. ~/.config/opencode/opencode.json을 만들거나 업데이트하세요.
각 설정의 역할은 다음과 같습니다.
  • npm: "@ai-sdk/openai-compatible"은 제공자의 기본 패키지이므로 Gemini, Grok, GLM, Kimi는 Chat Completions를 사용합니다.
  • 각 GPT 모델은 provider.npm을 Responses API를 사용하는 @ai-sdk/openai로 재정의합니다. 각 Claude 모델은 Anthropic Messages를 사용하는 @ai-sdk/anthropic으로 재정의합니다.
  • baseURL에는 모든 패키지에서 /v1이 포함됩니다.
  • {env:CAPRIOLE_AI_API_KEY}는 환경 변수에서 키를 읽습니다. Authorization 헤더는 모든 패키지에서 키를 Bearer 토큰으로 보냅니다.
  • limit은 OpenCode에 각 모델의 컨텍스트 창과 출력 한도를 알려 주어, OpenCode가 컨텍스트를 추적하고 제때 세션을 압축할 수 있게 합니다.
  • small_model은 OpenCode가 세션 제목 생성 같은 가벼운 작업에 사용하는 모델입니다.

OpenCode 실행

API 키를 설정한 다음 프로젝트 디렉터리에서 OpenCode를 시작하세요.
OpenCode 2는 백그라운드 서비스에서 모델 요청을 보내고, 이 서비스는 시작할 때 키를 읽습니다. 그래서 opencode service restart로 방금 설정한 키를 읽게 합니다. OpenCode 1에서는 이 단계를 건너뛰세요. /models로 모델을 전환하세요. 비대화형으로 실행하려면 opencode run을 사용하세요.

지원 모델

모델 참조는 capriole-ai/<model-id> 형식을 사용합니다. openai-latest, claude-latest, google-latest는 항상 각 계열의 최신 플래그십 모델을 가리킵니다. 현재는 GPT-6.2 Astra, Claude Fable 5.1, Gemini 4 Carbon입니다.

문제 해결

OpenCode가 인증 오류를 반환하는 이유는 무엇인가요?

OpenCode를 시작하기 전에 같은 셸에서 CAPRIOLE_AI_API_KEY를 내보냈는지, headers(OpenCode 2) 또는 options.headers(OpenCode 1) 아래에 Authorization 헤더가 있는지 확인하세요. OpenCode 2가 Missing Bearer token을 반환하면 백그라운드 서비스가 키 없이 시작된 것입니다. 그 셸에서 opencode service restart를 실행하세요.

Claude 요청이 Unsupported Claude Messages model로 실패하는 이유는 무엇인가요?

Anthropic 패키지를 사용하는 Claude 모델에는 claude-opus-5-5 같은 접두사 없는 Claude ID가 필요합니다. anthropic/ 접두사가 붙은 ID는 Chat Completions용입니다.

GPT 요청이 실패하는 이유는 무엇인가요?

각 GPT 모델에 "package": "@opencode/ai/providers/openai-compatible/responses"(OpenCode 2) 또는 "provider": { "npm": "@ai-sdk/openai" }(OpenCode 1)가 있어 요청이 Responses API를 사용하는지 확인하세요.

Capriole AI 모델이 나타나지 않는 이유는 무엇인가요?

모델 참조가 capriole-ai/moonshot/kimi-k3처럼 capriole-ai/<model-id> 형식인지, disabled_providers가 capriole-ai를 차단하지 않는지 확인하세요. OpenCode 1은 OpenCode 2의 providers 형식을 무시합니다.

구성 변경이 적용되지 않는 이유는 무엇인가요?

프로젝트 수준 opencode.json 또는 OPENCODE_CONFIG 재정의가 있는지 확인한 다음 OpenCode를 다시 시작하세요.

제공자 패키지 오류가 나타나는 이유는 무엇인가요?

~/.cache/opencode를 지우고 OpenCode를 다시 시작해 제공자 패키지를 다시 설치하게 하세요.

참고

마지막 수정일 2026년 11월 18일