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

Gateway

Sandbox vs kebijakan alat vs hak akses yang ditingkatkan

Status: active

OpenClaw memiliki tiga kontrol yang saling terkait tetapi berbeda:

  1. Sandbox (agents.defaults.sandbox.* / agents.list[].sandbox.*) menentukan tempat alat dijalankan (backend sandbox atau host).
  2. Kebijakan alat (tools.*, tools.sandbox.tools.*, agents.list[].tools.*) menentukan alat mana yang tersedia/diizinkan.
  3. Elevated (tools.elevated.*, agents.list[].tools.elevated.*) adalah jalan keluar khusus exec untuk menjalankan di luar sandbox ketika Anda berada dalam sandbox (gateway secara default, atau node ketika target exec dikonfigurasi sebagai node).

Debug cepat

Gunakan pemeriksa untuk melihat apa yang sebenarnya dilakukan OpenClaw:

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

Perintah ini menampilkan:

  • mode/cakupan/akses ruang kerja sandbox yang efektif
  • apakah sesi saat ini berada dalam sandbox (utama atau non-utama)
  • aturan izinkan/tolak alat sandbox yang efektif (dan apakah aturan tersebut berasal dari agen/global/default)
  • gerbang elevated dan jalur kunci perbaikan

Sandbox: tempat alat dijalankan

Penggunaan sandbox dikontrol oleh agents.defaults.sandbox.mode:

  • "off": semuanya berjalan pada host.
  • "non-main": hanya sesi non-utama yang berada dalam sandbox (hal yang sering "mengejutkan" untuk grup/saluran).
  • "all": semuanya berada dalam sandbox.

agents.defaults.sandbox.workspaceAccess mengontrol apa yang dapat dilihat sandbox: "none", "ro", atau "rw".

Lihat Penggunaan sandbox untuk matriks lengkap (cakupan, pemasangan ruang kerja, citra).

Bind mount (pemeriksaan keamanan cepat)

  • docker.binds menembus sistem berkas sandbox: apa pun yang Anda pasang akan terlihat di dalam kontainer dengan mode yang Anda tetapkan (:ro atau :rw).
  • Mode default adalah baca-tulis jika Anda tidak mencantumkan mode; utamakan :ro untuk sumber/rahasia.
  • scope: "shared" mengabaikan bind per agen (hanya bind global yang berlaku).
  • OpenClaw memvalidasi sumber bind dua kali: pertama pada jalur sumber yang telah dinormalisasi, lalu sekali lagi setelah menyelesaikannya melalui leluhur terdalam yang ada. Pelolosan melalui induk symlink tidak dapat melewati pemeriksaan jalur yang diblokir atau akar yang diizinkan.
  • Jalur daun yang belum ada tetap diperiksa dengan aman. Jika /workspace/alias-out/new-file diselesaikan melalui induk symlink menuju jalur yang diblokir atau ke luar akar yang dikonfigurasi, bind akan ditolak.
  • Mengikat /var/run/docker.sock secara efektif memberikan kendali host kepada sandbox; lakukan ini hanya secara sengaja.
  • Akses ruang kerja (workspaceAccess) tidak bergantung pada mode bind.

Kebijakan alat: alat yang tersedia/dapat dipanggil

Dua lapisan berpengaruh:

  • Profil alat: tools.profile dan agents.list[].tools.profile (daftar izin dasar)
  • Profil alat penyedia: tools.byProvider[provider].profile dan agents.list[].tools.byProvider[provider].profile
  • Kebijakan alat global/per agen: tools.allow/tools.deny dan agents.list[].tools.allow/agents.list[].tools.deny
  • Kebijakan alat penyedia: tools.byProvider[provider].allow/deny dan agents.list[].tools.byProvider[provider].allow/deny
  • Kebijakan alat sandbox (hanya berlaku saat berada dalam sandbox): tools.sandbox.tools.allow/tools.sandbox.tools.deny dan agents.list[].tools.sandbox.tools.*

Pedoman praktis:

  • deny selalu diutamakan.
  • Jika allow tidak kosong, semua yang lain dianggap diblokir.
  • Kebijakan alat adalah penghentian mutlak: /exec tidak dapat mengabaikan alat exec yang ditolak.
  • Kebijakan alat menyaring ketersediaan alat berdasarkan nama; kebijakan ini tidak memeriksa efek samping di dalam exec. Jika exec diizinkan, menolak write, edit, atau apply_patch tidak membuat perintah shell menjadi hanya-baca.
  • /exec hanya mengubah default sesi untuk pengirim yang berwenang; perintah ini tidak memberikan akses alat.
  • Kunci alat penyedia menerima provider (misalnya google-antigravity) atau provider/model (misalnya openai/gpt-5.4).
  • Log Gateway menyertakan entri audit agents/tool-policy ketika suatu langkah kebijakan alat menghapus alat atau kebijakan alat sandbox memblokir panggilan. Gunakan openclaw logs untuk melihat label aturan, kunci konfigurasi, dan nama alat yang terdampak.

