Penyiapan API kustom IronClaw: penyedia, kunci, dan batas privasi

IronClaw menerima API khusus dalam satu blok empat field: slot [llm.default] di ~/.ironclaw/reborn/config.toml yang memuat provider_id, base_url, model dan api_key_env — atau, jika tidak ada slot, variabel lingkungan LLM_BACKEND / LLM_BASE_URL / LLM_API_KEY yang menjadi fallback. Kedua bentuk tersebut saat ini berlaku dan terdokumentasi. Hal yang tidak dikumpulkan oleh halaman konfigurasi dalam satu tempat adalah daftar kemampuan yang kemudian tidak tersedia pada endpoint khusus — termasuk streaming native, penemuan model, breakpoint Anthropic cache_control dan tampilan biaya yang akurat — dan itulah bagian yang layak dibaca sebelum Anda memilih provider.

Satu klarifikasi terlebih dahulu, karena hasil pencarian didominasi produk lain. Halaman ini membahas github.com/nearai/ironclaw, yang dalam metadata repositorinya sendiri dijelaskan sebagai "IronClaw adalah Agent OS yang berfokus pada privasi, keamanan dan ekstensibilitas": Rust, tidak diarsipkan dan bukan fork, 12.626 bintang, dibuat pada 3 Februari 2026 dan terakhir didorong pada 21 September 2026 (GitHub API, hari yang sama). Ini bukan mouse gaming Corsair dengan nama tersebut, RPG tabletop Sanguine Productions, token kripto IRONCLAW, atau repositori JoasASantos/ironclaw yang tidak terkait — tidak satu pun harga atau konfigurasinya relevan untuk halaman ini. Dokumentasi kanonis adalah docs.ironclaw.com dan tree docs/ milik repositori; mirror Mintlify pihak ketiga muncul untuk judul yang sama dan dapat sudah usang.

Atribusi layak dikutip, bukan diparafrasekan, karena halaman milik vendor berbeda: ironclaw.com menempatkan "Built by" di samping logo NEAR dan kata-kata "Near Foundation" di isi halaman, serta "— by NEAR AI" di footer, sementara organisasi GitHub-nya adalah nearai.

Konfigurasi provider khusus IronClaw minimal

Struct slot di ironclaw_config menerima tepat empat field opsional, dan komentar dokumentasinya sendiri menjelaskannya sebagai override untuk entri katalog: model menggantikan default_model milik provider, api_key_env menggantikan api_key_env miliknya, dan base_url menggantikan default_base_url miliknya. Dokumentasi provider menambahkan bahwa base_url "juga berfungsi pada provider lain ketika Anda perlu merutekannya melalui proxy atau endpoint regional" — jadi ini bukan hanya fitur adapter generik.

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

Tiga aturan yang penting. Menghilangkan base_url berakibat fatal, bukan menggunakan default: dokumentasi menyatakan bahwa hal tersebut "membiarkan slot menunjuk ke mana pun dan resolusi model gagal", dan entri katalog openai_compatible memiliki base_url_required: true. api_key_env menerima nama variabel, bukan kunci — rahasia yang ditempelkan akan "ditolak saat parsing, bukan diterima secara diam-diam", sedangkan ironclaw config set <provider>.api_key meminta input dengan menyembunyikannya. Tidak ada yang berlaku sampai dimulai ulang: config set "tidak pernah memulai ulang apa pun", melainkan mencetak langkah ironclaw service restart yang masih harus Anda jalankan. Dan jangan berharap config set menulis slot tersebut untuk Anda — halaman konfigurasi mencantumkan [llm.default] di antara bagian yang "diedit langsung di config.toml", dan config set "menolak kunci yang tidak didukung, bukan diam-diam tidak melakukan apa-apa".

Bentuk lingkungan adalah fallback terdokumentasi ketika [llm.default] tidak ada, dan dokumentasi menjelaskan pilihan tersebut secara langsung: "Keduanya berfungsi … Utamakan slot TOML untuk instalasi permanen, dan bentuk lingkungan untuk eksekusi satu kali serta 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

Urutan resolusi adalah compiled defaults < config.toml < environment variables < CLI flags, sehingga variabel yang diekspor secara diam-diam mengungguli file yang baru saja Anda edit. Rute CLI menghindari pengeditan manual sepenuhnya: ironclaw models list, lalu ironclaw models set-provider <id> --model <model>, lalu ironclaw models status. Konfirmasikan path Anda dengan ironclaw config path, bukan mempercayai salah satu lokasi yang terdokumentasi — halaman quickstart menyatakan semuanya berada di bawah ~/.ironclaw, sedangkan halaman konfigurasi dan onboarding menyatakan ~/.ironclaw/reborn. Satu jebakan operasional bagi pengguna hosted: halaman konfigurasi menyatakan bahwa perintah ironclaw service "tidak berfungsi pada instance NEAR AI hosted — tidak ada pengelola layanan pengguna yang dapat diajak berkomunikasi", sehingga Anda harus masuk melalui SSH untuk ironclaw config dan memulai ulang dari Agent Dashboard. Semua kutipan dibaca dari branch main pada 21 September 2026.

