Konfigurasi — alat dan provider kustom

​

Alat

​

Profil alat

​

Grup alat

​

tools.allow / tools.deny

{
  tools: { deny: ["browser", "canvas"] },
}

​

tools.byProvider

{
  tools: {
    profile: "coding",
    byProvider: {
      "google-antigravity": { profile: "minimal" },
      "openai/gpt-5.4": { allow: ["group:fs", "sessions_list"] },
    },
  },
}

​

tools.elevated

{
  tools: {
    elevated: {
      enabled: true,
      allowFrom: {
        whatsapp: ["+15555550123"],
        discord: ["1234567890123", "987654321098765432"],
      },
    },
  },
}

• Override per-agen (agents.list[].tools.elevated) hanya dapat membatasi lebih lanjut.
• /elevated on|off|ask|full menyimpan status per sesi; direktif inline berlaku untuk satu pesan.
• exec elevated melewati sandboxing dan menggunakan escape path yang dikonfigurasi (gateway secara default, atau node saat target exec adalah node).

​

tools.exec

{
  tools: {
    exec: {
      backgroundMs: 10000,
      timeoutSec: 1800,
      cleanupMs: 1800000,
      notifyOnExit: true,
      notifyOnExitEmptySuccess: false,
      applyPatch: {
        enabled: false,
        allowModels: ["gpt-5.5"],
      },
    },
  },
}

​

tools.loopDetection

{
  tools: {
    loopDetection: {
      enabled: true,
      historySize: 30,
      warningThreshold: 10,
      criticalThreshold: 20,
      globalCircuitBreakerThreshold: 30,
      detectors: {
        genericRepeat: true,
        knownPollNoProgress: true,
        pingPong: true,
      },
    },
  },
}

• historySize: jumlah maksimum riwayat pemanggilan alat yang disimpan untuk analisis loop.
• warningThreshold: ambang pola berulang tanpa progres untuk peringatan.
• criticalThreshold: ambang berulang yang lebih tinggi untuk memblokir loop kritis.
• globalCircuitBreakerThreshold: ambang penghentian keras untuk eksekusi apa pun tanpa progres.
• detectors.genericRepeat: peringatkan pada pemanggilan alat yang sama/argumen yang sama secara berulang.
• detectors.knownPollNoProgress: peringatkan/blokir alat polling yang dikenal (process.poll, command_status, dll.).
• detectors.pingPong: peringatkan/blokir pola pasangan bolak-balik tanpa progres.
• Jika warningThreshold >= criticalThreshold atau criticalThreshold >= globalCircuitBreakerThreshold, validasi gagal.

​

tools.web

{
  tools: {
    web: {
      search: {
        enabled: true,
        apiKey: "brave_api_key", // atau env BRAVE_API_KEY
        maxResults: 5,
        timeoutSeconds: 30,
        cacheTtlMinutes: 15,
      },
      fetch: {
        enabled: true,
        provider: "firecrawl", // opsional; hilangkan untuk deteksi otomatis
        maxChars: 50000,
        maxCharsCap: 50000,
        maxResponseBytes: 2000000,
        timeoutSeconds: 30,
        cacheTtlMinutes: 15,
        maxRedirects: 3,
        readability: true,
        userAgent: "custom-ua",
      },
    },
  },
}

​

tools.media

{
  tools: {
    media: {
      concurrency: 2,
      asyncCompletion: {
        directSend: false, // opt-in: kirim musik/video async yang selesai langsung ke saluran
      },
      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}}"] },
        ],
      },
      video: {
        enabled: true,
        maxBytes: 52428800,
        models: [{ provider: "google", model: "gemini-3-flash-preview" }],
      },
    },
  },
}

​

tools.agentToAgent

{
  tools: {
    agentToAgent: {
      enabled: false,
      allow: ["home", "work"],
    },
  },
}

​

tools.sessions

{
  tools: {
    sessions: {
      // "self" | "tree" | "agent" | "all"
      visibility: "tree",
    },
  },
}

• self: hanya kunci sesi saat ini.
• tree: sesi saat ini + sesi yang dihasilkan 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 di bawah id agen yang sama).
• all: sesi apa pun. Penargetan lintas agen tetap memerlukan tools.agentToAgent.
• Pembatas sandbox: saat sesi saat ini tersandbox dan agents.defaults.sandbox.sessionToolsVisibility="spawned", visibility dipaksa menjadi tree meskipun tools.sessions.visibility="all".

​

tools.sessions_spawn

{
  tools: {
    sessions_spawn: {
      attachments: {
        enabled: false, // opt-in: setel true untuk mengizinkan lampiran file inline
        maxTotalBytes: 5242880, // total 5 MB untuk semua file
        maxFiles: 50,
        maxFileBytes: 1048576, // 1 MB per file
        retainOnSessionKeep: false, // pertahankan lampiran saat cleanup="keep"
      },
    },
  },
}

