Tài liệu

Nguyên nhân: API Key không hợp lệ, đã hết hạn, hoặc chưa được khai báo trong biến môi trường.

Giải pháp: Kiểm tra API Key bắt đầu bằng toc-. Đảm bảo biến ANTHROPIC_AUTH_TOKEN hoặc header Authorization đã được set đúng.

echo $ANTHROPIC_AUTH_TOKEN
# Kết quả: toc-xxxxx
# Nếu trống, chạy:
export ANTHROPIC_AUTH_TOKEN="toc-your-key-here"

Nguyên nhân: Ngân sách trong Rolling Window hiện tại đã hết.

Giải pháp: Chờ window tự động reset (xem thời gian reset trên Dashboard), hoặc mua thêm top-up credit, hoặc nâng cấp gói.

Nguyên nhân: Base URL sai hoặc thiếu. Một số tool dùng ANTHROPIC_BASE_URL, số khác dùng OPENAI_BASE_URL.

Giải pháp: Kiểm tra Base URL chính xác cho từng format:

# Anthropic format (Claude Code, v1/messages)
export ANTHROPIC_BASE_URL="https://api.techopenclaw.com"

# OpenAI format (Cursor, Codex CLI, v1/chat/completions)
export OPENAI_BASE_URL="https://api.techopenclaw.com/v1"

Nguyên nhân: Timeout mặc định của tool quá ngắn cho các request phức tạp (extended thinking, large context).

Giải pháp: Tăng timeout. Với Claude Code, set API_TIMEOUT_MS trong settings.json:

{
  "env": {
    "API_TIMEOUT_MS": "3000000"
  }
}

Nguyên nhân: Tên model nhập sai hoặc model chưa được hỗ trợ trên hệ thống.

Giải pháp: Kiểm tra tên model chính xác tại trang Danh mục Mô hình (/docs/models). Tên model phân biệt hoa/thường.

Nguyên nhân: Model đang xử lý extended thinking hoặc upstream provider đang chậm.

Giải pháp: Smart Routing sẽ tự động failover. Nếu vẫn chậm, thử giảm max_tokens hoặc tắt extended thinking để kiểm tra.

Nguyên nhân: ANTHROPIC_BASE_URL chưa được set, hoặc bị ghi đè bởi config khác.

Giải pháp: Kiểm tra thứ tự ưu tiên: biến môi trường > ~/.claude/settings.json. Chạy env | grep ANTHROPIC để xác nhận.

Nguyên nhân: Chưa cấu hình Custom Provider đúng cách hoặc đang dùng Cursor phiên bản miễn phí.

Giải pháp: Custom Model chỉ khả dụng trên Cursor Pro trở lên. Kiểm tra lại: Settings → Models → Add Custom Model → chọn OpenAI Protocol.

Nguyên nhân: Chọn sai Provider type. Phải chọn "OpenAI Compatible" thay vì "OpenAI".

Giải pháp: Trong Cline Settings, chọn Provider = OpenAI Compatible, nhập Base URL = https://api.techopenclaw.com/v1 và API Key.