OpenAI 호환 제공업체와 함께하는 OpenCode 및 Kilo Code 설정 파일과 컨텍스트 제한 함정

OpenCode와 Kilo Code 모두 자체 OpenAI 호환 제공업체를 추가할 수 있게 해주며, 두 구성(config) 모두 간단해 보입니다. 저를 당황하게 한 부분은 URL이나 키가 아니었습니다. 명확한 원인 없이 장시간 세션이 무너뜨리는 limit 블록의 누락이었습니다.

여기에 제가 사용하는 설정과 그 과정에서 저지른 실수들을 공유합니다. 제 예시는 제가 구축한 OpenAI 호환 게이트웨이인 APIClaw를 가리키므로, 이 점을 고려해 주십시오. 다른 제공업체의 기본 URL과 모델 ID로 교체하여 사용하시면 됩니다.

준비해야 할 것들

/v1로 끝나는 기본 URL (예: https://apiclaw.biz/v1). 여기에 /chat/completions를 추가하지 마십시오. 클라이언트가 경로를 추가합니다.
환경 변수에 API 키를 설정하여 파일에 커밋되지 않도록 합니다:

export APICLAW_API_KEY="sk-your-key"

제공업체의 모델 목록에서 가져온 정확한 모델 ID. 짧은 별칭이나 표시 이름이 대부분의 "모델을 찾을 수 없음(model not found)" 오류를 유발합니다.
모델의 실제 컨텍스트 창 크기와 최대 출력 토큰 수. 이 숫자들은 아래에서 필요합니다.

OpenCode

OpenCode의 제공업체 문서는 @ai-sdk/openai-compatible 패키지를 통해 모든 OpenAI 호환 API가 작동한다고 명시하고 있습니다. 이것을 ~/.config/opencode/opencode.json에 넣으십시오 (프로젝트 레벨의 opencode.json도 가능합니다):

{
  "$schema": "https://opencode.ai/config.json",
  "model": "apiclaw/YOUR_MODEL_ID",
...
}

각 부분이 연결되는 방식은 다음과 같습니다:

provider 아래의 apiclaw는 사용자가 선택하는 제공업체 ID입니다. 최상위 model은 해당 ID, 슬래시(/), 그리고 모델 키로 구성됩니다: apiclaw/YOUR_MODEL_ID.
models 아래의 키는 서버가 GET /v1/models에서 반환하는 ID와 일치해야 합니다. OpenCode 문서는 로컬 서버 예제에서도 동일한 규칙을 명시하고 있습니다.
{env:APICLAW_API_KEY}는 런타임에 변수를 읽어옵니다.

환경 변수를 사용하고 싶지 않다면 opencode auth login을 실행하거나 OpenCode 내부에서 /connect를 실행한 후 Other를 선택하고 동일한 제공업체 ID인 apiclaw를 입력하세요. 이렇게 하면 키가 저장되지만, 기본 URL이나 모델을 묻지는 않기 때문에 여전히 opencode.json 블록이 필요합니다. 여기에 입력하는 제공업체 ID는 provider 아래의 키와 정확히 일치해야 합니다.

/models로 확인하세요. 사용 중인 모델은 제공업체 이름 아래에 목록으로 나와야 합니다. 그런 다음 한 줄짜리 프롬프트를 보내고 제공업체의 요청 로그를 확인하세요.

Kilo Code

Kilo Code에는 두 가지 진입 방법이 있습니다.

VS Code 확장 프로그램: 설정(Settings) > 제공업체(Providers) 탭 > 하단의 Custom provider를 선택합니다. 고유한 제공업체 ID를 부여하고, 제공업체 API로 OpenAI Compatible을 선택한 다음, /v1 기본 URL과 키를 붙여넣고, 가져온 목록에서 모델을 선택하거나 정확한 ID를 붙여넣습니다.

Kilo CLI: 제공업체 블록은 전역(global) ~/.config/kilo/kilo.jsonc에 들어갑니다:

{
  "$schema": "https://app.kilo.ai/config.json",
  "model": "openai-compatible/YOUR_MODEL_ID",
...

전역 파일이 중요합니다. 제 설정에서는 {env:...}가 전역 구성에서만 해석되었고, 프로젝트 파일의 동일한 블록은 인증에 실패했습니다. Kilo는 키가 유효하지 않다고 말하고 curl은 괜찮다고 할 경우, 어느 파일에 해당 블록이 들어있는지 확인하세요. kilo models는 제공업체가 로드되었는지 확인해 줍니다.

컨텍스트 제한 함정 (The context limit trap)

두 도구 모두 자체 내장 카탈로그의 모델에 대한 컨텍스트 창(context window)을 알고 있습니다. 사용자 지정 제공업체의 모델은 그 카탈로그에 포함되어 있지 않기 때문에, 클라이언트는 limit에서 알려주는 것만 알게 됩니다.

limit을 생략하면 클라이언트는 컨텍스트 크기를 알지 못합니다. Kilo에서는 제한이 없는 사용자 지정 모델의 경우 0으로 해석됩니다. 압축(Compaction, 에이전트가 이전 대화를 요약하여 공간을 확보하는 단계)이 절대 트리거되지 않고, 대화는 계속 커지다가 결국 제공업체가 너무 길다는 이유로 요청을 거부합니다. 이는 세션 시작 후 한 시간쯤에 발생하는 무작위 실패처럼 보이지만, 제공업체가 불안정해서 생기는 문제는 아닙니다.

모델의 실제 컨텍스트 창(context window)을 context에, 최대 출력 토큰 수(max output tokens)를 output에 설정하세요. 이 값들을 실제 숫자보다 약간 낮게 설정하는 것은 괜찮으며 여유 공간을 남깁니다. 하지만 실제 숫자보다 높게 설정하면 동일한 오류가 발생합니다.

오류 및 의미

Invalid API key / 401. 트레일링 스페이스(trailing space)가 포함된 키를 붙여넣었거나, 키가 비활성화되었거나, (Kilo의 경우) 블록이 {env:...}로 해석되지 않은 프로젝트 파일 내에 있는 경우입니다.

Model not found / 404. 모델 키가 정확한 서버 ID가 아니거나, 기본 URL(base URL)에 /v1이 누락되었거나 끝에 /chat/completions이 붙어 있는 경우입니다.

모델은 보이지만 도구 호출(tool calls)이 무시됨. 모델이 함수 호출(function calling)을 제대로 지원하지 않거나, (Kilo의 경우) 사용자 정의 모델 항목에서 tool_call이 true로 설정되지 않은 경우입니다. 제공업체를 탓하기 전에 도구 사용에 알려진 모델로 테스트해 보세요.

긴 세션은 컨텍스트 길이 오류(context-length error)로 종료됨. limit이 누락되었거나 부풀려진 경우입니다. 위 내용을 참조하세요.

Responses API가 필요합니다. OpenCode의 경우, npm 패키지를 @ai-sdk/openai로 전환해야 합니다. @ai-sdk/openai-compatible은 Chat Completions를 처리합니다. 제공업체가 /v1/responses를 제공하는 경우에만 이 작업을 수행하세요.

체크리스트

Base URL이 /v1로 끝나며, 그 뒤에 다른 것이 없음.
키가 환경 변수(environment variable)에 존재하며 {env:NAME}으로 참조됨.
모델 키는 GET /v1/models에서 가져온 ID와 같고, 최상위 model은 providerid/modelkey임.
limit.context와 limit.output이 모델의 실제 숫자로 설정됨.
Kilo CLI 블록이 전역 ~/.config/kilo/kilo.jsonc에 있음.
/models (OpenCode) 또는 kilo models (Kilo)에서 모델이 표시되고, 테스트 프롬프트가 제공업체의 로그에 나타남.

설정 스키마가 변경된 경우, OpenCode의 providers 페이지(opencode.ai/docs)와 Kilo 자체 문서를 신뢰해야 합니다.

OpenAI 호환 제공업체와 함께하는 OpenCode 및 Kilo Code 설정 파일과 컨텍스트 제한 함정

요약

핵심 포인트