Hal yang tidak dapat dijangkau oleh endpoint khusus

Ini adalah pernyataan IronClaw sendiri tentang perilaku runtime yang dimaksudkan, dibaca dari file sumber dan kontrak pada main. Pernyataan ini bukan hasil eksekusi yang diamati, dan main sudah lebih baru daripada tag rilis 1.4.0 — yang dipublikasikan pada 28 Agustus 2026, menurut GitHub releases API — saat pernyataan tersebut dibaca.

Katalog IronClaw adalah katalog chat, dan Kunavo tidak menyediakan model embedding, text-to-speech, atau speech-to-text, jadi bagian mana pun dari setup Anda yang membutuhkannya harus diarahkan sepenuhnya ke tempat lain.

Tampilan biaya IronClaw bukan tagihan Anda

Dua jalur terpisah menghitung biaya di dalam IronClaw, hasilnya berbeda, dan tidak satu pun membaca provider Anda. price_usage() di ironclaw_common menentukan harga dari tabel hard-code per token dan menggunakan default_cost() sebagai fallback — 0.0000025 untuk input dan 0.00001 per token, setara GPT-4o sebesar $2,50 / $10,00 per juta — dengan alasan yang dinyatakan bahwa "model berbayar baru tidak pernah secara diam-diam dihargai nol". Sementara itu, StaticModelCostTable milik loop host melakukan kebalikan untuk reservasi anggaran: profil yang tidak ada di tabelnya "menggunakan None sebagai fallback, yang diperlakukan akuntan sebagai biaya nol". Pada jalur llm_costs, diskon pembacaan cache ditebak dari nama model berdasarkan substring — claude membaginya sepuluh, gpt atau prefiks o1/o3/o4 membaginya dua, dan lainnya membaginya satu.

Konsekuensi praktisnya adalah budget.user_daily_usd, budget.pause_at dan key [budget] lainnya milik IronClaw mengawasi estimasi, bukan tagihan. Key tersebut tetap layak diatur pada agen yang selalu aktif — loop yang tidak terkendali dihentikan lebih awal adalah tujuannya — tetapi cocokkan dengan penggunaan yang dicatat provider Anda, bukan dengan angka di layar.

Contoh estimasi untuk satu hari agen

Ini adalah perhitungan token, bukan biaya tugas yang diukur dan bukan batas atas tagihan. Asumsikan aktivitas agen selama satu hari berjumlah 1.000.000 token input tanpa cache dan 40.000 token output — asumsi untuk ilustrasi, dipilih karena runtime yang selalu aktif mengakumulasi input melalui tick heartbeat dan rutinitas, bukan melalui balasan panjang. Tarifnya adalah harga katalog Kunavo saat ini per juta token.

Kolom terakhir adalah kejutan yang berguna, dan merupakan properti string id, bukan modelnya. vision_models.rs mencocokkan substring dengan daftar tetap yang mencakup claude-opus-, claude-sonnet-, claude-haiku- dan claude-fable-, sehingga id tersebut meneruskan lampiran gambar; id lainnya dalam tabel di atas tidak cocok dengan gpt-4o, gemini-1.5, gemini-2 maupun bagian lain dari daftar tersebut dan akan diklasifikasikan sebagai hanya teks. Jika tidak cocok, gateway loop-host mengirim teks pesan tanpa bagian gambar dan tidak menimbulkan error — transkrip persisten menyimpan pointer <attachments>, tetapi model tidak pernah melihat gambarnya. Baca daftar pola berdasarkan id persis yang ingin Anda ketik sebelum menganggap input gambar berfungsi. Kalikan angka dolar dengan jumlah hari Anda sendiri sebelum menjadikannya anggaran. Jumlah katalog Kunavo adalah dasar penagihan, bukan batas maksimum: ketika upstream melaporkan biayanya, tagihan adalah nilai yang lebih besar antara biaya katalog dan biaya upstream dikalikan markup yang berlaku. Biaya cache dan alat eksternal berada di luar contoh ini, dan top-up minimum adalah $10 dalam kredit prabayar — minimum pendanaan, bukan biaya tugas atau langganan. Lihat detail penagihan.

