Đưa model catalog vào Raycast AI với một providers.yaml.

Câu trả lời nhanh: bật Custom Providers, sửa một file.

Đường đi của Raycast cho các endpoint tương thích OpenAI là tính năng Custom Providers, nhắm tới người dùng nâng cao và tắt theo mặc định. Bật nó ở cuối mục AI trong Raycast Settings, dùng Reveal Providers Config để mở thư mục cấu hình, và sao chép providers.template.yaml có sẵn thành providers.yaml. File này sống tại ~/.config/raycast/ai/providers.yaml. Mỗi entry provider nhận một id, một tên hiển thị, một base_url, và một khối api_keys; mỗi model bạn muốn trong bộ chọn được khai báo tường minh với id, một tên hiển thị, và cửa sổ context của nó, cộng một khối abilities mô tả những gì Raycast được phép yêu cầu từ nó. Hình dạng base_url theo cùng quy ước với các ví dụ model cục bộ có sẵn, thứ trỏ vào một gốc /v1, nên giá trị của APIsRouter là https://api.apisrouter.com/v1. File này giữ credential, nên hãy đối xử với nó như bất kỳ file secret nào.

providers:
  - id: apisrouter
    name: APIsRouter
    base_url: https://api.apisrouter.com/v1
    api_keys:
      default: sk-APIsRouter-...
    models:
      - id: claude-sonnet-4-6
        name: Claude Sonnet 4.6
        context: 200000
        abilities:
          temperature:
            supported: true
          tools:
            supported: true
      - id: claude-haiku-4-5-20251001
        name: Claude Haiku 4.5
        context: 200000
        abilities:
          temperature:
            supported: true

Hai tính năng Raycast nghe giống nhau, nhưng không phải.

Raycast tài liệu hóa hai cách để mang truy cập AI của riêng bạn, và tìm kiếm một cái đáng tin cậy sẽ trồi lên cái kia, nên sự khác biệt đáng nói rõ ràng. Bring Your Own Keys, trang BYOK trong sổ tay Raycast, kết nối key cá nhân Anthropic, Google, hoặc OpenAI của bạn (OpenRouter trên iOS) tới Raycast AI. Đây là tính năng đơn giản hơn, được ghi là hoạt động không cần subscription Pro, nhưng nó không phải một endpoint tùy chỉnh: request định tuyến qua server của Raycast để hợp nhất API, và sổ tay nói rõ chỉ các model đã có sẵn trong Raycast AI mới truy cập được. Một key gateway không cắm vào đó, vì BYOK không bao giờ hỏi một URL. Custom Providers là tính năng trang này cấu hình: base_url riêng của bạn, key riêng của bạn, model riêng bạn khai báo, request đi tới nơi bạn trỏ. Đây là đường đi cho một gateway đa vendor, cho các server cục bộ, và cho bất kỳ model nào danh sách có sẵn của Raycast không mang. Cái giá là sự tường minh, Raycast không tự lấy danh sách model của endpoint cho bạn (tiện ích đó là một yêu cầu tính năng đang chờ), nên bộ chọn hiển thị đúng những gì YAML của bạn khai báo, không hơn không kém.

Khai báo model trung thực: id, context, abilities.

Vì không có tự động khám phá, YAML là một hợp đồng, và mỗi trường trong đó làm việc thực sự. Id model phải khớp chính xác danh sách /v1/models của gateway; nó là thứ đi trong request. name chỉ là nhãn Raycast hiển thị. Giá trị context báo cho Raycast biết nó có thể nhồi bao nhiêu lịch sử hội thoại vào một request, nên khai thiếu lãng phí năng lực và khai khống tạo ra các request mà model từ chối; dùng cửa sổ đã tài liệu hóa cho id bạn đang khai báo. Khối abilities là thứ người ta hay làm sai. Nó khai báo Raycast được phép dựa vào những gì: kiểm soát temperature, đầu vào hình ảnh, system message, dùng tool, mức độ lý luận. Khai báo một khả năng model không có tạo ra các thất bại runtime gây bối rối bên trong các tính năng Raycast thay vì lỗi sạch sẽ, và bỏ sót một khả năng model thực sự có sẽ âm thầm vô hiệu hóa hành vi Raycast tương ứng. Bắt đầu tối giản, temperature cộng tools cho các model bạn sẽ dùng với extension AI, và thêm khả năng khi bạn xác nhận chúng đối chiếu với tài liệu của model. Một extension Raycast do cộng đồng bảo trì tồn tại chuyên để quản lý file này từ một UI, với sao lưu tự động trước mỗi thay đổi, đáng biết nếu YAML thủ công không phải sở thích của bạn. Dù cách nào, Raycast đọc file từ đĩa, nên sau khi sửa, hãy đợi một chút hoặc bật tắt tính năng để đảm bảo bộ chọn phản ánh file hiện tại.

curl -s https://api.apisrouter.com/v1/models \
  -H "Authorization: Bearer $APISROUTER_API_KEY" | head -50
# declare these ids verbatim in providers.yaml

Chọn model cho một launcher.

Vì mọi model đã khai báo tính phí qua cùng key, vòng lặp so sánh là một lần chuyển bộ chọn: chạy cùng các lệnh nhanh trên hai id trong một ngày, rồi đọc chi tiêu theo từng model trong console và giữ lại cái nào xứng đáng với vị trí của nó.

