Thiết lập API tùy chỉnh IronClaw: nhà cung cấp, khóa và ranh giới riêng tư

IronClaw nhận API tùy chỉnh trong một khối gồm bốn trường: một slot [llm.default] trong ~/.ironclaw/reborn/config.toml chứa provider_id, base_url, model và api_key_env — hoặc, khi không có slot, các biến môi trường LLM_BACKEND / LLM_BASE_URL / LLM_API_KEY mà nó dự phòng sử dụng. Cả hai hình thức đều hiện hành và được tài liệu hóa. Điều mà các trang cấu hình không thu thập ở một nơi duy nhất là danh sách những thứ mà một endpoint tùy chỉnh sau đó không có được — trong đó có streaming trực tiếp, khám phá model, các điểm ngắt Anthropic cache_control và hiển thị chi phí chính xác — và đó là phần đáng đọc trước khi bạn chọn nhà cung cấp.

Trước hết cần phân biệt rõ, vì kết quả tìm kiếm bị chi phối bởi các sản phẩm khác. Trang này nói về github.com/nearai/ironclaw, được chính siêu dữ liệu của kho mã mô tả là "IronClaw là một hệ điều hành dành cho tác nhân, tập trung vào quyền riêng tư, bảo mật và khả năng mở rộng": viết bằng Rust, chưa được đưa vào trạng thái lưu trữ và không phải bản fork, có 12.626 sao, được tạo ngày 3 tháng 2 năm 2026 và được đẩy mã lên lần cuối ngày 21 tháng 9 năm 2026 (theo GitHub API, cùng ngày). Đây không phải chuột chơi game Corsair cùng tên, trò chơi nhập vai trên bàn của Sanguine Productions, token tiền mã hóa IRONCLAW, hay kho mã JoasASantos/ironclaw không liên quan — giá cả hoặc cấu hình của bất kỳ mục nào trong số đó không thuộc về trang này. Tài liệu chính thức là docs.ironclaw.com và cây thư mục docs/ của chính kho mã; một bản sao trên Mintlify của bên thứ ba xuất hiện trong kết quả tìm kiếm với cùng các tiêu đề và có thể đã lỗi thời.

Việc ghi công đáng được trích dẫn thay vì diễn giải, vì các giao diện riêng của nhà cung cấp khác nhau: ironclaw.com đặt "Built by" cạnh logo NEAR và dòng chữ "Near Foundation" trong nội dung, cùng "— by NEAR AI" ở chân trang, trong khi tổ chức GitHub là nearai.

Cấu hình provider tùy chỉnh tối thiểu của IronClaw

Cấu trúc slot trong ironclaw_config chấp nhận chính xác bốn trường tùy chọn, và các chú thích tài liệu của chính nó mô tả chúng là các giá trị ghi đè mục catalog: model ghi đè default_model của provider, api_key_env ghi đè api_key_env của nó, và base_url ghi đè default_base_url của nó. Tài liệu provider bổ sung rằng base_url "cũng hoạt động trên bất kỳ provider nào khác khi bạn cần định tuyến nó qua proxy hoặc endpoint theo khu vực" — vì vậy đây không chỉ là tính năng của generic adapter.

[llm.default]
provider_id = "openai_compatible"
base_url    = "https://api.kunavo.com/v1"
model       = "claude-sonnet-4-6"
api_key_env = "LLM_API_KEY"

Ba quy tắc dễ gây lỗi. Bỏ qua base_url là lỗi nghiêm trọng, không có giá trị mặc định: tài liệu nói rằng điều đó "khiến slot không trỏ đến đâu và việc phân giải model thất bại", còn mục catalog openai_compatible chứa base_url_required: true. api_key_env nhận tên biến, không bao giờ nhận key — secret được dán trực tiếp sẽ bị "từ chối tại thời điểm phân tích cú pháp, không được chấp nhận âm thầm", và ironclaw config set <provider>.api_key thay vào đó sẽ yêu cầu nhập với nội dung được ẩn. Không có gì được áp dụng cho đến khi khởi động lại: config set "không bao giờ khởi động lại bất kỳ thứ gì", nó in ra bước ironclaw service restart mà bạn vẫn phải chạy. Và đừng mong config set ghi slot thay cho bạn — trang cấu hình liệt kê [llm.default] trong số các phần được "chỉnh sửa trực tiếp trong config.toml", còn config set "từ chối key không được hỗ trợ thay vì âm thầm không làm gì".

