OpenAI 호환 API로 OpenCode 설정하기

시작하기 전에 필요한 항목

OpenCode는 터미널에서 실행되는 오픈 소스 코딩 에이전트입니다. 여러 모델 제공자와 통신할 수 있으며, 엔드포인트가 OpenAI 채팅 형식을 따르는 경우 커스텀 제공자를 추가할 수 있습니다. 이 API는 해당 형식을 따르므로 몇 가지 필드를 입력하면 설정이 완료됩니다.

다음 세 가지 값을 먼저 준비하세요:

• 베이스 URL: https://api.kimicode.top/v1
• 모델 ID: uncensored
• API 키: API 키 페이지에서 생성하세요. 신규 계정은 클릭 한 번으로 $0.50 체험용 크레딧을 받을 수 있으며, 이는 아래 테스트에 충분합니다. 체험 키는 동시 요청 2개, 분당 60개 요청을 허용합니다.

키를 파일에 붙여넣지 말고 환경 변수에 보관하세요:

Copyexport KIMICODE_API_KEY="your-key-here"

단계 1: curl로 엔드포인트 테스트

도구 설정 전에 이 작업을 수행하세요. curl이 작동하고 OpenCode가 작동하지 않으면 문제가 설정에 있음을 알 수 있습니다. curl이 실패하면 키나 URL을 두 곳에서 수정하지 않고 한 번에 수정할 수 있습니다.

Copycurl https://api.kimicode.top/v1/chat/completions \
  -H "Authorization: Bearer $KIMICODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "messages": [{"role": "user", "content": "Say hello in five words."}],
    "max_tokens": 40
  }'

choices 배열과 usage 블록이 포함된 JSON 객체를 받아야 합니다. 401은 키가 잘못되었거나 Bearer 접두사가 누락되었음을 의미합니다. 404는 URL 오타 또는 이미 /chat/completions이 포함되어 있음을 의미합니다.

코딩 에이전트는 답변을 스트리밍하고 도구를 호출하므로 이 두 가지를 확인하세요:

Copycurl -N https://api.kimicode.top/v1/chat/completions \
  -H "Authorization: Bearer $KIMICODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "stream": true,
    "messages": [{"role": "user", "content": "Count from one to five."}]
  }'

각각 작은 JSON delta를 포함하는 data: 줄들을 보고, 사용량 수치와 마지막 마커로 끝나는 것을 확인하세요. -N 플래그는 curl의 버퍼링을 비활성화하여 청크가 도착하는 대로 표시되도록 합니다.

단계 2: OpenCode에 커스텀 제공자 추가

OpenCode는 프로젝트 폴더 또는 전역 설정 디렉토리에서 JSON 설정 파일 opencode.json을 읽습니다. OpenAI 스타일의 커스텀 프로바이더는 AI SDK의 OpenAI 호환 패키지로 선언하며, 기본 URL과 모델 목록을 사용합니다. 아래 레이아웃은 작성 시점의 OpenCode 공개 문서를 따릅니다. 릴리스 간에 필드명이 변경될 수 있으므로, 거부될 경우 최신 OpenCode 문서의 프로바이더 섹션과 비교하세요.

Copy{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "kimicode": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Kimicode API",
      "options": {
        "baseURL": "https://api.kimicode.top/v1",
        "apiKey": "{env:KIMICODE_API_KEY}"
      },
      "models": {
        "uncensored": {
          "name": "Uncensored",
          "limit": {
            "context": 100000,
            "output": 8192
          }
        }
      }
    }
  },
  "model": "kimicode/uncensored"
}

models 아래의 키는 서버로 전송되는 정확한 모델 ID이므로 uncensored로 읽혀야 합니다. 마지막 줄은 제공자 이름, 슬래시, 모델 ID 형식으로 기본 제공자 및 모델을 선택합니다.

{env:KIMICODE_API_KEY} 형식은 OpenCode가 셸에서 해당 변수를 읽도록 지시합니다. 버전에서 자체 로그인 명령어를 통해 인증 정보를 처리한다면 해당 경로를 사용하고 파일에서 키를 제거하세요. 어쨌든 실제 키는 커밋하지 마세요.

