Yapılandırma — araçlar ve özel sağlayıcılar

​

Araçlar

​

Araç profilleri

​

Araç grupları

​

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

• Aracı başına geçersiz kılma (agents.list[].tools.elevated) yalnızca daha fazla kısıtlama getirebilir.
• /elevated on|off|ask|full, durumu oturum başına saklar; satır içi yönergeler tek mesaja uygulanır.
• Yükseltilmiş exec, sandbox’ı atlar ve yapılandırılmış kaçış yolunu kullanır (varsayılan olarak gateway, veya exec hedefi node olduğunda 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: döngü analizi için tutulan en fazla araç çağrısı geçmişi.
• warningThreshold: uyarılar için yinelenen ilerlemesiz desen eşiği.
• criticalThreshold: kritik döngüleri engellemek için daha yüksek yineleme eşiği.
• globalCircuitBreakerThreshold: herhangi bir ilerlemesiz çalıştırma için sert durdurma eşiği.
• detectors.genericRepeat: yinelenen aynı-araç/aynı-bağımsız değişken çağrılarında uyarır.
• detectors.knownPollNoProgress: bilinen yoklama araçlarında (process.poll, command_status vb.) uyarır/engeller.
• detectors.pingPong: dönüşümlü ilerlemesiz çift desenlerde uyarır/engeller.
• warningThreshold >= criticalThreshold veya criticalThreshold >= globalCircuitBreakerThreshold ise doğrulama başarısız olur.

​

tools.web

{
  tools: {
    web: {
      search: {
        enabled: true,
        apiKey: "brave_api_key", // veya BRAVE_API_KEY env
        maxResults: 5,
        timeoutSeconds: 30,
        cacheTtlMinutes: 15,
      },
      fetch: {
        enabled: true,
        provider: "firecrawl", // isteğe bağlı; otomatik algılama için çıkarın
        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, // katılımlı: tamamlanmış eşzamansız müzik/videoyu doğrudan kanala gönder
      },
      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: yalnızca geçerli oturum anahtarı.
• tree: geçerli oturum + geçerli oturumun oluşturduğu oturumlar (alt aracılar).
• agent: geçerli aracı kimliğine ait herhangi bir oturum (aynı aracı kimliği altında gönderen başına oturumlar çalıştırıyorsanız başka kullanıcıları da içerebilir).
• all: herhangi bir oturum. Aracılar arası hedefleme yine de tools.agentToAgent gerektirir.
• Sandbox kıskacı: geçerli oturum sandbox içindeyse ve agents.defaults.sandbox.sessionToolsVisibility="spawned" ise, tools.sessions.visibility="all" olsa bile görünürlük tree olmaya zorlanır.

​

tools.sessions_spawn

{
  tools: {
    sessions_spawn: {
      attachments: {
        enabled: false, // katılımlı: satır içi dosya eklerine izin vermek için true yapın
        maxTotalBytes: 5242880, // tüm dosyalar arasında toplam 5 MB
        maxFiles: 50,
        maxFileBytes: 1048576, // dosya başına 1 MB
        retainOnSessionKeep: false, // cleanup="keep" olduğunda ekleri tut
      },
    },
  },
}

• Ekler yalnızca runtime: "subagent" için desteklenir. ACP çalışma zamanı bunları reddeder.
• Dosyalar alt çalışma alanında .openclaw/attachments/<uuid>/ içine .manifest.json ile birlikte somutlaştırılır.
• Ek içeriği transkript kalıcılığından otomatik olarak sansürlenir.
• Base64 girdileri sıkı alfabe/dolgu denetimleri ve kod çözme öncesi boyut koruması ile doğrulanır.
• Dosya izinleri dizinler için 0700, dosyalar için 0600 olur.
• Temizleme cleanup ilkesini izler: delete her zaman ekleri kaldırır; keep, yalnızca retainOnSessionKeep: true olduğunda bunları saklar.

​

tools.experimental

{
  tools: {
    experimental: {
      planTool: true, // deneysel update_plan aracını etkinleştir
    },
  },
}

• planTool: önemsiz olmayan çok adımlı iş takibi için yapılandırılmış update_plan aracını etkinleştirir.
• Varsayılan: agents.defaults.embeddedPi.executionContract (veya aracı başına geçersiz kılma) OpenAI veya OpenAI Codex GPT-5 ailesi bir çalıştırma için "strict-agentic" olarak ayarlanmadıkça false. Aracı bu kapsamın dışında zorla açmak için true, strict-agentic GPT-5 çalıştırmalarında bile kapalı tutmak için false ayarlayın.
• Etkinleştirildiğinde sistem istemi, modelin bunu yalnızca önemli işler için kullanması ve en fazla bir adımı in_progress tutması için kullanım yönergeleri de ekler.

​

agents.defaults.subagents

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

• model: oluşturulan alt aracılar için varsayılan model. Atlanırsa alt aracılar çağıranın modelini devralır.
• allowAgents: istekte bulunan aracı kendi subagents.allowAgents değerini ayarlamadığında sessions_spawn için hedef aracı kimliklerinin varsayılan izin listesi (["*"] = herhangi biri; varsayılan: yalnızca aynı aracı).
• runTimeoutSeconds: araç çağrısı runTimeoutSeconds sağlamadığında sessions_spawn için varsayılan zaman aşımı (saniye). 0, zaman aşımı olmadığı anlamına gelir.
• Alt aracı başına araç ilkesi: tools.subagents.tools.allow / tools.subagents.tools.deny.

​

Özel sağlayıcılar ve base URL’ler

{
  models: {
    mode: "merge", // merge (varsayılan) | 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,
          },
        ],
      },
    },
  },
}