• Lampiran hanya didukung untuk runtime: "subagent". Runtime ACP menolaknya.
• File dimaterialisasi ke workspace anak di .openclaw/attachments/<uuid>/ dengan .manifest.json.
• Konten lampiran secara otomatis disamarkan dari persistensi transkrip.
• Input Base64 divalidasi dengan pemeriksaan alfabet/padding yang ketat dan guard ukuran pra-decode.
• Izin file adalah 0700 untuk direktori dan 0600 untuk file.
• Pembersihan mengikuti kebijakan cleanup: delete selalu menghapus lampiran; keep mempertahankannya hanya saat retainOnSessionKeep: true.

​

tools.experimental

{
  tools: {
    experimental: {
      planTool: true, // aktifkan update_plan eksperimental
    },
  },
}

• planTool: mengaktifkan alat update_plan terstruktur untuk pelacakan pekerjaan multi-langkah yang tidak sepele.
• Default: false kecuali agents.defaults.embeddedPi.executionContract (atau override per-agen) disetel ke "strict-agentic" untuk eksekusi keluarga GPT-5 OpenAI atau OpenAI Codex. Setel true untuk memaksa alat aktif di luar cakupan itu, atau false untuk tetap menonaktifkannya bahkan untuk eksekusi GPT-5 strict-agentic.
• Saat diaktifkan, system prompt juga menambahkan panduan penggunaan agar model hanya menggunakannya untuk pekerjaan yang substansial dan mempertahankan paling banyak satu langkah in_progress.

​

agents.defaults.subagents

{
  agents: {
    defaults: {
      subagents: {
        allowAgents: ["research"],
        model: "minimax/MiniMax-M2.7",
        maxConcurrent: 8,
        runTimeoutSeconds: 900,
        archiveAfterMinutes: 60,
      },
    },
  },
}

• model: model default untuk subagen yang dihasilkan. Jika dihilangkan, subagen mewarisi model pemanggil.
• allowAgents: allowlist default id agen target untuk sessions_spawn saat agen peminta tidak menetapkan subagents.allowAgents sendiri (["*"] = apa pun; default: hanya agen yang sama).
• runTimeoutSeconds: timeout default (detik) untuk sessions_spawn saat pemanggilan alat tidak menyertakan runTimeoutSeconds. 0 berarti tanpa timeout.
• Kebijakan alat per-subagen: tools.subagents.tools.allow / tools.subagents.tools.deny.

​

Provider kustom dan base URL