프로젝트 설정 또는 전역 설정

제공자 블록을 두 곳에 둘 수 있습니다. 프로젝트 루트의 파일은 해당 리포지토리에만 적용되며, 하나의 설정을 공유하는 팀에 적합합니다. 사용자 설정 디렉토리의 파일은 전체에 적용되며 개인 기본값에 적합합니다. 둘 다 존재할 경우 프로젝트 파일이 전역 파일에 추가하거나 재정의합니다.

제공자 정의에는 전역 파일을 사용하고 키에는 환경 변수를 사용하세요. 그러면 모든 저장소에서 엔드포인트를 사용할 수 있으며, 소스 코드 옆에 비밀 정보가 위치하지 않습니다. 여러 사람이 하나의 프로젝트에서 작업한다면 키 없이 제공자 블록만 커밋하고, 각자가 자신의 변수를 설정하게 하세요. 이렇게 하면 키를 교체하는 것도 간단합니다. 변수를 변경하고 터미널을 다시 시작하면 설정 파일은 그대로 유지됩니다.

단계 3: 모델 선택 및 작업 실행

프로젝트 폴더에서 OpenCode를 시작하고 모델 선택기를 엽니다. 커스텀 제공자가 설정한 표시 이름으로 목록에 나타납니다. 선택한 후 에이전트에 함수 설명이나 짧은 파일용 단위 테스트 작성과 같은 작고 검증 가능한 작업을 부여하세요.

두 가지 이유로 작게 시작하세요. 첫째, 도구 호출이 작동하는지 확인할 수 있습니다: OpenCode가 모델을 호출하여 파일을 읽거나 편집할 때 도구 호출 인터페이스를 통해 수행합니다. 둘째, 코딩 에이전트는 턴당 많은 텍스트(파일 내용 및 기록 포함)를 보내므로 긴 세션은 토큰을 빠르게 소모합니다. 다음 섹션에서 이에 대한 수치를 확인합니다.

모델이 표시되지 않으면 파일이 유효한 JSON인지, OpenCode가 설정 파일을 찾는 위치에 있는지, 제공자 이름이 model 필드에 입력한 내용과 일치하는지 확인하세요.

도구 호출 및 JSON 모드 직접 테스트

OpenCode는 파일 읽기, 명령 실행, 코드 편집에 도구 호출에 의존하므로 에이전트의 실패를 탓하기 전에 엔드포인트가 도구 정의를 처리하는지 확인하는 것이 좋습니다. 이 요청은 하나의 도구를 제공하고 해당 도구가 필요한 질문을 합니다.

Copycurl https://api.kimicode.top/v1/chat/completions \
  -H "Authorization: Bearer $KIMICODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "messages": [{"role": "user", "content": "What is in the file notes.txt?"}],
    "tools": [{
      "type": "function",
      "function": {
        "name": "read_file",
        "description": "Read a text file by path",
        "parameters": {
          "type": "object",
          "properties": {"path": {"type": "string"}},
          "required": ["path"]
        }
      }
    }],
    "tool_choice": "auto"
  }'

좋은 응답에는 tool_calls 항목이 포함되어 있으며, 여기에는 JSON 인자 문자열과 함께 read_file 이름이 지정됩니다. 에이전트는 도구를 실행한 후 role을 tool로 설정한 메시지로 결과를 다시 전송하며, 모델은 이어서 처리합니다. 일반 텍스트만 보인다면 더 직접적인 프롬프트를 시도하세요. 모델이 도구 호출 여부를 결정하는 것은 그 동작의 일부이기 때문입니다.

JSON 모드는 별도의 스위치입니다. "response_format": {"type": "json_object"}을 추가하면 유효한 JSON 출력을 요청하며, 다른 스크립트가 반환된 내용을 구문 분석해야 할 때 도움이 됩니다. 모델이 기대하는 형식을 알 수 있도록 프롬프트에 JSON도 언급하세요.

컨텍스트 크기 및 세션 비용

컨텍스트 창은 프롬프트와 완성 텍스트를 합쳐 100,000 토큰입니다. limit.context을 100000으로 설정하면 에이전트가 실제 한계를 인지하여 서버가 요청을 거부하기 전에 이력을 정리하거나 요약할 수 있습니다. 완성 텍스트는 남은 공간을 모두 사용할 수 있으며, max_tokens은 선택 사항입니다.