Dạng môi trường là phương án dự phòng được tài liệu hóa khi không có [llm.default], và tài liệu nêu rõ lựa chọn này: "Cả hai đều hoạt động … Ưu tiên slot TOML cho cài đặt lâu dài, và dạng môi trường cho các lần chạy một lần cùng container."

export LLM_BACKEND=openai_compatible
export LLM_BASE_URL=https://api.kunavo.com/v1
export LLM_API_KEY=sk-kn-...
export LLM_MODEL=claude-sonnet-4-6

# optional: LLM_EXTRA_HEADERS is the openai_compatible entry's
# extra_headers_env; the timeout is a general .env.example setting
export LLM_EXTRA_HEADERS=X-Title:MyAgent
export LLM_REQUEST_TIMEOUT_SECS=120

Thứ tự phân giải là compiled defaults < config.toml < environment variables < CLI flags, vì vậy một biến đã export sẽ âm thầm được ưu tiên hơn file bạn vừa chỉnh sửa. Tuyến CLI hoàn toàn tránh việc chỉnh sửa thủ công: ironclaw models list, rồi ironclaw models set-provider <id> --model <model>, rồi ironclaw models status. Xác nhận các đường dẫn bằng ironclaw config path thay vì tin tuyệt đối vào một trong hai vị trí được tài liệu hóa — trang quickstart nói mọi thứ nằm dưới ~/.ironclaw, trong khi các trang cấu hình và onboarding nói ~/.ironclaw/reborn. Một bẫy vận hành đối với người dùng hosted: trang cấu hình nói các lệnh ironclaw service "không hoạt động trên một instance NEAR AI hosted — không có trình quản lý service người dùng để chúng giao tiếp", vì vậy bạn phải SSH vào để chạy ironclaw config và khởi động lại từ Agent Dashboard. Tất cả trích dẫn đều được đọc từ nhánh main vào ngày 21 tháng 9 năm 2026.

Những gì một endpoint tùy chỉnh không thể tiếp cận

Đây là các tuyên bố riêng của IronClaw về hành vi runtime dự kiến, được đọc từ source và các file contract trên main. Chúng không phải các lần chạy quan sát được, và main đã đi trước tag phát hành 1.4.0 — được công bố ngày 28 tháng 8 năm 2026, theo GitHub releases API — tại thời điểm chúng được đọc.

Catalog của IronClaw là catalog chat, còn Kunavo không cung cấp model embedding, text-to-speech hoặc speech-to-text, vì vậy bất kỳ phần nào trong thiết lập của bạn cần một loại model như vậy đều phải trỏ hoàn toàn sang nơi khác.

Hiển thị chi phí của IronClaw không phải hóa đơn của bạn

Có hai đường dẫn riêng biệt tính tiền bên trong IronClaw, chúng không nhất quán với nhau, và không đường dẫn nào đọc provider của bạn. price_usage() trong ironclaw_common định giá từ bảng hardcode theo từng token và rơi về default_cost() — 0.0000025 input và 0.00001 mỗi token, tương đương mức $2,50 / $10,00 trên mỗi một triệu token theo hình dạng GPT-4o — với lý do được nêu là "model trả phí mới sẽ không bao giờ âm thầm được định giá bằng không". Trong khi đó, StaticModelCostTable của loop host làm điều ngược lại đối với việc tạm giữ ngân sách: một profile không có trong bảng của nó "rơi về None, thứ mà bộ phận kế toán coi là không tốn chi phí". Và trên đường dẫn llm_costs, mức giảm giá đọc từ cache được đoán từ tên model bằng chuỗi con — claude chia cho mười, gpt hoặc tiền tố o1/o3/o4 chia cho hai, mọi thứ khác chia cho một.

