API khusus Hermes Agent: provider, transport, dan pemeriksaan panggilan pertama

Endpoint kustom Hermes Agent dikonfigurasi secara outbound, sebagai entri bernama di bawah providers: dalam ~/.hermes/config.yaml, dengan api sebagai base URL dan transport sebagai protokol wire. Itu berbeda dari server API milik Hermes sendiri, yang mengarah ke inbound. Keduanya disebut “Hermes custom API” dalam hasil pencarian, dan halaman dokumentasi resmi untuk masing-masing mendapat peringkat untuk kueri yang sama — jadi perbaiki arahnya terlebih dahulu.

Halaman ini membahas Hermes Agent, agen sumber terbuka dari Nous Research. Pemeriksaan terhadap GitHub API pada 21 September 2026 mengembalikan archived: false, disabled: false, lisensi MIT, dan push pada hari yang sama; rilis terbitan terbaru adalah Hermes Agent v0.21.3, diberi tag v2026.9.14 pada 14 September 2026, bukan prerelease. Sumber yang digunakan halaman ini untuk konfigurasi adalah repositori tersebut dan hermes-agent.nousresearch.com. hermes-agent.org mencakup proyek yang sama dari domain di luar nousresearch.com dan memuat analitik Microsoft Clarity (diperiksa 21 September 2026); itu bukan sumber milik proyek, jadi jangan mengambil konfigurasi darinya. Ini juga bukan Hermes 3 atau Hermes 4, keluarga model open-weight Nous, dan bukan mesin JavaScript dengan nama yang sama.

Dua hal berlawanan yang disebut Hermes custom API

Kedua baris dikutip dari halaman Hermes sendiri, dibaca pada 21 September 2026: referensi provider dan halaman server API. Satu perbedaan penamaan yang perlu diperiksa dalam instalasi Anda sendiri: halaman server API mendokumentasikan hermes gateway sebagai perintah untuk menjalankannya, sedangkan referensi CLI menjelaskan hermes gateway sebagai pengelola layanan pesan dengan subperintah run, start, stop dan status. Jalankan hermes gateway --help alih-alih menebak. Semua bagian di bawah ini adalah sisi outbound.

Konfigurasi outbound minimum

# ~/.hermes/config.yaml
providers:
  kunavo:
    api: https://api.kunavo.com/v1   # aliases accepted: base_url, url
    key_env: KUNAVO_API_KEY          # or inline api_key:, or key_cmd:
    transport: chat_completions      # set it by hand; see the transport section
    models:
      claude-sonnet-5:
        prompt_caching: true

model:
  default: claude-sonnet-5
  provider: custom:kunavo

KUNAVO_API_KEY=your-key

Dari referensi provider, berdasarkan setiap kolom: key konfigurasi adalah providers.<name>, kolom base URL adalah api (dengan base_url dan url diterima sebagai alias), kredensialnya adalah key_env, berupa api_key inline atau key_cmd, dan protokolnya adalah transport. Entri yang sama juga menerima name, default_model, models, context_length, discover_models, extra_body, extra_headers, session_affinity_header, ssl_ca_cert / ssl_verify, catalog_provider dan enabled: false. Pilih entri dengan model.provider: custom:kunavo, atau di tengah sesi dengan /model custom:kunavo:<model-id>.

Dua perintah ini tidak dapat dipertukarkan. hermes model, yang dijalankan di luar sesi chat, adalah wizard penyiapan provider lengkap dan satu-satunya hal yang dapat menambahkan provider atau mengambil key. /model di dalam sesi hanya beralih di antara konfigurasi yang sudah ada. Untuk endpoint enterprise yang menerbitkan token berumur pendek, key_cmd adalah perintah yang mencetak token ke stdout — mentah, atau sebagai JSON dengan kolom access_token — yang dijalankan Hermes dan di-cache hingga sesaat sebelum kedaluwarsa, serta mengungguli api_key atau key_env statis pada entri yang sama.

