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를 설치하세요.
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 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를 다시 시작해 제공자 패키지를 다시 설치하게 하세요.
참고
- 키는 환경 변수에 두세요.
opencode.json에 붙여 넣지 마세요. - 다른 Capriole AI 모델을 추가하려면 같은 계열 모델의 항목을 복사하고 ID를 바꾸세요.
GET https://api.caprioletech.com/v1/models는 모든 모델 ID를 나열합니다. - Gemini 4 Carbon은 Gemini 4 Argon보다 오래 추론하므로 턴마다 시간이 더 걸리고 토큰도 더 쓸 수 있습니다. 더 빠른 응답이 필요하면
google/gemini-4-argon을 사용하세요. - 같은 키를 다른 코딩 에이전트에서도 쓰려면 코딩 에이전트에 API 키 하나 사용하기 가이드를 참고하세요.
- OpenCode 2 참고: 설치, OpenCode 1에서 마이그레이션, 제공자, 모델, 백그라운드 서비스, 릴리스.
- OpenCode 1 참고: 설치, 구성, 제공자, 모델, 문제 해결.

