OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Gateway

Konfigurasi — alat dan penyedia khusus

Kunci konfigurasi tools.* dan penyiapan penyedia khusus / URL dasar. Untuk agen, kanal, dan kunci konfigurasi tingkat atas lainnya, lihat Referensi konfigurasi.

Alat

Profil alat

tools.profile menetapkan daftar izin dasar sebelum tools.allow/tools.deny:

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/<server>.d.ts") untuk memeriksa tanda tangan bergaya TypeScript sebelum memanggil MCP.<server>.<tool>(). Lihat Mode kode 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"] },}

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:<channelId>:<senderId>, id:<senderId>, e164:<phone>, username:<handle>, name:<displayName>, 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,      },    },  },}
historySizenumber

Jumlah maksimum riwayat pemanggilan alat yang dipertahankan untuk analisis perulangan.

warningThresholdnumber

Ambang pola berulang tanpa kemajuan untuk peringatan.

unknownToolThresholdnumber

Memblokir pemanggilan berulang terhadap nama alat yang sama yang tidak tersedia/tidak dikenal setelah kegagalan sebanyak ini.

criticalThresholdnumber

Ambang pengulangan yang lebih tinggi untuk memblokir perulangan kritis.

globalCircuitBreakerThresholdnumber

Ambang penghentian paksa untuk setiap proses tanpa kemajuan.

detectors.genericRepeatboolean

Memperingatkan pemanggilan berulang dengan alat dan argumen yang sama.

detectors.knownPollNoProgressboolean

Memperingatkan/memblokir alat jajak pendapat yang dikenal (process.poll, command_status, dan sebagainya).

detectors.pingPongboolean

Memperingatkan/memblokir pola pasangan tanpa kemajuan yang bergantian.

postCompactionGuard.windowSizenumber

Jumlah percobaan setelah pemadatan otomatis yang membuat pengaman tetap aktif; proses dibatalkan jika agen mengulangi kombinasi yang sama (alat, argumen, hasil) dalam jendela tersebut.

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.

Kolom entri model media

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",    },  },}
Cakupan visibilitas
  • 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"      },    },  },}
Catatan lampiran
  • Lampiran memerlukan enabled: true.
  • Lampiran subagen diwujudkan ke ruang kerja anak di .openclaw/attachments/<uuid>/ 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/<agentId>/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,          },        ],      },    },  },}
Autentikasi dan prioritas penggabungan
  • 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

Katalog tingkat atas
  • 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.<id> '<json>' --strict-json --merge atau openclaw config set models.providers.<id>.models '<json-array>' --strict-json --merge untuk pembaruan aditif. config set menolak penggantian destruktif kecuali Anda meneruskan --replace.
Koneksi dan autentikasi penyedia
  • 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.
Penimpaan transportasi permintaan

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.
Entri katalog model
  • 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.
Penemuan Amazon Bedrock
  • 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

Cerebras (GLM 4.7 / GPT OSS)

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.

Kimi Coding
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.

Model lokal (LM Studio)

Lihat Model Lokal. Singkatnya: jalankan model lokal besar melalui LM Studio Responses API pada perangkat keras berkemampuan tinggi; tetap gabungkan model yang di-host sebagai fallback.

MiniMax M3 (langsung)
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.

Moonshot AI (Kimi)
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.

OpenCode
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.

Synthetic (kompatibel dengan Anthropic)
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.

Z.AI (GLM-4.7)
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

Was this useful?
On this page

On this page