Claude용 OpenCode 구성: opencode.json 설정, 모델 및 일반적인 오류

OpenCode는 다음에서 설정을 읽습니다: opencode.json. 이 게이트웨이를 통해 Claude로 실행하려면 Anthropic 제공자의 다음 값 하나를 변경하고 baseURL, 키를 지정하면 됩니다. 아래에는 실제로 작동하는 설정 두 가지, 중요한 모델 및 컨텍스트 설정, 그리고 자체 요청 로그에서 확인한 이 게이트웨이 사용 시 OpenCode 사용자에게 발생하는 오류의 해결 방법이 나와 있습니다.

opencode.json의 위치

OpenCode는 전역 설정과 프로젝트별 설정을 병합합니다: ~/.config/opencode/opencode.json 은 모든 곳에 적용할 설정에 사용하고, opencode.json 은 프로젝트 루트에 두어 해당 저장소에 적용합니다. 다음 줄을 추가하면 $schema 대부분의 편집기에서 자동 완성과 유효성 검사를 사용할 수 있습니다.

키를 파일에 저장하지 마세요. 환경 변수에 넣고 다음과 같이 참조하세요: {env:AIPRIME_API_KEY}. 다음을 사용해 추가한 키는 /connect OpenCode 내에서 다음 위치에 저장됩니다: ~/.local/share/opencode/auth.json; opencode auth list 을 사용하면 저장된 내용을 확인할 수 있습니다.

export AIPRIME_API_KEY=your_gateway_key   # add to ~/.bashrc or ~/.zshrc
opencode auth list                         # credentials OpenCode already knows about

옵션 1: 기본 제공 Anthropic 제공자가 게이트웨이를 가리키도록 설정

가장 간단한 변경 방법은 OpenCode 자체의 Anthropic 제공자와 모델 목록을 유지하고, 요청을 보내는 위치만 재정의하는 것입니다.

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "baseURL": "https://aiprimetech.io/v1",
        "apiKey": "{env:AIPRIME_API_KEY}"
      }
    }
  },
  "model": "anthropic/claude-sonnet-5",
  "small_model": "anthropic/claude-haiku-4-5"
}

옵션 2: 원하는 모델 목록을 사용하는 사용자 지정 공급자

별도의 공급자 항목을 사용하면 게이트웨이를 Anthropic 로그인과 분리하고, 모델 선택기에 원하는 모델만 정확히 나열하며, 모델별로 컨텍스트 한도를 설정할 수 있습니다.

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "aiprime": {
      "npm": "@ai-sdk/anthropic",
      "name": "AI Prime Tech",
      "options": {
        "baseURL": "https://aiprimetech.io/v1",
        "apiKey": "{env:AIPRIME_API_KEY}"
      },
      "models": {
        "claude-sonnet-5":  { "name": "Claude Sonnet 5",  "limit": { "context": 200000, "output": 64000 } },
        "claude-opus-5-5":  { "name": "Claude Opus 5.5",  "limit": { "context": 200000, "output": 64000 } },
        "claude-haiku-4-5": { "name": "Claude Haiku 4.5", "limit": { "context": 200000, "output": 32000 } }
      }
    }
  },
  "model": "aiprime/claude-sonnet-5",
  "small_model": "aiprime/claude-haiku-4-5"
}

우선 선택하세요 @ai-sdk/anthropic Claude용: 네이티브 Messages API를 사용하므로 프롬프트 캐싱과 사고 기능이 Anthropic의 설계대로 작동합니다. 게이트웨이는 OpenAI 형식도 지원하므로 @ai-sdk/openai-compatible 동일한 https://aiprimetech.io/v1 기본 URL을 사용해도 작동하며, 동일한 키로 GPT 모델을 사용하려면 이 방식을 선택하면 됩니다.

모델과 컨텍스트 한도

model 는 주 에이전트가 사용하며, small_model 는 세션 제목 생성처럼 비용이 적게 드는 부수 작업을 처리합니다. limit.context 값은 OpenCode가 세션을 언제 압축할지 결정하는 기준입니다. 긴 세션에서 다음 오류가 발생하면 prompt is too long, 이 값을 낮추세요(200000이 안전한 값입니다). 그러면 OpenCode가 엔드포인트의 허용량을 초과해 전송하지 않고 더 일찍 요약합니다.

모델 ID는 정확히 일치해야 하는 문자열입니다. 다음과 같은 이전 이름이나 claude-3-5-sonnet-20241022 날짜가 붙은 스냅샷은 제공되지 않습니다. 위의 ID 또는 대시보드에 표시된 목록을 사용하세요.

OpenCode를 시작하기 전에 키와 URL 확인하기

터미널에서 요청을 한 번 보내면 OpenCode 설정과 별개로 키와 URL이 올바른지 확인할 수 있습니다.

curl -s https://aiprimetech.io/v1/messages \
  -H "x-api-key: $AIPRIME_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-haiku-4-5","max_tokens":20,"messages":[{"role":"user","content":"ping"}]}'

JSON 응답에 다음이 포함되어 있고 content 배열이라면 게이트웨이 측은 정상이며, 남은 문제는 다음에 있습니다. opencode.json. Invalid API key 는 변수가 비어 있거나 잘못된 키가 들어 있다는 뜻입니다.

문제 해결: OpenCode 사용자가 겪는 오류

이 게이트웨이에서 OpenCode를 사용할 때 가장 자주 발생하는 오류와 각 오류의 해결 방법입니다.

클라이언트가 아닌 모델 측에서 발생하는 오류는 다음을 참고하세요. Claude API 오류 가이드.

자주 묻는 질문

AI Prime Tech는 독립적인 API 게이트웨이입니다. Anthropic과 제휴 관계가 없으며, Anthropic의 보증을 받거나 Anthropic의 리셀러로 활동하지 않습니다. Claude 및 관련 모델 이름은 각 소유자의 상표입니다.