OpenCode có hỗ trợ base URL tùy chỉnh không?

Có. Bạn khai báo một nhà cung cấp tùy chỉnh trong opencode.json với base URL, khóa API và danh sách các mô hình. Hãy kiểm tra tài liệu hiện tại của OpenCode để biết chính xác tên các trường, vì chúng có thể thay đổi giữa các phiên bản.

Tôi nên nhập model ID nào?

Nhập uncensored, chính xác như cách viết. Nó phải khớp với khóa trong khối models và ID được trả về bởi GET /v1/models.

Có cách nào dùng thử miễn phí để kiểm tra cài đặt không?

Người dùng mới có thể nhận $0.50 tín dụng dùng thử bằng một cú nhấp chuột trên trang khóa API sau khi đăng ký. Tín dụng này có hiệu lực trong 7 ngày, không cần thẻ và giới hạn một lần cho mỗi người.

Tại sao tôi gặp lỗi 429 trong quá trình chạy agent?

Các agent thường gửi một vài yêu cầu cùng lúc. Khóa đầy đủ cho phép 8 yêu cầu đồng thời và 300 mỗi phút, trong khi khóa dùng thử cho phép 2 và 60. Giảm độ song song hoặc thử lại sau độ trễ Retry-After.

OpenCode với API tương thích OpenAI: Cài đặt

Những gì bạn cần trước khi bắt đầu

OpenCode là một agent lập trình mã nguồn mở chạy trong terminal của bạn. Nó có thể kết nối với nhiều nhà cung cấp mô hình và cho phép bạn thêm nhà cung cấp riêng nếu endpoint tuân theo định dạng chat của OpenAI. API này tuân theo, nên việc thiết lập chỉ là điền vào một vài trường.

Hãy chuẩn bị ba giá trị sau trước:

URL cơ sở: https://api.kimicode.top/v1
ID mô hình: uncensored
Khóa API: tạo một khóa trên trang khóa API. Tài khoản mới có thể yêu cầu tín dụng dùng thử $0.50 tại đó bằng một cú nhấp chuột, đủ cho các bài kiểm tra bên dưới. Khóa dùng thử cho phép 2 yêu cầu đồng thời và 60 yêu cầu mỗi phút.

Giữ khóa trong biến môi trường thay vì dán nó vào các tệp bạn sẽ commit:

export KIMICODE_API_KEY="your-key-here"

Bước 1: kiểm tra endpoint bằng curl

Hãy làm việc này trước khi cấu hình bất kỳ công cụ nào. Nếu curl hoạt động nhưng OpenCode không, bạn biết vấn đề nằm ở cấu hình. Nếu curl thất bại, bạn chỉ cần sửa khóa hoặc URL một lần, chứ không phải ở hai nơi.

curl https://api.kimicode.top/v1/chat/completions \
  -H "Authorization: Bearer $KIMICODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "messages": [{"role": "user", "content": "Say hello in five words."}],
    "max_tokens": 40
  }'

Bạn nên nhận được một đối tượng JSON với mảng choices và khối usage. Lỗi 401 có nghĩa là khóa sai hoặc thiếu tiền tố Bearer. Lỗi 404 thường có nghĩa là URL bị đánh sai hoặc đã bao gồm /chat/completions.

Một agent lập trình sẽ truyền phát câu trả lời và gọi các công cụ, vì vậy hãy kiểm tra cả hai tính năng này:

curl -N https://api.kimicode.top/v1/chat/completions \
  -H "Authorization: Bearer $KIMICODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "stream": true,
    "messages": [{"role": "user", "content": "Count from one to five."}]
  }'

Bạn nên thấy một chuỗi các dòng data:, mỗi dòng chứa một phần thay đổi JSON nhỏ, kết thúc bằng các số liệu sử dụng và một dấu hiệu kết thúc. Cờ -N tắt tính năng đệm của curl để các chunk xuất hiện ngay khi chúng đến.

Bước 2: thêm nhà cung cấp tùy chỉnh vào OpenCode

OpenCode đọc một tệp cấu hình JSON, opencode.json, từ thư mục dự án của bạn hoặc từ thư mục cấu hình toàn cục của nó. Các nhà cung cấp kiểu OpenAI tùy chỉnh được khai báo bằng gói tương thích OpenAI của AI SDK, một base URL và một danh sách các mô hình. Bố cục bên dưới tuân theo tài liệu công khai của OpenCode tại thời điểm viết. Tên các trường có thể thay đổi giữa các bản phát hành, vì vậy hãy so sánh nó với phần nhà cung cấp trong tài liệu OpenCode hiện tại nếu có lỗi bị từ chối.

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "kimicode": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Kimicode API",
      "options": {
        "baseURL": "https://api.kimicode.top/v1",
        "apiKey": "{env:KIMICODE_API_KEY}"
      },
      "models": {
        "uncensored": {
          "name": "Uncensored",
          "limit": {
            "context": 100000,
            "output": 8192
          }
        }
      }
    }
  },
  "model": "kimicode/uncensored"
}

