> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gravitex.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenCode

> OpenCode 연동 가이드: GravitexAI를 통해 75개 이상의 모델을 한곳에서 사용

## 1. 개요

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

<CardGroup cols={2}>
  <Card title="통합 멀티 모델" icon="layer-group">
    하나의 provider로 GPT / Claude / Gemini / Qwen 전체 제품군
  </Card>

  <Card title="셀프 호스트 친화적" icon="house">
    자체 백엔드 및 프로젝트별 설정 오버라이드 지원
  </Card>

  <Card title="Responses API 지원" icon="bolt">
    GPT Codex 시리즈와 `apiCompatibility: "responses"` 호환
  </Card>

  <Card title="오픈 & 감사 가능" icon="github">
    완전 오픈소스, 필요에 따라 커스터마이즈
  </Card>
</CardGroup>

**다운로드**: [https://opencode.ai/](https://opencode.ai/)

## 2. 빠른 설정 (GravitexAI)

### 2.1 API 키 발급

<Steps>
  <Step title="로그인">
    [GravitexAI 콘솔](https://maas.gravitex.ai)에서 회원가입 또는 로그인합니다.
  </Step>

  <Step title="토큰 생성">
    [API Keys](https://maas.gravitex.ai/#/keys)를 열고 "Create new token"을 클릭한 뒤 `sk-xxxxxxxxxx` 키를 복사합니다.
  </Step>
</Steps>

### 2.2 OpenCode에서 커스텀 provider 설정

<Steps>
  <Step title="Provider 설정 열기">
    OpenCode에서 **Server / Provider** 설정으로 이동하고 **Add custom provider**(OpenAI 호환)를 선택합니다.
  </Step>

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

  <Step title="모델 추가">
    **Models** 아래에 사용할 모델 ID를 추가합니다 (예: `gpt-5.5`, `claude-sonnet-4-6`, `gemini-3.5-flash`). ID는 [GravitexAI 모델 목록](https://maas.gravitex.ai/#/models)과 일치해야 합니다.
  </Step>

  <Step title="저장 및 사용">
    저장 후 채팅 및 설정에서 **`providerID/modelID`** 형식으로 선택합니다 (예: `gravitex/gpt-5.5`).
  </Step>
</Steps>

<img src="https://mintcdn.com/gravitexai/9di8VRqu8D1f5M93/images/open-code1.png?fit=max&auto=format&n=9di8VRqu8D1f5M93&q=85&s=58684b86ac98c126d9120754a130347f" alt="OpenCode custom provider setup" width="1920" height="1140" data-path="images/open-code1.png" />

<img src="https://mintcdn.com/gravitexai/9di8VRqu8D1f5M93/images/open-code2.png?fit=max&auto=format&n=9di8VRqu8D1f5M93&q=85&s=723042c873497ae0187189a37a8f4761" alt="OpenCode provider and API config" width="795" height="526" data-path="images/open-code2.png" />

<img src="https://mintcdn.com/gravitexai/9di8VRqu8D1f5M93/images/open-code3.png?fit=max&auto=format&n=9di8VRqu8D1f5M93&q=85&s=847981a9c861e6ee7a8117b8a5735503" alt="OpenCode model config" width="784" height="379" data-path="images/open-code3.png" />

### 2.3 모델 전환

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

<img src="https://mintcdn.com/gravitexai/9di8VRqu8D1f5M93/images/open-code4.png?fit=max&auto=format&n=9di8VRqu8D1f5M93&q=85&s=4df30df18c54c4e8ad70838be2895d55" alt="OpenCode switch model" width="1920" height="1140" data-path="images/open-code4.png" />

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

## 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에서 이 오류가 표시되는 모습입니다:

<img src="https://mintcdn.com/gravitexai/9di8VRqu8D1f5M93/images/open-code8.png?fit=max&auto=format&n=9di8VRqu8D1f5M93&q=85&s=fd180e21a6768b154ee4294cc197e230" alt="Error when using gpt-5.1-codex with Chat Completions" width="829" height="269" data-path="images/open-code8.png" />

### 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 / 벤더 문서**를 참조하세요:

* [Azure OpenAI Responses API](https://learn.microsoft.com/en-us/azure/ai-foundry/openai/how-to/responses)
* [Which models work with each operation](https://go.microsoft.com/fwlink/?linkid=2197993)

### 3.2 OpenCode에서 설정하는 방법

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

<Steps>
  <Step title="설정 파일 위치">
    * **Windows**: `C:\Users\<username>\.config\opencode\opencode.jsonc`
    * **macOS / Linux**: `~/.config/opencode/opencode.jsonc`

    <img src="https://mintcdn.com/gravitexai/9di8VRqu8D1f5M93/images/open-code5.png?fit=max&auto=format&n=9di8VRqu8D1f5M93&q=85&s=01584ee47c3224031512635d71eebb92" alt="Responses API requirement for some models" width="929" height="375" data-path="images/open-code5.png" />
  </Step>

  <Step title="매개변수 추가">
    기존 커스텀 provider(GravitexAI 또는 자체 API를 가리키는)에서 필요한 모델(예: `gpt-5.1-codex`)에 \*\*`"apiCompatibility": "responses"`\*\*를 추가합니다:

    <img src="https://mintcdn.com/gravitexai/9di8VRqu8D1f5M93/images/open-code6.png?fit=max&auto=format&n=9di8VRqu8D1f5M93&q=85&s=10f5fd588261bb1683fdd87cb38d5729" alt="opencode.jsonc: apiCompatibility responses for gpt-5.1-codex" width="1920" height="1109" data-path="images/open-code6.png" />

    ```jsonc theme={null}
    {
      "$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에 요청이 전송됩니다.
  </Step>

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

    <img src="https://mintcdn.com/gravitexai/9di8VRqu8D1f5M93/images/open-code7.png?fit=max&auto=format&n=9di8VRqu8D1f5M93&q=85&s=e6c28ca55abb6264a1f8ad008cfef6e6" alt="OpenCode chat after successful config" width="1920" height="1140" data-path="images/open-code7.png" />
  </Step>
</Steps>

### 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 모델 목록](https://maas.gravitex.ai/#/models)을 참조하세요.

### 성공 예시

GravitexAI를 사용한 OpenCode 일반 채팅:

<img src="https://mintcdn.com/gravitexai/9di8VRqu8D1f5M93/images/open-code7.png?fit=max&auto=format&n=9di8VRqu8D1f5M93&q=85&s=e6c28ca55abb6264a1f8ad008cfef6e6" alt="OpenCode success with GravitexAI" width="1920" height="1140" data-path="images/open-code7.png" />

## 5. FAQ

<AccordionGroup>
  <Accordion title="`The chatCompletion operation does not work…` 오류">
    해당 모델은 Responses API만 지원합니다. `opencode.jsonc`에 `"apiCompatibility": "responses"`를 추가하세요 — 3절을 참조하세요.
  </Accordion>

  <Accordion title="401 / invalid API key">
    1. 키가 완전하고 끝에 공백이 없는지 확인하세요.
    2. [GravitexAI 콘솔](https://maas.gravitex.ai/#/keys)에서 삭제/비활성화되지 않았는지 확인하세요.
    3. 잔액이 양수인지 확인하세요.
  </Accordion>

  <Accordion title="404 / endpoint not found">
    Base URL이 `/v1`로 끝나는지 확인하세요: `https://api.gravitex.ai/v1`.
  </Accordion>

  <Accordion title="유효해 보이는 ID에 `model not found`">
    모델 ID는 [GravitexAI 목록](https://maas.gravitex.ai/#/models)과 정확히 일치해야 합니다. 대소문자와 버전 접미사에 주의하세요 (예: `claude-sonnet-4-5-20250929`, `claude-sonnet-4-5` 아님).
  </Accordion>

  <Accordion title="팀 전체 표준화 방법?">
    `opencode.jsonc`를 저장소의 `.config/opencode/`(또는 프로젝트 루트)에 커밋하세요. 각 엔지니어는 자신의 API 키만 사용합니다.
  </Accordion>
</AccordionGroup>

## 6. 참고 자료

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