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

# CometAPI와 함께 OpenCode 사용하기

> 이 가이드를 사용해 네 가지 CometAPI API 형식을 OpenCode의 사용자 지정 공급자로 구성하세요.

이 가이드를 사용해 [OpenCode](https://opencode.ai/docs/) 를 CometAPI와 함께 실행하세요.
이 구성은 별도의 사용자 지정 공급자를 통해 네 가지 API 형식을 노출합니다.

이 구성은 OpenCode 1.18.16에서 테스트되었습니다.

공식 참고 자료:

* [OpenCode 설치](https://opencode.ai/docs/#install)
* [OpenCode 구성](https://opencode.ai/docs/config/)
* [OpenCode 사용자 지정 공급자](https://opencode.ai/docs/providers/#custom-provider)
* [OpenCode 모델 선택](https://opencode.ai/docs/models/)
* [OpenCode 권한](https://opencode.ai/docs/permissions/)

<Note>
  각 `your-model-id` 값을 다음
  [CometAPI 모델 페이지](/ko/overview/models)에서 제공하는 모델 ID로 바꾸세요. 주변 공급자 항목의 API
  형식을 지원하는 모델을 선택하세요.
</Note>

## 사전 요구 사항

* Node.js와 npm 또는 OpenCode 가이드에 설명된 다른 설치 방법
* 활성 API 키가 있는 CometAPI 계정. 키 발급처:
  [대시보드](https://www.cometapi.com/console/token)
* 하나 이상의 모델 ID 출처: [CometAPI 모델 페이지](/ko/overview/models)

## 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 구성

<Steps>
  <Step title="OpenCode 설치">
    공식 npm 패키지로 OpenCode를 설치하세요:

    ```bash theme={null}
    npm install -g opencode-ai
    ```

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

    ```bash theme={null}
    opencode --version
    ```

    다음을 참조하세요 [OpenCode 설치 가이드](https://opencode.ai/docs/#install)
    에서 Homebrew, Windows, Docker 및 기타 설치 방법을 확인할 수 있습니다.
  </Step>

  <Step title="CometAPI API 키 설정">
    CometAPI API 키를 `COMETAPI_KEY` 환경 변수에 저장하세요.

    <Tabs>
      <Tab title="macOS / Linux / WSL">
        터미널에 표시하지 않고 API 키를 읽으세요:

        ```bash theme={null}
        read -rsp "CometAPI API key: " COMETAPI_KEY
        printf '\n'
        export COMETAPI_KEY
        ```
      </Tab>

      <Tab title="Windows PowerShell">
        현재 PowerShell 세션으로 API 키를 읽어 오세요:

        ```powershell theme={null}
        $secureKey = Read-Host "CometAPI API key" -AsSecureString
        $env:COMETAPI_KEY = [System.Net.NetworkCredential]::new(
          "",
          $secureKey
        ).Password
        ```
      </Tab>
    </Tabs>

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

  <Step title="구성 위치 선택">
    지원되는 다음 위치 중 하나를 사용하세요:

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

    OpenCode는 구성 파일을 병합합니다. 프로젝트 구성은 전역 구성의 충돌하는 값을
    재정의합니다.

    모든 프로젝트에서 공급자를 사용하려면 전역 파일을 사용하세요. 리포지토리에 자체 모델 항목이 필요한 경우에는
    프로젝트 파일을 사용하세요.
  </Step>

  <Step title="CometAPI 공급자 추가">
    선택한 구성 파일을 만드세요. 파일에 이미
    `provider` 객체가 포함되어 있으면 해당 객체에 다음 네 개의 항목을 병합하세요:

    ```json theme={null}
    {
      "$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 형식과 모델을 선택할 수 있습니다.

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

  <Step title="각 공급자 선택 및 확인">
    액세스하려는 프로젝트에서 OpenCode를 시작하세요:

    ```bash theme={null}
    opencode
    ```

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

    명령줄에서 채팅 완성을 확인하려면 다음을 실행하세요:

    ```bash theme={null}
    opencode run \
      --model cometapi-chat/your-model-id \
      "Reply exactly with: COMETAPI_CHAT_OK"
    ```

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

    ```bash theme={null}
    opencode run \
      --model cometapi-responses/your-model-id \
      "Reply exactly with: COMETAPI_RESPONSES_OK"
    ```

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

    ```bash theme={null}
    opencode run \
      --model cometapi-messages/your-model-id \
      "Reply exactly with: COMETAPI_MESSAGES_OK"
    ```

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

    ```bash theme={null}
    opencode run \
      --model cometapi-gemini/your-model-id \
      "Reply exactly with: COMETAPI_GEMINI_OK"
    ```
  </Step>
</Steps>

## 문제 해결

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

  <Accordion title="OpenCode에서 API 키 또는 인증 오류가 발생함">
    OpenCode를 실행하는 셸에서 환경 변수 `COMETAPI_KEY`가 설정되어 있는지 확인하세요.
    설정되지 않은 `{env:COMETAPI_KEY}` 참조는 빈 값이 됩니다. 셸 프로필을 변경한 후에는 새
    셸을 여세요.
  </Accordion>

  <Accordion title="모델 ID를 사용할 수 없음">
    다음을 확인한 다음 [CometAPI Models 페이지](/ko/overview/models)를 확인한 다음, 선택한 공급자 항목의 모델
    ID를 교체하세요. 모델이 해당
    공급자의 API 형식을 지원하는지 확인하세요.
  </Accordion>

  <Accordion title="요청에서 잘못된 경로를 사용함">
    채팅 완성, 응답 및 Messages의 경우 `baseURL`를 `/v1`로 유지하세요. Gemini에는
    `/v1beta` 를 사용하세요. `baseURL`에 작업 경로를 포함하지 마세요.
  </Accordion>

  <Accordion title="한 공급자는 작동하지만 다른 공급자는 실패함">
    선택한 공급자의 API 형식을 지원하는 모델 ID를 사용하세요. 한
    모델 ID가 네 가지 형식을 모두 지원한다고 가정하지 마세요.
  </Accordion>

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

  <Accordion title="OpenCode가 예상보다 더 많은 액세스 권한을 가짐">
    OpenCode는 이를 실행한 프로세스의 권한을 사용합니다. 더 강력한 액세스 경계가 필요하면 OpenCode를
    컨테이너 또는 샌드박스에서 실행하세요.
  </Accordion>
</AccordionGroup>

## 관련 리소스

* [CometAPI 빠른 시작](/ko/overview/quick-start)
* [CometAPI 모델 페이지](/ko/overview/models)
* [OpenCode 사용자 지정 제공자](https://opencode.ai/docs/providers/#custom-provider)
* [OpenCode 구성](https://opencode.ai/docs/config/)
* [OpenCode 모델 선택](https://opencode.ai/docs/models/)

<script type="application/ld+json">
  {`
    {
    "@context": "https://schema.org",
    "@graph": [
      {
        "@type": "HowTo",
        "@id": "https://apidoc.cometapi.com/integrations/opencode#howto",
        "name": "CometAPI와 함께 OpenCode 사용하기",
        "description": "이 가이드를 사용하여 OpenCode에서 네 가지 CometAPI API 형식을 사용자 지정 제공자로 구성하세요.",
        "step": [
          {
            "@type": "HowToStep",
            "@id": "https://apidoc.cometapi.com/integrations/opencode#step-1",
            "position": 1,
            "name": "OpenCode 설치",
            "text": "OpenCode를 설치하고 CLI를 사용할 수 있는지 확인하세요."
          },
          {
            "@type": "HowToStep",
            "@id": "https://apidoc.cometapi.com/integrations/opencode#step-2",
            "position": 2,
            "name": "CometAPI API 키 설정",
            "text": "CometAPI API 키를 COMETAPI_KEY 환경 변수에 저장하세요."
          },
          {
            "@type": "HowToStep",
            "@id": "https://apidoc.cometapi.com/integrations/opencode#step-3",
            "position": 3,
            "name": "구성 위치 선택",
            "text": "전역 OpenCode 구성 또는 프로젝트 구성을 선택하세요."
          },
          {
            "@type": "HowToStep",
            "@id": "https://apidoc.cometapi.com/integrations/opencode#step-4",
            "position": 4,
            "name": "CometAPI 제공자 추가",
            "text": "opencode.json에 네 개의 CometAPI 사용자 지정 제공자 항목을 추가하세요."
          },
          {
            "@type": "HowToStep",
            "@id": "https://apidoc.cometapi.com/integrations/opencode#step-5",
            "position": 5,
            "name": "각 제공자 선택 및 확인",
            "text": "필요한 CometAPI 제공자와 모델을 선택하고 확인하세요."
          }
        ]
      },
      {
        "@type": "BreadcrumbList",
        "itemListElement": [
          {
            "@type": "ListItem",
            "position": 1,
            "name": "CometAPI 문서",
            "item": "https://apidoc.cometapi.com/"
          },
          {
            "@type": "ListItem",
            "position": 2,
            "name": "통합",
            "item": "https://apidoc.cometapi.com/integrations"
          },
          {
            "@type": "ListItem",
            "position": 3,
            "name": "CometAPI와 함께 OpenCode 사용하기",
            "item": "https://apidoc.cometapi.com/integrations/opencode"
          }
        ]
      }
    ]
    }
    `}
</script>