- Jauhkan mod milik pengguna, dengan atau tanpa mod milik Anda sendiri: Hentikan mod yang dipasang pengguna dari memuat
- Lihat apa yang didapat pengguna Anda saat Anda tidak mengubah apa pun: Ketahui apa yang terjadi secara default
- Biarkan mod tetap aktif dengan batasan lain: Pilih berapa banyak yang akan diizinkan
Kasus-kasus ini tercakup di halaman lain:
- Anda belum pernah menerapkan pengaturan terkelola sebelumnya: mulai dengan Terapkan pengaturan terkelola
- Anda ingin mengontrol plugin mana yang dapat dipasang pengguna: lihat Kelola plugin untuk organisasi Anda
Hentikan mod yang dipasang pengguna dari memuat
Untuk mencegah setiap mod yang dibawa pengguna Anda menjalankan hook-nya, atur opsiallowManagedModsOnly pada penjaga bawaan, mod kebijakan yang dimuat Claude Code sebelum setiap mod yang dipasang pengguna. Opsi ini masuk dalam pengaturan terkelola di bawah pluginConfigs, dengan kunci cc-plugin-sec-default@builtin:
managed-settings.json
- Tidak ada mod yang dibawa pengguna yang menjalankan hook-nya: itu mencakup mod dalam plugin yang dipasang pengguna, mod yang dimuat dengan
--plugin-dir, dan mod yang ditulis Claude selama sesi - Mod organisasi Anda tetap berjalan: mod yang dihitung sebagai milik organisasi Anda tidak diperiksa. Setiap mod lainnya dihitung sebagai milik pengguna dan ditolak. Itu termasuk mod yang diaktifkan organisasi Anda untuk anggotanya di claude.ai. Jika tidak ada yang dihitung sebagai milik Anda, tidak ada mod terpasang yang menjalankan hook-nya.
- Pengguna tidak dapat membatalkannya: penjaga membaca opsi dari pengaturan terkelola saja, jadi entri yang sama dalam file pengaturan pengguna, proyek, atau lokal, atau dalam file yang dilewatkan dengan
--settings, tidak mengubah apa pun - File atau kebijakan MDM mencakup setiap penyedia: saat Anda mengirimkan opsi sebagai file atau melalui MDM, opsi ini bekerja dengan cara yang sama di Amazon Bedrock, Agent Platform Google Cloud, dan Microsoft Foundry. Untuk pengiriman dari konsol admin claude.ai, lihat Ketersediaan Platform
- Kustomisasi lain pengguna tetap berfungsi: hook mereka dalam file pengaturan dan dalam
hooks/hooks.jsonmilik plugin, baris status, dan/goaltidak terpengaruh - Mod bawaan tetap berjalan: mod yang dibangun ke dalam Claude Code, seperti dukungan
AGENTS.md, masing-masing memiliki sakelar mereka sendiri
--plugin-dir dan jalur direktori yang menyimpan mod, seperti claude --plugin-dir ./first-mod. Hook mod tidak berjalan, dan transkrip serta log debug memiliki pesan penjaga, yang menyebutkan nama mod dan allowManagedModsOnly. Jika pesan tersebut tidak ada, lihat Periksa bahwa kebijakan berlaku dan aturan yang memutuskan apakah opsi berlaku.
Jika Anda menetapkan CLAUDE_CODE_ENABLE_FUNCTION_HOOKS ke 0 selama akses awal, gantikan dengan opsi ini. Claude Code v2.1.287 dan yang lebih baru mengabaikan variabel pada nilai apa pun, jadi 0 di sana membiarkan mod tetap aktif.
Ketahui apa yang terjadi secara default
Tanpa pengaturan mod milik Anda sendiri, inilah yang didapatkan pengguna Anda:-
Mod aktif. Pengguna dapat menginstal plugin yang berisi mod dari marketplace mana pun yang diizinkan oleh pengaturan plugin Anda, atau memuatnya dari sebuah direktori dengan
--plugin-dir. -
Penjaga bawaan berjalan lebih dulu. Claude Code memuat mod bawaan bernama
sec-default@builtinsebelum setiap mod yang diinstal pengguna. Pengguna tidak dapat mematikannya./plugindan log debug mencantumkannya sebagaicc-plugin-sec-default. Penjaga dimuat ketika salah satu dari kondisi berikut terpenuhi:- Mesin memiliki pengaturan terkelola atau file
managed-mcp.json - Sesi berjalan dengan kredensial
/loginuntuk paket Team atau Enterprise
managed-mcp.json. Sesi yang berjalan denganCLAUDE_CODE_OAUTH_TOKENberumur panjang juga tidak dihitung sebagai login tersebut, bahkan ketika login Team atau Enterprise tersimpan di mesin. - Mesin memiliki pengaturan terkelola atau file
-
Penjaga melindungi apa yang Anda kelola. Mod milik pengguna tidak dapat mengubah apa yang diterima atau diputuskan oleh hook terkelola Anda, system prompt, atau
CLAUDE.mdterkelola Anda dan instruksi terkelola lainnya. Mod tersebut juga tidak dapat mengubah apa yang dibaca mod mana pun sebagai pengaturan, atau tool dan deskripsi dari server MCP terkelola Anda setelah server tersebut terhubung. -
Pada v2.1.323 atau yang lebih baru, mod milik pengguna dapat mencegah server MCP terkelola terhubung. Dalam sesi pengguna tersebut,
/mcpmencantumkan server tersebut sebagai ditahan oleh mod tersebut. Untuk mencegahnya, hentikan mod yang diinstal pengguna agar tidak dimuat. - Di luar apa yang Anda kelola, mod milik pengguna bertindak sebagai pengguna tersebut. Mod mempertahankan izin pengguna tersebut: mod masih dapat membaca dan menulis file, memulai proses, dan membuat permintaan jaringan. Mod juga dapat menulis ulang panggilan tool dan prompt, menolak panggilan tool, menambahkan atau menghapus tool, dan menggambar di antarmuka.
-
Aturan izin dan hook
PreToolUsediutamakan daripada mod milik pengguna. Dengan penjaga dimuat, secara default mod milik pengguna tidak dapat menyetujui panggilan yang ditolak oleh aturandenyatau yang memerlukan permintaan izin menurut aturanask, di file pengaturan mana pun aturan tersebut berada. Mod juga tidak dapat menyetujui panggilan yang diblokir oleh hookPreToolUsemana pun. Aturan izin dan hookPreToolUseberlaku untuk panggilan tool Claude, bukan untuk panggilan$.fsdan$.processmilik mod. DenganRead(.env)ditolak, mod masih dapat membaca file tersebut dengan$.fs.readatau memulai program yang melakukannya. Untuk membatasi panggilan$.fsdan$.processmilik mod itu sendiri, cegah mod agar tidak dimuat atau tangani panggilan tersebut dalam mod kebijakan. -
Mod milik pengguna masih dapat melewati beberapa permintaan izin. Dalam auto mode, panggilan yang disetujui mod berjalan tanpa pemeriksaan pengklasifikasi, kecuali jika penjaga dimuat dan sesi berjalan dengan
--permission-prompt-toolatau callbackcanUseTooldari Agent SDK. Dalam kasus tersebut, pengklasifikasi memeriksa panggilan terlebih dahulu. Untuk permintaan izin yang tidak dilewati oleh persetujuan mod, lihat Memperluas izin dengan hook.
mods/sec-default pada repositori Claude Code.
Ketahui kontrol mana yang masih berlaku
Mod tidak menggantikan kontrol yang sudah Anda miliki:-
Hook pengaturan tetap berfungsi. Hook command, HTTP, prompt, dan agent di file pengaturan dan di
hooks/hooks.jsonmilik plugin berjalan seperti sebelumnya, berdampingan dengan mod. -
Aturan deny diutamakan di tempat penjaga dimuat. Mod milik pengguna tidak dapat menyetujui panggilan yang ditolak oleh aturan
deny, kecuali jika Anda menetapkanallowModsToOverrideDenyRules. -
Hook terkelola berjalan lebih dulu. Hook
PreToolUsedi pengaturan terkelola berjalan sebelum hooktool.callmilik mod mana pun, dan ketika hook terkelola tersebut memblokir panggilan tool, tidak ada hooktool.callmilik mod yang berjalan untuk panggilan tersebut. Jika panggilan dilanjutkan dan sebuah mod menulis ulangnya, hook terkelola Anda berjalan lagi pada panggilan yang ditulis ulang, sehingga secara default hook tersebut masih dapat memblokirnya. HookPreToolUsedari file pengaturan lain dan dari plugin berjalan setelah mod terakhir. Jika sebuah mod menjawab panggilan tool itu sendiri, tool tidak pernah berjalan dan hook tersebut juga tidak. Lihat Urutan berjalannya mod. -
Kebijakan jaringan mencakup
$.http.fetch.-
Kebijakan organisasi Anda tidak mengizinkan WebFetch: Claude Code juga menolak setiap permintaan
$.http.fetchmilik setiap mod. Lihat Ketersediaan WebFetch. -
Anda mematikan tool WebFetch dengan
CLAUDE_CODE_DISABLE_WEB_FETCHatau aturan denyWebFetch, di pengaturan terkelola atau file pengaturan lainnya: mod masih dapat membuat permintaan$.http.fetch. Untuk menghentikannya bagi setiap mod yang diinstal pengguna Anda, cegah mod yang diinstal pengguna agar tidak dimuat, atau pasang hook padahttp.fetchdalam mod kebijakan dan tolak permintaan dari mod milik pengguna. Berikan hook tersebut handler.catchyang juga menolak, karena Claude Code melewati hook yang gagal dan permintaan kemudian dilanjutkan. Jika Anda hanya membatasi plugin mana yang dapat diinstal pengguna, lebih sedikit mod yang dimuat, tetapi mod yang Anda izinkan masih dapat membuat permintaan ini. -
Anda menetapkan
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: mod yang Anda atau pengguna Anda instal masih dapat membuat permintaan ini. Variabel tersebut hanya menghentikan mod yang dibangun ke dalam Claude Code, ditambah setiap permintaan$.http.fetchyang membawa kredensial Anthropic milik sesi. Sebelum v2.1.288, variabel tersebut menghentikan setiap permintaan$.http.fetchmilik setiap mod.
$.process.run, yang menjangkau jaringan dengan akses milik pengguna sendiri. -
Kebijakan organisasi Anda tidak mengizinkan WebFetch: Claude Code juga menolak setiap permintaan
-
Kontrol plugin mencakup mod. Mod adalah plugin, sehingga pengaturan yang membatasi apa yang dapat diinstal pengguna, seperti
strictKnownMarketplaces, menentukan apakah mod dapat diinstal sama sekali. - Mod tidak dapat mengubah dialog izin. Mod dapat mengubah gaya sebagian besar antarmuka Claude Code, tetapi tidak dialog izin, sehingga mod tidak dapat mengubah apa yang ditampilkan dialog tersebut. Mod masih dapat menyetujui atau menolak panggilan tool sebelum dialog izin muncul, seperti yang dijelaskan dalam Ketahui apa yang terjadi secara default.
- Dialog kepercayaan muncul lebih dulu. Dalam sesi interaktif di direktori yang belum dipercayai pengguna, tidak ada mod yang dimuat hingga pengguna menjawab dialog kepercayaan.
-
--safe-modemematikan mod yang terinstal, termasuk milik Anda. Mulai sesi denganclaude --safe-modeuntuk memeriksa apakah sebuah mod menyebabkan masalah.
Ketahui hook mana dari mod milik pengguna yang tidak berjalan
Di tempat penjaga bawaan dimuat, hook yang didaftarkan mod milik pengguna pada salah satu event berikut tidak pernah berjalan, dan/plugin memberi tahu pengguna tersebut melalui sebuah catatan. Pada baris session.append, door adalah jenis baris tersimpan yang menjadi filter hook tersebut.
Penjaga juga melewati hook milik pengguna dalam beberapa kasus lain, seperti deskripsi tool organisasi Anda, pada
tool.describe, dan baris tersimpan untuk teks skill. /plugin tidak menampilkan catatan untuk kasus tersebut. Jika hook pada event lain tidak melakukan apa pun, lihat Cari tahu mengapa mod tidak melakukan apa pun.
Catatan tersebut muncul di detail plugin dan di tab Errors pada /plugin. Catatan ini memerlukan Claude Code v2.1.299 atau yang lebih baru. Catatan tersebut menyebutkan setiap hook dari tabel sebagaimana mod mendaftarkannya, seperti dalam contoh ini:
- Jalankan mod sebagai milik organisasi Anda: instal mod sehingga dihitung sebagai milik Anda. Hook miliknya pada event ini kemudian berjalan, dan penjaga tetap dimuat untuk setiap mod lainnya. Mod aktif untuk semua orang yang menerima pengaturan ini. Jika Anda mencantumkannya di
prependPlugins, pertahankansec-default@builtindalam daftar. - Hapus penjaga: jangan sertakan
sec-default@builtindalamprependPlugins. Daftar kosong,"prependPlugins": [], sudah cukup. Anda kehilangan seluruh penjaga, bukan hanya event ini. Mod milik pengguna kemudian dapat melakukan apa yang sebaliknya dicegah oleh penjaga, dan opsi penjaga tidak berlaku.
/plugin dalam sesi di mesin tersebut dan periksa bahwa catatan tersebut sudah hilang.
Hook session.append tanpa filter door tetap berjalan dan tidak mendapatkan catatan, tetapi baris tersimpan dalam tabel tidak sampai kepadanya.
Putuskan apakah akan membiarkan mod tetap aktif
Mod dapat melakukan lebih banyak daripada bagian lain dari plugin karena berjalan di dalam Claude Code. Ini melihat setiap prompt dan panggilan alat, dapat mengubahnya, dan dapat mengizinkan atau menolak panggilan alat sebelum prompt izin muncul. Apa yang dapat dimuat pengguna sebagai mod tergantung pada kontrol plugin yang sudah Anda miliki:
Kelola plugin untuk organisasi Anda mencantumkan cara-cara plugin dimuat dan pengaturan yang mengontrol masing-masing.
Untuk memeriksa mod dalam pasar sebelum pengguna Anda memasangnya, lihat Tinjau apa yang dapat dilakukan mod. Untuk menjaga mod pengguna tetap keluar sampai Anda melakukannya, lihat Hentikan mod yang dipasang pengguna dari memuat.
Tinjau apa yang dapat dilakukan mod
Anda dapat melihat apa yang dapat dilakukan mod tanpa menjalankannya. Di shell Anda, jalankanclaude plugin validate pada direktori plugin:
hooks: dan calls: dalam output menjelaskan kode mod:
hooks:: peristiwa yang diterima mod. Catatandefault matcher key: pluginberarti hook sebelumnya melewati kontrol dan gambar mod lain.calls:: metode API mod yang dipanggil kodenya
$ dalam kode mod, adalah cara mod menjangkau file, proses, dan jaringan. Claude Code menolak untuk memuat mod yang menggunakan API mod dengan cara yang tidak dapat dibaca perintah ini.
Jangan menyetujui mod yang gagal dalam perintah ini, karena beberapa kegagalan tidak mencegahnya dimuat. Jalankan perintah ini pada Claude Code v2.1.323 atau yang lebih baru, di mana daftar yang panjang berlanjut ke baris-baris berikutnya dengan label yang sama, dan baca setiap baris hooks: dan calls:. Dalam baris calls:, cari hal-hal berikut:
Dalam baris
hooks:, tool.call dan prompt.submit berarti mod melihat setiap panggilan tool dan setiap prompt, dan dapat mengubahnya. session.append berarti mod dapat menulis ulang setiap baris percakapan sebelum disimpan, kecuali baris yang dilewati oleh guard. ui.render{component=AskUserQuestion} berarti mod dapat menggambar ulang dialog yang digunakan Claude untuk menanyakan pengguna. tool.check berarti mod dapat menyetujui atau menolak panggilan tool sebelum permintaan izin muncul. Ketahui apa yang terjadi secara default mencantumkan aturan dan hook mana dari Anda yang diutamakan daripada jawabannya.
Pilih seberapa banyak yang diizinkan
Kebijakan mod berkisar dari tidak ada mod terinstal sama sekali hingga mod apa pun yang dipilih pengguna, dengan mod Anda sendiri yang memeriksa mod lainnya, dan masing-masing hanya berupa beberapa pengaturan terkelola. Temukan kebijakan yang Anda inginkan di kolom pertama dan atur apa yang disebutkan di kolom kedua. Men-deploy pengaturan terkelola menjelaskan lokasi pengaturan terkelola.
Fungsi setiap pengaturan:
allowManagedModsOnly: opsi pada penjaga bawaan. Claude Code menolak mod milik pengguna sendiri, sehingga tidak ada hook mereka yang berjalan. Hook pengaturan pengguna, baris status, dan/goaltetap berfungsi. Hentikan pemuatan mod yang diinstal pengguna mencantumkan apa saja yang dicakupnya.allowManagedHooksOnly: pengaturan yang lebih luas. Hanya mod organisasi Anda dan mod yang terpasang bawaan di Claude Code yang dimuat. Mod yang diinstal pengguna sendiri tidak dimuat. Pengaturan ini juga memblokir hook di file pengaturan milik pengguna sendiri. Baca Apa yang berjalan di bawahallowManagedHooksOnlysebelum Anda mengaturnya.disableAllHooks: pengaturan yang paling luas. Dalam pengaturan terkelola, pengaturan ini menghentikan mod di setiap plugin yang terinstal, termasuk milik Anda, dan mematikan setiap hook di file pengaturan, sehingga hookPreToolUsedi pengaturan terkelola Anda tidak lagi memblokir apa pun. Baris status kustom dan/goaljuga berhenti berfungsi. BacadisableAllHookssebelum Anda mengaturnya.disableSideloadFlags: menolak--plugin-dirdan--plugin-urlsaat startup, dan mencegah mod yang ditulis Claude selama sesi agar tidak dimuat. Pengaturan ini juga menolak--agentsdan--mcp-config. BacadisableSideloadFlagssebelum Anda mengaturnya.
AGENTS.md, tidak terpengaruh oleh pengaturan ini. Masing-masing memiliki saklarnya sendiri.
Pengguna yang mod-nya ditolak atau tidak dimuat dapat menemukan alasannya di log debug mereka. Pesan penolakan mencantumkan baris untuk allowManagedHooksOnly dan disableAllHooks, dan Pesan dari penjaga bawaan memuat baris untuk allowManagedModsOnly.
Izinkan hanya mod organisasi Anda
Untuk menjalankan mod organisasi Anda dan memblokir mod yang dibawa pengguna, deploy pengaturan dari baris Hanya mod organisasi Anda pada tabel kebijakan, ditambahdisableSideloadFlags. Dengan managed-settings.json lengkap ini, Claude Code menolak mod milik pengguna sendiri, sehingga tidak ada hook mereka yang berjalan, dan mod kebijakan Anda berjalan lebih dahulu daripada mod lainnya:
managed-settings.json
extraKnownMarketplaces,enabledPlugins, danprependPlugins: menginstal mod Anda agar dihitung sebagai milik Anda, dan menjalankannya lebih dahulu dengan penjaga setelahnya. Instal mod organisasi Anda dan atur urutannya menjelaskan direktori yang dituju oleh kunci-kunci ini.pluginConfigs: mengatur opsiallowManagedModsOnlypada penjaga, sehingga Claude Code menolak mod milik pengguna sendiri. Hook pengaturan, baris status, dan/goalmereka tetap berfungsi.disableSideloadFlags: lihatdisableSideloadFlagsuntuk flag yang ditolaknya saat startup
claude --debug dan baca log debug:
- Mod Anda: baris
hooks module-nya memuattier prepend - Mod yang diinstal pengguna: sebuah baris berbunyi
refused by cc-plugin-sec-default: mods are limited to your organization's by policy (allowManagedModsOnly). Baris sebelumnya menyatakan modul hook mod tersebutloaded, jadi cari baris penolakannya. - Direktori plugin:
claude --plugin-dir ./any-modkeluar dengan pesan yang diawali--plugin-dir is disabled by your organization's managed settings (disableSideloadFlags)
Terapkan kontrol plugin Anda pada mod
Mod adalah plugin, sehingga cara Anda mengelola plugin untuk organisasi Anda juga berlaku untuk plugin yang memuat mod:- Lihat plugin mana yang dimuat di seluruh armada Anda: Audit dan tinjau
- Tentukan kapan plugin yang telah Anda tinjau dapat diperbarui: Atur kebijakan pembaruan
- Berikan kebijakan berbeda untuk satu grup, seperti grup uji coba: Rencanakan untuk hal yang tidak dapat diberlakukan oleh pengaturan terkelola
- Periksa aplikasi dan jenis sesi mana yang menerapkan kunci plugin: Kapan setiap surface menerapkan kunci plugin
- Siapkan CI dan container: Seed container dan CI
- Tawarkan mod yang boleh diinstal pengguna Anda: Host marketplace. Mod yang disalin Claude Code dari sumber GitHub, git, URL, atau npm dihitung sebagai milik pengguna, kecuali Anda menginstalnya sebagai milik organisasi Anda.
Atur opsi pada penjaga bawaan
Penjaga bawaan menerima opsi. Atur opsi tersebut di pengaturan terkelola di bawahpluginConfigs, dengan kunci cc-plugin-sec-default@builtin, seperti yang dilakukan contoh di Hentikan pemuatan mod yang diinstal pengguna.
Tabel berikut menunjukkan apa yang didapat pengguna Anda dengan setiap opsi tidak diatur dan dengan opsi diatur ke true:
Aturan berikut menentukan apakah suatu opsi berlaku:
- ID hanya memiliki satu bentuk di sini: Claude Code membaca opsi hanya di bawah
cc-plugin-sec-default@builtin.prependPluginsjuga menerimasec-default@builtin, sedangkanpluginConfigstidak. - Hanya pengaturan terkelola yang dihitung: entri yang sama di file pengaturan pengguna, proyek, atau lokal, atau di file yang diteruskan dengan
--settings, tidak mengatur opsi dan tidak melonggarkannya - Penjaga harus dimuat: jika Anda mengatur
prependPlugins, sebutkan penjaga dalam daftar. Jika penjaga tidak dimuat, kedua opsi tidak berlaku. - Penjaga gagal dalam keadaan tertutup: jika penjaga tidak dapat membaca pengaturan terkelola, penjaga menolak setiap mod pengguna saat pemuatan. Jika penjaga tidak dapat memeriksa aturan deny untuk panggilan yang disetujui oleh mod pengguna, penjaga menolak panggilan tersebut.
Jalankan mod organisasi Anda sendiri
Anda dapat menerapkan mod Anda sendiri ke setiap pengguna, memilih di mana mereka berjalan relatif terhadap mod pengguna, dan menggunakan satu untuk menegakkan kebijakan.Pasang mod organisasi Anda dan atur urutan
Mod organisasi Anda memuat di mana mod pengguna tidak dan dapat berjalan sebelum mereka, jadi Claude Code harus dapat mengatakan bahwa mod berasal dari Anda. Agar mod dari marketplace jarak jauh, seperti repositori GitHub, dihitung sebagai milik Anda pada v2.1.324 atau yang lebih baru, lakukan semua hal berikut dalam pengaturan terkelola:- Tetapkan plugin mod ke
truedalamenabledPlugins - Deklarasikan marketplace dalam
extraKnownMarketplaces. Untuk mengontrol kapan kode mod berubah, sematkan marketplace dan entri mod. - Cantumkan id mod, seperti
acme-guard@acme-tools, dalamprependPluginsatauappendPlugins. DenganprependPlugins, cantumkan jugasec-default@builtinuntuk mempertahankan penjaga bawaan.
- Managed
enabledPluginsmenetapkan plugin mod ketrue - Pengaturan terkelola menyebutkan marketplace plugin sebagai direktori di mesin pengguna, menurut jalur absolut. Entri
extraKnownMarketplacesmelakukan itu dan juga mendaftarkan marketplace untuk pengguna. - Marketplace mencantumkan plugin menurut jalur relatif, jadi Claude Code memuatnya di tempat dari direktori itu
/opt/acme/claude-plugins/.claude-plugin/marketplace.json
enabledPlugins mengaktifkannya. Modnya berjalan di antara mod pengguna, prependPlugins dan appendPlugins melewatinya, allowManagedModsOnly menolaknya, dan allowManagedHooksOnly mencegahnya dimuat. Saat pengaturan terkelola mengaktifkannya, log debug pengguna memiliki baris yang dimulai dengan id plugin dan is enabled by managed settings, but.
Claude Code menaikkan peristiwa setiap kali akan bertindak, seperti menjalankan tool, dan meneruskannya ke setiap mod secara bergantian. Mod yang memenuhi kondisi direktori berjalan sebelum mod pengguna bahkan saat Anda tidak mencantumkannya di mana pun. Untuk menetapkan tempatnya, cantumkan id-nya dalam salah satu dari dua pengaturan. Id adalah nama plugin, @, dan nama marketplace, seperti acme-guard@acme-tools.
prependPlugins: mod Anda melihat peristiwa sebelum mod pengguna apa pun, dan hasil peristiwa setelahnya. Ini dapat mengubah peristiwa, menolaknya, atau melewati mod pengguna. Pada v2.1.323 atau yang lebih baru, periksa bahwa hook Anda masih menjangkau kontrol dan gambar mod lain.appendPlugins: mod Anda berjalan setelah setiap mod pengguna, jadi hanya melihat peristiwa yang dilewatkan mod tersebut, dalam bentuk yang mereka lewatkan
acme-tools di /opt/acme/claude-plugins, mengaktifkan acme-guard darinya, dan menjalankan mod itu terlebih dahulu, dengan penjaga bawaan setelahnya:
managed-settings.json
extraKnownMarketplaces: menyebutkan direktori yang menyimpan marketplaceacme-tools.pathadalah jalur absolut direktori yang berisi.claude-plugin/marketplace.json.enabledPlugins: mengaktifkanacme-guarduntuk setiap pengguna yang menerima pengaturan terkelola iniprependPlugins: menempatkanacme-guardterlebih dahulu dan penjaga bawaan kedua, keduanya sebelum mod apa pun yang dipasang pengguna. Claude Code mengikuti urutan yang Anda cantumkan.
claude --debug dan cari log debug untuk id mod:
hooks module acme-guard@acme-tools loaded, dengantier prepend: mod dihitung sebagai milik organisasi Anda dan berjalan terlebih dahulu- Baris yang sama dengan
tier user: Claude Code memperlakukannya sebagai mod pengguna. Baris kedua,prependPlugins names acme-guard@acme-tools, which is not an enabled managed plugin with a hooks module; skipped, mengatakan daftar melewatinya.
- Daftar menggantikan default: saat Anda menetapkan
prependPluginsdalam pengaturan terkelola, sebutkansec-default@builtindi dalamnya untuk menjaga penjaga bawaan. Penjaga dibangun dan tidak memerlukan entrienabledPlugins. - Id Anda sendiri harus dihitung sebagai milik Anda: dalam pengaturan terkelola, Claude Code melewati id yang pluginnya tidak memenuhi kondisi untuk mod organisasi
- Repositori tidak dapat menetapkan kedua daftar: Claude Code mengabaikan keduanya dalam file pengaturan repositori, jadi tetapkan keduanya dalam pengaturan terkelola.
- Pengguna dapat menetapkannya untuk mengurutkan mod mereka sendiri: dalam
~/.claude/settings.json, hanya di mesin tanpa pengaturan terkelola atau filemanaged-mcp.json, dan hanya saat kredensial sesi bukan/loginTeam atau Enterprise. Di tempat lain, Claude Code mengabaikan kedua kunci dalam pengaturan pengguna. Daftar di sana tidak menambah atau menghapus penjaga bawaan.
Terapkan kebijakan dengan mod Anda sendiri
Untuk menjaga setiap mod pengguna keluar, Anda tidak memerlukan mod Anda sendiri. AturallowManagedModsOnly. Tulis mod kebijakan saat Anda ingin mengizinkan beberapa mod pengguna dan menolak yang lain, atau untuk mencatat apa yang dilakukan mod.
Setiap kali mod lain akan memuat, mod Anda menerima daftar yang dicetak claude plugin validate, dalam peristiwa bernama plugin.register. Mod dalam prependPlugins dapat membaca daftar itu dan menolak mod. Ini juga dapat menangani panggilan API mods apa pun menurut nama untuk mencatat atau menolak panggilan itu untuk setiap mod lainnya. Nama adalah metode tanpa $., jadi hook pada fs.write melihat setiap panggilan $.fs.write.
Pada v2.1.323 atau yang lebih baru, hook
ui.focus memerlukan matcher yang lebih luas untuk menerima panggilan $.ui.focus dari mod lain. Lihat Hook gambar dan kontrol mod lain.$.process.run atau $.process.spawn. Ini juga menyimpan log audit, menulis setiap panggilan tool dan setiap file yang ditulis mod ke log debug. Karena berjalan terlebih dahulu, log mencatat apa yang diminta, sebelum mod pengguna apa pun mengubahnya. Simpan sebagai acme-guard/hooks/register.js:
acme-guard/hooks/register.js
plugin.register: memutuskan apakah mod lain memuat. Ini menolak mod pengguna yang memanggil metode yang diblokir dan meneruskan setiap mod lainnya.tool.call: menulis baris sepertiaudit tool.call Bashke log debug untuk setiap panggilan tool, dan tidak mengubah apa punfs.write: menulis baris sepertiaudit fs.write by reader "/tmp/notes.md"untuk setiap panggilan$.fs.writeyang dibuat mod lain, dan tidak mengubah apa pun. Nama mod datang terlebih dahulu dan jalurnya dikutip, jadi jalur yang dipilih mod tidak dapat lulus sebagai bidang lain dari baris.
plugin.register membaca dua bidang peristiwa:
e.tier: di mana mod akan berjalan, salah satu dariprepend,user,append, ataubuiltin. Setiap mod yang dipasang orang adalahuser.e.uses.calls: metode API mods yang dipanggil mod, masing-masing ditulisnamespace.methodsepertiprocess.run, tanpa$.yang dicetakclaude plugin validate
$.process.run, mod tidak memuat, dan log debug mereka memiliki baris yang berakhir dengan refused by acme-guard: dan alasan Anda. Penolakan juga mencapai transkrip dalam sesi yang memuat ulang panas direktori plugin.
Untuk memblokir panggilan tanpa menolak seluruh mod, kembalikan { deny: 'your reason' } dari hook pada nama panggilan itu, setelah Anda memeriksa siapa yang membuat panggilan tersebut.
Untuk mengirim baris audit ke tempat lain selain log debug, panggil $.http.fetch dari hook yang sama.
Sesi dapat berjalan tanpa mod Anda. Jika thread pekerja yang menjalankan mod yang dipasang mogok tiga kali, Claude Code membongkar setiap mod yang bukan bawaan, termasuk milik Anda, sampai pengguna menjalankan /reload-plugins atau memulai sesi baru. Dan pengguna yang memulai Claude Code dengan --safe-mode berjalan tanpa mod yang dipasang, termasuk milik Anda.
Buat mod mencakup file yang dibutuhkan mod. Uji mod kebijakan memiliki file uji untuk mod kebijakan ini.
Tolak mod saat pemeriksaan Anda gagal
Jika hookplugin.register Anda melempar atau melampaui batas waktu, Claude Code melewati hook, jadi pemeriksaan gagal terbuka dan mod yang diperiksa memuat. Untuk gagal tertutup dan menolak mod pengguna, pindahkan pemeriksaan ke fungsi bernama dan tambahkan handler .catch yang mengembalikan penolakan. Versi file ini menunjukkan hanya hook plugin.register, jadi simpan dua hook audit dari versi pertama dalam register:
acme-guard/hooks/register.js
refused by acme-guard: Acme policy check failed, so this mod was not loaded. Handler meneruskan setiap mod di luar tier user ke next(e), jadi pemeriksaan yang gagal tidak menghentikan mod yang dicantumkan organisasi Anda. Tangani hook yang gagal mencakup .catch untuk peristiwa lain.
Langkah berikutnya
- Keamanan plugin: apa yang dapat dilakukan plugin apa pun di mesin pengguna, dan cara meninjau satu sebelum dipasang
- Ikhtisar mod: apa itu mod dan bagaimana perbandingannya dengan hook, skill, dan server MCP
- Urutan mod berjalan: bagaimana
prependPluginsdanappendPluginscocok dengan mod pengguna - Pengaturan dan variabel lingkungan: setiap pengaturan yang dinamai di halaman ini dalam satu tabel