{
  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
        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 auth kustom.
• Override root config agen dengan OPENCLAW_AGENT_DIR (atau PI_CODING_AGENT_DIR, alias variabel environment lama).
• Prioritas merge untuk ID provider yang cocok:
  • Nilai baseUrl models.json agen yang tidak kosong menang.
  • Nilai apiKey agen yang tidak kosong menang hanya ketika provider tersebut tidak dikelola SecretRef dalam konteks config/profil-auth saat ini.
  • Nilai apiKey provider yang dikelola SecretRef disegarkan dari penanda sumber (ENV_VAR_NAME untuk ref env, secretref-managed untuk ref file/exec) alih-alih menyimpan secret yang telah diselesaikan.
  • Nilai header provider yang dikelola SecretRef disegarkan dari penanda sumber (secretref-env:ENV_VAR_NAME untuk ref env, secretref-managed untuk ref file/exec).
  • apiKey/baseUrl agen yang kosong atau tidak ada melakukan fallback ke models.providers di config.
  • contextWindow/maxTokens model yang cocok menggunakan nilai yang lebih tinggi antara config eksplisit dan nilai katalog implisit.
  • contextTokens model yang cocok mempertahankan batas runtime eksplisit saat ada; gunakan untuk membatasi konteks efektif tanpa mengubah metadata model bawaan.
  • Gunakan models.mode: "replace" saat Anda ingin config sepenuhnya menulis ulang models.json.
  • Persistensi marker bersifat source-authoritative: marker ditulis dari snapshot config sumber aktif (pra-resolusi), bukan dari nilai secret runtime yang telah diselesaikan.

​

Detail field provider

• models.mode: perilaku katalog provider (merge atau replace).
• models.providers: peta provider kustom yang diberi kunci oleh id provider.
  • Edit 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 memberikan --replace.
• models.providers.*.api: adaptor permintaan (openai-completions, openai-responses, anthropic-messages, google-generative-ai, dll).
• models.providers.*.apiKey: kredensial provider (lebih baik gunakan substitusi SecretRef/env).
• models.providers.*.auth: strategi auth (api-key, token, oauth, aws-sdk).
• models.providers.*.injectNumCtxForOpenAICompat: untuk Ollama + openai-completions, suntikkan options.num_ctx ke permintaan (default: true).
• models.providers.*.authHeader: paksa transport kredensial di header Authorization saat diperlukan.
• models.providers.*.baseUrl: base URL API upstream.
• models.providers.*.headers: header statis tambahan untuk perutean proxy/tenant.
• models.providers.*.request: override transport untuk permintaan HTTP provider model.
  • request.headers: header tambahan (digabungkan dengan default provider). Nilai menerima SecretRef.
  • request.auth: override strategi auth. Mode: "provider-default" (gunakan auth bawaan provider), "authorization-bearer" (dengan token), "header" (dengan headerName, value, prefix opsional).
  • request.proxy: override proxy HTTP. Mode: "env-proxy" (gunakan variabel env HTTP_PROXY/HTTPS_PROXY), "explicit-proxy" (dengan url). Kedua mode menerima sub-objek tls opsional.
  • request.tls: override TLS untuk koneksi langsung. Field: ca, cert, key, passphrase (semuanya menerima SecretRef), serverName, insecureSkipVerify.
  • request.allowPrivateNetwork: saat true, izinkan HTTPS ke baseUrl saat DNS menyelesaikan ke rentang private, CGNAT, atau serupa, melalui fetch guard HTTP provider (opt-in operator untuk endpoint self-hosted tepercaya yang kompatibel dengan OpenAI). WebSocket menggunakan request yang sama untuk header/TLS tetapi tidak menggunakan gerbang SSRF fetch itu. Default false.
• models.providers.*.models: entri katalog model provider eksplisit.
• models.providers.*.models.*.contextWindow: metadata jendela konteks model bawaan.
• models.providers.*.models.*.contextTokens: batas konteks runtime opsional. Gunakan ini saat Anda menginginkan anggaran konteks efektif yang lebih kecil daripada contextWindow bawaan model.
• models.providers.*.models.*.compat.supportsDeveloperRole: petunjuk kompatibilitas opsional. Untuk api: "openai-completions" dengan baseUrl non-native yang tidak kosong (host bukan api.openai.com), OpenClaw memaksa ini menjadi false saat runtime. baseUrl kosong/tidak ada mempertahankan perilaku default OpenAI.
• models.providers.*.models.*.compat.requiresStringContent: petunjuk kompatibilitas opsional untuk endpoint chat kompatibel OpenAI yang hanya menerima string. Saat true, OpenClaw meratakan array messages[].content teks murni menjadi string biasa sebelum mengirim permintaan.
• plugins.entries.amazon-bedrock.config.discovery: root pengaturan auto-discovery Bedrock.
• plugins.entries.amazon-bedrock.config.discovery.enabled: aktifkan/nonaktifkan discovery implisit.
• plugins.entries.amazon-bedrock.config.discovery.region: region AWS untuk discovery.
• plugins.entries.amazon-bedrock.config.discovery.providerFilter: filter id provider opsional untuk discovery terarah.
• plugins.entries.amazon-bedrock.config.discovery.refreshInterval: interval polling untuk refresh discovery.
• plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow: jendela konteks fallback untuk model yang ditemukan.
• plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens: token output maksimum fallback untuk model yang ditemukan.

​

Contoh provider

{
  env: { CEREBRAS_API_KEY: "sk-..." },
  agents: {
    defaults: {
      model: {
        primary: "cerebras/zai-glm-4.7",
        fallbacks: ["cerebras/zai-glm-4.6"],
      },
      models: {
        "cerebras/zai-glm-4.7": { alias: "GLM 4.7 (Cerebras)" },
        "cerebras/zai-glm-4.6": { alias: "GLM 4.6 (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: "zai-glm-4.6", name: "GLM 4.6 (Cerebras)" },
        ],
      },
    },
  },
}

{
  agents: {
    defaults: {
      model: { primary: "opencode/claude-opus-4-6" },
      models: { "opencode/claude-opus-4-6": { alias: "Opus" } },
    },
  },
}

{
  agents: {
    defaults: {
      model: { primary: "zai/glm-4.7" },
      models: { "zai/glm-4.7": {} },
    },
  },
}

{
  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,
          },
        ],
      },
    },
  },
}

{
  env: { KIMI_API_KEY: "sk-..." },
  agents: {
    defaults: {
      model: { primary: "kimi/kimi-code" },
      models: { "kimi/kimi-code": { alias: "Kimi Code" } },
    },
  },
}

{
  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,
          },
        ],
      },
    },
  },
}

{
  agents: {
    defaults: {
      model: { primary: "minimax/MiniMax-M2.7" },
      models: {
        "minimax/MiniMax-M2.7": { alias: "Minimax" },
      },
    },
  },
  models: {
    mode: "merge",
    providers: {
      minimax: {
        baseUrl: "https://api.minimax.io/anthropic",
        apiKey: "${MINIMAX_API_KEY}",
        api: "anthropic-messages",
        models: [
          {
            id: "MiniMax-M2.7",
            name: "MiniMax M2.7",
            reasoning: true,
            input: ["text", "image"],
            cost: { input: 0.3, output: 1.2, cacheRead: 0.06, cacheWrite: 0.375 },
            contextWindow: 204800,
            maxTokens: 131072,
          },
        ],
      },
    },
  },
}

​

Terkait

• Referensi konfigurasi — kunci tingkat atas lainnya
• Konfigurasi — agen
• Konfigurasi — channels
• Alat dan plugin