Chạy Factory Droid với Claude

Droid của Factory là một CLI dạng tác nhân cùng loại với Claude Code, cho phép bạn dùng mô hình riêng thông qua tệp cấu hình. Khi trỏ đến cổng kết nối AI Prime Tech, các vòng lặp tác nhân của Droid chạy trên Claude, bên cạnh mọi mô hình khác mà cổng kết nối cung cấp.

Chỉnh sửa tệp cài đặt

Droid đọc ~/.factory/settings.json. Thêm một mảng customModels, trong đó mỗi mục mô tả một mô hình bạn muốn sử dụng. Đây là đường dẫn cấu hình hiện hành; config.json cũ là cấu hình kế thừa và không hỗ trợ đầy đủ những gì settings.json hỗ trợ.

Một tệp bao quát toàn bộ thiết lập Droid của bạn, nên một danh sách customModels duy nhất xác định tất cả các mô hình mà CLI có thể chuyển đổi qua lại. Hãy lưu cấu hình ở cấp người dùng thay vì theo từng dự án.

Biết rằng settings.json là tệp hiện hành giúp tránh nhiều nhầm lẫn, vì các ghi chú và chủ đề thảo luận cũ vẫn nhắc đến config.json, còn một số tính năng hoạt động khác nhau giữa hai tệp. Khi một tính năng hoạt động ở nơi này nhưng không hoạt động ở nơi kia, settings.json gần như luôn là tệp nên tin cậy. Khi các hướng dẫn mâu thuẫn, ưu tiên settings.json thay cho config.json sẽ giải quyết phần lớn vấn đề. Tệp mới hơn là tệp được Factory hỗ trợ tích cực, và đó là nơi cú pháp biến thực sự hoạt động.

Mô tả mô hình

Mỗi mục customModels nhận một ID mô hình, một baseUrl, một apiKey, một provider và maxOutputTokens. Đặt model thành ID trên cổng kết nối, chẳng hạn claude-sonnet-4-5, và baseUrl thành địa chỉ máy chủ của cổng kết nối.

Các trường này kết hợp với nhau để cho Droid biết chính xác cách truy cập mô hình. Vì Droid không mặc định dùng một nhà cung cấp duy nhất, bạn cần chỉ định rõ từng thành phần; nhờ đó, Droid đủ linh hoạt để kết nối đến một cổng kết nối.

Việc chỉ định rõ như vậy cho phép một bản cài đặt Droid cung cấp quyền truy cập vào nhiều mô hình Claude trên cùng một cổng kết nối, mỗi mô hình là một mục customModels riêng dùng chung baseUrl và khóa. CLI coi chúng là các mô hình riêng biệt có thể lựa chọn, dù tất cả đều trỏ đến cùng một điểm cuối phía thượng nguồn. Chính các trường được chỉ định rõ cho phép một bản cài đặt truy cập nhiều mô hình Claude qua một điểm cuối. Mỗi mục dùng chung baseUrl và khóa nhưng giữ ID mô hình riêng, nên cổng kết nối thực hiện định tuyến còn Droid chỉ cần chọn tên.

Chọn chế độ nhà cung cấp

Trường provider thiết lập định dạng truyền dữ liệu. Dùng anthropic cho giao diện Messages gốc của cổng kết nối, openai cho kiểu Responses, hoặc generic-chat-completion-api cho điểm cuối chat /v1 theo kiểu OpenAI. Với Claude trên cổng kết nối, anthropic là lựa chọn phù hợp tự nhiên.

Đặt provider khớp với giao diện thực tế của cổng kết nối giúp tránh lỗi khi chạy lần đầu. Với provider anthropic, Droid sử dụng định dạng gốc mà cổng kết nối cung cấp cho Claude.

Ba chế độ nhà cung cấp cũng tương ứng rõ ràng với các giao diện mà một cổng kết nối đa mô hình có thể cung cấp, nên nếu cùng cổng kết nối đó cung cấp một mô hình theo kiểu OpenAI, bạn sẽ thêm mô hình ấy dưới dạng một mục riêng với generic-chat-completion-api. Giữ provider của từng mục khớp với giao diện tương ứng là nguyên tắc giúp cấu hình hỗn hợp không gặp lỗi. Đặt provider khớp với giao diện trong mọi mục là nguyên tắc giúp cấu hình cổng kết nối hỗn hợp hoạt động suôn sẻ. Một mục Claude gốc và một mục theo kiểu OpenAI có thể cùng tồn tại mà không gây xung đột.

Xử lý khóa API

Đặt khóa trong apiKey, tốt nhất dưới dạng tham chiếu ${VAR} như ${AIPRIME_API_KEY} để thông tin bí mật nằm trong môi trường thay vì trong tệp. Lưu ý rằng việc mở rộng ${VAR} hoạt động trong settings.json nhưng không hoạt động trong config.json cũ.

Trường apiKey cũng không được để trống, ngay cả khi cổng kết nối về mặt kỹ thuật có thể chấp nhận yêu cầu ẩn danh. Droid kiểm tra để đảm bảo trường này có giá trị, nên luôn cung cấp khóa hoặc biến chứa khóa đó.

Hai điều này giải thích một lỗi thường gặp: người dùng đặt ${VAR} trong config.json cũ, nơi biến không được mở rộng, và Droid nhận một chuỗi nguyên văn chưa được phân giải. Hãy dùng settings.json cho dạng biến và đảm bảo biến thực sự được xuất trong shell khởi chạy Droid. Xác nhận biến đã được xuất trong shell khởi chạy là bước cuối cùng mà mọi người thường bỏ sót. Droid chỉ thấy các biến có trong môi trường đã khởi chạy nó.

Chuyển đổi và chạy

Trong Droid CLI, chuyển đổi giữa các mô hình đã cấu hình bằng lệnh /model. Thêm một mục thứ hai cho claude-opus-4-8 và bạn có thể chuyển sang mô hình đó cho các tác vụ khó hơn mà không cần sửa lại cấu hình.

Từ đó, Droid chạy vòng lặp tác nhân với Claude trên cổng kết nối. Vì thiết lập nằm trong settings.json, cùng một cấu hình được áp dụng mỗi lần bạn khởi động CLI.

Chuẩn bị sẵn cả mục Sonnet lẫn Opus giúp bạn chọn mô hình phù hợp với tác vụ ngay trong lúc làm việc — Sonnet cho công việc triển khai thường xuyên, Opus khi vấn đề cần suy luận sâu hơn — tất cả đều qua cổng kết nối mà không cần cấu hình lại. Lệnh chuyển đổi /model giúp bạn thực hiện thay đổi đó bằng một dòng ngay giữa phiên. Việc chuyển đổi bằng một dòng /model giữa phiên giúp chọn mô hình theo tác vụ trở nên dễ dàng. Bạn chuyển từ Sonnet sang Opus mà không cần rời khỏi phiên.

// ~/.factory/settings.json
{
  "customModels": [
    {
      "model": "claude-sonnet-4-5",
      "baseUrl": "https://aiprimetech.io",
      "apiKey": "${AIPRIME_API_KEY}",
      "provider": "anthropic",
      "maxOutputTokens": 8192
    }
  ]
}
// export AIPRIME_API_KEY=<key>   (apiKey must NOT be empty)
// Switch models in the CLI with /model

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.