Hướng dẫn OpenCode API: Kết nối API Model và Bắt đầu Lập trình

OpenCode là gì?

OpenCode là một agent lập trình AI mã nguồn mở chạy trên terminal và cũng có thể được sử dụng thông qua các quy trình làm việc trên desktop, IDE và server. Nó giúp các nhà phát triển làm việc với codebase bằng cách đọc file, giải thích cấu trúc, chỉnh sửa code, đánh giá thay đổi và chạy các tác vụ thông qua các nhà cung cấp LLM được kết nối. Bạn kết nối nó với một nhà cung cấp mô hình, chẳng hạn như Kimi API, và OpenCode sử dụng nhà cung cấp đó để lập kế hoạch, suy luận và hành động trong môi trường phát triển của bạn.

Bạn có thể làm gì với OpenCode?

Bạn có thể chọn OpenCode khi muốn một quy trình lập trình AI có thể làm việc trực tiếp với dự án của mình. Ví dụ:

Viết, chỉnh sửa và tái cấu trúc code: Bạn có thể yêu cầu OpenCode thêm một tính năng, sửa đổi một file hiện có, tái cấu trúc một hàm, hoặc giải thích cách một module nên được thay đổi. Để có kết quả tốt nhất, hãy chỉ rõ các file hoặc thư mục liên quan.

Gỡ lỗi và tạo bài kiểm thử: OpenCode có thể kiểm tra kết quả lỗi, đọc các file liên quan, đề xuất cách sửa và thêm bài kiểm thử. Điều này đặc biệt hữu ích khi lỗi phụ thuộc vào ngữ cảnh của dự án.

Đánh giá thay đổi code: Bạn có thể dùng OpenCode để đánh giá các thay đổi cục bộ trước khi commit. Nó có thể tìm ra các lỗi tiềm ẩn, bài kiểm thử còn thiếu, các mẫu không nhất quán và các chỉnh sửa rủi ro.

Tự động hóa quy trình phát triển: OpenCode cũng hỗ trợ các quy trình không tương tác và dựa trên server. Ví dụ, bạn có thể chạy một prompt một lần từ dòng lệnh hoặc khởi động một server OpenCode headless và kết nối một client hoặc tích hợp khác với nó.

Điều kiện tiên quyết để cấu hình OpenCode với một API LLM

Trước khi cấu hình OpenCode với một API LLM, hãy chuẩn bị những điều sau:

• Một terminal hoạt động trên macOS, Linux, hoặc Windows (khuyến nghị dùng WSL).

• Node.js, Homebrew, hoặc một phương pháp cài đặt được hỗ trợ khác.

• Một thư mục dự án mà bạn có thể an toàn dùng để thử nghiệm.

• Một tài khoản nhà cung cấp mô hình.

Đối với OpenCode, hãy nhớ rằng thông tin xác thực của nhà cung cấp là nhạy cảm. Đừng dán khóa của bạn vào các issue công khai, ảnh chụp màn hình chia sẻ, file mã nguồn, hoặc cấu hình đã commit.

Bước 1: Cài đặt OpenCode

Phương pháp cài đặt nhanh nhất theo tài liệu chính thức của OpenCode là dùng script cài đặt. Chạy lệnh này trong terminal của bạn:

OpenCode cũng hỗ trợ cài đặt thông qua npm, Homebrew, và các lệnh khác. Nếu bạn thích phiên bản desktop, bạn có thể tải xuống phiên bản phù hợp với thiết bị của mình.

Bước 2: Khởi chạy OpenCode

Đi đến dự án mà bạn muốn OpenCode làm việc:

Khởi động OpenCode:

Nếu đây là lần đầu tiên bạn dùng OpenCode trong dự án, hãy khởi tạo nó từ bên trong TUI:

Cách cấu hình OpenCode với một API LLM

Trong hầu hết các trường hợp, việc sử dụng “OpenCode API” có nghĩa là kết nối OpenCode với một nhà cung cấp LLM bên ngoài thông qua một khóa API. Nhà cung cấp sẽ cung cấp mô hình, trong khi OpenCode xử lý quy trình agent lập trình bên trong dự án của bạn. Các bước sau đây sử dụng Kimi API làm ví dụ về nhà cung cấp.

Bước 1: Tạo khóa Kimi API của bạn

Mở nền tảng Kimi API. Tạo một khóa API từ bảng điều khiển, sau đó lưu trữ nó trong một trình quản lý mật khẩu hoặc trình quản lý bí mật. Nếu bảng điều khiển của bạn chỉ hiển thị khóa đầy đủ một lần, hãy sao chép nó trước khi rời khỏi trang.

