Korumalı alan, araç ilkesi ve yükseltilmiş izinler

OpenClaw'ın üç ilişkili (ama farklı) denetimi vardır:

1. Korumalı alan (agents.defaults.sandbox.* / agents.list[].sandbox.*) araçların nerede çalışacağını belirler (korumalı alan arka ucu veya ana makine).
2. Araç ilkesi (tools.*, tools.sandbox.tools.*, agents.list[].tools.*) hangi araçların kullanılabilir/izinli olduğunu belirler.
3. Yükseltilmiş (tools.elevated.*, agents.list[].tools.elevated.*), korumalı alandayken korumalı alanın dışında çalışmak için yalnızca exec'e özgü bir çıkış kapısıdır (varsayılan olarak gateway, veya exec hedefi node olarak yapılandırıldığında node).

Hızlı hata ayıklama

OpenClaw'ın gerçekte ne yaptığını görmek için denetleyiciyi kullanın:

openclaw sandbox explainopenclaw sandbox explain --session agent:main:mainopenclaw sandbox explain --agent workopenclaw sandbox explain --json

Şunları yazdırır:

• etkin korumalı alan modu/kapsamı/çalışma alanı erişimi
• oturumun şu anda korumalı alanda olup olmadığı (main ve non-main)
• etkin korumalı alan aracı izin/verme reddi (ve bunun agent/global/default kaynaklarından hangisinden geldiği)
• yükseltilmiş kapılar ve düzeltme anahtar yolları

Korumalı alan: araçların nerede çalıştığı

Korumalı alan kullanımı agents.defaults.sandbox.mode ile denetlenir:

• "off": her şey ana makinede çalışır.
• "non-main": yalnızca non-main oturumlar korumalı alana alınır (gruplar/kanallar için yaygın bir "sürpriz").
• "all": her şey korumalı alana alınır.

Tam matris (kapsam, çalışma alanı bağlamaları, imajlar) için Korumalı Alan Kullanımı bölümüne bakın.

Bağlama bağlamaları (güvenlik hızlı kontrolü)

• docker.binds, korumalı alan dosya sistemini deler: bağladığınız her şey, ayarladığınız modla (:ro veya :rw) konteyner içinde görünür.
• Modu atlarsanız varsayılan okuma-yazmadır; kaynak/gizli bilgiler için :ro tercih edin.
• scope: "shared" agent başına bağlamaları yok sayar (yalnızca global bağlamalar uygulanır).
• OpenClaw bağlama kaynaklarını iki kez doğrular: önce normalleştirilmiş kaynak yolunda, sonra en derindeki mevcut üst dizin üzerinden çözdükten sonra tekrar. Sembolik bağlantı üst dizini kaçışları, engellenen yol veya izinli kök denetimlerini atlatmaz.
• Var olmayan yaprak yollar yine de güvenli şekilde denetlenir. /workspace/alias-out/new-file, sembolik bağlantılı bir üst dizin üzerinden engellenen bir yola veya yapılandırılmış izinli köklerin dışına çözülürse bağlama reddedilir.
• /var/run/docker.sock bağlamak, korumalı alana fiilen ana makine denetimi verir; bunu yalnızca bilinçli olarak yapın.
• Çalışma alanı erişimi (workspaceAccess: "ro"/"rw") bağlama modlarından bağımsızdır.

Araç ilkesi: hangi araçların var/çağrılabilir olduğu

İki katman önemlidir:

• Araç profili: tools.profile ve agents.list[].tools.profile (temel izin listesi)
• Sağlayıcı araç profili: tools.byProvider[provider].profile ve agents.list[].tools.byProvider[provider].profile
• Global/agent başına araç ilkesi: tools.allow/tools.deny ve agents.list[].tools.allow/agents.list[].tools.deny
• Sağlayıcı araç ilkesi: tools.byProvider[provider].allow/deny ve agents.list[].tools.byProvider[provider].allow/deny
• Korumalı alan araç ilkesi (yalnızca korumalı alandayken geçerlidir): tools.sandbox.tools.allow/tools.sandbox.tools.deny ve agents.list[].tools.sandbox.tools.*

Genel kurallar:

• deny her zaman kazanır.
• allow boş değilse diğer her şey engellenmiş kabul edilir.
• Araç ilkesi kesin durdurucudur: /exec, reddedilmiş bir exec aracını geçersiz kılamaz.
• Araç ilkesi araç kullanılabilirliğini ada göre filtreler; exec içindeki yan etkileri incelemez. exec izinliyse write, edit veya apply_patch reddetmek kabuk komutlarını salt okunur yapmaz.
• /exec yalnızca yetkili göndericiler için oturum varsayılanlarını değiştirir; araç erişimi vermez. Sağlayıcı araç anahtarları provider (örn. google-antigravity) veya provider/model (örn. openai/gpt-5.4) kabul eder.
• Gateway günlükleri, bir araç ilkesi adımı araçları kaldırdığında veya bir korumalı alan araç ilkesi bir çağrıyı engellediğinde agents/tool-policy denetim girdileri içerir. Kural etiketini, yapılandırma anahtarını ve etkilenen araç adlarını görmek için openclaw logs kullanın.

Araç grupları (kısaltmalar)

Araç ilkeleri (global, agent, korumalı alan), birden fazla araca genişleyen group:* girdilerini destekler:

{  tools: {    sandbox: {      tools: {        allow: ["group:runtime", "group:fs", "group:sessions", "group:memory"],      },    },  },}

Kullanılabilir gruplar:

• group:runtime: exec, process, code_execution (bash, exec için bir takma ad olarak kabul edilir)
• group:fs: read, write, edit, apply_patch Salt okunur agent'lar için, korumalı alan dosya sistemi ilkesi veya ayrı bir ana makine sınırı salt okunur kısıtını zorunlu kılmıyorsa, dosya sistemini değiştiren araçların yanı sıra group:runtime grubunu da reddedin.
• group:sessions: sessions_list, sessions_history, sessions_send, sessions_spawn, sessions_yield, subagents, session_status
• 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
• group:agents: agents_list, update_plan
• group:media: image, image_generate, music_generate, video_generate, tts
• group:openclaw: tüm yerleşik OpenClaw araçları (sağlayıcı Plugin'lerini hariç tutar)
• group:plugins: bundle-mcp üzerinden açığa çıkarılan yapılandırılmış MCP sunucuları dahil, yüklenmiş tüm Plugin sahibi araçlar

Korumalı alandaki MCP sunucuları için korumalı alan araç ilkesi ikinci bir izin kapısıdır. mcp.servers yapılandırılmışsa ancak korumalı alandaki turlarda yalnızca yerleşik araçlar görünüyorsa, tools.sandbox.tools.alsoAllow içine bundle-mcp, group:plugins veya outlook__send_mail ya da outlook__* gibi sunucu önekli bir MCP araç adı/glob ekleyin, ardından gateway'i yeniden başlatın/yeniden yükleyin ve araç listesini yeniden yakalayın. Sunucu glob'ları sağlayıcı açısından güvenli MCP sunucu önekini kullanır: [A-Za-z0-9_-] dışındaki karakterler - olur, harfle başlamayan adlar mcp- öneki alır ve uzun ya da yinelenen önekler kısaltılabilir veya son ek alabilir.

openclaw doctor şu anda OpenClaw tarafından yönetilen mcp.servers içindeki sunucular için bu şekli denetler. Paketlenmiş Plugin manifestlerinden veya Claude .mcp.json dosyasından yüklenen MCP sunucuları aynı korumalı alan kapısını kullanır, ancak bu tanılama bu kaynakları henüz numaralandırmaz; araçları korumalı alandaki turlarda kaybolursa aynı izin listesi girdilerini kullanın.

Yükseltilmiş: yalnızca exec için "ana makinede çalıştır"

Yükseltilmiş ek araç vermez; yalnızca exec aracını etkiler.

• Korumalı alandaysanız, /elevated on (veya elevated: true ile exec) korumalı alanın dışında çalışır (onaylar yine de geçerli olabilir).
• Oturum için exec onaylarını atlamak üzere /elevated full kullanın.
• Zaten doğrudan çalışıyorsanız, yükseltilmiş fiilen işlem yapmaz (yine de kapılara tabidir).
• Yükseltilmiş Skills kapsamlı değildir ve araç izin/verme reddini geçersiz kılmaz.
• Yükseltilmiş, host=auto üzerinden rastgele ana makineler arası geçersiz kılmalar vermez; normal exec hedef kurallarını izler ve yalnızca yapılandırılmış/oturum hedefi zaten node olduğunda node değerini korur.
• /exec, yükseltilmişten ayrıdır. Yalnızca yetkili göndericiler için oturum başına exec varsayılanlarını ayarlar.

Kapılar:

• Etkinleştirme: tools.elevated.enabled (ve isteğe bağlı olarak agents.list[].tools.elevated.enabled)
• Gönderici izin listeleri: tools.elevated.allowFrom.<provider> (ve isteğe bağlı olarak agents.list[].tools.elevated.allowFrom.<provider>)

Bkz. Yükseltilmiş Mod.

Yaygın "korumalı alan hapishanesi" düzeltmeleri

"Araç X korumalı alan araç ilkesi tarafından engellendi"

Düzeltme anahtarları (birini seçin):

• Korumalı alanı devre dışı bırakın: agents.defaults.sandbox.mode=off (veya agent başına agents.list[].sandbox.mode=off)
• Araca korumalı alan içinde izin verin:
  • onu tools.sandbox.tools.deny listesinden kaldırın (veya agent başına agents.list[].tools.sandbox.tools.deny)
  • ya da tools.sandbox.tools.allow listesine ekleyin (veya agent başına izin)
• agents/tool-policy girdisi için openclaw logs denetleyin. Bu girdi korumalı alan modunu ve aracın izin kuralı mı yoksa reddetme kuralı mı tarafından engellendiğini kaydeder.

"Bunun main olduğunu sanıyordum, neden korumalı alanda?"

"non-main" modunda grup/kanal anahtarları main değildir. Ana oturum anahtarını kullanın (sandbox explain tarafından gösterilir) veya modu "off" olarak değiştirin.

İlgili

• Korumalı Alan Kullanımı -- tam korumalı alan başvurusu (modlar, kapsamlar, arka uçlar, imajlar)
• Çoklu Agent Korumalı Alanı ve Araçları -- agent başına geçersiz kılmalar ve öncelik sırası
• Yükseltilmiş Mod