• Özel kimlik doğrulama gereksinimleri için authHeader: true + headers kullanın.
• Aracı yapılandırma kökünü OPENCLAW_AGENT_DIR ile geçersiz kılın (veya eski ortam değişkeni takma adı olan PI_CODING_AGENT_DIR ile).
• Eşleşen sağlayıcı kimlikleri için birleştirme önceliği:
  • Boş olmayan aracı models.json baseUrl değerleri kazanır.
  • Boş olmayan aracı apiKey değerleri yalnızca bu sağlayıcı mevcut yapılandırma/auth-profile bağlamında SecretRef tarafından yönetilmiyorsa kazanır.
  • SecretRef tarafından yönetilen sağlayıcı apiKey değerleri, çözümlenmiş gizli bilgileri kalıcı kılmak yerine kaynak işaretçilerinden (ENV_VAR_NAME çevre ref’leri için, secretref-managed dosya/exec ref’leri için) yenilenir.
  • SecretRef tarafından yönetilen sağlayıcı üst bilgi değerleri kaynak işaretçilerinden yenilenir (secretref-env:ENV_VAR_NAME çevre ref’leri için, secretref-managed dosya/exec ref’leri için).
  • Boş veya eksik aracı apiKey/baseUrl değerleri yapılandırmadaki models.providers değerlerine geri düşer.
  • Eşleşen model contextWindow/maxTokens, açık yapılandırma ile örtük katalog değerleri arasındaki daha yüksek değeri kullanır.
  • Eşleşen model contextTokens, varsa açık çalışma zamanı üst sınırını korur; doğal model meta verisini değiştirmeden etkin bağlamı sınırlamak için bunu kullanın.
  • Yapılandırmanın models.json dosyasını tamamen yeniden yazmasını istediğinizde models.mode: "replace" kullanın.
  • İşaretçi kalıcılığı kaynak açısından yetkilidir: işaretçiler çözümlenmiş çalışma zamanı gizli değerlerinden değil, etkin kaynak yapılandırma anlık görüntüsünden (çözümleme öncesi) yazılır.

​

Sağlayıcı alanı ayrıntıları

• models.mode: sağlayıcı katalog davranışı (merge veya replace).
• models.providers: sağlayıcı kimliğine göre anahtarlanmış özel sağlayıcı eşlemesi.
  • Güvenli düzenlemeler: eklemeli güncellemeler için openclaw config set models.providers.<id> '<json>' --strict-json --merge veya openclaw config set models.providers.<id>.models '<json-array>' --strict-json --merge kullanın. config set, --replace geçmediğiniz sürece yıkıcı değiştirmeleri reddeder.
