> ## 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.

# Sử dụng OpenCode với CometAPI

> Dùng hướng dẫn này để cấu hình bốn định dạng API của CometAPI làm các nhà cung cấp tùy chỉnh trong OpenCode.

Dùng hướng dẫn này để chạy [OpenCode](https://opencode.ai/docs/) với CometAPI.
Cấu hình này cung cấp bốn định dạng API thông qua các nhà cung cấp tùy chỉnh riêng biệt.

Cấu hình này đã được kiểm thử với OpenCode 1.18.16.

Tài liệu tham khảo chính thức:

* [Cài đặt OpenCode](https://opencode.ai/docs/#install)
* [Cấu hình OpenCode](https://opencode.ai/docs/config/)
* [Nhà cung cấp tùy chỉnh của OpenCode](https://opencode.ai/docs/providers/#custom-provider)
* [Chọn model trong OpenCode](https://opencode.ai/docs/models/)
* [Quyền của OpenCode](https://opencode.ai/docs/permissions/)

<Note>
  Thay mỗi giá trị `your-model-id` bằng một model ID từ
  [trang CometAPI Models](/vi/overview/models). Chọn một model chấp nhận định dạng API
  của mục nhập nhà cung cấp bao quanh.
</Note>

## Điều kiện tiên quyết

* Node.js và npm hoặc một phương thức cài đặt khác từ hướng dẫn OpenCode
* Tài khoản CometAPI có API key đang hoạt động từ
  [bảng điều khiển](https://www.cometapi.com/console/token)
* Một hoặc nhiều model ID từ [trang CometAPI Models](/vi/overview/models)

## Tìm hiểu các định dạng API

Mỗi ID nhà cung cấp chọn một adapter SDK và một định dạng API.

| ID nhà cung cấp      | Adapter OpenCode            | URL cơ sở                         | Định dạng API          |
| -------------------- | --------------------------- | --------------------------------- | ---------------------- |
| `cometapi-chat`      | `@ai-sdk/openai-compatible` | `https://api.cometapi.com/v1`     | Chat Completions       |
| `cometapi-responses` | `@ai-sdk/openai`            | `https://api.cometapi.com/v1`     | Responses              |
| `cometapi-messages`  | `@ai-sdk/anthropic`         | `https://api.cometapi.com/v1`     | Anthropic Messages     |
| `cometapi-gemini`    | `@ai-sdk/google`            | `https://api.cometapi.com/v1beta` | Gemini generateContent |

Hướng dẫn này xác minh thao tác Streaming Gemini được sử dụng trong một lượt
agent OpenCode thông thường. Adapter Google sẽ thêm
`:streamGenerateContent?alt=sse` vào đường dẫn model.

Không thêm `/chat/completions`, `/responses`, `/messages` hoặc đường dẫn model Gemini
vào `baseURL`. Mỗi adapter sẽ thêm đường dẫn thao tác bắt buộc của nó.

## Tìm hiểu quyền khi chạy

OpenCode chạy với các quyền của tiến trình khởi chạy nó. Hãy khởi động
OpenCode trong thư mục dự án dự kiến và duy trì một phương án khôi phục như
git. Hãy dùng container hoặc sandbox khi cần các ranh giới mạnh hơn cho hệ thống tệp, tiến trình,
mạng hoặc API key.

## Cấu hình OpenCode

<Steps>
  <Step title="Cài đặt OpenCode">
    Cài đặt OpenCode bằng gói npm chính thức:

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

    Xác nhận rằng CLI khả dụng:

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

    Xem [hướng dẫn cài đặt OpenCode](https://opencode.ai/docs/#install)
    để biết các phương thức cài đặt bằng Homebrew, Windows, Docker và những phương thức khác.
  </Step>

  <Step title="Thiết lập API key CometAPI của bạn">
    Lưu trữ API key CometAPI của bạn trong biến môi trường `COMETAPI_KEY`.

    <Tabs>
      <Tab title="macOS / Linux / WSL">
        Đọc API key mà không hiển thị trong terminal:

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

      <Tab title="Windows PowerShell">
        Đọc API key vào phiên PowerShell hiện tại:

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

    Thiết lập biến trong mọi phiên shell khởi chạy OpenCode. Không
    commit API key vào hệ thống kiểm soát phiên bản.
  </Step>

  <Step title="Chọn vị trí cấu hình">
    Sử dụng một trong các vị trí được hỗ trợ sau:

    * Cấu hình toàn cục: `~/.config/opencode/opencode.json`
    * Cấu hình dự án: `opencode.json` tại thư mục gốc của dự án

    OpenCode hợp nhất các tệp cấu hình. Cấu hình dự án sẽ ghi đè
    các giá trị xung đột từ cấu hình toàn cục.

    Dùng tệp toàn cục khi bạn muốn các provider xuất hiện trong mọi dự án. Dùng tệp
    dự án khi một repository cần các mục mô hình riêng.
  </Step>

  <Step title="Thêm các provider CometAPI">
    Tạo tệp cấu hình đã chọn. Nếu tệp đã chứa một
    `provider` đối tượng, hãy hợp nhất bốn mục này vào đối tượng đó:

    ```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"
            }
          }
        }
      }
    }
    ```

    Thay thế độc lập từng khóa `your-model-id`. Bốn mục có thể dùng
    các model ID khác nhau.

    Cấu hình không thiết lập `model` cấp cao nhất. Điều này cho phép bạn chọn
    định dạng API và mô hình cần thiết thông qua `/models`.

    <Warning>
      Không dùng `/connect` cho cấu hình này. Các trường `apiKey` đọc
      `COMETAPI_KEY` từ môi trường. Một biến chưa được thiết lập sẽ được phân giải thành một
      giá trị rỗng thay vì API key `/connect` đã lưu trữ.
    </Warning>
  </Step>

  <Step title="Chọn và xác minh từng provider">
    Khởi động OpenCode trong dự án mà bạn muốn nó truy cập:

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

    Chạy `/models`, sau đó chọn một mục `provider/model`. Trong bốn lần xác minh
    trong hướng dẫn này, mỗi lượt mô hình đều sử dụng định dạng API tương ứng với mục đã chọn.
    Không quan sát thấy việc phân tán yêu cầu đa định dạng hoặc tự động thương lượng định dạng API
    nào.

    Để xác minh Chat Completions từ dòng lệnh, hãy chạy:

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

    Để xác minh Responses từ dòng lệnh, hãy chạy:

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

    Để xác minh Anthropic Messages từ dòng lệnh, hãy chạy:

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

    Để xác minh Gemini generateContent từ dòng lệnh, hãy chạy:

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

## Khắc phục sự cố

<AccordionGroup>
  <Accordion title="OpenCode không hiển thị model CometAPI">
    Xác nhận rằng cấu hình là JSON hợp lệ. Mỗi mục tùy chỉnh phải nằm
    bên trong đối tượng `provider` cấp cao nhất, và mỗi ID model phải nằm bên trong
    đối tượng `models` tương ứng. Khởi động lại OpenCode, rồi mở lại `/models`.
  </Accordion>

  <Accordion title="OpenCode báo lỗi API key hoặc xác thực">
    Xác nhận rằng `COMETAPI_KEY` được đặt trong shell khởi chạy OpenCode.
    Tham chiếu `{env:COMETAPI_KEY}` chưa được đặt sẽ trở thành một giá trị rỗng. Mở một
    shell mới sau khi thay đổi hồ sơ shell.
  </Accordion>

  <Accordion title="Một ID model không khả dụng">
    Kiểm tra [trang Models của CometAPI](/vi/overview/models), rồi thay thế model
    ID trong mục provider đã chọn. Xác nhận rằng model chấp nhận định dạng API của provider đó.
    provider đó.
  </Accordion>

  <Accordion title="Các request sử dụng đường dẫn không chính xác">
    Giữ `baseURL` là `/v1` cho Chat Completions, Responses và Messages. Sử dụng
    `/v1beta` cho Gemini. Không đưa đường dẫn thao tác vào `baseURL`.
  </Accordion>

  <Accordion title="Một provider hoạt động nhưng provider khác gặp lỗi">
    Sử dụng ID model chấp nhận định dạng API của provider đã chọn. Đừng
    cho rằng một ID model chấp nhận cả bốn định dạng.
  </Accordion>

  <Accordion title="Cấu hình dự án thay đổi một provider toàn cục">
    OpenCode hợp nhất cấu hình toàn cục và cấu hình dự án. Đổi tên provider của dự án
    ID hoặc xóa các giá trị xung đột khi bạn muốn mục provider toàn cục
    không thay đổi.
  </Accordion>

  <Accordion title="OpenCode có nhiều quyền truy cập hơn dự kiến">
    OpenCode sử dụng quyền của tiến trình đã khởi chạy nó. Chạy OpenCode
    trong container hoặc sandbox khi bạn cần ranh giới truy cập chặt chẽ hơn.
  </Accordion>
</AccordionGroup>

## Tài nguyên liên quan

* [Hướng dẫn bắt đầu nhanh CometAPI](/vi/overview/quick-start)
* [Trang Models của CometAPI](/vi/overview/models)
* [Các provider tùy chỉnh của OpenCode](https://opencode.ai/docs/providers/#custom-provider)
* [Cấu hình OpenCode](https://opencode.ai/docs/config/)
* [Lựa chọn model trong 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": "Sử dụng OpenCode với CometAPI",
        "description": "Sử dụng hướng dẫn này để cấu hình bốn định dạng API của CometAPI dưới dạng các provider tùy chỉnh trong OpenCode.",
        "step": [
          {
            "@type": "HowToStep",
            "@id": "https://apidoc.cometapi.com/integrations/opencode#step-1",
            "position": 1,
            "name": "Cài đặt OpenCode",
            "text": "Cài đặt OpenCode và xác nhận rằng CLI khả dụng."
          },
          {
            "@type": "HowToStep",
            "@id": "https://apidoc.cometapi.com/integrations/opencode#step-2",
            "position": 2,
            "name": "Đặt khóa API CometAPI của bạn",
            "text": "Lưu khóa API CometAPI trong biến môi trường COMETAPI_KEY."
          },
          {
            "@type": "HowToStep",
            "@id": "https://apidoc.cometapi.com/integrations/opencode#step-3",
            "position": 3,
            "name": "Chọn vị trí cấu hình",
            "text": "Chọn cấu hình OpenCode toàn cục hoặc cấu hình dự án."
          },
          {
            "@type": "HowToStep",
            "@id": "https://apidoc.cometapi.com/integrations/opencode#step-4",
            "position": 4,
            "name": "Thêm các provider CometAPI",
            "text": "Thêm bốn mục provider tùy chỉnh của CometAPI vào opencode.json."
          },
          {
            "@type": "HowToStep",
            "@id": "https://apidoc.cometapi.com/integrations/opencode#step-5",
            "position": 5,
            "name": "Chọn và xác minh từng provider",
            "text": "Chọn và xác minh provider cùng model CometAPI cần thiết."
          }
        ]
      },
      {
        "@type": "BreadcrumbList",
        "itemListElement": [
          {
            "@type": "ListItem",
            "position": 1,
            "name": "Tài liệu CometAPI",
            "item": "https://apidoc.cometapi.com/"
          },
          {
            "@type": "ListItem",
            "position": 2,
            "name": "Tích hợp",
            "item": "https://apidoc.cometapi.com/integrations"
          },
          {
            "@type": "ListItem",
            "position": 3,
            "name": "Sử dụng OpenCode với CometAPI",
            "item": "https://apidoc.cometapi.com/integrations/opencode"
          }
        ]
      }
    ]
    }
    `}
</script>