Menghubungkan API Model AI ke Agen Android FoneClaw: Base URL, API Key, dan Uji Aksi
Panduan aman mengatur API Base URL, API Key, dan model ID di FoneClaw, menguji koneksi model, memperbaiki error, lalu menjalankan aksi Android yang terkelola.
- FoneClaw dapat dipakai lewat dua jalur: model default gratis untuk mulai cepat, atau model kompatibel yang dikonfigurasi dengan API Base URL, API Key, dan model ID.
- API Base URL menentukan endpoint layanan model, API Key mengautentikasi permintaan, sedangkan model ID memilih model yang akan dipakai untuk penalaran di dalam runtime FoneClaw.
- Respons teks yang berhasil belum membuktikan aksi Android berjalan; uji koneksi model lebih dulu, lalu lanjutkan dengan tindakan ponsel berisiko rendah yang terlihat hasilnya.
- Model hanya merencanakan; FoneClaw tetap mengatur 100+ built-in tools, izin Android sesuai kebutuhan, approval, hasil terlihat, dan pemulihan saat alur gagal.
Pakai model default atau hubungkan API sendiri
Jika Anda ingin menghubungkan API model AI ke agen Android, FoneClaw memberi dua jalur yang sama-sama sah. Jalur pertama adalah memakai model default gratis agar Anda bisa langsung mencoba phone agent tanpa menyiapkan kredensial model sendiri. Jalur kedua adalah mengonfigurasi model kompatibel di dalam FoneClaw memakai API Base URL, API Key, dan model ID. Keduanya tetap berjalan melalui runtime FoneClaw, bukan melalui dua aplikasi terpisah yang saling mengoperasikan ponsel.
| Jalur | Kapan dipakai | Yang perlu diperhatikan |
|---|---|---|
| Model default gratis | Ingin mulai cepat, menguji alur FoneClaw, atau belum punya endpoint model sendiri | Paling sederhana untuk validasi awal, terutama tugas Android berisiko rendah |
| Model kompatibel sendiri | Ingin memakai penyedia tertentu, endpoint perusahaan, model berbiaya sendiri, atau kebijakan model khusus | Perlu Base URL, API Key, model ID, koneksi HTTPS, dan format API yang kompatibel |
Pemisahan perannya penting. Model membantu memahami instruksi, menalar, dan menyusun rencana. FoneClaw adalah runtime phone agent Android yang mengatur tindakan perangkat yang didukung, izin, approval, hasil terlihat, dan pemulihan saat gagal. Jadi konfigurasi model bukan berarti model mendapat akses bebas ke ponsel. Model memberi keputusan penalaran; FoneClaw menentukan apakah rencana itu bisa diterjemahkan menjadi aksi Android yang aman dan didukung.
Untuk gambaran lengkap setelah model dikonfigurasi, Kontrol Ponsel dengan AI Agent: Cara Kerja, Batas, dan Keamanan Android menjelaskan bagaimana niat pengguna berubah menjadi tool, izin, approval, dan hasil di ponsel.
API Base URL, API Key, dan model ID dijelaskan
Tiga nilai yang sering membuat pengguna bingung adalah API Base URL, API Key, dan model ID. Ketiganya punya fungsi berbeda. API Base URL adalah alamat endpoint layanan model yang kompatibel. API Key adalah kredensial rahasia untuk membuktikan bahwa permintaan memang berasal dari akun atau proyek Anda. model ID adalah nama model yang ingin dipakai pada endpoint tersebut.
Contoh bentuk yang aman untuk dipahami adalah seperti ini: https://api.example.com/v1 sebagai Base URL tiruan, sk-...contoh-placeholder... sebagai API Key palsu, dan model-contoh sebagai model ID. Jangan pernah menaruh API Key asli di artikel, screenshot publik, chat dukungan yang tidak aman, issue publik, atau catatan yang mudah dibaca orang lain. Kunci model dapat menimbulkan biaya atau akses ke layanan yang Anda bayar.
Dokumentasi autentikasi OpenAI API menunjukkan pola umum bahwa API Key dipakai untuk mengautentikasi request dan harus dilindungi. Sementara itu, dokumentasi kompatibilitas OpenAI pada Gemini API menunjukkan bahwa sebagian penyedia dapat menyediakan endpoint kompatibel melalui Base URL khusus dan nama model dari penyedia tersebut. Ini contoh pola kompatibilitas, bukan bukti bahwa semua penyedia memakai jalur yang identik.
| Kolom | Artinya | Kesalahan umum |
|---|---|---|
API Base URL | Alamat dasar layanan model yang kompatibel | Memasukkan halaman dashboard, lupa https://, memakai path provider yang salah, atau mencampur endpoint chat dan endpoint lain |
API Key | Kredensial untuk autentikasi permintaan | Menyalin spasi tambahan, memakai key yang sudah dicabut, menaruh key di tempat publik, atau memakai key dari proyek yang salah |
model ID | Nama model yang akan dipanggil | Salah kapitalisasi, memakai nama pemasaran bukan ID API, atau memilih model yang tidak tersedia untuk akun tersebut |
Aturan praktisnya: Base URL menjawab “ke layanan mana FoneClaw mengirim permintaan model?”, API Key menjawab “siapa yang berhak memakai layanan itu?”, dan model ID menjawab “model mana yang menjalankan penalaran?”.
Cara mengatur model di FoneClaw langkah demi langkah
Untuk memakai model kustom untuk agen ponsel, siapkan dulu nilai dari penyedia model: Base URL yang kompatibel, API Key, dan model ID. Pastikan layanan model mendukung format yang dibutuhkan oleh konfigurasi FoneClaw. Jangan mulai dari tindakan ponsel yang sensitif. Konfigurasi model sebaiknya diuji sebagai koneksi penalaran dulu, baru kemudian dipakai untuk aksi Android yang terlihat.
- Buka pengaturan FoneClaw yang berkaitan dengan konfigurasi agen atau model.
- Pilih apakah ingin tetap memakai model default gratis atau beralih ke endpoint kompatibel milik Anda.
- Masukkan
API Base URLdari penyedia model. Gunakan alamat HTTPS yang memang ditujukan untuk API, bukan halaman login atau dashboard. - Masukkan
API Keysecara hati-hati. Jangan menambahkan spasi di awal atau akhir. Jangan membagikan nilainya di screenshot. - Masukkan
model IDsesuai nama yang didukung oleh penyedia dan akun Anda. - Simpan konfigurasi, lalu pilih model tersebut sebagai model aktif bila FoneClaw menampilkan pilihan model.
- Jalankan uji koneksi ringan sebelum meminta FoneClaw menjalankan tindakan Android.
Jika Anda berpindah dari model default ke model sendiri, perubahan utamanya ada pada sumber penalaran. Runtime FoneClaw tetap bertanggung jawab atas tool Android yang didukung. Ini berarti model yang lebih kuat dapat membantu memahami instruksi dan menyusun rencana, tetapi izin perangkat, approval, dan hasil tetap diproses di lapisan FoneClaw.
Untuk pengguna yang ingin membandingkan beberapa model dan routing tugas, Kimi K3, DeepSeek V4, dan GLM-5.2 untuk Phone Agent: Cara Memilih Model membahas pemilihan model lebih dalam tanpa mencampurnya dengan langkah konfigurasi dasar di halaman ini.
Satu catatan keamanan: jangan menganggap API Key sebagai password yang boleh ditempel di mana saja selama perangkat pribadi. Jika ponsel dipakai bersama, dicadangkan ke layanan cloud, atau direkam untuk tutorial, pastikan nilai kunci tidak terlihat. Bila kunci pernah terekspos, cabut dari penyedia model dan buat kunci baru.
Uji koneksi model sebelum kontrol ponsel
Setelah konfigurasi disimpan, uji API Base URL untuk agen Android secara bertahap. Tahap pertama cukup membuktikan bahwa FoneClaw bisa menghubungi model dan mendapat respons teks. Misalnya, minta model menjawab pertanyaan sederhana atau merangkum instruksi pendek. Jika tahap ini gagal, jangan lanjut ke aksi ponsel. Perbaiki endpoint, API Key, model ID, atau jaringan terlebih dahulu.
Respons teks yang berhasil juga belum berarti kontrol Android sudah valid. Model mungkin dapat menjawab, tetapi tindakan ponsel masih membutuhkan tool yang didukung, status perangkat yang tepat, dan izin sesuai kebutuhan. Karena itu, tahap kedua adalah tugas Android berisiko rendah dan terlihat. Contohnya: minta FoneClaw membuka aplikasi yang tidak sensitif, membaca status yang terlihat, atau menyiapkan draf tanpa mengirim. Hindari uji awal seperti mengirim pesan, menghapus data, membagikan lokasi, membeli sesuatu, atau mengubah pengaturan penting.
| Tahap uji | Tujuan | Contoh aman |
|---|---|---|
| Uji respons model | Memastikan endpoint, key, dan model ID berfungsi | “Jelaskan dalam satu kalimat apa yang akan kamu lakukan sebelum menjalankan tool.” |
| Uji rencana tanpa aksi sensitif | Melihat apakah model memahami batas tugas | “Buat rencana untuk membuka aplikasi catatan, tetapi jangan menjalankan tindakan dulu.” |
| Uji aksi Android rendah risiko | Memastikan runtime dan tool bekerja | “Buka aplikasi catatan yang tersedia dan beri tahu jika sudah terlihat.” |
| Uji approval | Memastikan tindakan berdampak berhenti untuk keputusan pengguna | “Siapkan draf pesan, tampilkan dulu, jangan kirim sebelum saya setujui.” |
Setiap tahap menjawab pertanyaan berbeda. Uji model menjawab apakah konfigurasi API benar. Uji rencana menjawab apakah model mengikuti instruksi. Uji aksi menjawab apakah FoneClaw bisa menjalankan tool Android yang didukung. Uji approval menjawab apakah batas tindakan terlihat sebelum efek eksternal terjadi.
Mengatasi error 401, 404, timeout, model, dan izin
Saat mengatur API Key LLM di ponsel, jangan langsung menyimpulkan FoneClaw atau modelnya rusak. Error koneksi model dan error tindakan Android berada di lapisan berbeda. Error 401 biasanya mengarah ke autentikasi, seperti API Key salah, key dicabut, proyek tidak aktif, atau format header yang tidak sesuai dengan penyedia. Error 404 sering terkait endpoint atau path yang keliru, tetapi maknanya tetap perlu dibaca sesuai dokumentasi penyedia. Timeout bisa berasal dari jaringan, endpoint lambat, wilayah, atau model yang sedang tidak responsif.
| Gejala | Kemungkinan penyebab | Perbaikan |
|---|---|---|
| 401 atau unauthorized | API Key salah, kedaluwarsa, dicabut, tidak punya akses proyek, atau tersalin dengan spasi | Buat key baru bila perlu, salin ulang tanpa spasi, pastikan key berasal dari akun dan proyek yang benar |
| 404 atau not found | Base URL salah, path kompatibilitas keliru, atau model ID tidak tersedia pada endpoint itu | Cek dokumentasi penyedia, bedakan dashboard dari endpoint API, pastikan model ID valid untuk akun Anda |
| Timeout | Jaringan ponsel buruk, server lambat, request terlalu berat, atau endpoint tidak stabil | Coba jaringan berbeda, pakai prompt lebih pendek, uji model ringan, dan periksa status layanan penyedia |
| Model menjawab tetapi tool tidak berjalan | Koneksi model berhasil, tetapi tindakan Android tidak didukung, tool belum aktif, atau target tidak jelas | Pilih tindakan rendah risiko yang didukung, perjelas target, dan cek kontrol tool di FoneClaw |
| FoneClaw meminta izin Android | Tugas membutuhkan kemampuan sistem seperti lokasi, notifikasi, akses layar, atau data tertentu | Beri izin hanya jika konteksnya jelas. API Key model tidak menggantikan permission Android |
| Approval muncul sebelum tindakan | Tindakan punya efek eksternal atau mengikuti kebijakan approval | Tinjau target dan konsekuensi. Gunakan approval override hanya untuk tindakan yang benar-benar Anda percayai |
| Respons model tidak mengikuti format | Model kurang cocok untuk tool calling, terlalu kreatif, atau konteks sistem tidak dipatuhi | Gunakan model yang lebih stabil untuk instruksi agen, kurangi ambiguitas, atau kembali ke model default untuk uji pembanding |
Pembedaan ini penting: API Key yang benar hanya membuktikan model bisa dipanggil. Ia tidak memberi izin lokasi Android, tidak membuat semua aplikasi dapat dikontrol, dan tidak menghapus approval tindakan. Jika model menjawab tetapi tindakan gagal, periksa tool, izin, target layar, dan dukungan tindakan. Jika tindakan didukung tetapi model sering salah rencana, barulah evaluasi model atau prompt konfigurasi.
Untuk contoh penyedia tertentu, pembahasan DeepSeek AI Agent dan Kontrol Ponsel Android: Bisa Langsung Mengoperasikan HP? membantu memisahkan kemampuan model dari eksekusi Android yang tetap membutuhkan runtime seperti FoneClaw.
Memilih model untuk aksi ponsel Android
Model tercepat belum tentu menjadi model terbaik untuk phone agent. Untuk model kustom untuk agen ponsel, perhatikan lima hal: kemampuan mengikuti instruksi, stabilitas format, latensi, biaya, dan kualitas penalaran pada tugas multi-langkah. Phone agent membutuhkan model yang dapat memahami batas seperti “siapkan draf, jangan kirim”, “minta izin jika perlu”, atau “berhenti jika target ambigu”. Model yang terlalu bebas berkreasi bisa terlihat pintar di chat, tetapi kurang cocok untuk tindakan perangkat yang harus jelas.
Latensi juga harus dibaca end-to-end. Model yang merespons cepat dapat membantu waktu umpan balik pertama, tetapi hasil akhir masih bergantung pada status Android, tool, izin, approval, dan verifikasi. Sebaliknya, model yang lebih lambat tetapi lebih stabil mungkin mengurangi retry. Untuk tugas ponsel, lebih baik menyelesaikan satu alur dengan benar daripada menjawab cepat lalu membuat pengguna memperbaiki kesalahan.
Jika Anda ingin memakai model Grok sebagai bagian dari pemahaman pertanyaan phone-control, artikel Bisakah Grok Mengontrol Ponsel Android? Panggilan, Asisten, dan FoneClaw memberi contoh cara membaca peran model tanpa menganggap aplikasi model itu sendiri otomatis mengoperasikan Android.
Pertimbangkan juga privasi dan biaya. Endpoint pihak ketiga dapat menerima teks instruksi dan konteks yang dikirim sesuai konfigurasi. Jangan masukkan data sensitif bila tidak diperlukan untuk tugas. Untuk penggunaan harian, mulai dari model default gratis atau model kompatibel yang sudah Anda pahami biayanya. Naikkan kompleksitas hanya setelah alur rendah risiko terbukti stabil.
Ubah model terhubung menjadi aksi ponsel yang terkelola
Setelah model berhasil merespons, barulah hubungkan penalaran itu ke aksi Android yang terkelola. Alurnya sederhana: pengguna memberi tujuan, model aktif di FoneClaw menyusun rencana, FoneClaw memilih tool Android yang didukung, izin diminta saat dibutuhkan, approval muncul bila kebijakan mengharuskan, lalu hasil dibuat terlihat. Inilah bedanya phone agent dengan chatbot biasa: hasil akhirnya bukan hanya kalimat, tetapi perubahan atau status yang dapat diperiksa di ponsel.
FoneClaw menyediakan 100+ built-in tools untuk aksi Android yang didukung. Gunakan cakupan ini sebagai daftar kemampuan yang perlu diuji sesuai kebutuhan Anda, bukan sebagai janji bahwa setiap aplikasi atau setiap tindakan Android bisa dikendalikan. Mulai dari tugas yang aman: buka aplikasi, baca konteks yang terlihat, buat draf, atau siapkan pengingat. Setelah itu, uji tindakan yang membutuhkan approval dengan target yang jelas.
Berdasarkan kemampuan yang tersedia saat ini, FoneClaw menambahkan kontrol per tool, approval override, permission recovery, dan penanganan kegagalan yang lebih kuat. Untuk mulai dari pemasangan atau pembaruan, gunakan halaman Download FoneClaw. Setelah terpasang, pilih model default atau endpoint kompatibel Anda, lalu jalankan satu alur rendah risiko sampai hasilnya terlihat.
Ukuran suksesnya bukan sekadar “model menjawab”. Ukuran yang lebih tepat adalah: FoneClaw memahami tujuan, memilih tool yang masuk akal, meminta izin hanya saat perlu, menampilkan approval untuk tindakan berdampak, dan memberi status akhir yang bisa dipercaya. Dengan begitu, menghubungkan API model AI ke agen Android menjadi langkah operasional yang aman, bukan sekadar menempelkan key ke aplikasi.