OpenCode

1. 개요

OpenCode는 75개 이상의 모델과 셀프 호스팅 배포를 기본 지원하는 오픈소스 AI 코딩 어시스턴트입니다. GravitexAI를 통해 각 벤더를 개별 설정하지 않고 OpenCode에서 주류 모델(GPT, Claude, Gemini, Qwen 등)을 사용할 수 있습니다.

통합 멀티 모델

하나의 provider로 GPT / Claude / Gemini / Qwen 전체 제품군

셀프 호스트 친화적

자체 백엔드 및 프로젝트별 설정 오버라이드 지원

Responses API 지원

GPT Codex 시리즈와 apiCompatibility: "responses" 호환

오픈 & 감사 가능

완전 오픈소스, 필요에 따라 커스터마이즈

다운로드: https://opencode.ai/

2. 빠른 설정 (GravitexAI)

2.1 API 키 발급

로그인

GravitexAI 콘솔에서 회원가입 또는 로그인합니다.

토큰 생성

API Keys를 열고 “Create new token”을 클릭한 뒤 sk-xxxxxxxxxx 키를 복사합니다.

2.2 OpenCode에서 커스텀 provider 설정

Provider 설정 열기

OpenCode에서 Server / Provider 설정으로 이동하고 Add custom provider(OpenAI 호환)를 선택합니다.

Provider 정보 입력

Field	Value
Provider ID	`gravitex` (소문자, 숫자, 하이픈 또는 밑줄)
Display name	`GravitexAI`
Base URL	`https://api.gravitex.ai/v1` (반드시 `/v1`로 끝나야 함)
API key	이전 단계에서 발급한 GravitexAI 키 붙여넣기

모델 추가

Models 아래에 사용할 모델 ID를 추가합니다 (예: gpt-5.5, claude-sonnet-4-6, gemini-3.5-flash). ID는 GravitexAI 모델 목록과 일치해야 합니다.

저장 및 사용

저장 후 채팅 및 설정에서 providerID/modelID 형식으로 선택합니다 (예: gravitex/gpt-5.5).

2.3 모델 전환

채팅 또는 설정에서 구성된 provider/모델(예: gravitex/gpt-5.5)을 선택하여 전환합니다.