• AI của launcher là công việc bùng nổ: tóm tắt cái này, viết lại cái kia, giải thích phần đã chọn. claude-haiku-4-5-20251001 và gemini-3.5-flash trả về trước khi hoạt ảnh cửa sổ kết thúc, đây là cảm giác người dùng Raycast mong đợi.
• Phiên AI Chat và soạn thảo dài xứng đáng với claude-sonnet-4-6 hoặc gpt-5.5; khai báo chúng cạnh tầng nhanh và chuyển đổi theo từng tác vụ trong bộ chọn.
• Các extension AI gọi tool cần một model dùng tool đáng tin cậy, và khối abilities khai báo khớp; claude-sonnet-4-6 là lựa chọn an toàn đầu tiên ở đó.
• deepseek-v4-flash là lựa chọn khối lượng cho người dùng nối AI vào mọi ô văn bản họ chạm tới; các completion nhỏ liên tục cộng dồn lại, và tầng nhanh giữ thói quen đó vô hình trên số dư.
• Khai báo ít model có chủ đích thay vì nhiều model theo suy đoán: mỗi entry là một hàng bộ chọn bạn phải cuộn qua, và YAML dễ mở rộng ngày bạn cần một id khác.

Trả theo mức sử dụng · thấp hơn giá chính thức

Selected models are priced below official list prices. Exact input, output, cache, and per-request prices are shown for each model.

Các kiểu lỗi đặc thù của Raycast.

Cấu hình BYOK khi bạn định dùng Custom Providers là lỗi cấp cao nhất, và không phải lỗi của bạn: hai tính năng chia sẻ cùng một không gian tìm kiếm. Nếu luồng bạn đang ở hỏi một key vendor nhưng không bao giờ hỏi một URL, bạn đang ở BYOK, và gateway không thuộc về đó. Quay lại Settings, AI, và toggle Custom Providers ở cuối. File bị bỏ qua thường nghĩa là toggle tính năng đang tắt, file vẫn tên providers.template.yaml, hoặc YAML có lỗi cú pháp, trong trường hợp đó Raycast không có gì hợp lệ để nạp và bộ chọn đơn giản không hiển thị model tùy chỉnh nào. Xác thực YAML trước khi nghi ngờ điều gì sâu hơn. Một model lỗi trên một số tính năng Raycast nhưng không phải tất cả là một sự không khớp abilities: các extension AI dùng tool thất bại trong khi chat thuần hoạt động khi tools được khai báo trên một model không có nó, hoặc không bao giờ được khai báo trên một model có nó. Request bị từ chối vì kích thước chỉ tới một giá trị context bị khai khống. Và hãy trung thực về ranh giới nền tảng: Custom Providers được cấu hình trên Mac, trong một file cấu hình cục bộ. Nếu một phần việc dùng Raycast của bạn ở nơi khác, hãy kiểm tra sổ tay xem tính năng hỗ trợ gì ở đó trước khi giả định tương đương.

Ai định tuyến Raycast AI qua một gateway.

• Người dùng nâng cao sống trong launcher muốn các lệnh AI nhanh trên các id catalog nhanh mà không cần một subscription quyết định họ được chạm vào model nào.
• Người đã định tuyến editor và công cụ terminal qua một gateway muốn launcher trên cùng key, một log sử dụng qua mọi bề mặt.
• Người dùng muốn các model danh sách có sẵn của Raycast không mang, gồm cả id DeepSeek và GLM, khai báo một lần trong YAML và khả dụng ở mọi nơi trong app.
• Người xây dựng extension AI cần một model có khả năng tool cụ thể sau extension của họ, ghim theo id thay vì phụ thuộc vào một danh sách lưu trữ.
• Lập trình viên không có quyền truy cập billing của một vendor cụ thể. Truy cập dựa trên nạp tiền không yêu cầu thẻ loại bỏ phụ thuộc đăng ký theo từng provider.

Xác minh endpoint và debug lệnh đầu tiên.

Chạy curl danh sách model trước và copy id từ đầu ra của nó vào YAML; gõ id từ trí nhớ là nguyên nhân hàng đầu của lỗi model-not-found ở đây, vì file này là nguồn model duy nhất Raycast có. Sau đó bật toggle, xác nhận bộ chọn hiển thị các tên đã khai báo của bạn, và chạy một lệnh AI nhanh trên model nhanh. Một bộ chọn trống là toggle, tên file, hoặc cú pháp YAML. Một lỗi xác thực là khối api_keys. Một lỗi not-found là id không khớp với danh sách bạn vừa curl. Một lệnh hoạt động trong chat nhưng thất bại trong một extension AI là khai báo abilities trên model đó. Khi các lệnh chảy qua, console APIsRouter hiển thị model theo từng request, số lượng token, và chi tiêu. AI của launcher là hàng trăm request nhỏ thay vì vài request lớn, và log sử dụng là nơi mẫu hình đó trở thành một con số, theo từng model, theo từng ngày, trên cùng trang với mọi công cụ khác bạn định tuyến qua gateway.

curl -s https://api.apisrouter.com/v1/chat/completions \
  -H "Authorization: Bearer $APISROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-haiku-4-5-20251001",
       "messages":[{"role":"user","content":"ping"}]}'

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