--- read_when: - Mengonfigurasi kebijakan, daftar izin, atau fitur eksperimental `tools.*` - Mendaftarkan penyedia kustom atau mengganti URL dasar - Menyiapkan endpoint yang dihosting sendiri dan kompatibel dengan OpenAI sidebarTitle: Tools and custom providers summary: Konfigurasi alat (kebijakan, pengalih eksperimental, alat yang didukung penyedia) dan penyiapan penyedia/URL dasar khusus title: Konfigurasi — alat dan penyedia khusus x-i18n: generated_at: "2026-07-12T14:11:16Z" model: gpt-5.6 postprocess_version: locale-links-v1 provider: openai source_hash: 91f392efc7ca08ddd18875625ed3c95d21c5c12f70396594f8dc8e88a20293fc source_path: gateway/config-tools.md workflow: 16 --- Kunci konfigurasi `tools.*` dan penyiapan penyedia khusus / URL dasar. Untuk agen, kanal, dan kunci konfigurasi tingkat atas lainnya, lihat [Referensi konfigurasi](/id/gateway/configuration-reference). ## Alat ### Profil alat `tools.profile` menetapkan daftar izin dasar sebelum `tools.allow`/`tools.deny`: Orientasi awal lokal secara default menetapkan konfigurasi lokal baru ke `tools.profile: "coding"` jika belum diatur (profil eksplisit yang sudah ada tetap dipertahankan). | Profil | Mencakup | | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `minimal` | hanya `session_status` | | `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `get_goal`, `create_goal`, `update_goal`, `update_plan`, `skill_workshop`, `image`, `image_generate`, `music_generate`, `video_generate` | | `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | | `full` | Tanpa batasan (sama seperti belum diatur) | `coding` dan `messaging` juga secara implisit mengizinkan `bundle-mcp` (server MCP yang dikonfigurasi). ### Grup alat | Grup | Alat | | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | `group:runtime` | `exec`, `process`, `code_execution` (`bash` diterima sebagai alias untuk `exec`) | | `group:fs` | `read`, `write`, `edit`, `apply_patch` | | `group:sessions` | `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status`, `spawn_task`, `dismiss_task` | | `group:memory` | `memory_search`, `memory_get` | | `group:web` | `web_search`, `x_search`, `web_fetch` | | `group:ui` | `browser`, `canvas` | | `group:automation` | `heartbeat_respond`, `cron`, `gateway` | | `group:messaging` | `message` | | `group:nodes` | `nodes`, `computer` | | `group:agents` | `agents_list`, `get_goal`, `create_goal`, `update_goal`, `update_plan`, `skill_workshop` | | `group:media` | `image`, `image_generate`, `music_generate`, `video_generate`, `tts` | | `group:openclaw` | Semua alat bawaan di atas kecuali `read`/`write`/`edit`/`apply_patch`/`exec`/`process`/`canvas` (tidak mencakup alat plugin) | | `group:plugins` | Alat milik plugin yang dimuat, termasuk server MCP terkonfigurasi yang diekspos melalui `bundle-mcp` | `spawn_task` memungkinkan agen pengodean mengusulkan pekerjaan lanjutan yang telah dikonfirmasi tanpa memulainya. UI Kontrol menampilkan judul dan ringkasan sebagai cip yang dapat ditindaklanjuti; TUI yang didukung Gateway menampilkan permintaan interaktif yang setara. Menerima salah satunya akan membuat sesi direktori kerja terkelola baru dan mengirimkan perintah lengkap ke sana sementara giliran saat ini berlanjut. `dismiss_task` menarik kembali saran yang masih tertunda berdasarkan `task_id` sementara yang dikembalikan oleh `spawn_task`. Alat tersebut hanya ditawarkan ketika antarmuka operator pemrakarsa dapat menerima dan menindaklanjuti peristiwa saran tugas Gateway. Sesi kanal dan sesi TUI lokal/tertanam tidak menerimanya; transportasi kanal memerlukan tindakan tugas bertipe yang portabel sebelum dapat mengekspos alur ini dengan aman. Saran bersifat lokal terhadap proses dan menghilang ketika Gateway dimulai ulang. Kedua alat tetap berada dalam profil `coding` dan `group:sessions`, sehingga kebijakan `tools.allow` dan `tools.deny` biasa mengonfigurasinya secara otomatis ketika antarmuka mendukungnya. ### Alat MCP dan plugin dalam kebijakan alat sandbox Server MCP yang dikonfigurasi diekspos sebagai alat milik plugin di bawah ID plugin `bundle-mcp`. Profil alat biasa dapat mengizinkannya, tetapi `tools.sandbox.tools` merupakan gerbang tambahan untuk sesi dalam sandbox. Jika mode sandbox adalah `"all"` atau `"non-main"`, sertakan salah satu entri berikut dalam daftar izin alat sandbox ketika alat MCP/plugin harus terlihat: - `bundle-mcp` untuk server MCP yang dikelola OpenClaw dari `mcp.servers` - ID plugin untuk plugin native tertentu - `group:plugins` untuk semua alat milik plugin yang dimuat - nama alat server MCP persis atau glob server seperti `outlook__send_mail` atau `outlook__*` jika Anda hanya menginginkan satu server Glob server menggunakan prefiks server MCP yang aman bagi penyedia, bukan selalu kunci mentah `mcp.servers`. Karakter selain `[A-Za-z0-9_-]` menjadi `-`, nama yang tidak diawali huruf mendapatkan prefiks `mcp-`, dan prefiks yang panjang atau duplikat dapat dipotong atau diberi sufiks; misalnya, `mcp.servers["Outlook Graph"]` menggunakan glob seperti `outlook-graph__*`. ```json5 { agents: { defaults: { sandbox: { mode: "all" } } }, mcp: { servers: { outlook: { command: "node", args: ["./outlook-mcp.js"] }, }, }, tools: { sandbox: { tools: { alsoAllow: ["web_search", "web_fetch", "memory_search", "memory_get", "bundle-mcp"], }, }, }, } ``` Tanpa entri lapisan sandbox tersebut, server MCP tetap dapat dimuat dengan sukses sementara alatnya disaring sebelum permintaan penyedia. Gunakan `openclaw doctor` untuk mendeteksi bentuk ini pada server yang dikelola OpenClaw dalam `mcp.servers`. Server MCP yang dimuat dari manifes plugin bawaan atau `.mcp.json` milik Claude menggunakan gerbang sandbox yang sama, tetapi diagnostik ini belum mencantumkan sumber-sumber tersebut; gunakan entri daftar izin yang sama jika alatnya menghilang dalam giliran yang berjalan di sandbox. ### `tools.codeMode` `tools.codeMode` mengaktifkan antarmuka mode kode OpenClaw generik. Ketika diaktifkan untuk proses yang menggunakan alat, alat OpenClaw biasa berpindah ke balik jembatan katalog `tools.*` di dalam sandbox, dan alat MCP tersedia melalui namespace `MCP` yang dihasilkan. Model biasanya melihat `exec` dan `wait`; alat seperti `computer` yang hasil terstrukturnya tidak dapat melewati jembatan khusus JSON tetap tersedia secara langsung. ```json5 { tools: { codeMode: { enabled: true, }, }, } ``` Bentuk singkat juga diterima: ```json5 { tools: { codeMode: true }, } ``` Deklarasi MCP diekspos melalui antarmuka berkas API virtual hanya-baca dalam mode kode. Kode tamu dapat memanggil `API.list("mcp")` dan `API.read("mcp/.d.ts")` untuk memeriksa tanda tangan bergaya TypeScript sebelum memanggil `MCP..()`. Lihat [Mode kode](/id/reference/code-mode) untuk kontrak runtime, batasan, dan langkah-langkah penelusuran kesalahan. ### `tools.allow` / `tools.deny` Kebijakan global untuk mengizinkan/menolak alat (penolakan diprioritaskan). Tidak peka huruf besar-kecil, mendukung karakter pengganti `*`. Tetap diterapkan meskipun sandbox Docker dinonaktifkan. ```json5 { tools: { deny: ["browser", "canvas"] }, } ``` `write` dan `apply_patch` merupakan ID alat yang terpisah. `allow: ["write"]` juga mengaktifkan `apply_patch` untuk model yang kompatibel, tetapi `deny: ["write"]` tidak menolak `apply_patch`. Untuk memblokir semua perubahan berkas, tolak `group:fs` atau cantumkan secara eksplisit setiap alat yang dapat melakukan perubahan: ```json5 { tools: { deny: ["write", "edit", "apply_patch"] }, } ``` `allow` dan `alsoAllow` tidak dapat ditetapkan bersamaan dalam cakupan yang sama (`tools`, `tools.byProvider.`, `agents.list[].tools`) — validasi konfigurasi akan menolaknya. Gabungkan entri `alsoAllow` ke dalam `allow`, atau hapus `allow` dan gunakan `profile` + `alsoAllow` sebagai gantinya. ### `tools.byProvider` Membatasi alat lebih lanjut untuk penyedia atau model tertentu. Urutan: profil dasar → profil penyedia → izinkan/tolak. ```json5 { tools: { profile: "coding", byProvider: { "google-antigravity": { profile: "minimal" }, "openai/gpt-5.4": { allow: ["group:fs", "sessions_list"] }, }, }, } ``` ### `tools.toolsBySender` Membatasi alat untuk identitas peminta tertentu. Ini merupakan pertahanan berlapis di atas kontrol akses kanal; nilai pengirim harus berasal dari adaptor kanal, bukan dari teks pesan. ```json5 { tools: { toolsBySender: { "channel:discord:1234567890123": { alsoAllow: ["group:fs"] }, "id:guest-user-id": { deny: ["group:runtime", "group:fs"] }, "*": { deny: ["exec", "process", "write", "edit", "apply_patch"] }, }, }, } ``` Kunci menggunakan prefiks eksplisit: `channel::`, `id:`, `e164:`, `username:`, `name:`, atau `"*"`. ID kanal adalah ID OpenClaw kanonis; alias seperti `teams` dinormalisasi menjadi `msteams`. Kunci lama tanpa prefiks hanya diterima sebagai `id:`. Urutan pencocokan adalah kanal+ID, ID, e164, nama pengguna, nama, lalu karakter pengganti. `agents.list[].tools.toolsBySender` per agen mengesampingkan kecocokan pengirim global jika cocok, bahkan dengan kebijakan `{}` kosong. ### `tools.elevated` Mengontrol akses eksekusi dengan hak istimewa di luar sandbox: ```json5 { tools: { elevated: { enabled: true, allowFrom: { whatsapp: ["+15555550123"], discord: ["1234567890123", "987654321098765432"], }, }, }, } ``` - Penggantian per agen (`agents.list[].tools.elevated`) hanya dapat membatasi lebih lanjut. - `/elevated on|off|ask|full` menyimpan status per sesi; direktif sebaris berlaku untuk satu pesan. - `exec` dengan hak istimewa melewati sandbox dan menggunakan jalur keluar yang dikonfigurasi (`gateway` secara default, atau `node` jika target eksekusinya adalah `node`). ### `tools.exec` ```json5 { tools: { exec: { backgroundMs: 10000, timeoutSec: 1800, cleanupMs: 1800000, approvalRunningNoticeMs: 10000, notifyOnExit: true, notifyOnExitEmptySuccess: false, commandHighlighting: false, applyPatch: { enabled: true, allowModels: ["gpt-5.6-sol"], }, }, }, } ``` Nilai yang ditampilkan adalah nilai bawaan, kecuali `applyPatch.allowModels` (kosong/tidak ditetapkan secara default, yang berarti model kompatibel apa pun dapat menggunakan `apply_patch`). `approvalRunningNoticeMs` menampilkan pemberitahuan bahwa proses sedang berjalan ketika eksekusi yang memerlukan persetujuan berlangsung lama; `0` menonaktifkannya. ### `tools.loopDetection` Pemeriksaan keamanan perulangan alat **dinonaktifkan secara default**. Tetapkan `enabled: true` untuk mengaktifkan deteksi. Pengaturan dapat ditentukan secara global di `tools.loopDetection` dan diganti per agen di `agents.list[].tools.loopDetection`. ```json5 { tools: { loopDetection: { enabled: true, historySize: 30, warningThreshold: 10, unknownToolThreshold: 10, criticalThreshold: 20, globalCircuitBreakerThreshold: 30, detectors: { genericRepeat: true, knownPollNoProgress: true, pingPong: true, }, postCompactionGuard: { windowSize: 3, }, }, }, } ``` Jumlah maksimum riwayat pemanggilan alat yang dipertahankan untuk analisis perulangan. Ambang pola berulang tanpa kemajuan untuk peringatan. Memblokir pemanggilan berulang terhadap nama alat yang sama yang tidak tersedia/tidak dikenal setelah kegagalan sebanyak ini. Ambang pengulangan yang lebih tinggi untuk memblokir perulangan kritis. Ambang penghentian paksa untuk setiap proses tanpa kemajuan. Memperingatkan pemanggilan berulang dengan alat dan argumen yang sama. Memperingatkan/memblokir alat jajak pendapat yang dikenal (`process.poll`, `command_status`, dan sebagainya). Memperingatkan/memblokir pola pasangan tanpa kemajuan yang bergantian. Jumlah percobaan setelah pemadatan otomatis yang membuat pengaman tetap aktif; proses dibatalkan jika agen mengulangi kombinasi yang sama (alat, argumen, hasil) dalam jendela tersebut. Jika `warningThreshold >= criticalThreshold` atau `criticalThreshold >= globalCircuitBreakerThreshold`, validasi gagal. ### `tools.web` ```json5 { tools: { web: { search: { enabled: true, apiKey: "brave_api_key", // or BRAVE_API_KEY env (Brave provider) maxResults: 5, timeoutSeconds: 30, cacheTtlMinutes: 15, }, fetch: { enabled: true, provider: "firecrawl", // optional; omit for auto-detect maxChars: 20000, maxCharsCap: 20000, maxResponseBytes: 750000, timeoutSeconds: 30, cacheTtlMinutes: 15, maxRedirects: 3, readability: true, userAgent: "custom-ua", }, }, }, } ``` Nilai yang ditampilkan merupakan nilai bawaan, kecuali `provider` dan `userAgent`. `maxResponseBytes` dibatasi ke 32000–10000000; `maxChars` dibatasi hingga `maxCharsCap` (naikkan `maxCharsCap` untuk mengizinkan respons yang lebih besar). ### `tools.media` Mengonfigurasi pemahaman media masuk (gambar/audio/video): ```json5 { tools: { media: { concurrency: 2, asyncCompletion: { directSend: false, // deprecated: completions stay agent-mediated }, audio: { enabled: true, maxBytes: 20971520, scope: { default: "deny", rules: [{ action: "allow", match: { chatType: "direct" } }], }, models: [ { provider: "openai", model: "gpt-4o-mini-transcribe" }, { type: "cli", command: "whisper", args: ["--model", "base", "{{MediaPath}}"] }, ], }, image: { enabled: true, timeoutSeconds: 180, models: [{ provider: "ollama", model: "gemma4:26b", timeoutSeconds: 300 }], }, video: { enabled: true, maxBytes: 52428800, models: [{ provider: "google", model: "gemini-3-flash-preview" }], }, }, }, } ``` `concurrency` (bawaan `2`), `audio.maxBytes` (bawaan 20 MB), dan `video.maxBytes` (bawaan 50 MB) ditampilkan dengan nilai bawaannya; nilai bawaan `image.maxBytes` adalah 10 MB. Nilai bawaan batas waktu permintaan per kemampuan: gambar/audio `60` detik, video `120` detik. **Entri penyedia** (`type: "provider"` atau dihilangkan): - `provider`: id penyedia API (`openai`, `anthropic`, `google`/`gemini`, `groq`, dan sebagainya) - `model`: penggantian id model - `profile` / `preferredProfile`: pemilihan profil `auth-profiles.json` **Entri CLI** (`type: "cli"`): - `command`: berkas yang dapat dieksekusi untuk dijalankan - `args`: argumen bertemplat (mendukung `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}`, dan sebagainya; `openclaw doctor --fix` memigrasikan placeholder `{input}` yang tidak digunakan lagi ke `{{MediaPath}}`) **Kolom umum:** - `capabilities`: daftar opsional (`image`, `audio`, `video`). Setiap Plugin penyedia mendeklarasikan kumpulan kemampuan bawaannya sendiri; misalnya, penyedia `openai` yang disertakan menggunakan gambar+audio secara bawaan, `anthropic`/`minimax` menggunakan gambar, `google` menggunakan gambar+audio+video, dan `groq` menggunakan audio. - `prompt`, `maxChars`, `maxBytes`, `timeoutSeconds`, `language`: penggantian per entri. - `tools.media.image.timeoutSeconds` dan entri `timeoutSeconds` model gambar yang sesuai juga berlaku saat agen memanggil alat `image` secara eksplisit. Untuk pemahaman gambar, batas waktu ini berlaku pada permintaan itu sendiri dan tidak dikurangi oleh pekerjaan persiapan sebelumnya. - Jika terjadi kegagalan, sistem beralih ke entri berikutnya. Autentikasi penyedia mengikuti urutan standar: `auth-profiles.json` → variabel lingkungan → `models.providers.*.apiKey`. **Kolom penyelesaian asinkron:** - `asyncCompletion.directSend`: tanda kompatibilitas yang tidak digunakan lagi. Tugas media asinkron yang selesai tetap dimediasi melalui sesi pemohon agar agen menerima hasilnya, memutuskan cara menyampaikannya kepada pengguna, dan menggunakan alat pesan ketika pengiriman ke sumber memerlukannya. ### `tools.agentToAgent` ```json5 { tools: { agentToAgent: { enabled: false, allow: ["home", "work"], }, }, } ``` ### `tools.sessions` Mengontrol sesi yang dapat ditargetkan oleh alat sesi (`sessions_list`, `sessions_history`, `sessions_send`). Bawaan: `tree` (sesi saat ini + sesi yang dibuat olehnya, seperti subagen). ```json5 { tools: { sessions: { // "self" | "tree" | "agent" | "all" visibility: "tree", }, }, } ``` - `self`: hanya kunci sesi saat ini. - `tree`: sesi saat ini + sesi yang dibuat oleh sesi saat ini (subagen). - `agent`: sesi apa pun yang dimiliki oleh id agen saat ini (dapat mencakup pengguna lain jika Anda menjalankan sesi per pengirim dengan id agen yang sama). - `all`: sesi apa pun. Penargetan lintas agen tetap memerlukan `tools.agentToAgent`. - Pembatasan sandbox: ketika sesi saat ini berada dalam sandbox dan `agents.defaults.sandbox.sessionToolsVisibility="spawned"` (nilai bawaan), visibilitas dipaksa menjadi `tree` meskipun `tools.sessions.visibility="all"`. - Jika bukan `all`, `sessions_list` menyertakan kolom ringkas `visibility` yang menjelaskan mode efektif dan peringatan bahwa beberapa sesi mungkin tidak disertakan karena berada di luar cakupan saat ini. ### `tools.sessions_spawn` Mengontrol dukungan lampiran sebaris untuk `sessions_spawn`. ```json5 { tools: { sessions_spawn: { attachments: { enabled: false, // opt-in: set true to allow inline file attachments maxTotalBytes: 5242880, // 5 MB total across all files maxFiles: 50, maxFileBytes: 1048576, // 1 MB per file retainOnSessionKeep: false, // keep attachments when cleanup="keep" }, }, }, } ``` - Lampiran memerlukan `enabled: true`. - Lampiran subagen diwujudkan ke ruang kerja anak di `.openclaw/attachments//` dengan sebuah `.manifest.json`. - Lampiran ACP hanya mendukung gambar dan diteruskan secara sebaris ke lingkungan waktu proses ACP setelah memenuhi batas jumlah berkas, jumlah byte per berkas, dan jumlah byte total yang sama. - Konten lampiran secara otomatis disamarkan dari penyimpanan transkrip. - Masukan Base64 divalidasi dengan pemeriksaan alfabet/padding yang ketat dan pengaman ukuran sebelum dekode. - Izin berkas lampiran subagen adalah `0700` untuk direktori dan `0600` untuk berkas. - Pembersihan subagen mengikuti kebijakan `cleanup`: `delete` selalu menghapus lampiran; `keep` mempertahankannya hanya ketika `retainOnSessionKeep: true`. ### `tools.experimental` Tanda alat bawaan eksperimental. Dinonaktifkan secara bawaan kecuali aturan pengaktifan otomatis GPT-5 dengan agen ketat berlaku. ```json5 { tools: { experimental: { planTool: true, // enable experimental update_plan }, }, } ``` - `planTool`: mengaktifkan alat terstruktur `update_plan` untuk melacak pekerjaan bertahap nontrivial. - Bawaan: `false`, kecuali `agents.defaults.embeddedAgent.executionContract` (atau penggantian per agen) diatur ke `"strict-agentic"` untuk proses penyedia `openai` terhadap id model keluarga GPT-5 (ini juga mencakup proses OpenAI Codex CLI karena perutean autentikasi/model Codex berada di bawah penyedia `openai`). Atur ke `true` untuk memaksa alat aktif di luar cakupan tersebut, atau `false` agar tetap nonaktif bahkan untuk proses GPT-5 dengan agen ketat. - Saat diaktifkan, prompt sistem juga menambahkan panduan penggunaan agar model hanya menggunakannya untuk pekerjaan yang substansial dan mempertahankan paling banyak satu langkah `in_progress`. ### `agents.defaults.subagents` ```json5 { agents: { defaults: { subagents: { allowAgents: ["research"], model: "minimax/MiniMax-M2.7", maxConcurrent: 8, runTimeoutSeconds: 900, announceTimeoutMs: 120000, archiveAfterMinutes: 60, }, }, }, } ``` - `model`: model bawaan untuk subagen yang dibuat. Jika dihilangkan, subagen mewarisi model pemanggil. - `allowAgents`: daftar izin bawaan id agen target yang dikonfigurasi untuk `sessions_spawn` ketika agen pemohon tidak menetapkan `subagents.allowAgents` miliknya sendiri (`["*"]` = target terkonfigurasi apa pun; bawaan: hanya agen yang sama). Entri kedaluwarsa yang konfigurasi agennya telah dihapus akan ditolak oleh `sessions_spawn` dan tidak disertakan dalam `agents_list`; jalankan `openclaw doctor --fix` untuk membersihkannya. - `maxConcurrent`: jumlah maksimum proses subagen bersamaan. Bawaan: `8`. - `runTimeoutSeconds`: batas waktu (detik) untuk `sessions_spawn` ketika pemanggil tidak memberikan penggantian sendiri. Bawaan: `0` (tanpa batas waktu); nilai `900` yang ditampilkan di atas adalah nilai opsional yang umum digunakan, bukan nilai bawaan bawaan sistem. - `announceTimeoutMs`: batas waktu per pemanggilan (milidetik) untuk percobaan pengiriman pengumuman `agent` oleh Gateway. Bawaan: `120000`. Percobaan ulang sementara dapat membuat total waktu tunggu pengumuman lebih lama daripada satu batas waktu yang dikonfigurasi. - `archiveAfterMinutes`: jumlah menit setelah sesi subagen selesai sebelum diarsipkan secara otomatis. Bawaan: `60`; `0` menonaktifkan pengarsipan otomatis. - Kebijakan alat per subagen: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`. --- ## Penyedia khusus dan URL dasar Plugin penyedia menerbitkan baris katalog modelnya sendiri. Tambahkan penyedia khusus melalui `models.providers` dalam konfigurasi atau `~/.openclaw/agents//agent/models.json`. Mengonfigurasi `baseUrl` penyedia khusus/lokal juga merupakan keputusan kepercayaan jaringan terbatas untuk permintaan HTTP model: OpenClaw mengizinkan asal `scheme://host:port` yang tepat tersebut melalui jalur pengambilan yang diamankan, tanpa menambahkan opsi konfigurasi terpisah atau memercayai asal privat lainnya. ```json5 { models: { mode: "merge", // merge (default) | replace providers: { "custom-proxy": { baseUrl: "http://localhost:4000/v1", apiKey: "LITELLM_KEY", api: "openai-completions", // openai-completions | openai-responses | anthropic-messages | google-generative-ai | etc. models: [ { id: "llama-3.1-8b", name: "Llama 3.1 8B", reasoning: false, input: ["text"], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, contextWindow: 128000, contextTokens: 96000, maxTokens: 32000, }, ], }, }, }, } ``` - Gunakan `authHeader: true` + `headers` untuk kebutuhan autentikasi khusus. - Timpa akar konfigurasi agen dengan `OPENCLAW_AGENT_DIR`. - Prioritas penggabungan untuk ID penyedia yang cocok: - Nilai `baseUrl` yang tidak kosong dalam `models.json` agen diprioritaskan. - Nilai `apiKey` agen yang tidak kosong diprioritaskan hanya jika penyedia tersebut tidak dikelola SecretRef dalam konteks konfigurasi/profil autentikasi saat ini. - Nilai `apiKey` penyedia yang dikelola SecretRef disegarkan dari penanda sumber (`ENV_VAR_NAME` untuk referensi variabel lingkungan, `secretref-managed` untuk referensi file/exec), alih-alih mempertahankan rahasia yang telah diuraikan. - Nilai header penyedia yang dikelola SecretRef disegarkan dari penanda sumber (`secretref-env:ENV_VAR_NAME` untuk referensi variabel lingkungan, `secretref-managed` untuk referensi file/exec). - `apiKey`/`baseUrl` agen yang kosong atau tidak ada kembali menggunakan `models.providers` dalam konfigurasi. - Untuk `contextWindow`/`maxTokens` model yang cocok: nilai konfigurasi eksplisit diprioritaskan jika tersedia dan valid (bilangan positif berhingga); jika tidak, nilai katalog implisit/yang dihasilkan akan digunakan. - `contextTokens` model yang cocok mengikuti aturan yang sama, yaitu nilai eksplisit diprioritaskan dan jika tidak ada maka nilai implisit digunakan; gunakan ini untuk membatasi konteks efektif tanpa mengubah metadata bawaan model. - Katalog Plugin penyedia disimpan sebagai serpihan katalog yang dihasilkan dan dimiliki Plugin di bawah status Plugin agen. - Gunakan `models.mode: "replace"` jika Anda ingin konfigurasi menulis ulang `models.json` sepenuhnya dan melewati penggabungan serpihan katalog yang dimiliki Plugin. - Persistensi penanda bersifat mengikuti sumber resmi: penanda ditulis dari snapshot konfigurasi sumber aktif (sebelum penguraian), bukan dari nilai rahasia runtime yang telah diuraikan. ### Detail bidang penyedia - `models.mode`: perilaku katalog penyedia (`merge` atau `replace`). - `models.providers`: peta penyedia khusus yang menggunakan ID penyedia sebagai kunci. - Pengeditan aman: gunakan `openclaw config set models.providers. '' --strict-json --merge` atau `openclaw config set models.providers..models '' --strict-json --merge` untuk pembaruan aditif. `config set` menolak penggantian destruktif kecuali Anda meneruskan `--replace`. - `models.providers.*.api`: adaptor permintaan (`openai-completions`, `openai-responses`, `openai-chatgpt-responses`, `anthropic-messages`, `google-generative-ai`, `google-vertex`, `github-copilot`, `bedrock-converse-stream`, `ollama`, `azure-openai-responses`). Untuk backend `/v1/chat/completions` yang dihosting sendiri seperti MLX, vLLM, SGLang, dan sebagian besar server lokal yang kompatibel dengan OpenAI, gunakan `openai-completions`. Penyedia khusus dengan `baseUrl` tetapi tanpa `api` menggunakan `openai-completions` secara default; tetapkan `openai-responses` hanya jika backend mendukung `/v1/responses`. - `models.providers.*.apiKey`: kredensial penyedia (utamakan substitusi SecretRef/variabel lingkungan). - `models.providers.*.auth`: strategi autentikasi (`api-key`, `token`, `oauth`, `aws-sdk`). - `models.providers.*.contextWindow`: jendela konteks bawaan default untuk model di bawah penyedia ini ketika entri model tidak menetapkan `contextWindow`. - `models.providers.*.contextTokens`: batas konteks runtime efektif default untuk model di bawah penyedia ini ketika entri model tidak menetapkan `contextTokens`. - `models.providers.*.maxTokens`: batas token keluaran default untuk model di bawah penyedia ini ketika entri model tidak menetapkan `maxTokens`. - `models.providers.*.timeoutSeconds`: batas waktu opsional per penyedia untuk permintaan HTTP model dalam detik, termasuk koneksi, header, isi, dan penanganan pembatalan total permintaan. - `models.providers.*.injectNumCtxForOpenAICompat`: untuk Ollama + `openai-completions`, sisipkan `options.num_ctx` ke dalam permintaan (default: `true`). - `models.providers.*.authHeader`: paksa pengiriman kredensial dalam header `Authorization` jika diperlukan. - `models.providers.*.baseUrl`: URL dasar API hulu. - `models.providers.*.headers`: header statis tambahan untuk perutean proksi/tenant. `models.providers.*.request`: penimpaan transportasi untuk permintaan HTTP penyedia model. - `request.headers`: header tambahan (digabungkan dengan default penyedia). Nilainya menerima SecretRef. - `request.auth`: penimpaan strategi autentikasi. Mode: `"provider-default"` (gunakan autentikasi bawaan penyedia), `"authorization-bearer"` (dengan `token`), `"header"` (dengan `headerName`, `value`, dan `prefix` opsional). - `request.proxy`: penimpaan proksi HTTP. Mode: `"env-proxy"` (gunakan variabel lingkungan `HTTP_PROXY`/`HTTPS_PROXY`), `"explicit-proxy"` (dengan `url`). Kedua mode menerima subobjek `tls` opsional. - `request.tls`: penimpaan TLS untuk koneksi langsung. Bidang: `ca`, `cert`, `key`, `passphrase` (semuanya menerima SecretRef), `serverName`, `insecureSkipVerify`. - `request.allowPrivateNetwork`: jika `true`, izinkan permintaan HTTP penyedia model ke rentang privat, CGNAT, atau rentang serupa melalui pengaman pengambilan HTTP penyedia. URL dasar penyedia khusus/lokal sudah memercayai origin yang dikonfigurasi secara persis, kecuali origin metadata/link-local yang tetap diblokir tanpa persetujuan eksplisit. Tetapkan ini ke `false` untuk tidak menggunakan kepercayaan origin persis. WebSocket menggunakan `request` yang sama untuk header/TLS, tetapi tidak menggunakan gerbang SSRF pengambilan tersebut. Default `false`. - `models.providers.*.models`: entri katalog model penyedia eksplisit. - `models.providers.*.models.*.input`: modalitas masukan model. Gunakan `["text"]` untuk model khusus teks dan `["text", "image"]` untuk model gambar/visi bawaan. Lampiran gambar hanya disisipkan ke giliran agen ketika model yang dipilih ditandai memiliki kemampuan gambar. - `models.providers.*.models.*.contextWindow`: metadata jendela konteks bawaan model. Nilai ini menimpa `contextWindow` tingkat penyedia untuk model tersebut. - `models.providers.*.models.*.contextTokens`: batas konteks runtime opsional. Nilai ini menimpa `contextTokens` tingkat penyedia; gunakan ketika Anda menginginkan anggaran konteks efektif yang lebih kecil daripada `contextWindow` bawaan model; `openclaw models list` menampilkan kedua nilai ketika nilainya berbeda. - `models.providers.*.models.*.compat.supportsDeveloperRole`: petunjuk kompatibilitas opsional. Untuk `api: "openai-completions"` dengan `baseUrl` nonbawaan yang tidak kosong (host bukan `api.openai.com`), OpenClaw memaksanya menjadi `false` saat runtime. `baseUrl` yang kosong/tidak dicantumkan mempertahankan perilaku default OpenAI. - `models.providers.*.models.*.compat.requiresStringContent`: petunjuk kompatibilitas opsional untuk endpoint obrolan kompatibel OpenAI yang hanya menerima string. Jika `true`, OpenClaw meratakan larik `messages[].content` yang hanya berisi teks menjadi string biasa sebelum mengirim permintaan. - `models.providers.*.models.*.compat.strictMessageKeys`: petunjuk kompatibilitas opsional untuk endpoint obrolan kompatibel OpenAI yang ketat. Jika `true`, OpenClaw menyederhanakan objek pesan Chat Completions keluar agar hanya berisi `role` dan `content` sebelum mengirim permintaan. - `models.providers.*.models.*.compat.thinkingFormat`: petunjuk opsional untuk muatan pemikiran. Gunakan `"together"` untuk `reasoning.enabled` bergaya Together, `"qwen"` untuk `enable_thinking` tingkat atas, atau `"qwen-chat-template"` untuk `chat_template_kwargs.enable_thinking` pada server kompatibel OpenAI keluarga Qwen yang mendukung argumen bernama templat obrolan tingkat permintaan, seperti vLLM. Model Qwen vLLM yang dikonfigurasi menyediakan pilihan biner `/think` (`off`, `on`) untuk format-format ini. - `models.providers.*.models.*.compat.requiresReasoningContentOnAssistantMessages`: petunjuk kompatibilitas opsional untuk backend Chat Completions bergaya DeepSeek yang mengharuskan pesan asisten sebelumnya mempertahankan `reasoning_content` saat diputar ulang. Jika `true`, OpenClaw mempertahankan bidang tersebut pada pesan asisten keluar. Gunakan ini saat menghubungkan proksi khusus kompatibel DeepSeek yang menolak permintaan setelah penalaran dihapus. Default `false`. - `plugins.entries.amazon-bedrock.config.discovery`: akar pengaturan penemuan otomatis Bedrock. - `plugins.entries.amazon-bedrock.config.discovery.enabled`: aktifkan/nonaktifkan penemuan implisit. - `plugins.entries.amazon-bedrock.config.discovery.region`: wilayah AWS untuk penemuan. - `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: filter ID penyedia opsional untuk penemuan yang ditargetkan. - `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`: interval polling untuk penyegaran penemuan. - `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: jendela konteks cadangan untuk model yang ditemukan. - `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: jumlah maksimum token keluaran cadangan untuk model yang ditemukan. Orientasi penyedia khusus interaktif menyimpulkan masukan gambar untuk pola ID model visi yang dikenal, termasuk GPT-4o/GPT-4.1/GPT-5+, keluarga penalaran `o1`/`o3`/`o4`, Claude, Gemini, semua ID dengan akhiran `-vl` (Qwen-VL dan yang serupa), serta keluarga bernama seperti LLaVA, Pixtral, InternVL, Mllama, MiniCPM-V, dan GLM-4V; proses ini melewati pertanyaan tambahan untuk keluarga yang diketahui hanya mendukung teks (Llama, DeepSeek, Mistral/Mixtral, Kimi/Moonshot, Codestral, Devstral, Phi, QwQ, CodeLlama, dan ID Qwen polos tanpa akhiran vl/vision). ID model yang tidak dikenal tetap memunculkan pertanyaan tentang dukungan gambar. Orientasi noninteraktif menggunakan penyimpulan yang sama; teruskan `--custom-image-input` untuk memaksakan metadata berkemampuan gambar atau `--custom-text-input` untuk memaksakan metadata khusus teks. ### Contoh penyedia Plugin penyedia eksternal resmi `cerebras` dapat mengonfigurasi ini melalui `openclaw onboard --auth-choice cerebras-api-key`. Gunakan konfigurasi penyedia eksplisit hanya saat menimpa default. ```json5 { env: { CEREBRAS_API_KEY: "sk-..." }, agents: { defaults: { model: { primary: "cerebras/zai-glm-4.7", fallbacks: ["cerebras/gpt-oss-120b"], }, models: { "cerebras/zai-glm-4.7": { alias: "GLM 4.7 (Cerebras)" }, "cerebras/gpt-oss-120b": { alias: "GPT OSS 120B (Cerebras)" }, }, }, }, models: { mode: "merge", providers: { cerebras: { baseUrl: "https://api.cerebras.ai/v1", apiKey: "${CEREBRAS_API_KEY}", api: "openai-completions", models: [ { id: "zai-glm-4.7", name: "GLM 4.7 (Cerebras)" }, { id: "gpt-oss-120b", name: "GPT OSS 120B (Cerebras)" }, ], }, }, }, } ``` Gunakan `cerebras/zai-glm-4.7` untuk Cerebras; `zai/glm-4.7` untuk akses langsung Z.AI. ```json5 { env: { KIMI_API_KEY: "sk-..." }, agents: { defaults: { model: { primary: "kimi/kimi-for-coding" }, models: { "kimi/kimi-for-coding": { alias: "Kimi Code" } }, }, }, } ``` Kompatibel dengan Anthropic, penyedia bawaan. Pintasan: `openclaw onboard --auth-choice kimi-code-api-key`. Lihat [Model Lokal](/id/gateway/local-models). Singkatnya: jalankan model lokal besar melalui LM Studio Responses API pada perangkat keras berkemampuan tinggi; tetap gabungkan model yang di-host sebagai fallback. ```json5 { agents: { defaults: { model: { primary: "minimax/MiniMax-M3" }, models: { "minimax/MiniMax-M3": { alias: "Minimax" }, }, }, }, models: { mode: "merge", providers: { minimax: { baseUrl: "https://api.minimax.io/anthropic", apiKey: "${MINIMAX_API_KEY}", api: "anthropic-messages", models: [ { id: "MiniMax-M3", name: "MiniMax M3", reasoning: true, input: ["text", "image"], cost: { input: 0.6, output: 2.4, cacheRead: 0.12, cacheWrite: 0 }, contextWindow: 1000000, maxTokens: 131072, }, ], }, }, }, } ``` Tetapkan `MINIMAX_API_KEY`. Pintasan: `openclaw onboard --auth-choice minimax-global-api` atau `openclaw onboard --auth-choice minimax-cn-api`. Katalog model secara default menggunakan M3 dan juga mencakup varian M2.7. Pada jalur streaming yang kompatibel dengan Anthropic, OpenClaw menonaktifkan proses berpikir MiniMax M2.x secara default kecuali Anda menetapkan `thinking` sendiri secara eksplisit; MiniMax-M3 (dan M3.x) secara default tetap menggunakan jalur proses berpikir adaptif/tidak ditentukan milik penyedia. `/fast on` atau `params.fastMode: true` mengubah `MiniMax-M2.7` menjadi `MiniMax-M2.7-highspeed`. ```json5 { env: { MOONSHOT_API_KEY: "sk-..." }, agents: { defaults: { model: { primary: "moonshot/kimi-k2.6" }, models: { "moonshot/kimi-k2.6": { alias: "Kimi K2.6" } }, }, }, models: { mode: "merge", providers: { moonshot: { baseUrl: "https://api.moonshot.ai/v1", apiKey: "${MOONSHOT_API_KEY}", api: "openai-completions", models: [ { id: "kimi-k2.6", name: "Kimi K2.6", reasoning: false, input: ["text", "image"], cost: { input: 0.95, output: 4, cacheRead: 0.16, cacheWrite: 0 }, contextWindow: 262144, maxTokens: 262144, }, ], }, }, }, } ``` Untuk endpoint Tiongkok: `baseUrl: "https://api.moonshot.cn/v1"` atau `openclaw onboard --auth-choice moonshot-api-key-cn`. Endpoint asli Moonshot menyatakan kompatibilitas penggunaan streaming pada transport `openai-completions` bersama, dan OpenClaw mengaktifkannya berdasarkan kemampuan endpoint, bukan hanya ID penyedia bawaan. ```json5 { agents: { defaults: { model: { primary: "opencode/claude-opus-4-6" }, models: { "opencode/claude-opus-4-6": { alias: "Opus" } }, }, }, } ``` Tetapkan `OPENCODE_API_KEY` (atau `OPENCODE_ZEN_API_KEY`). Gunakan referensi `opencode/...` untuk katalog Zen atau referensi `opencode-go/...` untuk katalog Go. Pintasan: `openclaw onboard --auth-choice opencode-zen` atau `openclaw onboard --auth-choice opencode-go`. ```json5 { env: { SYNTHETIC_API_KEY: "sk-..." }, agents: { defaults: { model: { primary: "synthetic/hf:MiniMaxAI/MiniMax-M2.5" }, models: { "synthetic/hf:MiniMaxAI/MiniMax-M2.5": { alias: "MiniMax M2.5" } }, }, }, models: { mode: "merge", providers: { synthetic: { baseUrl: "https://api.synthetic.new/anthropic", apiKey: "${SYNTHETIC_API_KEY}", api: "anthropic-messages", models: [ { id: "hf:MiniMaxAI/MiniMax-M2.5", name: "MiniMax M2.5", reasoning: true, input: ["text"], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, contextWindow: 192000, maxTokens: 65536, }, ], }, }, }, } ``` URL dasar tidak boleh menyertakan `/v1` (klien Anthropic menambahkannya). Pintasan: `openclaw onboard --auth-choice synthetic-api-key`. ```json5 { agents: { defaults: { model: { primary: "zai/glm-4.7" }, models: { "zai/glm-4.7": {} }, }, }, } ``` Tetapkan `ZAI_API_KEY`. Referensi model menggunakan ID penyedia kanonis `zai/*`. Pintasan: `openclaw onboard --auth-choice zai-api-key`. - Endpoint umum: `https://api.z.ai/api/paas/v4` - Endpoint pemrograman: `https://api.z.ai/api/coding/paas/v4` - Pilihan autentikasi default `zai-api-key` memeriksa kunci Anda dan secara otomatis mendeteksi endpoint yang sesuai (beralih ke prompt dengan default Global jika hasil deteksi tidak meyakinkan). Pilihan autentikasi khusus CN dan Coding-Plan juga tersedia untuk pemilihan eksplisit. - Untuk endpoint umum, tentukan penyedia khusus dengan penggantian URL dasar. --- ## Terkait - [Konfigurasi — agen](/id/gateway/config-agents) - [Konfigurasi — saluran](/id/gateway/config-channels) - [Referensi konfigurasi](/id/gateway/configuration-reference) — kunci tingkat teratas lainnya - [Alat dan Plugin](/id/tools)