Thiết lập nhà cung cấp tương thích OpenAI cho OpenCode rất hữu ích khi bạn muốn OpenCode giao tiếp với một tuyến mô hình hoạt động giống như API Chat Completions của OpenAI, trong khi nhóm của bạn giữ quyền sở hữu khóa, định tuyến mô hình và xem xét việc sử dụng trong một cổng duy nhất.
Phần quan trọng là OpenCode có một đường dẫn nhà cung cấp tùy chỉnh được tài liệu hóa. Trong tài liệu nhà cung cấp của OpenCode được kiểm tra vào ngày 8 tháng 7 năm 2026, quy trình là: thêm thông tin xác thực bằng /connect, chọn Other cho một nhà cung cấp chưa được liệt kê, đặt cho nhà cung cấp đó một ID dễ nhớ, cấu hình nhà cung cấp trong opencode.json, sau đó chạy /models để chọn từ các mô hình đã được cấu hình.
Flatkey phù hợp với mô hình đó với vai trò là cổng kết nối phía sau nhà cung cấp. Bạn giữ OpenCode làm tác nhân mã hóa, trỏ nhà cung cấp đến URL cơ sở API tương thích OpenAI của Flatkey và xác minh rằng lưu lượng mô hình OpenCode xuất hiện trong nhật ký sử dụng hoặc yêu cầu của Flatkey trước khi bạn đặt nó làm tuyến mặc định.
Câu trả lời nhanh cho việc thiết lập nhà cung cấp tương thích OpenAI cho OpenCode
Sử dụng hình thức thiết lập này khi điểm cuối của mô hình tương thích với Chat Completions.
| Quyết định | Giá trị đề xuất | Tại sao lại quan trọng |
|---|---|---|
| ID nhà cung cấp | flatkey |
ID phải khớp giữa /connect, opencode.json, và các mô hình đã chọn. |
| Gói NPM | @ai-sdk/openai-compatible |
Tài liệu của OpenCode chỉ định gói này cho các nhà cung cấp tương thích OpenAI sử dụng /v1/chat/completions. |
| URL cơ sở API của OpenCode | https://router.flatkey.ai/v1 |
Trang web công khai của Flatkey hướng các máy khách tương thích OpenAI đến gốc API này. |
| ID mô hình | Các bí danh mô hình Flatkey hiện có sẵn cho khóa của bạn | OpenCode sử dụng các ID mô hình đã được cấu hình trong bộ chọn /models. |
| Xác minh | Phản hồi của OpenCode cộng với nhật ký yêu cầu hoặc sử dụng của Flatkey | Điều này chứng tỏ yêu cầu của tác nhân mã hóa đã sử dụng tuyến cổng kết nối dự định. |
| Khôi phục | Giữ lại giá trị model trước đó và cấu hình nhà cung cấp cũ |
Việc thay đổi nhà cung cấp nên có thể đảo ngược mà không cần tái cấu trúc các câu lệnh hoặc quy trình làm việc của tác nhân. |
Hướng dẫn về nhà cung cấp tương thích OpenAI cho OpenCode này sử dụng các mẫu. Hãy xác thực các bí danh mô hình và họ điểm cuối chính xác với tài khoản Flatkey của bạn trước khi định tuyến công việc của tác nhân mã hóa trong môi trường sản xuất.
OpenCode yêu cầu những gì
OpenCode có hai phần trạng thái riêng biệt cho một nhà cung cấp tùy chỉnh.
| Lớp OpenCode | Những gì bạn cấu hình | Hành vi nguồn cần tuân thủ |
|---|---|---|
| Thông tin xác thực | Khóa API được nhập qua /connect dưới mục Other |
ID nhà cung cấp bạn nhập ở đây phải khớp với ID nhà cung cấp trong cấu hình. |
| Cấu hình nhà cung cấp | provider.<id> trong opencode.json |
Cấu hình đặt tên cho gói AI SDK, URL cơ sở, các mô hình và các tiêu đề tùy chọn hoặc tham chiếu khóa API. |
| Lựa chọn mô hình | Bộ chọn /models hoặc giá trị model mặc định |
Các mô hình của nhà cung cấp đã được cấu hình sẽ xuất hiện sau khi nhà cung cấp được cấu hình. |
| Mặc định khi chạy | model và small_model tùy chọn |
Cấu hình OpenCode hỗ trợ các mặc định nhà cung cấp/mô hình cho các tác vụ thông thường và nhẹ. |
Cấu hình OpenCode có thể là JSON hoặc JSONC. Bạn có thể đặt nó toàn cục tại ~/.config/opencode/opencode.json, hoặc trong thư mục gốc của dự án với tên opencode.json. Cấu hình dự án có độ ưu tiên tiêu chuẩn cao hơn, vì vậy hãy sử dụng tệp dự án khi bạn muốn một kho lưu trữ thử nghiệm Flatkey mà không thay đổi mọi không gian làm việc của OpenCode.
Bước 1: Tạo khóa Flatkey cho OpenCode
Tạo một khóa Flatkey cho khối lượng công việc này và ghi lại ba giá trị bên ngoài hệ thống kiểm soát phiên bản.
FLATKEY_API_KEY=sk-fk-your-key
FLATKEY_BASE_URL=https://router.flatkey.ai/v1
FLATKEY_MODEL=your-current-flatkey-model-alias
Giữ gốc API tách biệt với đường dẫn điểm cuối. Cấu hình nhà cung cấp OpenCode nên sử dụng https://router.flatkey.ai/v1 làm options.baseURL; các kiểm tra sơ bộ HTTP trực tiếp sẽ thêm /chat/completions.
Trước khi kết nối OpenCode, hãy chạy một thử nghiệm trực tiếp với cùng một khóa Flatkey và bí danh mô hình.
curl "$FLATKEY_BASE_URL/chat/completions" \
-H "Authorization: Bearer $FLATKEY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "'"$FLATKEY_MODEL"'",
"messages": [
{ "role": "user", "content": "Reply with exactly: flatkey route ok" }
]
}'
Nếu yêu cầu trực tiếp này không thành công, hãy sửa khóa Flatkey, bí danh mô hình, họ điểm cuối hoặc tuyến tài khoản trước khi gỡ lỗi OpenCode. Một nhà cung cấp tương thích OpenAI cho OpenCode không thể bù đắp cho một bí danh mô hình mà tài khoản cổng kết nối không thể gọi.
Bước 2: Thêm thông tin xác thực Flatkey trong OpenCode
OpenCode lưu trữ thông tin xác thực của nhà cung cấp thông qua /connect. Trong TUI của OpenCode:
/connect
Chọn Other, nhập ID nhà cung cấp chẳng hạn như flatkey, sau đó dán khóa API Flatkey. Không dán URL cơ sở vào lời nhắc thông tin xác thực. Khóa chứng minh danh tính; URL cơ sở thuộc về opencode.json.
Sử dụng một ID nhà cung cấp đơn giản. flatkey tốt hơn flatkey-prod-openai-compatible-gateway-v2 vì bạn sẽ gõ nó trong ID mô hình và ghi chú khôi phục.
Bước 3: Thêm cấu hình nhà cung cấp OpenCode
Tạo hoặc cập nhật opencode.json trong thư mục gốc của dự án bạn muốn kiểm tra.
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"flatkey": {
"npm": "@ai-sdk/openai-compatible",
"name": "Flatkey",
"options": {
"baseURL": "https://router.flatkey.ai/v1"
},
"models": {
"your-current-flatkey-model-alias": {
"name": "Flatkey primary model"
}
}
}
},
"model": "flatkey/your-current-flatkey-model-alias"
}
Đây là cấu hình nhà cung cấp tương thích OpenAI cho OpenCode nhỏ nhất. Nó cung cấp cho OpenCode một nhà cung cấp tên là flatkey, yêu cầu OpenCode sử dụng gói AI SDK tương thích OpenAI, và hiển thị một bí danh mô hình trong bộ chọn mô hình.
Nếu bạn muốn OpenCode sử dụng một định tuyến nhỏ hơn cho các tác vụ nhẹ, hãy thêm small_model chỉ sau khi định tuyến chính hoạt động.
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"flatkey": {
"npm": "@ai-sdk/openai-compatible",
"name": "Flatkey",
"options": {
"baseURL": "https://router.flatkey.ai/v1"
},
"models": {
"primary-flatkey-model-alias": {
"name": "Flatkey primary"
},
"lighter-flatkey-model-alias": {
"name": "Flatkey lightweight"
}
}
}
},
"model": "flatkey/primary-flatkey-model-alias",
"small_model": "flatkey/lighter-flatkey-model-alias"
}
Sử dụng các bí danh mô hình mà khóa Flatkey của bạn thực sự có thể gọi. Nếu tài khoản của bạn có một định tuyến /v1/models đã được xác thực, hãy so sánh các ID mô hình đã cấu hình với phản hồi đó. Nếu không, hãy sao chép các bí danh từ bảng điều khiển Flatkey hiện tại hoặc thư mục mô hình và xác minh chúng bằng một yêu cầu thực tế.
Bước 4: Chọn và kiểm tra mô hình trong OpenCode
Sau khi lưu cấu hình, hãy mở bộ chọn mô hình.
/models
Chọn mô hình của nhà cung cấp Flatkey. Sau đó chạy một câu lệnh nhỏ trong OpenCode:
Reply with exactly: opencode flatkey route ok
Đừng vội chuyển toàn bộ quy trình làm việc mã hóa. Trước tiên, hãy lưu một gói xác minh nhỏ gọn.
| Kiểm tra | Điều kiện đạt | Bằng chứng cần giữ lại |
|---|---|---|
| Nhà cung cấp xuất hiện | /models hiển thị mô hình Flatkey đã cấu hình |
Ảnh chụp màn hình hoặc ghi chú terminal với ID mô hình đã chọn. |
| Xác thực hoạt động | OpenCode nhận được phản hồi mô hình bình thường, không phải 401 hay 403 |
Chủ sở hữu khóa đã được che, thời gian phản hồi và dấu thời gian yêu cầu. |
| URL cơ sở sạch sẽ | Không có /v1/v1 trùng lặp, không thiếu hành vi /chat/completions |
options.baseURL cuối cùng và điểm cuối curl trực tiếp. |
| Flatkey nhìn thấy nó | Yêu cầu xuất hiện trong nhật ký sử dụng hoặc nhật ký yêu cầu của Flatkey | Dấu thời gian yêu cầu, bí danh mô hình, các trường token hoặc đơn vị, nhãn khóa/khối lượng công việc. |
| Có thể khôi phục | Bạn có thể quay lại nhà cung cấp/mô hình trước đó chỉ bằng một lần chỉnh sửa cấu hình | model trước đó, ID nhà cung cấp trước đó và chủ sở hữu khóa trước đó. |
Điều này biến việc di chuyển nhà cung cấp tương thích OpenAI cho OpenCode thành một thay đổi vận hành nhỏ thay vì một sự hoán đổi nhà cung cấp một cách mù quáng.
Bước 5: Giữ riêng biệt Chat Completions và Responses
Tài liệu về nhà cung cấp tùy chỉnh của OpenCode chỉ ra một ranh giới gói: sử dụng @ai-sdk/openai-compatible cho các nhà cung cấp tương thích OpenAI sử dụng /v1/chat/completions; nếu một nhà cung cấp hoặc mô hình sử dụng /v1/responses, hãy sử dụng @ai-sdk/openai.
Điều đó có nghĩa là định tuyến Flatkey đầu tiên nên là một mô hình kiểu Chat Completions trừ khi bạn có bằng chứng hiện tại cho thấy mô hình và đường dẫn máy khách bạn đã chọn sử dụng một họ điểm cuối khác.
Sử dụng bảng quyết định này trước khi thêm các mô hình khác.
| Định tuyến mô hình | Hướng dẫn gói OpenCode | Cần kiểm tra gì |
|---|---|---|
| Tương thích Chat Completions | @ai-sdk/openai-compatible |
Trò chuyện đơn giản, streaming, hành vi gọi công cụ nếu cần. |
| Định tuyến kiểu Responses | @ai-sdk/openai theo tài liệu OpenCode |
Tạo phản hồi, xử lý công cụ và phân tích cú pháp đầu ra. |
| Các định tuyến hỗn hợp dưới một nhà cung cấp | Ghi đè gói cho từng mô hình nếu cấu hình của bạn sử dụng nó | Từng mô hình một, với nhật ký riêng biệt. |
Đối với hầu hết công việc thiết lập, hãy bắt đầu với một định tuyến Chat Completions. Thêm streaming, gọi công cụ và các bí danh mô hình phụ sau khi kiểm tra sơ bộ (smoke test) đầu tiên của nhà cung cấp tương thích OpenAI cho OpenCode hiển thị trong Flatkey.
Bước 6: Thêm các kiểm soát nhóm sau khi định tuyến hoạt động
Khi OpenCode có thể gọi Flatkey, hãy làm cho định tuyến có thể quan sát được.
| Kiểm soát | Lý do hữu ích |
|---|---|
| Đặt tên khóa | Gắn nhãn khóa cho OpenCode, môi trường, nhóm hoặc kho lưu trữ. |
| Phê duyệt mô hình | Giới hạn cấu hình đầu tiên cho các bí danh đã được phê duyệt trước khi thêm lựa chọn mô hình rộng rãi. |
| Xem xét việc sử dụng | Kiểm tra nhật ký yêu cầu hoặc sử dụng của Flatkey theo dấu thời gian sau mỗi lần kiểm tra OpenCode. |
| Xem xét chi phí | Đối chiếu việc sử dụng mô hình, token và khóa với người sở hữu ngân sách. |
| Chính sách thời gian chờ | Chỉ sử dụng các tùy chọn nhà cung cấp OpenCode sau khi bạn biết tuyến đường cơ sở hoạt động. |
| Ghi chú khôi phục | Lưu các giá trị nhà cung cấp và mô hình trước đó trước khi đặt Flatkey làm mặc định. |
Đây là lúc Flatkey trở nên không chỉ là một URL cơ sở. Một nhà cung cấp tương thích OpenAI cho OpenCode hoạt động hiệu quả cũng nên cung cấp cho các nhóm nền tảng, tài chính và vận hành một nơi để xem xét việc sử dụng mô hình và thay đổi tuyến đường mà không cần yêu cầu mỗi nhà phát triển phải quản lý các tài khoản nhà cung cấp riêng biệt.
Để lập kế hoạch di chuyển rộng hơn, hãy kết hợp hướng dẫn này với hướng dẫn di chuyển API tương thích OpenAI của Flatkey. Nếu bạn đang so sánh các công cụ mã hóa liền kề, hãy xem hướng dẫn nhà cung cấp tương thích OpenAI cho Continue.dev và hướng dẫn thiết lập tương thích OpenAI cho Roo Code.
Xử lý sự cố nhà cung cấp tương thích OpenAI cho OpenCode
| Triệu chứng | Nguyên nhân có thể | Cần kiểm tra gì |
|---|---|---|
Nhà cung cấp không xuất hiện trong /models |
ID nhà cung cấp không khớp hoặc cấu hình không được tải | Xác nhận ID /connect và khóa provider đều là flatkey; xác nhận tệp cấu hình nằm trong thư mục gốc của dự án hoặc đường dẫn cấu hình toàn cục mà bạn mong đợi. |
401 hoặc 403 |
Thiếu, bị thu hồi hoặc sai khóa Flatkey | Nhập lại thông tin xác thực bằng /connect; không bao giờ in toàn bộ khóa trong nhật ký. |
404 |
Sai gốc API hoặc họ điểm cuối | options.baseURL phải là gốc API, không phải là một URL /chat/completions đầy đủ. |
| Không tìm thấy mô hình | Bí danh không có sẵn cho khóa hoặc họ điểm cuối | Xác minh bí danh mô hình trong Flatkey và kiểm tra một yêu cầu trực tiếp. |
| Truyền dữ liệu bị treo | Sự cố về khả năng định tuyến, hỗ trợ mô hình hoặc thời gian chờ của chunk | Chứng minh trò chuyện không truyền dữ liệu hoạt động trước, sau đó chỉ điều chỉnh chunkTimeout của OpenCode nếu cần. |
| Thiếu thông tin sử dụng trong Flatkey | Yêu cầu không đi qua Flatkey hoặc nhật ký đã bị lọc | Tìm kiếm theo dấu thời gian, nhãn khóa, bí danh mô hình và môi trường. |
| Các tính năng phản hồi không thành công | Sai gói cho họ điểm cuối | Kiểm tra lại xem tuyến đường đã chọn sử dụng /v1/chat/completions hay /v1/responses. |
Nếu yêu cầu đầu tiên không thành công, đừng vội thay đổi lời nhắc, tác nhân, quyền hoặc mã kho lưu trữ. Giữ cho phạm vi gỡ lỗi của nhà cung cấp tương thích OpenAI cho OpenCode ở mức nhỏ: thông tin xác thực, ID nhà cung cấp, URL cơ sở, gói, bí danh mô hình và một yêu cầu trò chuyện đơn giản.
Danh sách kiểm tra cuối cùng
Trước khi sử dụng Flatkey làm tuyến đường OpenCode mặc định, hãy xác nhận:
/connectcó thông tin xác thực Flatkey dưới cùng một ID nhà cung cấp được sử dụng trongopencode.json.provider.flatkey.npmlà@ai-sdk/openai-compatiblecho tuyến đường Chat Completions.provider.flatkey.options.baseURLlàhttps://router.flatkey.ai/v1.modeltrỏ đến một giá trịflatkey/<model-alias>đã được cấu hình./modelshiển thị mô hình Flatkey đã được cấu hình.- Một lời nhắc OpenCode một dòng trả về thành công.
- Nhật ký sử dụng hoặc yêu cầu của Flatkey hiển thị yêu cầu kiểm tra OpenCode.
- Tuyến đường nhà cung cấp/mô hình trước đó được ghi lại để khôi phục.
Việc thiết lập nhà cung cấp tương thích OpenAI cho OpenCode hoàn tất khi nhà cung cấp được cấu hình, có thể lựa chọn, được xác minh trong nhật ký Flatkey và có thể đảo ngược. Khi bạn đã sẵn sàng định tuyến lưu lượng mô hình coding-agent qua một khóa duy nhất, hãy lấy khóa Flatkey và bắt đầu với một lời nhắc OpenCode đơn giản, ít rủi ro.