Bước 2: Kết nối một nhà cung cấp mô hình

Khởi chạy OpenCode trong dự án của bạn:

Bên trong giao diện OpenCode, chạy:

Tìm mục Moonshot AI hoặc mục nhà cung cấp tương thích Kimi hiển thị trong phiên bản OpenCode của bạn. Tài liệu chính thức về nhà cung cấp của OpenCode có hướng dẫn luồng Moonshot AI: tạo key trong Moonshot AI console, chạy /connect, tìm Moonshot AI, rồi nhập API key.

Nếu phiên bản của bạn không hiển thị Moonshot AI, hãy cập nhật OpenCode và làm mới danh sách model:

Bước 3: Nhập Kimi API key của bạn

Khi OpenCode yêu cầu API key, dán Kimi API key của bạn vào.

OpenCode lưu thông tin xác thực nhà cung cấp trong tệp auth cục bộ của nó. Tài liệu chính thức về nhà cung cấp liệt kê đường dẫn này:

Thông thường bạn không cần chỉnh sửa tệp đó theo cách thủ công. Hãy dùng luồng /connect của nhà cung cấp trong OpenCode.

Bước 4: Chọn một model Kimi

Sau khi kết nối nhà cung cấp, chọn một model bên trong OpenCode:

Chọn model Kimi bạn muốn dùng. Với các quy trình agent lập trình mới, hãy bắt đầu với:

Nếu bạn cần chạy OpenCode không tương tác với một model cụ thể, hãy dùng định dạng provider/model được hiển thị trong danh sách model của OpenCode. Ví dụ:

Sau đó dùng đúng mã định danh model mà OpenCode hiển thị.

Bước 5: Chạy tác vụ lập trình đầu tiên

Bắt đầu với một tác vụ rủi ro thấp để bạn có thể kiểm tra xem nhà cung cấp, model, quyền truy cập dự án và quyền hạn có hoạt động hay không:

Kết quả mong đợi:

Sau đó thử một tác vụ lập trình nhỏ:

Điều này xác nhận rằng OpenCode có thể đọc dự án và suy luận trên codebase trước khi bạn cho phép nó thực hiện thay đổi.

Vì Sao Nên Dùng Kimi API Với OpenCode?

Kimi API là lựa chọn phù hợp cho OpenCode khi bạn muốn một nhà cung cấp model tương thích OpenAI cho các quy trình lập trình và agent.

Khả năng lập trình và suy luận mạnh

{{KIMI_MODEL_LATEST_FULL}} được định vị chính thức cho việc lập trình dài hạn, tuân theo chỉ dẫn, tự sửa lỗi và thực thi agent. Điều đó khiến nó phù hợp với các tác vụ OpenCode như chỉnh sửa nhiều tệp, gỡ lỗi, tái cấu trúc và review.

Hỗ trợ ngữ cảnh dài cho các dự án lớn hơn

Tài liệu chính thức về {{KIMI_MODEL_LATEST_FULL}} liệt kê khả năng hỗ trợ ngữ cảnh dài cho {{KIMI_MODEL_LATEST_FULL}} và một số model dòng K2. Trong quy trình agent, ngữ cảnh dài có thể hữu ích khi tác vụ yêu cầu đọc nhiều tệp, so sánh các mẫu triển khai, hoặc lưu giữ một lượng lớn lịch sử tác vụ.

API tương thích OpenAI giúp thiết lập dễ dàng hơn

Kimi API tương thích với định dạng API của OpenAI. Đối với các công cụ vốn đã hỗ trợ chat completions kiểu OpenAI, điều này thường có nghĩa là bạn chỉ cần cấu hình API key, Base URL và tên model.

Sử dụng linh hoạt ngoài phạm vi OpenCode

Bạn có thể dùng cùng một Kimi API key trong các công cụ dành cho nhà phát triển tương thích OpenAI khác, các script trực tiếp, hoặc các quy trình nội bộ. Nếu sau này bạn dùng OpenCode server hoặc OpenCode SDK, hãy cấu hình Kimi làm nhà cung cấp model trước.

Các Thiết Lập API OpenCode Quan Trọng Bạn Nên Biết

Những thiết lập này kiểm soát phần lớn các vấn đề về API OpenCode và thiết lập nhà cung cấp.

API key

API key dùng để xác thực yêu cầu của bạn với nhà cung cấp model. Trong OpenCode, bạn thường thêm nó bằng:

Provider

