Sử dụng OpenCode với CometAPI

Dùng hướng dẫn này để chạy OpenCode 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:

Thay mỗi giá trị your-model-id bằng một model ID từ trang CometAPI 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.

Đ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
Một hoặc nhiều model ID từ trang CometAPI 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

Cài đặt OpenCode

Cài đặt OpenCode bằng gói npm chính thức:

npm install -g opencode-ai

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

opencode --version

Xem hướng dẫn cài đặt OpenCode để 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.

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.

macOS / Linux / WSL
Windows PowerShell

Đọc API key mà không hiển thị trong terminal:

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

Đọc API key vào phiên PowerShell hiện tại:

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

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.

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.

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 đó:

{
  "$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.

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

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:

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:

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:

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:

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:

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

Khắc phục sự cố

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.

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.

Một ID model không khả dụng

Kiểm tra trang Models của CometAPI, 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 đó.

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.

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.

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.

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.

Tổng quan

Tác nhân lập trình AI

Tác nhân AI

Ứng dụng chat AI

Dịch thuật và ngôn ngữ

Nền tảng tự động hóa

Quan sát và đánh giá

Framework AI

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

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

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

Cấu hình OpenCode

Khắc phục sự cố

Tài nguyên liên quan

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

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

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

​Cấu hình OpenCode

​Khắc phục sự cố

​Tài nguyên liên quan

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

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

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

Cấu hình OpenCode

Khắc phục sự cố

Tài nguyên liên quan