Hệ quả thực tế là budget.user_daily_usd, budget.pause_at và các key còn lại trong [budget] của IronClaw kiểm soát một ước tính, không phải một khoản phí. Chúng vẫn đáng được thiết lập trên một agent luôn bật — dừng sớm một vòng lặp chạy mất kiểm soát mới là mục tiêu — nhưng hãy đối soát với mức sử dụng mà provider của bạn ghi nhận, không phải con số trên màn hình.

Một ước tính mẫu cho một ngày của agent

Đây là phép tính token, không phải chi phí tác vụ được đo lường và không phải trần hóa đơn. Giả sử một ngày hoạt động của agent tổng cộng 1.000.000 token input không cache và 40.000 token output — một giả định để minh họa, được chọn vì runtime luôn bật tích lũy input thông qua các nhịp heartbeat và routine thay vì các câu trả lời dài. Mức giá là giá catalog Kunavo hiện hành trên mỗi một triệu token.

Cột cuối là điều bất ngờ hữu ích, và nó là thuộc tính của chuỗi id chứ không phải của model. vision_models.rs so khớp chuỗi con với một danh sách cố định bao gồm claude-opus-, claude-sonnet-, claude-haiku- và claude-fable-, vì vậy các id đó định tuyến tệp đính kèm hình ảnh; các id khác trong bảng trên không khớp với bất kỳ mục nào trong gpt-4o, gemini-1.5, gemini-2 hoặc phần còn lại của danh sách và sẽ được phân loại là chỉ văn bản. Khi không khớp, gateway loop-host gửi văn bản message mà không có các phần hình ảnh và không tạo lỗi — transcript lâu dài vẫn giữ một con trỏ <attachments>, nhưng model không nhìn thấy hình ảnh. Hãy đối chiếu danh sách mẫu với đúng id bạn định nhập trước khi cho rằng đầu vào hình ảnh hoạt động. Hãy nhân các con số dollar theo số ngày của riêng bạn trước khi coi chúng là ngân sách. Số tiền trong catalog của Kunavo là mức sàn thanh toán chứ không phải mức trần: khi upstream báo cáo khoản phí, hóa đơn là giá trị lớn hơn giữa chi phí catalog và chi phí upstream nhân với markup áp dụng. Phí bộ nhớ đệm và tool bên ngoài nằm ngoài ví dụ này, và mức nạp thêm tối thiểu là $10 tín dụng trả trước — mức tối thiểu để nạp tiền, không phải phí tác vụ hay phí thuê bao. Xem chi tiết thanh toán.

Tuyến nào thắng, và bản thân IronClaw tốn bao nhiêu

Phần mềm miễn phí: thư mục gốc của repository chứa cả LICENSE-APACHE và LICENSE-MIT, còn README nêu giấy phép MIT OR Apache 2.0. Không có bản binary trả phí và không có phí giấy phép. Khoản bạn trả là token, cộng thêm chi phí hosting nếu bạn sử dụng hosting của nhà cung cấp.

Giá các gói lưu trữ được đọc từ ironclaw.com vào ngày 21 tháng 9 năm 2026; không có trang /pricing, các gói nằm trên trang chủ, và mã đánh dấu được kết xuất hiển thị $5 bên trong một span bị gạch ngang, còn $0 là giá hiện hành. Trang chủ cũng tuyên bố "Khởi chạy tối đa 5 tác nhân trong Môi trường thực thi tin cậy với tối đa 130 triệu token mỗi tháng" — câu này nằm phía trên cả ba thẻ và không nêu tên gói nào, vì vậy đừng gắn nó với một gói cụ thể. Ba điều mà hướng dẫn này không thể xác định và sẽ không phỏng đoán: liệu các gói lưu trữ có cho phép sử dụng khóa của bên thứ ba hay không, khoản tín dụng đi kèm thực sự mua được gì hoặc điều gì xảy ra khi dùng hết, và con số 130 triệu thuộc về gói nào. Mức giá token được đọc từ near.ai/pricing cùng ngày; trang này nêu rằng "Không có phí nền tảng cộng thêm vào mức giá của mô hình" và chỉ bao gồm các mô hình văn bản bảo mật của họ.