Grup alat (singkatan)

Kebijakan alat (global, agen, sandbox) mendukung entri group:* yang diperluas menjadi beberapa alat:

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

Grup yang tersedia:

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
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 sebagian besar alat bawaan OpenClaw (tidak mencakup primitif sistem berkas dan waktu proses read/write/edit/apply_patch/exec/process, canvas, serta plugin penyedia)
group:plugins semua alat milik plugin yang dimuat, termasuk server MCP yang dikonfigurasi dan diekspos melalui bundle-mcp

Untuk agen hanya-baca, tolak group:runtime serta alat sistem berkas yang dapat mengubah data, kecuali kebijakan sistem berkas sandbox atau batas host terpisah memberlakukan pembatasan hanya-baca.

Untuk server MCP dalam sandbox, kebijakan alat sandbox merupakan gerbang izin kedua. Jika mcp.servers dikonfigurasi tetapi giliran dalam sandbox hanya menampilkan alat bawaan, tambahkan bundle-mcp, group:plugins, atau nama/pola glob alat MCP berawalan server seperti outlook__send_mail atau outlook__* ke tools.sandbox.tools.alsoAllow, lalu mulai ulang/muat ulang Gateway dan ambil kembali daftar alat. Pola glob server menggunakan awalan server MCP yang aman bagi penyedia: karakter selain [A-Za-z0-9_-] menjadi -, nama yang tidak diawali huruf mendapat awalan mcp-, dan awalan yang panjang atau duplikat dapat dipotong atau diberi akhiran.

openclaw doctor saat ini memeriksa bentuk ini untuk server yang dikelola OpenClaw dalam mcp.servers. Server MCP yang dimuat dari manifes plugin bawaan atau .mcp.json 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 berada dalam sandbox.

Elevated: "jalankan pada host" khusus exec

Elevated tidak memberikan alat tambahan; fitur ini hanya memengaruhi exec.

  • Jika Anda berada dalam sandbox, /elevated on (atau exec dengan elevated: true) berjalan di luar sandbox (persetujuan mungkin tetap berlaku).
  • Gunakan /elevated full untuk melewati persetujuan exec selama sesi.
  • Jika Anda sudah berjalan secara langsung, elevated pada dasarnya tidak berpengaruh (tetap dibatasi oleh gerbang).
  • Elevated tidak dibatasi berdasarkan skill dan tidak mengabaikan aturan izinkan/tolak alat.
  • Elevated tidak memberikan pengabaian lintas-host sewenang-wenang dari host=auto; fitur ini mengikuti aturan target exec normal dan hanya mempertahankan node ketika target yang dikonfigurasi/target sesi sudah berupa node.
  • /exec terpisah dari elevated. Perintah ini hanya menyesuaikan default exec per sesi untuk pengirim yang berwenang.

Gerbang:

  • Pengaktifan: tools.elevated.enabled (dan secara opsional agents.list[].tools.elevated.enabled)
  • Daftar izin pengirim: tools.elevated.allowFrom.<provider> (dan secara opsional agents.list[].tools.elevated.allowFrom.<provider>)

Lihat Mode Elevated.

Perbaikan umum untuk "penjara sandbox"

"Alat X diblokir oleh kebijakan alat sandbox"

Kunci perbaikan (pilih salah satu):

  • Nonaktifkan sandbox: agents.defaults.sandbox.mode=off (atau per agen agents.list[].sandbox.mode=off)
  • Izinkan alat di dalam sandbox:
    • hapus alat tersebut dari tools.sandbox.tools.deny (atau per agen agents.list[].tools.sandbox.tools.deny)
    • atau tambahkan alat tersebut ke tools.sandbox.tools.allow (atau daftar izin per agen)
  • Periksa openclaw logs untuk entri agents/tool-policy. Entri tersebut mencatat mode sandbox dan apakah aturan izinkan atau tolak memblokir alat.

"Saya kira ini sesi utama, mengapa berada dalam sandbox?"

Dalam mode "non-main", kunci grup/saluran bukan utama. Gunakan kunci sesi utama (ditampilkan oleh sandbox explain) atau ubah mode menjadi "off".

Terkait

Was this useful?
On this page

On this page