요금 체계는 입력 토큰 100만 개당 $0.15, 출력 토큰 100만 개당 $0.50입니다. 에이전트는 입력이 많으며, 매 턴마다 대화 내용을 다시 전송하기 때문입니다. 다음은 중간 정도의 세션에 대한 계산 예시입니다:

• 40턴, 각 턴당 약 30,000 입력 토큰 전송: 1,200,000 입력 토큰, 즉 1.2 x $0.15 = $0.18.
• 각 턴당 약 800 출력 토큰 반환: 32,000 출력 토큰, 즉 0.032 x $0.50 = $0.016.
• 합계: $0.196, 즉 전체 세션에 약 20센트.

귀하의 숫자는 다를 수 있습니다. 응답의 usage 값을 읽거나 각 응답에서 잔액을 보고하는 X-Balance-USD 헤더를 확인하세요. 크레딧은 선불 방식이며 만료되지 않으며, 실패하거나 거부된 요청에는 요금이 부과되지 않습니다. 자세한 내용은 가격 책정 페이지에서 확인하세요.

코딩 에이전트에 대한 정직한 기대

이것은 합법적인 성인 사용에 대한 콘텐츠 거부 없이 답변하도록 조정된 일반 텍스트 모델입니다. 코드 전용 모델이 아니며 이 페이지는 벤치마크 주장을 하지 않습니다. 중요한 것을 맡기기 전에 버전 관리와 함께 자체 작업에서 저장소를 신뢰할 수 있게 편집하는지 테스트해야 합니다.

에이전트에 필요한 기초적인 인프라를 처리합니다: 스트리밍 tool_calls, role: "tool" 메시지로 전송되는 도구 결과, response_format을 통한 JSON 모드. 이미지 없이 텍스트 전용이므로 스크린샷을 첨부하는 기능은 작동하지 않습니다.

에이전트에 두 가지 제한이 중요합니다. 전체 키는 동시 요청 8개와 분당 300개 요청을 허용합니다. 한 번에 많은 호출을 실행하는 하위 에이전트 또는 병렬 도구 실행은 동시성 한도에 도달할 수 있으며, 스트리밍된 요청은 스트림이 끝날 때까지 슬롯을 유지합니다. 이 경우 코드 concurrency와 함께 HTTP 429를 받습니다. 코드 rate_limited은 분당 요청이 너무 많음을 의미합니다. 일시적 과부하 시 Retry-After: 5와 함께 429도 표시될 수 있습니다. 동시성을 줄이거나 기다렸다가 재시도하세요.

문제 해결

증상	잠재적 원인	해결 방법
401 Unauthorized	빈 키 또는 잘못된 키; OpenCode를 실행한 셸에서 환경 변수가 설정되지 않았습니다	동일한 터미널에서 echo $KIMICODE_API_KEY을 실행한 후 OpenCode를 다시 시작하세요
404 Not Found	Base URL이 /chat/completions을 포함하거나 /v1이 누락되어 있습니다	정확히 https://api.kimicode.top/v1를 사용하세요
모델을 찾을 수 없음	모델 키가 uncensored와 다름	models의 키를 GET /v1/models이 반환한 ID와 일치시키세요.
concurrency가 포함된 429	너무 많은 동시 요청	동시 함수 호출을 줄이거나 스트리밍이 완료될 때까지 기다리세요.
요청이 너무 큼	본문 크기가 8 MB를 초과하거나 이력이 컨텍스트 창 한계에 근접한 경우	새 세션을 시작하거나 기록을 요약하세요.

여기서 다루지 않은 항목에 대해서는 문서 페이지에 전체 요청 참조가 있으며, 연동 가이드에는 다른 OpenAI 스타일 클라이언트의 관점에서 동일한 엔드포인트가 다루어져 있습니다.

더 많은 가이드

• OpenAI 호환이란 API 관점에서 무엇을 의미합니까?
• Kimicode 대체재: 무검열 호스팅 LLM API
• 무검열 LLM API: OpenAI 호환 통합 및 가격