• models.providers.*.api: istek bağdaştırıcısı (openai-completions, openai-responses, anthropic-messages, google-generative-ai vb).
• models.providers.*.apiKey: sağlayıcı kimlik bilgisi (tercihen SecretRef/env substitution).
• models.providers.*.auth: kimlik doğrulama stratejisi (api-key, token, oauth, aws-sdk).
• models.providers.*.injectNumCtxForOpenAICompat: Ollama + openai-completions için isteklere options.num_ctx enjekte eder (varsayılan: true).
• models.providers.*.authHeader: gerektiğinde kimlik bilgisinin Authorization üst bilgisinde taşınmasını zorlar.
• models.providers.*.baseUrl: üst akış API base URL’si.
• models.providers.*.headers: proxy/tenant yönlendirme için ek statik üst bilgiler.
• models.providers.*.request: model-sağlayıcı HTTP istekleri için taşıma geçersiz kılmaları.
  • request.headers: ek üst bilgiler (sağlayıcı varsayılanlarıyla birleştirilir). Değerler SecretRef kabul eder.
  • request.auth: kimlik doğrulama stratejisi geçersiz kılması. Kipler: "provider-default" (sağlayıcının yerleşik kimlik doğrulamasını kullan), "authorization-bearer" (token ile), "header" (headerName, value, isteğe bağlı prefix ile).
  • request.proxy: HTTP proxy geçersiz kılması. Kipler: "env-proxy" (HTTP_PROXY/HTTPS_PROXY ortam değişkenlerini kullan), "explicit-proxy" (url ile). Her iki kip de isteğe bağlı bir tls alt nesnesi kabul eder.
  • request.tls: doğrudan bağlantılar için TLS geçersiz kılması. Alanlar: ca, cert, key, passphrase (hepsi SecretRef kabul eder), serverName, insecureSkipVerify.
  • request.allowPrivateNetwork: true olduğunda, DNS özel, CGNAT veya benzeri aralıklara çözülürse sağlayıcı HTTP fetch koruması aracılığıyla baseUrl için HTTPS’e izin verir (güvenilen kendi kendine barındırılan OpenAI uyumlu uç noktalar için operatör katılımı). WebSocket aynı request alanını üst bilgiler/TLS için kullanır, ancak o fetch SSRF geçidi için kullanmaz. Varsayılan false.
• models.providers.*.models: açık sağlayıcı model katalog girdileri.
• models.providers.*.models.*.contextWindow: doğal model bağlam penceresi meta verisi.
• models.providers.*.models.*.contextTokens: isteğe bağlı çalışma zamanı bağlam üst sınırı. Modelin doğal contextWindow değerinden daha küçük etkin bağlam bütçesi istediğinizde bunu kullanın.
• models.providers.*.models.*.compat.supportsDeveloperRole: isteğe bağlı uyumluluk ipucu. api: "openai-completions" ile boş olmayan doğal olmayan bir baseUrl için (api.openai.com olmayan ana makine), OpenClaw bunu çalışma zamanında false olmaya zorlar. Boş/atlanmış baseUrl, varsayılan OpenAI davranışını korur.
• models.providers.*.models.*.compat.requiresStringContent: yalnızca dizge destekleyen OpenAI uyumlu sohbet uç noktaları için isteğe bağlı uyumluluk ipucu. true olduğunda, OpenClaw isteği göndermeden önce yalnızca metin içeren messages[].content dizilerini düz dizgelere indirger.
• plugins.entries.amazon-bedrock.config.discovery: Bedrock otomatik keşif ayarlarının kökü.
• plugins.entries.amazon-bedrock.config.discovery.enabled: örtük keşfi aç/kapat.
• plugins.entries.amazon-bedrock.config.discovery.region: keşif için AWS bölgesi.
• plugins.entries.amazon-bedrock.config.discovery.providerFilter: hedefli keşif için isteğe bağlı sağlayıcı kimliği filtresi.
• plugins.entries.amazon-bedrock.config.discovery.refreshInterval: keşif yenileme için yoklama aralığı.
• plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow: keşfedilen modeller için geri dönüş bağlam penceresi.
• plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens: keşfedilen modeller için geri dönüş en fazla çıktı token sayısı.

​

Sağlayıcı örnekleri

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

​

İlgili

• Yapılandırma başvurusu — diğer üst düzey anahtarlar
• Yapılandırma — aracılar
• Yapılandırma — kanallar
• Araçlar ve Plugins