Plugin izin istekleri

Plugin izin istekleri, bir kullanıcı onaylayana veya reddedene kadar Plugin kodunun bir araç çağrısını ya da Plugin’e ait bir işlemi duraklatmasını sağlar. Gateway plugin.approval.* akışını ve sohbet onay düğmeleri ile /approve komutlarını işleyen aynı onay UI yüzeylerini kullanırlar.

Plugin izin isteklerini Plugin/uygulama izinleri için kullanın. Bunlar host exec onaylarının, isteğe bağlı araç izin listelerinin veya Codex’in yerel izin incelemesinin yerine geçmez.

Doğru geçidi seçin

İhtiyacınız olan karar noktasına uygun geçidi seçin:

İsteğe bağlı araçlar keşif zamanı geçididir. Plugin izin istekleri çağrı başına bir geçittir. Hassas bir aracın model tarafından görülebilmeden önce açık katılım ve eylem çalışmadan önce onay gerektirmesi gerektiğinde ikisini birlikte kullanın.

Bir araç çağrısından önce onay isteyin

Plugin tarafından yazılan çoğu istem bir before_tool_call hook’unda başlamalıdır. Hook, model bir araç seçtikten sonra ve OpenClaw onu çalıştırmadan önce çalışır:

 export default definePluginEntry({  id: "deploy-policy",  name: "Deploy Policy",  register(api) {    api.on("before_tool_call", async (event) => {      if (event.toolName !== "deploy_service") {        return;      }       const environment =        typeof event.params.environment === "string" ? event.params.environment : "unknown";       return {        requireApproval: {          title: "Deploy service",          description: `Deploy service to ${environment}.`,          severity: environment === "production" ? "critical" : "warning",          allowedDecisions:            environment === "production"              ? ["allow-once", "deny"]              : ["allow-once", "allow-always", "deny"],          timeoutMs: 120_000,          timeoutBehavior: "deny",          onResolution(decision) {            console.log(`deploy approval resolved: ${decision}`);          },        },      };    });  },});

İstem metnini eylemi onaylayacak kişi için yazın:

• title kısa ve eylem odaklı olsun. Gateway en fazla 80 karakter kabul eder.
• description belirli ve sınırlı olsun. Gateway en fazla 256 karakter kabul eder.
• Eylemi, hedefi ve riski ekleyin. Sohbet onay yüzeylerinde görünmemesi gereken gizli anahtarları, token’ları veya özel yükleri eklemeyin.
• severity: "critical" değerini yalnızca yanlış kararın üretim hasarına veya veri kaybına neden olabileceği eylemler için kullanın.
• Kalıcı güven bu eylem için güvenli değilse allowedDecisions: ["allow-once", "deny"] kullanın.

Karar davranışı

OpenClaw plugin: ID’si olan bekleyen bir onay oluşturur, bunu kullanılabilir onay yüzeylerine iletir ve bir karar bekler.

allow-always yalnızca istekte bulunan Plugin veya çalışma zamanı bu kalıcılığı uyguladığında kalıcıdır. Sıradan before_tool_call.requireApproval hook’ları için OpenClaw, allow-once ve allow-always kararlarını geçerli çağrıya yönelik onay kararları olarak ele alır ve çözümlenen değeri onResolution’a geçirir. Plugin’iniz allow-always sunuyorsa, gelecekte hangi çağrılara güvendiğini tam olarak belgeleyin ve uygulayın.

Hook ayrıca params döndürürse, OpenClaw bu parametre değişikliklerini yalnızca onay başarılı olduktan sonra uygular. Daha düşük öncelikli bir hook, daha yüksek öncelikli bir hook onay istemiş olsa bile yine de engelleyebilir.

allowedDecisions, kullanıcıya gösterilen düğmeleri ve komutları sınırlar. Gateway, isteğin sunmadığı herhangi bir karar için çözümleme girişimini reddeder.

Onay istemlerini yönlendirin

Onay istemleri yerel UI yüzeylerinde veya onay işlemeyi destekleyen sohbet kanallarında çözümlenebilir. Plugin onay istemlerini açık sohbet hedeflerine iletmek için approvals.plugin yapılandırın:

{  approvals: {    plugin: {      enabled: true,      mode: "targets",      agentFilter: ["main"],      targets: [{ channel: "slack", to: "U12345678" }],    },  },}

approvals.plugin, approvals.exec’ten bağımsızdır. Exec onayı iletmeyi etkinleştirmek Plugin onay istemlerini yönlendirmez; Plugin onayı iletmeyi etkinleştirmek de host exec ilkesini değiştirmez.

Bir istem manuel onay metni içerdiğinde, sunulan kararlardan biriyle çözümleyin:

/approve <id> allow-once/approve <id> allow-always/approve <id> deny

Tam iletme modeli, aynı sohbet onay davranışı, yerel kanal teslimi ve kanala özgü onaylayan kuralları için Gelişmiş exec onayları bölümüne bakın.

Codex yerel izinleri

Codex yerel izin istemleri de Plugin onayları üzerinden ilerleyebilir, ancak sahiplikleri Plugin tarafından yazılmış hook’lardan farklıdır.

• Codex app-server onay istekleri Codex incelemesinden sonra OpenClaw üzerinden yönlendirilir.
• Yerel hook permission_request rölesi, bu röle etkin olduğunda plugin.approval.request üzerinden sorabilir.
• MCP araç onay istemleri, Codex _meta.codex_approval_kind değerini "mcp_tool_call" olarak işaretlediğinde Plugin onayları üzerinden yönlendirilir.

Codex’e özgü davranış ve fallback kuralları için Codex harness çalışma zamanı bölümüne bakın.

Sorun giderme

Araç, Plugin onaylarının kullanılamadığını söylüyor. Hiçbir onay UI’sı veya yapılandırılmış onay rotası isteği kabul etmedi. Onay yetenekli bir istemci bağlayın, aynı sohbet içinde /approve destekleyen bir kanal kullanın veya approvals.plugin yapılandırın.

allow-always görünüyor ama sonraki çağrı tekrar istem gösteriyor. Genel Plugin onay akışı rastgele hook’lar için güveni otomatik olarak kalıcı hale getirmez. onResolution("allow-always") sonrasında Plugin’e ait güveni Plugin’inizde kalıcı hale getirin veya yalnızca allow-once ve deny sunun.

/approve kararı reddediyor. İstek allowedDecisions değerini kısıtladı. İstemde yazdırılan kararlardan birini kullanın.

Bir Slack, Discord, Telegram veya Matrix istemi exec onaylarından farklı yönlendiriliyor. Plugin onayları ve exec onayları ayrı yapılandırma kullanır ve farklı yetkilendirme kontrolleri kullanabilir. Yalnızca approvals.exec denetlemek yerine approvals.plugin değerini ve kanalın Plugin onay desteğini doğrulayın.

İlgili

• Plugin hook’ları
• Plugin oluşturma
• Gelişmiş exec onayları
• Gateway protokolü
• Codex harness çalışma zamanı