Nếu bạn vẫn duy trì các bản cài đặt Roo Code, con đường Roo Code OpenAI compatible API chủ yếu là một bề mặt cấu hình: loại nhà cung cấp, Base URL, API key và Model ID. Rủi ro khi triển khai là phần rất dễ bị bỏ sót. Tài liệu nhà cung cấp của Roo Code yêu cầu gọi công cụ theo kiểu nguyên bản của OpenAI cho đường dẫn này, vì vậy một phản hồi chat thuần túy là chưa đủ để chứng minh cho quy trình làm việc của một coding agent.
Hướng dẫn này cho thấy cách định tuyến các cấu hình Roo Code hiện có qua Flatkey dành cho nhà phát triển, nhóm sản phẩm AI, người xây dựng tự động hóa, kỹ sư nền tảng, người vận hành tài chính và người rà soát mua sắm. Nội dung bao gồm lưu ý hiện tại của Roo Code, xác thực Base URL của Flatkey, các bí danh model chính xác, kiểm tra trước native tool-call, cài đặt Roo Code, rà soát mức sử dụng và rollback.
Lưu ý nguồn: nội dung này đã được kiểm tra vào ngày 29 tháng 6 năm 2026 đối chiếu với trang chủ tài liệu Roo Code chính thức, tài liệu nhà cung cấp Roo Code OpenAI Compatible chính thức, các trang công khai trực tiếp của Flatkey, và một bài kiểm tra khởi động nhanh gateway Flatkey đã xác thực. Trang chủ tài liệu của Roo Code cho biết tiện ích mở rộng Roo Code đã bị ngừng vào ngày 15 tháng 5 năm 2026, vì vậy hãy xem đây là hướng dẫn thiết lập cho các bản cài đặt hiện có, cấu hình đã lưu trữ, hoặc rà soát di chuyển, thay vì một khuyến nghị chuẩn hóa cho một lần triển khai mới mà không kiểm tra tình trạng sẵn có của tiện ích mở rộng.
Trả lời nhanh: thiết lập Roo Code OpenAI compatible API
Với thiết lập Roo Code OpenAI compatible API cùng Flatkey, hãy chọn OpenAI Compatible làm API provider, dán Base URL hiện tại của Flatkey, dùng Flatkey API key, và nhập chính xác một Flatkey model alias hỗ trợ chat tương thích OpenAI và native tool calling. Sau đó hãy chứng minh tuyến này bằng một yêu cầu curl nhỏ trước khi tin cậy nó trong không gian làm việc code.
| Trường Roo Code | Giá trị Flatkey | Kiểm tra rà soát |
|---|---|---|
| API Provider | OpenAI Compatible | Dùng nhà cung cấp này cho Flatkey, không phải nhà cung cấp OpenAI chính thức. |
| Base URL | Base URL nhà cung cấp Flatkey hiện tại cho tài khoản của bạn, chẳng hạn https://router.flatkey.ai/v1 khi đó là giá trị đã được xác minh |
Chỉ dán Base URL. Không dán toàn bộ endpoint /chat/completions vào Roo Code. |
| API Key | Một khóa Flatkey thuộc về đúng người dùng, nhóm hoặc môi trường | Không trộn lẫn khóa của nhà cung cấp upstream với Base URL của Flatkey. |
| Model ID | Flatkey model alias chính xác đã được bật cho khóa đó | Xác nhận alias hỗ trợ endpoint chat của OpenAI và native tool calls trước khi dùng cho tác vụ lập trình. |
| Validation | Kiểm tra nhanh bằng chat nhỏ và tool-call, sau đó một prompt an toàn của Roo Code | Kiểm tra mức sử dụng Flatkey sau bài test để bộ phận tài chính và chủ sở hữu nền tảng có thể đối soát tuyến này. |
Con đường an toàn ngắn nhất là: chứng minh đường truyền Flatkey, chứng minh model alias, chứng minh native tool calling, rồi lưu cài đặt Roo Code. Phần còn lại của hướng dẫn Roo Code OpenAI compatible API này sẽ biến điều đó thành một checklist có thể lặp lại.
Những gì tài liệu hiện tại của Roo Code xác nhận
Trang chủ tài liệu của Roo Code hiện có cảnh báo ngừng hỗ trợ tiện ích mở rộng. Điều đó rất quan trọng cho việc lập kế hoạch. Nếu nhóm của bạn đang dùng một bản cài Roo Code hiện có, các chi tiết cấu hình bên dưới vẫn hữu ích cho việc bảo trì và xem xét di chuyển. Nếu nhóm của bạn đang chọn một trợ lý lập trình tiêu chuẩn mới, trước tiên hãy xác minh trạng thái tiện ích mở rộng, marketplace và fork trước khi phân bổ Roo Code cho một nhóm rộng hơn.
Trang nhà cung cấp Roo Code OpenAI Compatible ghi lại ba giá trị chính cho lớp nhà cung cấp này: Base URL, API Key và Model ID. Trang này cũng nói hãy chọn OpenAI Compatible làm nhà cung cấp API. Base URL là endpoint của nhà cung cấp và rõ ràng không phải URL API chính thức của OpenAI khi bạn đang dùng một nhà cung cấp không tương thích với OpenAI.
Ràng buộc quan trọng riêng của Roo là gọi công cụ. Cùng trang nhà cung cấp đó cho biết Roo Code chỉ sử dụng gọi công cụ gốc và không có phương án dự phòng dựa trên XML. Trang này cũng nói mô hình được chọn phải hỗ trợ gọi công cụ tương thích với OpenAI. Với lộ trình Roo Code OpenAI compatible API đi qua Flatkey, điều đó có nghĩa là biệt danh mô hình không thể được xác thực chỉ bằng tạo văn bản đơn thuần.
Các giá trị Flatkey cần xác nhận trước khi mở Roo Code
1. Xác nhận base URL cho tài khoản của bạn
Trang chủ của Flatkey được kiểm tra vào ngày 29 tháng 6 năm 2026 có tiêu đề One API gateway for production AI teams và mô tả meta nói rằng Flatkey hợp nhất quyền truy cập mô hình, định tuyến, thanh toán, phân tích mức sử dụng và các kiểm soát vận hành. Các ví dụ công khai trên trang chủ bao gồm chat completions kiểu OpenAI. Một kiểm tra runtime đã xác thực cho bài viết này sử dụng https://router.flatkey.ai/v1 và trả về danh sách mô hình hợp lệ.
Vì các ví dụ công khai và các tuyến đường theo từng tài khoản có thể thay đổi theo thời gian, hãy sao chép base URL Flatkey hiện tại từ console, tài liệu hoặc môi trường làm việc của bạn trước khi đưa vào sản xuất. Trong Roo Code, Base URL phải là base của nhà cung cấp, không phải /v1/chat/completions.
2. Xác nhận biệt danh mô hình và hỗ trợ công cụ
Trang giá của Flatkey được kiểm tra vào ngày 29 tháng 6 năm 2026 cho biết nó công bố bảng giá được render phía máy chủ cho 635 mô hình AI trên 23 nhà cung cấp. Bản đồ endpoint của nó bao gồm /v1/chat/completions, /v1/responses, /v1/messages, /v1/images/generations và /v1/video/generations. Đây là bằng chứng về danh mục và endpoint, không phải lời hứa rằng mọi khóa Flatkey đều có thể gọi mọi mô hình.
Đối với thiết lập Roo Code OpenAI compatible API, hãy chọn một biệt danh mô hình có thể nhìn thấy trong tài khoản và hỗ trợ chat cùng gọi công cụ tương thích với OpenAI. Kiểm tra đã xác thực cho bài viết này trả về 56 mô hình có thể thấy trong tài khoản, và một yêu cầu gọi công cụ nhỏ với gpt-5.4-mini trả về HTTP 200 với finish_reason: tool_calls và metadata mức sử dụng. Hãy xem đó là bằng chứng tuyến đường theo thời điểm cho tài khoản đã kiểm thử, không phải khuyến nghị lâu dài cho mọi workspace Flatkey.
3. Xác nhận quyền sở hữu khóa và việc rà soát mức sử dụng
Roo Code có thể tác động lên một workspace mã nguồn, nên quyền sở hữu khóa rất quan trọng. Hãy dùng một khóa Flatkey được phạm vi hóa cho nhà phát triển, nhóm hoặc môi trường chịu trách nhiệm cho rủi ro. Ghi lại ai có thể xoay vòng khóa, biệt danh mô hình nào được phép, họ endpoint nào được kỳ vọng và nơi nhật ký sử dụng sẽ được xem lại sau prompt đầu tiên.
Từng bước: cấu hình Roo Code với Flatkey
- Kiểm tra xem đây có phải là một cài đặt Roo Code hiện có hay không. Vì tài liệu chính thức hiện đề cập đến việc extension bị tắt, đừng mặc định rằng có thể bắt đầu bằng một cài đặt marketplace mới.
- Mở phần cài đặt provider của Roo Code. Trong cấu hình extension hiện có, hãy vào khu vực model provider hoặc cấu hình API.
- Chọn OpenAI Compatible. Sử dụng kiểu provider được Roo Code tài liệu hóa cho các endpoint không tương thích OpenAI.
- Đặt Base URL. Nhập URL base Flatkey đã được xác minh, ví dụ
https://router.flatkey.ai/v1khi đó là giá trị đang hoạt động hiện tại cho tài khoản của bạn. - Dán API key của Flatkey. Giữ nó khỏi các file repository, bình luận issue, ảnh chụp màn hình và prompt.
- Đặt Model ID. Nhập chính xác alias model của Flatkey. Không dùng tên họ nhà cung cấp chung chung trừ khi Flatkey hiển thị đúng alias đó cho key của bạn.
- Chạy preflight curl bên dưới. Chat thuần hữu ích, nhưng Roo Code yêu cầu native tool calling, vì vậy hãy bao gồm một tool schema trong bài kiểm tra.
- Chạy một prompt Roo Code an toàn. Sử dụng một workspace dùng một lần hoặc một tác vụ không gây thay đổi trước khi trỏ Roo Code vào các repository production.
- Kiểm tra mức sử dụng Flatkey. Xác nhận timestamp, chủ sở hữu key, alias model, mức sử dụng token, trạng thái và khả năng hiển thị chi phí.
- Ghi lại quy trình rollback. Lưu lại các cài đặt provider trước đó, alias model và chủ sở hữu trước khi yêu cầu thêm developer chuyển sang.
Mẫu preflight gọi công cụ native
Cách an toàn nhất để gỡ lỗi một thiết lập Roo Code OpenAI compatible API là kiểm tra đường dẫn Flatkey bên ngoài Roo Code trước. Mẫu này xác minh endpoint chat và yêu cầu model trả về một tool call theo kiểu OpenAI.
export FLATKEY_API_KEY="fk_replace_me"
export FLATKEY_BASE_URL="https://router.flatkey.ai/v1"
export FLATKEY_ROO_MODEL="replace-with-tool-capable-flatkey-model"
curl "$FLATKEY_BASE_URL/chat/completions" \
-H "Authorization: Bearer $FLATKEY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "'"$FLATKEY_ROO_MODEL"'",
"messages": [
{
"role": "user",
"content": "Call route_check with status ok and do not include prose."
}
],
"tools": [
{
"type": "function",
"function": {
"name": "route_check",
"description": "Return the routing smoke-test status.",
"parameters": {
"type": "object",
"properties": {
"status": { "type": "string" }
},
"required": ["status"]
}
}
}
],
"tool_choice": {
"type": "function",
"function": { "name": "route_check" }
},
"max_tokens": 64
}'Một phản hồi lành mạnh nên bao gồm một tin nhắn assistant với tool_calls. Nếu yêu cầu này thất bại, hãy sửa key Flatkey, base URL, alias model, hoặc khả năng của model trước khi thay đổi cài đặt Roo Code. Nếu nó thành công nhưng Roo Code thất bại, hãy tập trung vào các trường Roo Code đã lưu, quyền truy cập mạng cục bộ, trạng thái extension, hoặc chính xác Model ID đã nhập trong cài đặt provider.
Các chế độ lỗi cần gỡ lỗi trước
| Triệu chứng | Nguyên nhân có khả năng | Cách khắc phục |
|---|---|---|
| Khóa API không hợp lệ | Khóa đã được sao chép không chính xác, đã xoay vòng, được giới hạn cho một môi trường khác, hoặc thuộc về nhà cung cấp nguồn thay vì Flatkey. | Dùng một khóa Flatkey mới, kiểm tra bằng curl, rồi dán cùng khóa đó vào Roo Code. |
| Lỗi kết nối | Base URL sai, dán toàn bộ đường dẫn endpoint vào trường Base URL, đường mạng bị chặn, hoặc sự cố proxy cục bộ. | Xác minh URL gốc của nhà cung cấp từ cùng máy và kiểm tra lại /chat/completions. |
| Không tìm thấy mô hình | Model ID của Roo Code không khớp với một bí danh Flatkey được bật cho khóa đó. | Sao chép đúng bí danh từ bảng giá Flatkey, danh mục, hoặc danh sách mô hình hiển thị trong tài khoản. |
| Lỗi gọi công cụ | Mô hình đã chọn có thể trả lời chat nhưng không hỗ trợ các lệnh gọi công cụ gốc tương thích OpenAI. | Chuyển sang một bí danh mô hình có hỗ trợ công cụ và chạy lại bước kiểm tra trước khi dùng Roo Code. |
| Tiện ích mở rộng không khả dụng | Trạng thái phân phối Roo Code hiện tại không hỗ trợ đường dẫn cài đặt hoặc cập nhật dự kiến. | Hãy coi thiết lập này là bảo trì hệ thống cũ và chọn quy trình tác nhân lập trình đang hoạt động cho các lần triển khai mới. |
| Không thể đối soát mức sử dụng | Nhóm chưa ghi lại chủ sở hữu khóa, bí danh mô hình, người dùng Roo Code, môi trường, hoặc dấu thời gian. | Thêm một dòng vào runbook trước khi mở rộng tuyến này cho nhiều nhà phát triển hơn. |
Cài đặt hiện có hay tiêu chuẩn mới?
Lộ trình Roo Code OpenAI compatible API có thể hữu ích, nhưng thông báo ngừng tiện ích mở rộng đã thay đổi quyết định. Hãy dùng bảng này trước khi yêu cầu một nhóm phụ thuộc vào nó.
| Tình huống | Hành động khuyến nghị | Vì sao điều đó quan trọng |
|---|---|---|
| Cài đặt Roo Code hiện có vẫn đang được một nhà phát triển sử dụng | Ghi lại tuyến Flatkey, kiểm tra các lệnh gọi công cụ, và giữ phương án khôi phục. | Có thể tiếp tục bảo trì trong khi nhóm lên kế hoạch di chuyển hoặc thay thế. |
| Triển khai tác nhân lập trình mới trên toàn đội | Trước tiên xác minh tình trạng khả dụng hiện tại của tiện ích mở rộng, rồi so sánh các lựa chọn thay thế đang hoạt động. | Một tiện ích mở rộng đã ngừng có thể tạo ra rủi ro hỗ trợ, bảo mật, và tiếp nhận cho người dùng mới. |
| Chuẩn hóa cụm tích hợp công cụ | Sử dụng cùng một khóa Flatkey, Base URL, model alias, và mẫu nhật ký sử dụng trên mọi công cụ. | Tính nhất quán giúp việc tính phí, gỡ lỗi, và rà soát mua sắm dễ hơn. |
Runbook sản xuất cho Roo Code kết hợp Flatkey
Trước khi thêm nhiều nhà phát triển sử dụng tuyến Roo Code OpenAI compatible API, hãy ghi lại các факт vận hành giúp việc hỗ trợ và rà soát chi phí trở nên khả thi.
| Trường runbook | Ghi lại mục này |
|---|---|
| Phạm vi Roo Code | Bản cài đặt cục bộ hiện có, image của nhóm, hồ sơ đã lưu trữ, hoặc kiểm thử chỉ dành cho di chuyển. |
| Khóa Flatkey | Chủ sở hữu, môi trường, ngày xoay vòng, và chủ sở hữu thu hồi. |
| Base URL | Base URL gốc của nhà cung cấp đã lưu chính xác trong Roo Code và ngày đã được xác minh. |
| Bí danh model | Roo Code Model ID, bí danh model Flatkey, họ endpoint, và kết quả gọi công cụ gốc. |
| Kiểm thử nhanh | Mã trạng thái HTTP, lý do kết thúc, tổng mức sử dụng, và việc tool_calls có xuất hiện hay không. |
| Rà soát mức sử dụng | Nơi chủ sở hữu nền tảng và tài chính kiểm tra khối lượng yêu cầu, chi phí, và các thay đổi model không mong đợi. |
| Khôi phục | Cấu hình nhà cung cấp trước đó, bí danh model trước đó, và ai có thể khôi phục nó. |
Lộ trình di chuyển nội bộ
Nếu nhóm của bạn đang chuẩn hóa các cấu hình công cụ tương thích OpenAI trên Flatkey, hãy giữ thiết lập này đồng bộ với phần còn lại của cụm tích hợp. Dùng hướng dẫn di chuyển API tương thích OpenAI làm base URL và trung tâm khôi phục. Với một mẫu client desktop khác, hãy so sánh hướng dẫn thiết lập API Cherry Studio. Với định tuyến tác tử lập trình trên máy của nhà phát triển, hãy xem hướng dẫn cc-switch Claude Code.
Sau khi prompt Roo Code an toàn đầu tiên hoạt động, hãy xem lại trang giá model Flatkey hiện tại, rồi Lấy key cho từng ranh giới riêng biệt của người dùng, nhóm, hoặc môi trường.
Câu hỏi thường gặp
Roo Code còn hỗ trợ các nhà cung cấp tương thích OpenAI không?
Tài liệu nhà cung cấp OpenAI Compatible của Roo Code vẫn mô tả các trường nhà cung cấp: API Provider, Base URL, API Key, và Model ID. Trang chủ tài liệu cũng cho biết tiện ích mở rộng Roo Code đã bị đóng vào ngày 15 tháng 5 năm 2026, vì vậy hãy xác minh đường dẫn cài đặt của bạn trước khi triển khai mới.
Tôi nên dùng Base URL nào cho nhà cung cấp API tương thích OpenAI của Roo Code?
Hãy dùng base URL nhà cung cấp Flatkey hiện tại cho tài khoản của bạn. Các kiểm tra Flatkey đã xác thực trong bài viết này dùng https://router.flatkey.ai/v1, trong khi các ví dụ công khai có thể thay đổi. Trong Roo Code, chỉ dán base URL, không phải toàn bộ endpoint chat-completions.
Tại sao cần native tool calling?
Tài liệu nhà cung cấp của Roo Code nói rằng native tool calling là giao thức công cụ duy nhất được hỗ trợ cho các nhà cung cấp tương thích OpenAI. Một model có thể trả lời chat thuần nhưng không thể tạo lệnh gọi công cụ kiểu OpenAI thì chưa đủ cho một thiết lập Roo Code đáng tin cậy.
Model ID có nên khớp chính xác với bí danh model Flatkey không?
Có. Hãy dùng đúng bí danh Flatkey mà key của bạn có thể gọi, và xác minh bằng một kiểm thử nhanh gọi công cụ. Tên họ model, tên tiếp thị của nhà cung cấp, và bí danh gateway có thể khác nhau.
Tôi có thể dùng hướng dẫn này cho các triển khai Roo Code mới không?
Chỉ dùng sau khi kiểm tra tình trạng khả dụng hiện tại của Roo Code. Các kiểm tra định tuyến Flatkey vẫn hữu ích, nhưng thông báo ngừng Roo Code có nghĩa là các triển khai mới trên toàn nhóm cần một quyết định hỗ trợ sản phẩm rõ ràng.
Kết luận
Một thiết lập Roo Code OpenAI compatible API an toàn thông qua Flatkey nên chứng minh được nhiều hơn một phản hồi chat thành công. Hãy xác nhận base URL hiện tại, sử dụng một khóa do Flatkey sở hữu, chọn đúng alias mô hình, kiểm tra các lệnh gọi công cụ gốc, và xem khả năng hiển thị mức sử dụng trước khi cho Roo Code quyền truy cập vào công việc mã nguồn thực tế. Khi tuyến đường đã sẵn sàng cho người dùng hoặc môi trường khác, Get a key và giữ dòng rollback ngay cạnh các hướng dẫn thiết lập.