Khóa dưới models là ID mô hình chính xác được gửi đến máy chủ, vì vậy nó phải đọc uncensored. Dòng cuối cùng chọn nhà cung cấp và mô hình làm mặc định, được viết dưới dạng tên nhà cung cấp, dấu gạch chéo, sau đó là ID mô hình.

Dạng {env:KIMICODE_API_KEY} cho biết OpenCode đọc biến từ shell của bạn. Nếu phiên bản của bạn xử lý thông tin xác thực qua lệnh đăng nhập riêng, hãy dùng cách đó và để khóa ra khỏi tệp. Dù theo cách nào, đừng commit một khóa thật.

Cấu hình dự án hoặc cấu hình toàn cục

Bạn có thể giữ khối nhà cung cấp ở hai nơi. Một tệp trong thư mục gốc dự án chỉ áp dụng cho kho lưu trữ đó, phù hợp với một nhóm chia sẻ một cấu hình. Một tệp trong thư mục cấu hình người dùng của bạn áp dụng cho mọi nơi, phù hợp với một cấu hình mặc định cá nhân. Khi cả hai đều tồn tại, tệp dự án sẽ thêm vào hoặc ghi đè lên tệp toàn cục.

Ưu tiên tệp toàn cầu cho định nghĩa nhà cung cấp và biến môi trường cho khóa. Khi đó mọi kho lưu trữ đều có thể sử dụng endpoint, và không có dữ liệu bí mật nào nằm cạnh mã nguồn của bạn. Nếu nhiều người làm việc trên một dự án, chỉ commit khối nhà cung cấp không có khóa, và yêu cầu mỗi người thiết lập biến riêng. Điều này cũng giúp đổi khóa dễ dàng: thay đổi biến, khởi động lại terminal và tệp cấu hình vẫn giữ nguyên.

Bước 3: chọn mô hình và chạy tác vụ

Khởi động OpenCode trong một thư mục dự án và mở trình chọn mô hình của nó. Nhà cung cấp tùy chỉnh của bạn sẽ xuất hiện trong danh sách với tên hiển thị bạn đã đặt. Chọn nó, sau đó giao cho agent một tác vụ nhỏ, có thể kiểm tra được như giải thích một hàm hoặc viết một bài kiểm tra đơn vị cho một tệp ngắn.

Hãy bắt đầu nhỏ vì hai lý do. Thứ nhất, bạn có thể xem liệu các lệnh gọi công cụ có hoạt động không: khi OpenCode yêu cầu mô hình đọc hoặc chỉnh sửa một tệp, nó thực hiện việc đó thông qua giao diện gọi hàm. Thứ hai, một agent mã hóa gửi rất nhiều văn bản mỗi lượt, bao gồm nội dung tệp và lịch sử, vì vậy một phiên dài sẽ tiêu tốn token nhanh chóng. Phần tiếp theo sẽ đưa ra các con số cụ thể về điều đó.

Nếu mô hình không hiển thị, hãy kiểm tra xem tệp có phải là JSON hợp lệ không, tệp có nằm ở vị trí mà OpenCode tìm kiếm cấu hình không và tên nhà cung cấp có khớp với những gì bạn đã nhập trong trường model không.

Kiểm tra gọi hàm và chế độ JSON trực tiếp

OpenCode dựa vào gọi công cụ để đọc tệp, chạy lệnh và chỉnh sửa mã, nên việc xác nhận endpoint xử lý định nghĩa công cụ trước khi xác định nguồn gốc lỗi ở agent là rất đáng giá. Yêu cầu này cung cấp một công cụ và đặt một câu hỏi cần đến nó.

curl https://api.kimicode.top/v1/chat/completions \
  -H "Authorization: Bearer $KIMICODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "uncensored",
    "messages": [{"role": "user", "content": "What is in the file notes.txt?"}],
    "tools": [{
      "type": "function",
      "function": {
        "name": "read_file",
        "description": "Read a text file by path",
        "parameters": {
          "type": "object",
          "properties": {"path": {"type": "string"}},
          "required": ["path"]
        }
      }
    }],
    "tool_choice": "auto"
  }'

Một phản hồi tốt chứa một mục tool_calls đặt tên read_file với một chuỗi đối số JSON. Agent chạy công cụ, sau đó gửi kết quả lại dưới dạng một thông điệp với role được đặt thành tool, và mô hình tiếp tục từ đó. Nếu bạn chỉ thấy văn bản thuần, hãy thử một prompt trực tiếp hơn, vì việc mô hình quyết định gọi công cụ hay không là một phần hành vi của nó.

Chế độ JSON là một công tắc riêng biệt. Thêm "response_format": {"type": "json_object"} yêu cầu đầu ra JSON hợp lệ, và nó hữu ích khi một kịch bản khác phải phân tích những gì trả về. Hãy đề cập đến JSON trong prompt của bạn, để mô hình biết hình dạng bạn mong đợi.

