CometAPI와 함께 OpenCode 사용하기

이 가이드를 사용해 OpenCode 를 CometAPI와 함께 실행하세요. 이 구성은 별도의 사용자 지정 공급자를 통해 네 가지 API 형식을 노출합니다. 이 구성은 OpenCode 1.18.16에서 테스트되었습니다. 공식 참고 자료:

각 your-model-id 값을 다음 CometAPI 모델 페이지에서 제공하는 모델 ID로 바꾸세요. 주변 공급자 항목의 API 형식을 지원하는 모델을 선택하세요.

사전 요구 사항

Node.js와 npm 또는 OpenCode 가이드에 설명된 다른 설치 방법
활성 API 키가 있는 CometAPI 계정. 키 발급처: 대시보드
하나 이상의 모델 ID 출처: CometAPI 모델 페이지

API 형식 이해하기

각 공급자 ID는 하나의 SDK 어댑터와 하나의 API 형식을 선택합니다.

공급자 ID	OpenCode 어댑터	기본 URL	API 형식
`cometapi-chat`	`@ai-sdk/openai-compatible`	`https://api.cometapi.com/v1`	채팅 완성
`cometapi-responses`	`@ai-sdk/openai`	`https://api.cometapi.com/v1`	응답
`cometapi-messages`	`@ai-sdk/anthropic`	`https://api.cometapi.com/v1`	Anthropic 메시지
`cometapi-gemini`	`@ai-sdk/google`	`https://api.cometapi.com/v1beta`	Gemini generateContent

이 가이드에서는 일반적인 OpenCode 에이전트 실행 중 사용되는 Gemini 스트리밍(Streaming) 작업을 검증합니다. Google 어댑터는 :streamGenerateContent?alt=sse 모델 경로에 추가합니다. /chat/completions, /responses, /messages 또는 Gemini 모델 경로를 baseURL에 추가하지 마세요. 각 어댑터가 필요한 작업 경로를 추가합니다.

런타임 권한 이해하기

OpenCode는 이를 시작하는 프로세스의 권한으로 실행됩니다. 다음과 같이 시작하세요 의도한 프로젝트 디렉터리에서 OpenCode를 실행하고 다음과 같은 롤백 경로를 유지하세요: git. 더 강력한 파일 시스템, 프로세스, 네트워크 또는 API 키 경계가 필요할 때는 컨테이너나 샌드박스를 사용하세요.

OpenCode 구성

OpenCode 설치

공식 npm 패키지로 OpenCode를 설치하세요:

npm install -g opencode-ai

CLI를 사용할 수 있는지 확인하세요:

opencode --version

다음을 참조하세요 OpenCode 설치 가이드 에서 Homebrew, Windows, Docker 및 기타 설치 방법을 확인할 수 있습니다.

CometAPI API 키 설정

CometAPI API 키를 COMETAPI_KEY 환경 변수에 저장하세요.

macOS / Linux / WSL
Windows PowerShell

터미널에 표시하지 않고 API 키를 읽으세요:

read -rsp "CometAPI API key: " COMETAPI_KEY
printf '\n'
export COMETAPI_KEY

현재 PowerShell 세션으로 API 키를 읽어 오세요:

$secureKey = Read-Host "CometAPI API key" -AsSecureString
$env:COMETAPI_KEY = [System.Net.NetworkCredential]::new(
  "",
  $secureKey
).Password

OpenCode를 실행하는 모든 셸 세션에서 변수를 설정하세요. API 키를 버전 관리에 커밋하지 마세요.

구성 위치 선택

지원되는 다음 위치 중 하나를 사용하세요:

전역 구성: ~/.config/opencode/opencode.json
프로젝트 구성: 프로젝트 루트의 opencode.json

OpenCode는 구성 파일을 병합합니다. 프로젝트 구성은 전역 구성의 충돌하는 값을 재정의합니다.모든 프로젝트에서 공급자를 사용하려면 전역 파일을 사용하세요. 리포지토리에 자체 모델 항목이 필요한 경우에는 프로젝트 파일을 사용하세요.

CometAPI 공급자 추가

선택한 구성 파일을 만드세요. 파일에 이미 provider 객체가 포함되어 있으면 해당 객체에 다음 네 개의 항목을 병합하세요:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "cometapi-chat": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "CometAPI Chat Completions",
      "options": {
        "baseURL": "https://api.cometapi.com/v1",
        "apiKey": "{env:COMETAPI_KEY}"
      },
      "models": {
        "your-model-id": {
          "name": "CometAPI Chat model"
        }
      }
    },
    "cometapi-responses": {
      "npm": "@ai-sdk/openai",
      "name": "CometAPI Responses",
      "options": {
        "baseURL": "https://api.cometapi.com/v1",
        "apiKey": "{env:COMETAPI_KEY}"
      },
      "models": {
        "your-model-id": {
          "name": "CometAPI Responses model"
        }
      }
    },
    "cometapi-messages": {
      "npm": "@ai-sdk/anthropic",
      "name": "CometAPI Anthropic Messages",
      "options": {
        "baseURL": "https://api.cometapi.com/v1",
        "apiKey": "{env:COMETAPI_KEY}"
      },
      "models": {
        "your-model-id": {
          "name": "CometAPI Messages model"
        }
      }
    },
    "cometapi-gemini": {
      "npm": "@ai-sdk/google",
      "name": "CometAPI Gemini",
      "options": {
        "baseURL": "https://api.cometapi.com/v1beta",
        "apiKey": "{env:COMETAPI_KEY}"
      },
      "models": {
        "your-model-id": {
          "name": "CometAPI Gemini model"
        }
      }
    }
  }
}

