Source: https://aiprimetech.io/ko/learn/use-claude-api-with-opencode/ [홈](/ko/) / [학습](/ko/learn/) / Claude용 OpenCode 설정: opencode.json 설정, 모델 및 일반적인 오류 # 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 제공자와 모델 목록을 유지하고, 요청을 보내는 위치만 재정의하는 것입니다. opencode.json복사 ``` { "$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" } ``` 이 baseURL 은 다음으로 끝나야 합니다: /v1. OpenCode의 Anthropic 제공자는 AI SDK의 다음 항목입니다: @ai-sdk/anthropic. 기본값은 다음과 같습니다: https://api.anthropic.com/v1; 여기에 다음을 추가합니다: /messages 지정한 값에 그대로 덧붙입니다. 다음이 없으면 /v1 요청이 웹사이트로 전달되어 HTML을 반환하며, OpenCode는 이를 파싱 오류로 표시합니다. ## 옵션 2: 원하는 모델 목록을 사용하는 사용자 지정 공급자 별도의 공급자 항목을 사용하면 게이트웨이를 Anthropic 로그인과 분리하고, 모델 선택기에 원하는 모델만 정확히 나열하며, 모델별로 컨텍스트 한도를 설정할 수 있습니다. opencode.json복사 ``` { "$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 모델을 사용하려면 이 방식을 선택하면 됩니다. ## 모델과 컨텍스트 한도 | 모델 ID | 권장 용도 | claude-sonnet-5 | 코딩과 에이전트 작업의 기본 선택: 빠르고 성능이 뛰어나며 가격은 중간 수준입니다. | claude-opus-5-5 | 더 어려운 추론, 대규모 리팩터링, 장시간 에이전트 실행. | claude-fable-5-1 | 성능이 가장 뛰어나고 가격도 가장 높습니다. 가장 어려운 작업에 사용하세요. | claude-haiku-4-5 | 저렴하고 빠름: 제목, 요약, 분류, 간단한 단계. 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를 사용할 때 가장 자주 발생하는 오류와 각 오류의 해결 방법입니다. | 표시되는 내용 | 원인 | 해결 방법 | JSON 파싱 오류, 응답이 다음으로 시작함: < | baseURL 없이 /v1: 요청이 API가 아닌 웹사이트에 도달했습니다. | 끝에 추가하세요. baseURL 다음으로 바꾸세요: /v1 | 404 page not found | /v1 두 번 추가되어 경로가 다음과 같이 됩니다. /v1/v1/messages | 정확히 다음 값을 사용하세요. https://aiprimetech.io/v1 | Invalid API key | OpenCode를 시작한 셸에서 변수를 내보내지 않았거나 다른 키를 사용하고 있습니다. | echo $AIPRIME_API_KEY, opencode auth list, OpenCode를 다시 시작하세요. | 지원되지 않는 모델 / 모델을 찾을 수 없음 | 엔드포인트에서 제공하지 않는 ID이며, 오래된 날짜가 붙은 이름인 경우가 많습니다. | 위 표의 ID를 사용하세요 | prompt is too long: N tokens > N tokens | 세션이 모델의 허용량을 초과했습니다. | /compact, 다음 값을 낮추세요. limit.context | Concurrency limit exceeded for user | 병렬 하위 에이전트 수가 키의 동시 처리 한도를 초과합니다. | 동시에 실행하는 하위 에이전트 수를 줄이거나 지원팀에 동시 처리 한도 상향을 요청하세요. | Insufficient account balance | 잔액이 없음 | [충전](/ko/topup/) 후 다시 시도하세요. | No available accounts 또는 This request could not be completed | 업스트림의 일시적인 처리 용량 문제 | 메시지를 다시 보내세요. 문제가 지속되면 모델을 전환하세요. 클라이언트가 아닌 모델 측에서 발생하는 오류는 다음을 참고하세요. [Claude API 오류 가이드](/ko/learn/claude-api-errors-troubleshooting/). ## 자주 묻는 질문 OpenCode 설정 파일은 어디에 있나요? 전역 설정 파일은 ~/.config/opencode/opencode.json에 있으며, 프로젝트별 설정 파일은 저장소 루트의 opencode.json입니다. OpenCode는 두 설정을 병합합니다. API 키로 OpenCode에서 Claude를 사용하려면 어떻게 하나요? provider.anthropic.options.baseURL을 /v1로 끝나는 게이트웨이 URL로, apiKey를 {env:YOUR_VAR}로 설정하거나 npm @ai-sdk/anthropic을 사용하는 사용자 지정 공급자를 추가한 다음, model: provider/model-id로 모델을 선택하세요. OpenCode에서 파싱 오류가 발생하거나 응답이 '<'로 시작하는 이유는 무엇인가요? baseURL에 /v1이 빠져 있어 요청이 API 대신 웹사이트에 도달하기 때문입니다. @ai-sdk/anthropic에는 전체 접두 경로가 필요합니다. 예: https://aiprimetech.io/v1. OpenCode에서 Claude Pro 또는 Max 로그인을 사용할 수 있나요? OpenCode 문서에 따르면 Anthropic은 타사 Pro/Max 플러그인을 금지하며, OpenCode는 1.3.0에 해당 플러그인을 기본 포함하는 것을 중단했습니다. 지원되는 방식은 API 키를 사용하는 것입니다. 몇 분 만에 Claude 사용 시작하기 API 키를 발급받으세요 — Anthropic 계정이나 대기자 명단 등록이 필요하지 않습니다.[API 키 발급받기](/register) AI Prime Tech는 독립적인 API 게이트웨이입니다. Anthropic과 제휴 관계가 없으며, Anthropic의 보증을 받거나 Anthropic의 리셀러로 활동하지 않습니다. Claude 및 관련 모델 이름은 각 소유자의 상표입니다. ## 더 많은 Claude API 가이드 [Claude API 키 발급 방법](/ko/learn/how-to-get-a-claude-api-key/)[Claude API 요금 해설](/ko/learn/claude-api-pricing-explained/)[Claude API를 가장 저렴하게 사용하는 방법](/ko/learn/cheapest-way-to-use-claude-api/)[Claude API로 Cursor 무제한 사용](/learn/use-claude-api-with-cursor/)[Claude Code 무제한 이용](/ko/learn/use-claude-api-with-claude-code/)[Claude API 게이트웨이와 Anthropic 직접 이용 비교](/ko/learn/claude-api-vs-anthropic-direct/)[OpenAI 호환 API를 통해 Claude 사용하기](/ko/learn/openai-compatible-claude-api/)[Claude 모델 해설: Claude Opus, Sonnet, Haiku, Fable 비교 — 모든 Claude API 모델, Anthropic 모델 이름 및 가격 (2026)](/ko/learn/claude-api-models-compared/)[암호화폐로 Claude API 요금 결제하기](/ko/learn/claude-api-with-crypto-payment/)[대기 명단 없이 Claude API 이용하기](/ko/learn/claude-api-without-waitlist/)[Claude 토큰 사용량을 줄이는 방법](/ko/learn/how-to-reduce-claude-token-usage/)[Claude API로 Cline 무제한 사용](/ko/learn/use-claude-api-with-cline/)[Claude API로 Roo Code 무제한 사용](/ko/learn/use-claude-api-with-roo-code/)[JetBrains IDE에서 Claude 무제한 사용](/ko/learn/use-claude-api-with-jetbrains/)[Claude API로 Aider 무제한 사용하기](/ko/learn/use-claude-api-with-aider/)[VS Code에서 Claude 무제한 사용](/ko/learn/use-claude-api-with-vscode/)[Claude에서 Hermes 에이전트 무제한 실행하기](/ko/learn/run-hermes-agent-with-claude-api/)[Claude에서 OpenClaw 무제한 실행하기](/ko/learn/run-openclaw-with-claude-api/)[Anthropic 호환 API의 의미](/ko/learn/anthropic-compatible-api/)[Claude Code API 키 — ANTHROPIC_API_KEY: 발급 및 설정 방법과 대신 claude setup-token을 사용해야 하는 경우](/ko/learn/claude-code-api-key-setup/)[Claude Code API 비용 — 요금과 절감 방법](/ko/learn/claude-code-api-costs/)[Claude API 오류 설명: 서버 오류 500, 과부하 529, 사용량 제한 429, 잘못된 요청 400 — 각 오류의 해결 방법](/ko/learn/claude-api-errors-troubleshooting/)[Claude API 크레딧 구매 방법 — 그리고 Claude 크레딧이 어떤 "Claude 계정 구매" 상품보다 나은 이유](/ko/learn/buy-claude-api-credits/)[Claude 무료 API: 무료 Claude API 키가 있나요? 2026년에 실제로 무료인 것은 무엇인가요?](/ko/learn/claude-api-free-trial/)[Claude API와 Claude Pro/Max 구독 — 어떤 것을 선택할까요](/ko/learn/claude-api-vs-subscription/)[Claude에서 Codex CLI 실행하기](/ko/learn/use-claude-api-with-codex/)[Claude를 n8n에 연결하기](/ko/learn/use-claude-api-with-n8n/)[LiteLLM을 Claude로 라우팅하기](/ko/learn/use-claude-api-with-litellm/)[Kilo Code에서 Claude 사용하기](/ko/learn/use-claude-api-with-kilo-code/)[GitHub Copilot에 Claude 연결하기](/ko/learn/use-claude-api-with-github-copilot/)[게이트웨이를 통해 Zed를 Claude에 연결하기](/ko/learn/use-claude-api-with-zed/)[Cherry Studio를 Claude에 연결하기](/ko/learn/use-claude-api-with-cherry-studio/)[LangChain의 ChatAnthropic: 가져오기, base_url, 스트리밍, 도구 및 오류](/ko/learn/use-claude-api-with-langchain/)[Anthropic Python SDK: 설치, base_url 설정, 스트리밍 및 오류 처리](/ko/learn/anthropic-python-sdk/)[Vercel AI SDK로 Claude 사용하기: createAnthropic baseURL, 스트리밍 및 문제 해결](/ko/learn/use-claude-api-with-vercel-ai-sdk/)[Claude로 Factory Droid 실행하기](/ko/learn/use-claude-api-with-factory-droid/)[Claude Code API 이해하기](/ko/learn/claude-code-api/)[애플리케이션에 Claude API 통합하기](/ko/learn/claude-api-integration/)[Claude를 무제한으로 사용하는 방법 — 그리고 "Claude Code 크랙 버전"이 없는 이유](/ko/learn/get-unlimited-claude-usage/)