Kích thước ngữ cảnh và chi phí cho một phiên

Cửa sổ ngữ cảnh là 100.000 token, tính cả prompt và phần hoàn thành cùng nhau. Việc đặt limit.context xuống 100000 cho agent biết giới hạn trần thực tế, để nó có thể cắt bớt hoặc tóm tắt lịch sử trước khi máy chủ phải từ chối một yêu cầu. Phần hoàn thành có thể sử dụng bất kỳ không gian nào còn lại và max_tokens là tùy chọn.

Chi phí tính là $0.15 cho mỗi 1M token đầu vào và $0.50 cho mỗi 1M token đầu ra. Các agent nặng về đầu vào, vì mỗi lượt gửi lại toàn bộ cuộc trò chuyện. Dưới đây là một ví dụ tính toán chi tiết cho một phiên ở mức độ vừa phải:

40 lượt, mỗi lượt gửi khoảng 30.000 token đầu vào: 1.200.000 token đầu vào, tương đương 1,2 x $0,15 = $0,18.
Mỗi lượt trả về khoảng 800 token đầu ra: 32.000 token đầu ra, tương đương 0,032 x $0,50 = $0,016.
Tổng cộng: $0,196, tức là khoảng hai mươi xu cho toàn bộ phiên.

Các số liệu của bạn sẽ khác. Đọc các giá trị usage trong phản hồi, hoặc theo dõi tiêu đề X-Balance-USD, báo cáo số dư còn lại của bạn trên mỗi phản hồi. Tín dụng là trả trước và không bao giờ hết hạn, các yêu cầu thất bại hoặc bị từ chối không bị tính phí. Chi tiết có trên trang giá cả.

Kỳ vọng thực tế cho một agent mã hóa

Đây là một mô hình văn bản chung được tinh chỉnh để trả lời mà không có các từ chối nội dung cho người dùng trưởng thành hợp pháp. Nó không phải là mô hình được xây dựng đặc biệt cho mã, và trang này không đưa ra các tuyên bố về benchmark. Việc nó có chỉnh sửa kho lưu trữ của bạn một cách đáng tin cậy hay không là điều bạn nên tự kiểm tra trên các tác vụ của mình, với kiểm soát phiên bản đang bật, trước khi giao cho nó bất cứ thứ gì quan trọng.

Nó xử lý các công việc nền tảng mà một agent cần: gọi hàm với tool_calls được truyền phát, kết quả công cụ được gửi lại dưới dạng các thông điệp role: "tool" và chế độ JSON thông qua response_format. Nó chỉ xử lý văn bản, không có hình ảnh, vì vậy các tính năng đính kèm ảnh chụp màn hình sẽ không hoạt động.

Hai giới hạn quan trọng đối với các agent. Khóa đầy đủ cho phép 8 yêu cầu đồng thời và 300 yêu cầu mỗi phút. Các agent con hoặc các lần chạy công cụ song song bắn ra nhiều lệnh gọi cùng lúc có thể chạm ngưỡng giới hạn đồng thời, và một yêu cầu truyền phát giữ vị trí của nó cho đến khi luồng kết thúc. Khi đó bạn sẽ nhận được HTTP 429 với mã concurrency. Mã rate_limited có nghĩa là quá nhiều yêu cầu mỗi phút. Trong trường hợp quá tải tạm thời, bạn cũng có thể thấy lỗi 429 với Retry-After: 5. Hãy giảm độ đồng thời hoặc đợi và thử lại.

Khắc phục sự cố

Triệu chứng	Nguyên nhân có thể	Cách khắc phục
401 Không được ủy quyền	Khóa trống hoặc sai; biến môi trường chưa được thiết lập trong shell đã khởi động OpenCode	Chạy `echo $KIMICODE_API_KEY` trong cùng một terminal, sau đó khởi động lại OpenCode
404 Not Found	Base URL bao gồm `/chat/completions` hoặc thiếu `/v1`	Sử dụng chính xác `https://api.kimicode.top/v1`
Không tìm thấy mô hình	Khóa mô hình khác với `uncensored`	Khớp khóa trong `models` với ID được trả về bởi `GET /v1/models`
429 với `concurrency`	Quá nhiều yêu cầu cùng một lúc	Giảm số lượng gọi hàm song song, hoặc đợi các luồng truyền phát hoàn tất
Yêu cầu quá lớn	Thân yêu cầu quá 8 MB hoặc lịch sử gần giới hạn cửa sổ ngữ cảnh	Bắt đầu một phiên mới hoặc tóm tắt lịch sử

Đối với mọi nội dung chưa được đề cập ở đây, trang tài liệu cung cấp tài liệu tham khảo đầy đủ về yêu cầu, còn hướng dẫn tích hợp bao gồm cùng một endpoint này từ góc độ của các máy khách tương thích OpenAI khác.