각 your-model-id 키를 독립적으로 교체하세요. 네 개의 항목은 서로 다른 모델 ID를 사용할 수 있습니다.이 구성에서는 최상위 model을 설정하지 않습니다. 이렇게 하면 /models을 통해 필요한 API 형식과 모델을 선택할 수 있습니다.

이 구성에는 /connect을 사용하지 마세요. apiKey 필드는 COMETAPI_KEY 환경에서 읽습니다. 설정되지 않은 변수는 저장된 /connect API 키 대신 빈 값으로 해석됩니다.

각 공급자 선택 및 확인

액세스하려는 프로젝트에서 OpenCode를 시작하세요:

opencode

/models을 실행한 다음 provider/model 항목을 선택하세요. 이 가이드의 네 가지 검증 실행에서 각 모델 턴은 선택한 항목에 해당하는 API 형식을 사용했습니다. 교차 형식 요청 팬아웃이나 자동 API 형식 협상은 관찰되지 않았습니다.명령줄에서 채팅 완성을 확인하려면 다음을 실행하세요:

opencode run \
  --model cometapi-chat/your-model-id \
  "Reply exactly with: COMETAPI_CHAT_OK"

명령줄에서 응답을 확인하려면 다음을 실행하세요:

opencode run \
  --model cometapi-responses/your-model-id \
  "Reply exactly with: COMETAPI_RESPONSES_OK"

명령줄에서 Anthropic 메시지를 확인하려면 다음을 실행하세요:

opencode run \
  --model cometapi-messages/your-model-id \
  "Reply exactly with: COMETAPI_MESSAGES_OK"

명령줄에서 Gemini generateContent를 확인하려면 다음을 실행하세요:

opencode run \
  --model cometapi-gemini/your-model-id \
  "Reply exactly with: COMETAPI_GEMINI_OK"

문제 해결

OpenCode에 CometAPI 모델이 표시되지 않음

구성이 유효한 JSON인지 확인하세요. 각 사용자 지정 항목은 최상위 provider 객체 안에 있어야 하며, 각 모델 ID는 일치하는 models 객체 안에 있어야 합니다. OpenCode를 다시 시작한 다음 /models을 다시 여세요.

OpenCode에서 API 키 또는 인증 오류가 발생함

OpenCode를 실행하는 셸에서 환경 변수 COMETAPI_KEY가 설정되어 있는지 확인하세요. 설정되지 않은 {env:COMETAPI_KEY} 참조는 빈 값이 됩니다. 셸 프로필을 변경한 후에는 새 셸을 여세요.

모델 ID를 사용할 수 없음

다음을 확인한 다음 CometAPI Models 페이지를 확인한 다음, 선택한 공급자 항목의 모델 ID를 교체하세요. 모델이 해당 공급자의 API 형식을 지원하는지 확인하세요.

요청에서 잘못된 경로를 사용함

채팅 완성, 응답 및 Messages의 경우 baseURL를 /v1로 유지하세요. Gemini에는 /v1beta 를 사용하세요. baseURL에 작업 경로를 포함하지 마세요.

한 공급자는 작동하지만 다른 공급자는 실패함

선택한 공급자의 API 형식을 지원하는 모델 ID를 사용하세요. 한 모델 ID가 네 가지 형식을 모두 지원한다고 가정하지 마세요.

프로젝트 구성이 전역 공급자를 변경함

OpenCode는 전역 구성과 프로젝트 구성을 병합합니다. 전역 공급자 항목을 변경하지 않으려면 프로젝트 공급자 ID의 이름을 바꾸거나 충돌하는 값을 제거하세요.

OpenCode가 예상보다 더 많은 액세스 권한을 가짐

OpenCode는 이를 실행한 프로세스의 권한을 사용합니다. 더 강력한 액세스 경계가 필요하면 OpenCode를 컨테이너 또는 샌드박스에서 실행하세요.

개요

AI 코딩 에이전트

AI 에이전트

AI 채팅 클라이언트

번역 및 언어

자동화 플랫폼

관측성 및 평가

AI 프레임워크

CometAPI와 함께 OpenCode 사용하기

사전 요구 사항

API 형식 이해하기

런타임 권한 이해하기

OpenCode 구성

문제 해결

관련 리소스

​사전 요구 사항

​API 형식 이해하기

​런타임 권한 이해하기

​OpenCode 구성

​문제 해결

​관련 리소스

사전 요구 사항

API 형식 이해하기

런타임 권한 이해하기

OpenCode 구성

문제 해결

관련 리소스