Menghubungkan API Model AI di Android: Penyedia, Gambar, dan Uji Alat FoneClaw
Atur preset penyedia, Base URL, API Key, dan model ID di FoneClaw. Uji teks, gambar, serta alat Android secara terpisah dan bedakan masalah API dari izin ponsel.
- FoneClaw menyediakan model default gratis atau model daring kompatibel yang Anda konfigurasi sendiri. Langganan aplikasi chatbot tidak otomatis memberikan akses atau saldo API.
- Preset penyedia membantu konfigurasi, tetapi Base URL, API Key, dan model ID tetap harus sesuai dengan endpoint serta akun Anda. Pengaturan dukungan gambar dan alat tidak menciptakan kemampuan yang tidak dimiliki model.
- Uji respons teks, interpretasi gambar pilihan, dan satu alat Android berisiko rendah secara terpisah. Keberhasilan teks belum membuktikan dukungan gambar, tool calling, atau izin perangkat.
- Status model yang mulai dihentikan berbeda dari model yang sudah dinonaktifkan. Setelah mengganti model, ulangi pengujian dan periksa hasil tindakan sebelumnya sebelum mencoba kembali agar tidak terjadi pengiriman atau penyimpanan ganda.
Pakai model default atau hubungkan API sendiri
Jika Anda ingin menghubungkan API model AI di Android, FoneClaw memberi dua jalur. Jalur pertama adalah memakai model default gratis agar Anda bisa langsung mencoba agen ponsel tanpa menyiapkan kredensial model sendiri. Jalur kedua adalah mengonfigurasi model daring kompatibel di dalam FoneClaw memakai API Base URL, API Key, dan model ID. Keduanya tetap berjalan melalui 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 | Mulai dari tugas Android berisiko rendah untuk memeriksa alur dan hasilnya |
| Model daring kompatibel sendiri | Ingin memakai penyedia tertentu, endpoint perusahaan, atau kebijakan model khusus | Perlu akses API, Base URL, API Key, model ID, koneksi HTTPS, dan format API yang kompatibel |
Akses API harus diperiksa pada akun penyedia. Langganan aplikasi chatbot tidak otomatis mencakup kredensial, penagihan, atau akses model melalui API. Pastikan akun atau proyek yang menghasilkan kunci memang dapat memanggil model pilihan Anda.
Pemisahan perannya penting. Model yang dipilih di dalam FoneClaw memahami instruksi, menalar, dan menyusun rencana. Alat Android yang aktif menjalankan langkah yang didukung sesuai izin, keadaan aplikasi, dan kebijakan persetujuan yang berlaku. Konfigurasi model bukan berarti model mendapat akses bebas ke ponsel.
Untuk gambaran lengkap setelah model dikonfigurasi, AI Agent Mengontrol Ponsel Android: Dari Niat ke Tindakan yang Terverifikasi menjelaskan bagaimana niat pengguna berubah menjadi pemanggilan alat dan hasil yang dapat diperiksa di ponsel.
Pahami preset penyedia, Base URL, API Key, dan model ID
Preset penyedia membantu menyiapkan konfigurasi model daring, tetapi bukan bukti bahwa akun Anda sudah memiliki akses atau semua kemampuan model tersedia. Base URL, API Key, dan model ID tetap punya fungsi berbeda dan harus sesuai dengan layanan yang sama.
| Pengaturan | Artinya | Yang perlu diperiksa |
|---|---|---|
| Preset penyedia | Pilihan awal untuk membantu konfigurasi penyedia | Cocokkan nilai yang digunakan dengan dokumentasi endpoint dan akun Anda |
API Base URL | Alamat dasar layanan model yang kompatibel | Gunakan endpoint API, bukan halaman dashboard atau login; periksa path dan format protokolnya |
API Key | Kredensial rahasia untuk autentikasi permintaan | Pastikan kunci aktif, berasal dari proyek yang benar, dan tidak tersalin dengan spasi tambahan |
model ID | Pengenal model yang dipanggil pada endpoint tersebut | Gunakan ID API persis seperti yang tersedia untuk akun, bukan sekadar nama pemasaran |
| Dukungan gambar | Pengaturan penggunaan masukan gambar | Model dan endpoint harus benar-benar mendukung pemahaman gambar |
| Dukungan alat | Pengaturan penggunaan pemanggilan alat atau tool calling | Model dan endpoint harus mendukung format pemanggilan alat yang kompatibel |
Jangan pernah menaruh API Key asli di tangkapan layar publik, percakapan dukungan yang tidak aman, laporan masalah publik, atau catatan yang mudah dibaca orang lain. Kunci dapat memberikan akses ke layanan berbayar dan menimbulkan biaya pada akun Anda.
Dokumentasi autentikasi OpenAI API menjelaskan penggunaan serta perlindungan API Key. Sementara itu, dokumentasi kompatibilitas OpenAI pada Gemini API menunjukkan contoh penyedia yang menyediakan jalur kompatibel melalui Base URL khusus dan ID modelnya sendiri. Ini contoh pola kompatibilitas, bukan bukti bahwa semua penyedia memakai protokol yang identik.
Aturan praktisnya: Base URL menjawab “ke layanan mana permintaan dikirim?”, API Key menjawab “akun atau proyek mana yang berhak memakai layanan itu?”, dan model ID menjawab “model mana yang menjalankan penalaran?”.
Atur penyedia dan kemampuan model di FoneClaw
Untuk memakai model kustom untuk agen ponsel, siapkan nilai dari penyedia model dan pastikan format API-nya kompatibel dengan konfigurasi FoneClaw. Kami menyediakan preset penyedia serta pengaturan dukungan gambar dan alat untuk membantu menyesuaikan konfigurasi dengan kemampuan model yang Anda pilih.
- Buka pengaturan FoneClaw yang berkaitan dengan konfigurasi agen atau model.
- Pilih model default gratis atau konfigurasi model daring kompatibel Anda.
- Gunakan preset penyedia yang sesuai bila tersedia, lalu periksa kembali Base URL yang digunakan.
- Masukkan API Key dari akun atau proyek yang benar tanpa spasi tambahan. Jangan membagikan nilainya dalam tangkapan layar.
- Masukkan model ID persis sesuai model yang tersedia pada endpoint dan akun Anda.
- Sesuaikan dukungan gambar dan alat dengan kemampuan yang didokumentasikan penyedia. Jangan mengaktifkannya hanya karena ingin model memiliki kemampuan tersebut.
- Simpan konfigurasi dan gunakan model itu untuk pengujian teks, gambar jika didukung, lalu satu alat Android berisiko rendah.
Pengaturan dukungan gambar tidak mengubah model teks menjadi model vision. Pengaturan dukungan alat juga tidak membuat endpoint yang hanya menerima percakapan teks menjadi kompatibel dengan tool calling. Keduanya harus mengikuti kemampuan nyata model dan layanan.
Jika berpindah dari model default ke model sendiri, perubahan utamanya ada pada sumber penalaran. Eksekusi Android tetap bergantung pada alat yang aktif, izin perangkat, keadaan aplikasi, dan kebijakan persetujuan. Untuk pembahasan pemilihan model dan pembagian tugas yang lebih luas, Kimi K3, DeepSeek V4, dan GLM-5.2 untuk Phone Agent: Cara Memilih Model membantu membandingkan pertimbangan tersebut tanpa mencampurnya dengan konfigurasi dasar.
Jika ponsel dipakai bersama, dicadangkan ke layanan cloud, atau direkam untuk tutorial, pastikan nilai kunci tidak terlihat. Bila kunci pernah terekspos, cabut melalui penyedia dan buat kunci baru.
Uji teks, gambar, dan alat Android secara terpisah
Setelah konfigurasi disimpan, lakukan tiga pengujian terpisah. Mulai dari teks tanpa tindakan perangkat. Jika tahap ini gagal, perbaiki endpoint, API Key, model ID, akses akun, atau jaringan sebelum melanjutkan. Respons teks yang berhasil belum membuktikan bahwa gambar dapat dipahami atau alat Android dapat dijalankan.
| Tahap uji | Contoh permintaan | Hasil yang perlu diperiksa |
|---|---|---|
| Teks | “Jelaskan dalam satu kalimat mengapa hasil tindakan perlu diperiksa.” | Respons teks diterima tanpa error autentikasi, endpoint, atau model |
| Gambar pilihan, jika didukung | Lampirkan foto benda yang tidak sensitif, lalu minta model menjelaskan apa yang terlihat | Jawaban sesuai isi gambar yang dilampirkan, bukan sekadar menyatakan bahwa gambar diterima |
| Satu alat Android berisiko rendah | “Periksa status volume media saat ini tanpa mengubahnya.” | Alat yang sesuai benar-benar dipanggil dan hasilnya dapat dicocokkan dengan keadaan perangkat |
Pada pengujian gambar, gunakan model vision yang kompatibel dan pengaturan dukungan gambar yang sesuai. FoneClaw mengoptimalkan gambar besar yang dipilih serta membetulkan orientasinya untuk masukan model. Pemrosesan masukan ini tidak menggantikan kemampuan vision dan bukan fitur pemindai OCR atau PDF. Model daring dapat menerima gambar serta konteks yang Anda kirim, jadi hindari materi sensitif yang tidak diperlukan.
Untuk pengujian alat, pastikan alat terkait aktif dan izin yang dibutuhkan tersedia. Model di dalam FoneClaw menafsirkan permintaan dan meminta alat yang didukung; eksekusinya mengikuti kebijakan persetujuan yang berlaku. Jangan menganggap balasan “sudah diperiksa” sebagai bukti jika tidak ada hasil alat yang dapat dicocokkan dengan perangkat.
Hindari pengujian awal berupa mengirim pesan, menghapus data, membagikan lokasi, membeli sesuatu, atau mengubah pengaturan penting. Rencana dalam percakapan berguna untuk ditinjau, tetapi tidak membuktikan tool calling maupun perubahan Android berhasil.
Mengatasi error API, dukungan model, dan izin
Saat mengatur API model di ponsel, cari lapisan yang gagal sebelum mencoba ulang. Error koneksi model dan kegagalan tindakan Android berada di lapisan berbeda. Kode error perlu dibaca bersama pesan serta dokumentasi penyedia, bukan dijadikan diagnosis tunggal.
| Gejala | Kemungkinan penyebab | Pemeriksaan berikutnya |
|---|---|---|
| 401 atau autentikasi ditolak | API Key salah, dicabut, berasal dari proyek yang keliru, atau format autentikasi tidak sesuai | Periksa kunci, akses akun atau proyek, serta format autentikasi endpoint |
| 404 atau sumber tidak ditemukan | Base URL atau path salah, model ID keliru, atau model tidak tersedia pada endpoint tersebut | Cocokkan endpoint dan model ID dengan dokumentasi serta daftar model akun |
| Timeout | Jaringan bermasalah, layanan lambat, atau permintaan terlalu berat | Uji teks pendek, periksa jaringan dan status layanan sebelum mengulangi tindakan |
| Model ditandai deprecated atau sudah retired | Model memasuki masa penghentian atau sudah dinonaktifkan penyedia | Periksa tanggal siklus hidup, model pengganti, dan jadwal platform yang digunakan |
| Teks berhasil, gambar gagal | Model atau endpoint tidak mendukung gambar, pengaturan tidak sesuai, atau masukan ditolak | Periksa kemampuan vision, dukungan gambar, dan persyaratan masukan penyedia |
| Teks berhasil, pemanggilan alat gagal | Tool calling tidak kompatibel, pengaturan dukungan alat tidak sesuai, atau alat belum aktif | Periksa dukungan model dan protokol, lalu uji satu alat baca status yang aktif |
| Alat dipanggil tetapi tindakan Android terhambat | Izin belum tersedia, keadaan aplikasi tidak sesuai, target tidak jelas, atau tindakan tidak didukung | Periksa izin, target, keadaan aplikasi, dan hasil alat; API Key tidak menggantikan izin Android |
| Eksekusi menunggu persetujuan | Kebijakan yang berlaku meminta keputusan pengguna | Tinjau target dan konsekuensi sebelum menyetujui; jangan mengubah kebijakan hanya untuk melewati hambatan yang belum dipahami |
API Key yang benar hanya menunjukkan bahwa kredensial diterima untuk permintaan terkait. Ia tidak memberi izin lokasi Android, tidak membuat semua aplikasi dapat dikontrol, dan tidak menghapus kebijakan persetujuan. Demikian pula, model yang sudah dinonaktifkan tidak berarti izin ponsel rusak.
Untuk contoh pemisahan kemampuan model dan eksekusi perangkat, DeepSeek AI Agent dan Kontrol Ponsel Android: Bisa Langsung Mengoperasikan HP? menjelaskan mengapa model tetap memerlukan jalur eksekusi Android yang didukung. Jika masalahnya gangguan layanan sementara, gunakan Gangguan Model Asisten AI di Android: Coba Ulang, Ganti Model, dan Pulihkan Tugas untuk menentukan kapan mencoba ulang atau memakai model lain.
Periksa siklus hidup model sebelum menggantinya
Selain kemampuan mengikuti instruksi, stabilitas format, latensi, biaya, dan penalaran bertahap, periksa siklus hidup model. Pengenal yang pernah bekerja dapat memasuki masa penghentian, lalu tidak lagi menerima permintaan setelah tanggal penonaktifan.
Sebagai contoh pemeliharaan API bertanggal, dokumentasi resmi siklus hidup model Anthropic mencatat claude-sonnet-4-5-20250929 sebagai deprecated sejak 30 September 2026, dengan penonaktifan yang direncanakan pada 30 November 2026. Pengganti yang direkomendasikan adalah claude-sonnet-5-5. Status deprecated berarti model masih berfungsi selama masa tersebut; status retired berarti permintaan ke model gagal.
Tanggal itu berlaku pada platform yang dioperasikan Anthropic. Platform mitra menetapkan jadwalnya sendiri. Rekomendasi pengganti juga bukan bukti bahwa model tersebut tersedia pada akun Anda atau bahwa protokol Anthropic Messages API asli otomatis cocok dengan endpoint berformat OpenAI yang Anda konfigurasi di FoneClaw. Periksa model ID, akses akun, dan format API pada penyedia yang benar sebelum mengganti konfigurasi.
Setelah migrasi, ulangi pengujian teks, gambar jika didukung, dan pemanggilan alat jika didukung. Jangan hanya mengganti nama model lalu melanjutkan tindakan yang terputus. Untuk contoh lain tentang peran model tanpa menganggap aplikasi chatbot otomatis mengoperasikan Android, baca Bisakah Grok Mengontrol Ponsel Android? Panggilan, Asisten, dan FoneClaw.
Pertimbangkan juga privasi dan biaya. Endpoint pihak ketiga dapat menerima instruksi dan konteks yang Anda kirim sesuai konfigurasi. Mulai dari model default gratis atau layanan kompatibel yang ketentuannya Anda pahami, lalu tambah kompleksitas setelah pengujian rendah risiko berhasil.
Uji ulang konfigurasi dan periksa tindakan yang belum selesai
Setelah konfigurasi lolos pengujian, lanjutkan ke tujuan Android yang jelas. Pengguna memberi instruksi, model aktif di FoneClaw menafsirkan serta merencanakan, kemudian alat yang aktif menjalankan langkah yang didukung sesuai izin, keadaan aplikasi, dan kebijakan persetujuan. Hasil akhirnya harus berupa status atau perubahan yang dapat diperiksa, bukan hanya kalimat dari model.
Cakupan konfigurasi dan tindakan yang didukung tersedia di halaman fitur FoneClaw. Untuk pemasangan atau pembaruan aplikasi Android, gunakan halaman unduhan FoneClaw. Pilih model default atau endpoint kompatibel Anda, lalu mulai dari satu pemeriksaan status perangkat tanpa perubahan.
Jika sebelumnya ada tugas yang terputus, buka tujuan sebenarnya sebelum mengulang. Periksa apakah pesan sudah terkirim pada akun yang dimaksud, item ToDo sudah tersimpan, atau acara kalender sudah dibuat. Teks balasan yang disusun dalam percakapan bukan bukti draf tersimpan di kotak surat, dan permintaan pengiriman bukan bukti pesan terkirim. Lanjutkan hanya langkah yang belum selesai agar efek eksternal tidak terjadi dua kali.
Untuk menelusuri hasil parsial, izin, target, dan titik kegagalan, Debug dan Pemulihan Kegagalan Agen Ponsel Android: Runbook Praktis FoneClaw memberi langkah pemulihan yang lebih terarah. Ukuran suksesnya adalah konfigurasi yang sesuai, alat yang benar-benar berjalan, serta hasil aktual yang cocok dengan permintaan Anda.