Pilih transport secara manual alih-alih membiarkan kolom kosong

Referensi provider mencantumkan tiga nilai yang diterima untuk transport pada entri kustom. Referensi itu juga menyatakan bahwa wizard hermes model Custom Endpoint kini meminta protokol secara eksplisit dan menyimpan jawabannya ke config.yaml, serta bahwa deteksi otomatis berbasis URL “masih dilakukan sebagai fallback ketika kolom dibiarkan kosong”. Satu aturan deteksi yang dijelaskan dokumentasi adalah jalur /anthropic yang dipetakan ke anthropic_messages, yang tidak cocok dengan base URL Kunavo; heuristik lainnya tidak dirinci di halaman mana pun yang dibaca di sini, sehingga kolom sebaiknya ditulis daripada ditebak. Kunavo menyediakan /v1/chat/completions, /v1/messages dan /v1/responses, jadi setiap transport memiliki rute yang cocok di atas kertas.

Baris Anthropic memerlukan catatan kehati-hatian, bukan jawaban yang terlalu yakin. Panduan Azure Foundry Hermes menyatakan bahwa /v1 dihapus dari URL dasar karena SDK Anthropic menambahkan /v1/messages ke setiap permintaan — tetapi kalimat itu berada di bawah judul Azure, dan contoh milik referensi penyedia (api: https://proxy.example.com/anthropic) tidak pernah menyebutkan akhiran apa yang ditambahkan Hermes untuk proksi generik. Jadi kedua kandidat di atas masuk akal dan salah satunya dapat menghasilkan 404 dengan /v1 ganda. Periksa jalur permintaan yang benar-benar dicatat oleh panggilan pertama Anda; dokumentasi URL dasar membahas jebakan perbedaan antara origin dan /v1 di balik sebagian besar 404 pada jalur komunikasi ini. Autentikasi adalah kekhawatiran yang lebih kecil: rute Messages Kunavo menerima baik Authorization: Bearer maupun x-api-key, sehingga header mana pun yang dikirim SDK Anthropic untuk proksi generik seharusnya diterima — tetapi Hermes tidak mendokumentasikan pilihan itu, jadi “seharusnya” adalah kata yang jujur.

Satu pertanyaan terbuka yang juga tidak akan dijawab halaman ini. Hermes mendokumentasikan peningkatan diam-diam nama model keluarga GPT-5.x ke codex_responses meskipun config.yaml masih menyatakan chat_completions — tetapi kalimat itu muncul di bawah provider: azure-foundry sembari dirumuskan sebagai deteksi nama model. Apakah slug GPT pada provider: custom memicu perpindahan yang sama tidak didokumentasikan. Jika Anda memilih model kelas GPT, catat rute yang dituju panggilan pertama.

Hal yang tidak diperoleh endpoint kustom secara gratis, berdasarkan transport

Tidak satu pun dari ini merupakan pembatas paket. Hermes Agent “gratis dan bersumber terbuka di bawah lisensi MIT” menurut FAQ beranda proyek, dan dict providers: didokumentasikan sebagai konfigurasi biasa, bukan fitur tingkat paket. Ini adalah pembatas kemampuan, dan berbeda menurut wire.

Dua jalan keluar untuk gateway secara khusus. catalog_provider menerima ID provider Hermes atau ID models.dev dan membuat model pada entri mewarisi metadata katalog tersebut — hanya untuk pencarian; permintaan tetap dikirim ke URL api Anda dengan key Anda. Dan discover_models: false melewati probe /models sepenuhnya serta hanya menggunakan model yang Anda cantumkan pada entri, yang merupakan perbaikan ketika discovery berisik atau lambat. Apakah respons /v1/models Kunavo memenuhi probe Hermes belum diuji di sini; jika tidak, deteksi konteks berakhir pada default 128K tersebut. Alasan biaya di balik pengaturan ini — slot tambahan, worker delegasi, dan kesinambungan cache — tersedia di harga Hermes Agent, bukan diulang di sini.

Tangga verifikasi yang dijalankan sebelum memindahkan pekerjaan nyata

Ini adalah langkah-langkah yang harus Anda jalankan beserta hal yang diharapkan, bukan hasil yang diperoleh Kunavo. Tidak ada eksekusi Hermes terhadap Kunavo yang dilakukan, tidak ada panduan penyiapan Kunavo untuk Hermes, dan tidak ada bagian di halaman ini yang boleh dibaca sebagai integrasi teruji. Pertahankan rute kerja Anda tetap tersedia sepanjang proses.

1. Tambahkan provider, lalu diagnosis. hermes model menambahkannya; hermes doctor didokumentasikan untuk mendiagnosis masalah konfigurasi dan dependensi, dan referensi CLI mencatat dua pemeriksaan konfigurasi endpoint kustom yang dijalankannya — key custom_providers yang bukan daftar YAML, dan entri daftar lama tanpa entri providers: yang cocok. Keduanya hanya menghasilkan peringatan dan --fix tidak menulis ulang keduanya.
2. Pastikan key dimuat sebelum membelanjakan apa pun. hermes dump mencetak ringkasan penyiapan yang dapat disalin-tempel — versi, provider, model, dan apakah API key tersedia. Harapkan ID model Anda dan key yang tersedia. hermes prompt-size berjalan offline dan melaporkan rincian byte prompt sistem serta skema alat, yaitu bagian tetap yang dibawa setiap giliran sebelum konten percakapan apa pun.
3. Satu giliran teks non-streaming. Harapkan balasan, dan harapkan permintaan dikirim ke jalur yang Anda tuju. Endpoint kustom yang “berfungsi” tetapi mengembalikan hasil kacau merupakan baris dalam tabel pemecahan masalah quickstart Hermes, yang menyebut base URL yang salah, nama model yang salah, atau endpoint yang sebenarnya tidak kompatibel dengan OpenAI, serta menyarankan agar endpoint diverifikasi terlebih dahulu di klien terpisah.
4. Satu giliran streaming. Harapkan output bertahap, bukan satu blok di akhir. Apakah framing stream endpoint tertentu memenuhi parsing progres Hermes tidak diuji oleh halaman ini.
5. Satu putaran alat. Harapkan alat dieksekusi. Jika pemanggilan dicetak sebagai teks, itu merupakan dukungan pemanggilan alat di sisi penyajian, bukan transport.
6. Baca meter. /usage adalah panel token, biaya, dan konteks dalam sesi. Bandingkan dengan biaya yang benar-benar dicatat akun provider Anda — perhitungan agen sendiri atas token yang dilaporkan adalah estimasi, bukan buku besar. Lihat dokumen penggunaan.

Biaya tangga ini, dan biaya perpindahan di tengah sesi

Anggap enam langkah di atas mengirim 26.000 token input dan menerima total 1.150 token output — prompt sistem tetap dan skema alat pada masing-masing dari tiga panggilan, ditambah hasil alat yang dikirim ulang sekali. Asumsi ini hanya ilustrasi; hermes prompt-size melaporkan prompt tetap Anda sendiri sebagai rincian byte, yang lebih mendekati kenyataan daripada angka yang dapat ditebak halaman ini. Tarifnya adalah harga katalog Kunavo yang berlaku per juta token.

Ini adalah perhitungan token ilustratif dengan tarif katalog, bukan tugas Hermes yang diukur dan bukan batas maksimum tagihan. Ini tidak mencakup penulisan cache, alat eksternal, atau pajak. Tujuan angka ini adalah menunjukkan kecilnya biaya: memverifikasi rute jauh lebih murah daripada menemukan salah konfigurasi setelah pekerjaan terjadwal berjalan selama seminggu.

Angka kedua adalah angka yang disembunyikan perintah /model. Cache prompt dikaitkan dengan model yang melayani permintaan, sehingga setiap perubahan model di tengah percakapan membuat pesan berikutnya membaca ulang seluruh percakapan dengan harga input penuh, bukan tarif cache, yang menurut Hermes kira-kira 75 hingga 90 persen lebih murah. Pada percakapan 120.000 token dengan Claude Sonnet 5, perbedaan antara $1,40 per juta dan tarif baca-cache $0,14 sekitar $0,151 untuk satu giliran itu — sepele jika hanya terjadi sekali, tetapi tidak sepele jika menjadi kebiasaan. Nilai katalog Kunavo adalah batas bawah penagihan, bukan batas maksimum: ketika upstream melaporkan biayanya, tagihan adalah nilai yang lebih besar antara biaya katalog dan biaya upstream dikalikan markup yang berlaku. Minimum adalah top-up prabayar $10 tanpa langganan. Lihat penagihan.

Mengembalikan konfigurasi

Hermes mendokumentasikan jalur pembatalan, sehingga uji coba berisiko rendah. enabled: false pada entri menyembunyikannya tanpa menghapusnya. Salinan config.yaml pada titik waktu ditulis ke backups/config/config.yaml.<reason>.<timestamp> sebelum hermes setup atau hermes migrate menulis ulangnya dan setiap kali file tersebut diurai, dengan pengulangan identik dilewati dan hanya lima salinan terbaru per alasan yang disimpan; jika file kemudian gagal diurai, Hermes menyajikan salinan baik terbaru alih-alih default bawaan. Referensi konfigurasi juga memberi anotasi model.base_url sebagai “dikosongkan saat berpindah provider”, jadi berpindah kembali ke provider bawaan didokumentasikan untuk menghapus base URL lama, bukan meninggalkannya di file — periksa nilai yang tertulis setelahnya alih-alih mengasumsikannya.

Tiga jebakan berasal dari tutorial lama. Daftar tingkat atas lama custom_providers: masih berfungsi dan hermes update secara otomatis memigrasikannya ke dict providers:, tempat model lama menjadi default_model dan api_mode lama menjadi transport. LLM_MODEL dalam .env telah dihapus sepenuhnya — config.yaml adalah satu-satunya sumber kebenaran. Dan OPENAI_BASE_URL didokumentasikan dengan dua cara oleh dua halaman resmi yang masih berlaku: referensi provider menyatakan bahwa ini hanya dihormati untuk provider openai-api, sedangkan referensi variabel lingkungan mencantumkannya sebagai base URL untuk endpoint kustom. Perbedaan itu belum terselesaikan, jadi konfigurasikan endpoint dalam config.yaml dan jangan mengandalkan variabel lingkungan tersebut sebagai rute.

Jika Anda sedang memilih provider, bukan menghubungkannya, OpenAI-compatible API menjelaskan apa yang dicakup dan tidak dicakup oleh permukaan kompatibel tersebut, dan Hermes vs OpenClaw membandingkan kedua agen. Saat siap menguji rute ini dengan key yang didanai, buat akun Kunavo.

Pertanyaan umum

Dokumentasi Hermes Agent — referensi provider, halaman server API, halaman konfigurasi model, halaman konfigurasi, referensi CLI, referensi perintah garis miring, quickstart, dan beranda proyek — dibaca pada 21 September 2026. Status repositori dan rilis terbaru diperiksa terhadap GitHub API pada hari yang sama. Tiga rute API Kunavo dikonfirmasi dalam source-nya sendiri. Setiap angka dolar adalah perhitungan token ilustratif berdasarkan tarif katalog yang berlaku, bukan biaya tugas yang diukur. Konfigurasi Hermes dilaporkan dari dokumen sumber; tidak ada eksekusi Hermes terhadap Kunavo yang dilakukan.