Cần nêu rõ một ranh giới về quyền riêng tư, vì đó là lý do mọi người chọn môi trường chạy này. Các biện pháp kiểm soát mà README và trang bảo mật của chính IronClaw mô tả — các bí mật được "mã hóa khi lưu trữ" và được đưa vào tại ranh giới máy chủ, hộp cát WASM dành cho các công cụ không đáng tin cậy, danh sách cho phép các điểm cuối, phát hiện rò rỉ — là các biện pháp kiểm soát cục bộ trên máy chạy tác nhân. Chứng thực phần cứng là một thuộc tính riêng của NEAR AI Cloud: near.ai nói rằng việc suy luận ở đó "được thực thi trong một vùng cách ly Intel TDX + GPU bảo mật NVIDIA" và rằng "mỗi phản hồi đều kèm theo một bản chứng thực phần cứng có thể xác minh". Việc trỏ IronClaw đến một điểm cuối của bên thứ ba sẽ gửi nội dung lời nhắc đến điểm cuối đó theo các điều khoản của điểm cuối đó, và không có biện pháp nào trong hai danh sách trên đi theo nội dung đến đó. Bảng "OpenClaw vs IronClaw" do nhà cung cấp viết trên ironclaw.com là hoạt động tiếp thị từ một phía, không phải so sánh trung lập — và hãy cẩn thận với kết quả tìm kiếm, vì trong một mẫu trang kết quả lấy ngày 17 tháng 9 năm 2026, bốn dạng truy vấn best api for ironclaw, cheapest api for ironclaw, best model for ironclaw và ironclaw custom provider mỗi dạng đều trả về từ tám kết quả OpenClaw trở lên trong mười kết quả đầu, mà các bảng xếp hạng mô hình trong đó mô tả một sản phẩm khác.

Thiết lập xong, rồi kiểm tra khoản phí đầu tiên

Kunavo công bố một endpoint dạng OpenAI tại https://api.kunavo.com/v1 và một endpoint dạng Anthropic, lần lượt ánh xạ tới các provider id openai_compatible và anthropic. Kunavo chưa kiểm thử IronClaw trong runtime, vì vậy hãy xem khối trên là điểm bắt đầu dựa trên giao thức được tài liệu hóa, không phải tuyên bố tương thích: duy trì một tuyến hoạt động, chạy một tác vụ có giới hạn và đọc khoản phí mà tài khoản của bạn thực sự ghi nhận. Nếu bạn điều khiển Goose từ IronClaw qua ACP — .env.example tài liệu hóa sandbox Agent Client Protocol và lệnh ironclaw acp add goose — thì phần tích hợp Goose bao quát riêng phía đó, còn tạo tài khoản Kunavo là bước để nạp tiền cho một khóa khi bạn sẵn sàng. Đối với các lựa chọn liên quan, xem tài liệu tham khảo API tương thích OpenAI, các lựa chọn thay thế OpenRouter và tối ưu hóa chi phí AI.

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

Metadata repository, providers.json, CONTRACT.md, llm_costs.rs, vision_models.rs, cây docs/, ironclaw.com và near.ai/pricing đều được đọc vào ngày 21 tháng 9 năm 2026 từ nhánh main thay vì tag phát hành 1.4.0. Chưa có request IronClaw nào được gửi đến endpoint Kunavo; mọi tuyên bố về khả năng tương thích ở đây đều là việc đọc tài liệu của cả hai phía. Mức giá token Kunavo lấy từ catalog hiện hành, và mọi ví dụ dollar đều là phép tính token mang tính minh họa.