셀프 호스트 또는 백업 GravitexAI 엔드포인트의 경우 Base URL을 변경하세요 (예: http://your-server:3003/v1).
프로젝트 또는 전역 opencode.json에서 "model": "gravitex/modelID"로 기본 모델을 설정하세요.

3. 일부 모델은 Responses API 필요 (중요)

일부 Azure / OpenAI 모델은 레거시 Chat Completions 엔드포인트가 아닌 Responses API만 지원합니다. OpenCode가 Chat Completions를 기본으로 사용하면 다음 오류가 표시됩니다:

The chatCompletion operation does not work with the specified model, gpt-5.1-codex. Please choose different model and try again.

아래 스크린샷은 OpenCode에서 이 오류가 표시되는 모습입니다:

Error when using gpt-5.1-codex with Chat Completions

3.1 Responses API가 필요한 모델

Model ID / family	Notes
gpt-5.1-codex	GPT 5.1 Codex (코드 중심) — Responses API 전용
gpt-5.2-codex	위와 동일
computer-use-preview	Responses API computer-use 도구와 함께 사용하는 실험 모델

최신 전체 목록은 Azure / 벤더 문서를 참조하세요:

3.2 OpenCode에서 설정하는 방법

설정의 모델에 apiCompatibility 매개변수를 추가하면 됩니다 — 코드 변경은 필요 없습니다.

설정 파일 위치

Windows: C:\Users\<username>\.config\opencode\opencode.jsonc
macOS / Linux: ~/.config/opencode/opencode.jsonc

Responses API requirement for some models

매개변수 추가

기존 커스텀 provider(GravitexAI 또는 자체 API를 가리키는)에서 필요한 모델(예: gpt-5.1-codex)에 **"apiCompatibility": "responses"**를 추가합니다:

opencode.jsonc: apiCompatibility responses for gpt-5.1-codex

{
  "$schema": "https://opencode.ai/config.json",
  "disabled_providers": [
    "backup_gravitex"
  ],
  "provider": {
    "backup_gravitex": {
      "name": "backup_gravitex",
      "npm": "@ai-sdk/openai-compatible",
      "models": {
        "gpt-5.2": {
          "name": "gpt-5.2"
        },
        "gpt-5.1-codex": {
          "name": "gpt-5.1-codex",
          "apiCompatibility": "responses"
        },
        "gpt-5.1-chat": {
          "name": "gpt-5.1-chat"
        }
      },
      "options": {
        "baseURL": "xxxxxxxx"
      }
    },
    "backup_v1": {
      "name": "backup_v1",
      "npm": "@ai-sdk/openai-compatible",
      "models": {
        "gpt-5.2": {
          "name": "gpt-5.2"
        },
        "gpt-5.1-codex": {
          "name": "gpt-5.1-codex",
          "apiCompatibility": "responses"
        },
        "gpt-5.1-chat": {
          "name": "gpt-5.1-chat"
        }
      },
      "options": {
        "baseURL": "https://api.gravitex.ai/v1"
      }
    }
  }
}

저장 후 해당 provider의 gpt-5.1-codex(예: backup_v1/gpt-5.1-codex)를 선택하면 Responses API 형식으로 해당 baseURL에 요청이 전송됩니다.

설정 확인

올바르게 구성된 모델(예: backup_v1/gpt-5.1-chat)을 선택하고 채팅을 테스트하세요 — 정상 응답이 오면 설정이 완료된 것입니다:

3.3 요약

시나리오	조치
Responses만 지원하는 모델 (예: gpt-5.1-codex, gpt-5.2-codex)	`opencode.jsonc`의 커스텀 provider models 아래 해당 모델에 `"apiCompatibility": "responses"` 추가
일반 모델 (예: gpt-5.5, claude-sonnet-4-6, gemini-3.5-flash)	`apiCompatibility` 불필요 — 빠른 설정 따라하기

4. 추천 모델 (GravitexAI 경유)

Category	Model ID examples	Notes
플래그십 코딩	`gpt-5.5`, `claude-opus-4-7`	최고의 종합 코딩 능력
Codex 시리즈	`gpt-5.1-codex`	Responses API 필요 (3절 참조)
일반 채팅 + 코드	`gpt-5.4`, `claude-sonnet-4-6`, `claude-sonnet-4-5-20250929`	즉시 사용 가능
빠른 / 저지연	`gemini-3.5-flash`, `claude-haiku-4-5-20251001`	자동 완성 및 도구 사용에 적합
가성비	`gpt-5.4-mini`, `gemini-3.1-flash-lite-preview`, `qwen3-coder-plus`	고동시성 / 배치

전체 ID는 GravitexAI 모델 목록을 참조하세요.

성공 예시

GravitexAI를 사용한 OpenCode 일반 채팅:

5. FAQ

`The chatCompletion operation does not work…` 오류

해당 모델은 Responses API만 지원합니다. opencode.jsonc에 "apiCompatibility": "responses"를 추가하세요 — 3절을 참조하세요.

401 / invalid API key

키가 완전하고 끝에 공백이 없는지 확인하세요.
GravitexAI 콘솔에서 삭제/비활성화되지 않았는지 확인하세요.
잔액이 양수인지 확인하세요.

404 / endpoint not found

Base URL이 /v1로 끝나는지 확인하세요: https://api.gravitex.ai/v1.

유효해 보이는 ID에 `model not found`

모델 ID는 GravitexAI 목록과 정확히 일치해야 합니다. 대소문자와 버전 접미사에 주의하세요 (예: claude-sonnet-4-5-20250929, claude-sonnet-4-5 아님).

팀 전체 표준화 방법?

opencode.jsonc를 저장소의 .config/opencode/(또는 프로젝트 루트)에 커밋하세요. 각 엔지니어는 자신의 API 키만 사용합니다.

6. 참고 자료

OpenCode 사이트 및 다운로드: https://opencode.ai/
OpenCode 설정 및 모델: Models, Providers
GravitexAI 콘솔: https://maas.gravitex.ai
모델 카탈로그: https://maas.gravitex.ai/#/models

대화형 AI

프로그래밍 개발

AI 에이전트

기술 엔지니어링

번역

1. 개요

통합 멀티 모델

셀프 호스트 친화적

Responses API 지원

오픈 & 감사 가능