Rute mana yang menang, dan berapa biaya IronClaw itu sendiri

Perangkat lunaknya gratis: root repositori memuat LICENSE-APACHE dan LICENSE-MIT, dan README-nya menyatakan MIT OR Apache 2.0. Tidak ada edisi berbayar untuk biner tersebut dan tidak ada biaya lisensi. Yang Anda bayar adalah token, ditambah hosting jika menggunakan hosting vendor.

Harga paket hosted yang dibaca dari ironclaw.com pada 21 September 2026; tidak ada halaman /pricing, paket tersebut berada di beranda, dan markup yang dirender menampilkan $5 di dalam span yang dicoret dengan $0 sebagai harga aktif. Beranda juga menyatakan "Nyalakan hingga 5 agen dalam Trusted Execution Environment dengan hingga 130M token per bulan" — kalimat tersebut berada di atas ketiga kartu dan tidak menyebut paket, jadi jangan kaitkan dengan salah satunya. Tiga hal yang tidak dapat ditetapkan oleh panduan ini dan tidak akan ditebak: apakah paket hosted mengizinkan key pihak ketiga, apa yang sebenarnya dibeli oleh kredit yang disertakan atau apa yang terjadi saat kredit habis, dan paket mana yang memiliki angka 130M tersebut. Tarif token dibaca dari near.ai/pricing pada hari yang sama, yang menyatakan "Tidak ada biaya platform di atas tarif model" dan hanya mencakup model teks rahasia miliknya.

Satu batas privasi yang perlu dinyatakan dengan jelas, karena itulah alasan orang memilih runtime ini. Kontrol yang dijelaskan oleh README dan halaman keamanan IronClaw sendiri — secret "dienkripsi saat tidak aktif" dan disuntikkan pada batas host, sandbox WASM untuk alat yang tidak tepercaya, allowlisting endpoint, deteksi kebocoran — adalah kontrol lokal atas mesin yang menjalankan agen. Attestation perangkat keras adalah properti terpisah milik NEAR AI Cloud: near.ai menyatakan bahwa inferensi di sana "dieksekusi dalam enclave confidential-GPU Intel TDX + NVIDIA" dan bahwa "setiap respons membawa hardware quote yang dapat diverifikasi". Mengarahkan IronClaw ke endpoint pihak ketiga mengirimkan isi prompt ke endpoint tersebut berdasarkan ketentuannya, dan tidak ada bagian dari kedua daftar tersebut yang mengikutinya ke sana. Tabel vendor-authored "OpenClaw vs IronClaw" di ironclaw.com adalah pemasaran dari satu pihak, bukan perbandingan netral — dan berhati-hatilah dengan hasil pencarian, karena dalam sampel halaman hasil yang diambil pada 17 September 2026, keempat bentuk kueri best api for ironclaw, cheapest api for ironclaw, best model for ironclaw dan ironclaw custom provider masing-masing menghasilkan delapan atau lebih hasil OpenClaw di sepuluh teratas, yang peringkat modelnya menggambarkan produk berbeda.

Siapkan, lalu periksa tagihan pertama

Kunavo menerbitkan endpoint berbentuk OpenAI di https://api.kunavo.com/v1 dan endpoint berbentuk Anthropic, yang dipetakan ke id provider openai_compatible dan anthropic. Kunavo belum menguji IronClaw saat runtime, jadi perlakukan blok di atas sebagai titik awal berdasarkan protokol terdokumentasi, bukan klaim kompatibilitas: pertahankan rute yang berfungsi, jalankan satu tugas terbatas, dan baca biaya yang benar-benar dicatat oleh akun Anda. Jika Anda menjalankan Goose dari IronClaw melalui ACP — .env.example mendokumentasikan sandbox Agent Client Protocol dan perintah ironclaw acp add goose — integrasi Goose membahas sisi tersebut secara terpisah, dan membuat akun Kunavo akan mendanai key saat Anda siap. Untuk pilihan di sekitarnya, lihat referensi API OpenAI-compatible, alternatif OpenRouter dan optimisasi biaya AI.

Pertanyaan umum

Metadata repositori, providers.json, CONTRACT.md, llm_costs.rs, vision_models.rs, tree docs/, ironclaw.com dan near.ai/pricing semuanya dibaca pada 21 September 2026, dari branch main, bukan tag rilis 1.4.0. Tidak ada permintaan IronClaw yang dikirim ke endpoint Kunavo; setiap pernyataan kompatibilitas di sini merupakan pembacaan dokumentasi kedua pihak. Tarif token Kunavo berasal dari katalog aktif, dan setiap contoh dolar adalah perhitungan token ilustratif.