Provider cho biết OpenCode lấy model từ đâu. Trong hướng dẫn này, provider là Moonshot AI / Kimi API. Các provider khác có thể được cấu hình riêng, nhưng mỗi provider cần thông tin xác thực và danh sách model riêng.

Base URL

Base URL là endpoint dùng cho các yêu cầu API tương thích OpenAI trực tiếp. Với các ví dụ Kimi API, hãy dùng endpoint được nêu trong tài liệu Kimi API hiện hành hoặc trong bảng điều khiển tài khoản của bạn.

Model name

Tên model phải khớp chính xác với tên do provider cung cấp. Chỉ một lỗi gõ nhỏ cũng có thể gây ra lỗi không tìm thấy model.

Ví dụ phổ biến:

Trong OpenCode, xác nhận định danh provider/model bằng:

Khắc Phục Các Lỗi API Thường Gặp Của OpenCode

Hầu hết các vấn đề khi thiết lập đều xuất phát từ một trong năm nguyên nhân: thông tin xác thực, endpoint, provider, tên model, hoặc kích thước ngữ cảnh.

Xác thực thất bại

Việc xác thực có thể thất bại nếu API key được dán sai, đã bị xóa, hoặc đã được đổi mới. Điều này cũng có thể xảy ra khi chọn sai provider, hoặc khi key thuộc về một tài khoản hoặc khu vực khác với tài khoản/khu vực hiện đang được cấu hình trong OpenCode.

Cách khắc phục:

Kết nối lại provider và dán một API key mới. Nếu bạn dùng biến môi trường để kiểm tra trực tiếp, hãy đặt lại key:

Lỗi endpoint không hợp lệ

Lỗi endpoint không hợp lệ thường có nghĩa là OpenCode không thể kết nối đến đúng endpoint của provider. Các nguyên nhân phổ biến bao gồm Base URL bị nhập sai, dùng lẫn lộn endpoint .ai và .cn giữa các công cụ, hoặc có proxy/tường lửa can thiệp và viết lại yêu cầu trước khi đến được provider.

Cách khắc phục:

Kiểm tra endpoint được nêu trong tài liệu Kimi API hoặc bảng điều khiển hiện hành của bạn. Với các bài kiểm tra API trực tiếp, hãy dùng nhất quán một endpoint:

Model không được hỗ trợ

Lỗi này có thể xảy ra khi tên model bị nhập sai, model được chọn không khả dụng cho tài khoản của bạn, hoặc bộ nhớ đệm danh sách model của OpenCode đã lỗi thời. Nó cũng có thể xảy ra khi định danh provider/model mà OpenCode sử dụng khác với tên model gốc được nêu trong tài liệu của provider.

Cách khắc phục:

Sau đó chọn lại model:

Vượt quá giới hạn tốc độ

Lỗi vượt quá giới hạn tốc độ thường có nghĩa là provider đã nhận quá nhiều yêu cầu trong thời gian quá ngắn. Điều này có thể xảy ra nếu nhiều tác vụ agent đang chạy cùng lúc, hoặc nếu một script hay tích hợp đang thử lại các yêu cầu thất bại quá dồn dập.

Cách khắc phục:

Tạm dừng tác vụ, giảm số lượt chạy song song, và kiểm tra bảng điều khiển provider của bạn về hạn mức hoặc tình trạng thanh toán. Tránh viết các vòng lặp thử lại vô hạn quanh OpenCode hoặc các lệnh gọi Kimi API trực tiếp.

Tràn cửa sổ ngữ cảnh

Tràn cửa sổ ngữ cảnh thường có nghĩa là tác vụ quá lớn để model xử lý cùng một lúc. Điều này có thể xảy ra nếu có quá nhiều tệp được đưa vào, nếu OpenCode được yêu cầu kiểm tra toàn bộ kho mã, hoặc nếu một phiên làm việc dài đã tích lũy quá nhiều lịch sử hội thoại.

Cách khắc phục:

Yêu cầu OpenCode xử lý một phạm vi nhỏ hơn:

Bạn cũng có thể bắt đầu một phiên làm việc mới cho một tác vụ hẹp hơn.

Kết luận

OpenCode có thể kết nối codebase của bạn với các nhà cung cấp model, chạy các tác vụ lập trình từ terminal. Kimi API có thể cung cấp phần model backend cho các workflow đó thông qua cấu hình tương thích OpenAI. Nếu bạn muốn một workflow agent lập trình thực tế, hãy tạo Kimi API key, kết nối Moonshot AI trong OpenCode, chọn một model Kimi, rồi chạy một tác vụ dự án nhỏ để xác nhận cấu hình.