Cấu hình OpenCode cho Claude: thiết lập opencode.json, mô hình và các lỗi thường gặp

OpenCode đọc các thiết lập từ opencode.json. Để chạy OpenCode với Claude qua gateway này, bạn thay đổi một giá trị, đó là giá trị sau của nhà cung cấp Anthropic: baseURL, và cung cấp khóa. Bên dưới là hai cấu hình hoạt động được, các thiết lập mô hình và ngữ cảnh quan trọng, cùng cách khắc phục những lỗi người dùng OpenCode gặp trên gateway này, được lấy từ nhật ký yêu cầu của chúng tôi.

Vị trí của opencode.json

OpenCode hợp nhất cấu hình toàn cục với cấu hình riêng cho từng dự án: ~/.config/opencode/opencode.json cho các thiết lập bạn muốn dùng ở mọi nơi, và opencode.json ở thư mục gốc của dự án cho kho mã đó. Thêm dòng $schema sẽ cung cấp tính năng tự động hoàn thành và kiểm tra tính hợp lệ trong hầu hết trình soạn thảo.

Không lưu khóa trong tệp. Đặt khóa trong biến môi trường và tham chiếu đến nó dưới dạng {env:AIPRIME_API_KEY}. Các khóa bạn thêm bằng /connect trong OpenCode được lưu trong ~/.local/share/opencode/auth.json; opencode auth list hiển thị những gì được lưu ở đó.

export AIPRIME_API_KEY=your_gateway_key   # add to ~/.bashrc or ~/.zshrc
opencode auth list                         # credentials OpenCode already knows about

Phương án 1: trỏ nhà cung cấp Anthropic tích hợp sẵn đến gateway

Thay đổi tối thiểu: giữ nhà cung cấp Anthropic và danh sách mô hình có sẵn của OpenCode, đồng thời ghi đè đích gửi yêu cầu.

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "baseURL": "https://aiprimetech.io/v1",
        "apiKey": "{env:AIPRIME_API_KEY}"
      }
    }
  },
  "model": "anthropic/claude-sonnet-5",
  "small_model": "anthropic/claude-haiku-4-5"
}

Phương án 2: nhà cung cấp tùy chỉnh với danh sách mô hình của riêng bạn

Một mục nhà cung cấp riêng giúp tách cổng API khỏi mọi phiên đăng nhập Anthropic, cho phép bạn liệt kê chính xác các mô hình muốn xuất hiện trong bộ chọn và đặt giới hạn ngữ cảnh cho từng mô hình.

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "aiprime": {
      "npm": "@ai-sdk/anthropic",
      "name": "AI Prime Tech",
      "options": {
        "baseURL": "https://aiprimetech.io/v1",
        "apiKey": "{env:AIPRIME_API_KEY}"
      },
      "models": {
        "claude-sonnet-5":  { "name": "Claude Sonnet 5",  "limit": { "context": 200000, "output": 64000 } },
        "claude-opus-5-5":  { "name": "Claude Opus 5.5",  "limit": { "context": 200000, "output": 64000 } },
        "claude-haiku-4-5": { "name": "Claude Haiku 4.5", "limit": { "context": 200000, "output": 32000 } }
      }
    }
  },
  "model": "aiprime/claude-sonnet-5",
  "small_model": "aiprime/claude-haiku-4-5"
}

Ưu tiên @ai-sdk/anthropic cho Claude: nó sử dụng Messages API gốc, nên tính năng lưu bộ nhớ đệm prompt và suy nghĩ hoạt động đúng như Anthropic thiết kế. Cổng API cũng hỗ trợ định dạng OpenAI, vì vậy @ai-sdk/openai-compatible với cùng https://aiprimetech.io/v1 URL cơ sở cũng hoạt động, và đây là cách cần dùng cho các mô hình GPT với cùng khóa.

Mô hình và giới hạn ngữ cảnh

model là mô hình mà tác nhân chính sử dụng; small_model xử lý các tác vụ phụ ít tốn kém như tạo tiêu đề phiên. Giá trị limit.context cho OpenCode biết khi nào cần rút gọn phiên. Nếu một phiên dài gặp lỗi prompt is too long, hãy giảm giá trị này (200000 là giá trị an toàn) để OpenCode tóm tắt sớm hơn thay vì gửi lượng nội dung vượt quá khả năng tiếp nhận của điểm cuối.

ID mô hình phải là các chuỗi chính xác. Những tên cũ như claude-3-5-sonnet-20241022 hoặc các phiên bản chụp nhanh có gắn ngày không được cung cấp; hãy dùng các ID ở trên hoặc danh sách trong bảng điều khiển của bạn.

Kiểm tra khóa và URL trước khi khởi động OpenCode

Một yêu cầu từ terminal sẽ cho bạn biết khóa và URL có đúng hay không, độc lập với cấu hình của OpenCode:

curl -s https://aiprimetech.io/v1/messages \
  -H "x-api-key: $AIPRIME_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-haiku-4-5","max_tokens":20,"messages":[{"role":"user","content":"ping"}]}'

Phản hồi JSON có một mảng content nghĩa là phía cổng API hoạt động bình thường và mọi vấn đề còn lại nằm trong opencode.json. Invalid API key nghĩa là biến đang trống hoặc chứa khóa sai.

Khắc phục sự cố: các lỗi người dùng OpenCode thường gặp

Đây là những lỗi xuất hiện thường xuyên nhất khi dùng OpenCode trên cổng API này, cùng cách khắc phục từng lỗi.

Đối với các lỗi xuất phát từ phía mô hình thay vì ứng dụng khách, hãy xem hướng dẫn về lỗi Claude API.

Câu hỏi thường gặp

AI Prime Tech là một cổng API độc lập. AI Prime Tech không liên kết với, không được Anthropic chứng thực và không phải là đại lý bán lại của Anthropic. Claude và các tên mô hình liên quan là nhãn hiệu của chủ sở hữu tương ứng.