Terapkan pengaturan terkelola

​

Terapkan file pengaturan terkelola

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./secrets/**)"
    ],
    "disableBypassPermissionsMode": "disable"
  },
  "allowManagedPermissionRulesOnly": true
}

​

Pilih mekanisme pengiriman

• Kontrol pengiriman: policyHelper, wslInheritsWindowsSettings, dan managedSourcesBehavior
• Kunci login gateway: forceLoginGatewayUrl, gatewayInternalNetworks, dan nilai "gateway" dari forceLoginMethod

​

Di mana dan kapan kebijakan berlaku

• Permukaan: di mesin pengembang, terminal, ekstensi VS Code dan JetBrains, tab Code aplikasi desktop, dan sesi Agent SDK membaca semua sumber ini. Sesi Agent SDK memuat pengaturan terkelola bahkan ketika settingSources mengecualikan file pengguna, proyek, dan lokal.
• Sesi cloud: sesi di lingkungan yang dihosting Anthropic tidak membaca profil MDM atau file perangkat, jadi kebijakan untuk itu harus berasal dari pengaturan terkelola server. Sesi di lingkungan yang di-host sendiri juga membaca file pengaturan terkelola di gambar runner-nya, secara default hanya ketika pengaturan terkelola server tidak mengirimkan kunci kebijakan, kecuali kunci yang Claude Code baca dari setiap sumber admin. Bagaimana Claude Code menggabungkan sumber terkelola mencakup opt-in yang menerapkan keduanya.
• Sesi Claude Tag: sesi Claude Tag berjalan di lingkungan cloud tetapi tidak menerima pengaturan terkelola server. Di lingkungan yang di-host sendiri, mereka masih membaca file pengaturan terkelola di gambar runner. Konfigurasikan Claude Tag itu sendiri di pengaturan admin Claude Tag.
• Sesi Cowork: Cowork di aplikasi Claude Desktop menjalankan sesinya di Claude Code. Dalam sesi Cowork, Claude Code tidak pernah mengambil pengaturan terkelola server dari konsol admin claude.ai, bahkan ketika pengguna masuk dengan akun Team atau Enterprise, jadi kebijakan mana yang berlaku tergantung di mana sesi berjalan:
  • Di mesin pengguna: secara default, Claude Code dalam sesi Cowork membaca kebijakan MDM atau tingkat OS dan file pengaturan terkelola di perangkat itu, jadi terapkan kebijakan di sana.
  • Di sandbox VM penuh: ketika konfigurasi terkelola Claude Desktop Anda menetapkan requireCoworkFullVmSandbox, Claude Code berjalan di dalam mesin virtual di mana kebijakan MDM perangkat dan file pengaturan terkelola tidak ada.
  • Sesi Cowork jarak jauh: ini berjalan di VM yang dikelola Anthropic, di mana Claude Code tidak memiliki kebijakan perangkat untuk dibaca.
  Di mana pun sesi berjalan, claude.ai menerapkan daftar strictKnownMarketplaces dan blockedMarketplaces konsol admin itu sendiri ketika siapa pun menambahkan marketplace dari repositori git di claude.ai atau dari Customize di Cowork. Bagaimana pembatasan bekerja menjelaskan pemeriksaan itu. Tabel cakupan surface membandingkan Cowork dengan surface lainnya.
• Sesi yang berjalan: sebagian besar perubahan mencapai sesi yang berjalan sesuai jadwal dalam tabel mekanisme pengiriman, tanpa restart.
  • Perubahan pada forceRemoteSettingsRefresh, requiredMinimumVersion, dan beberapa kunci yang dapat diedit pengguna berlaku pada startup sesi berikutnya.
  • Entri policyHelper yang baru atau berubah berlaku pada peluncuran berikutnya. Jika pengaturan terkelola server menaungi helper pada peluncuran itu, helper berjalan segera setelah pengambilan melaporkan pengaturan tersebut dihapus.
• Perubahan yang memerlukan persetujuan: kecuali untuk pembaruan yang menunggu peluncuran berikutnya, perubahan terkelola server ke pengaturan yang memerlukan persetujuan, seperti hook atau variabel env, menunggu pengembang menerima dialog dalam sesi interaktif, dan berlaku untuk run saat ini dalam sesi yang dihosting ekstensi IDE atau Agent SDK. Perubahan terkelola server lainnya berlaku pada polling berikutnya.
• Sesi yang tahan lama: sesi yang dibiarkan terbuka selama berminggu-minggu masih bisa tertinggal dari rollout. requiredMinimumVersion memblokir biner yang ketinggalan zaman dari memulai dan tidak mengakhiri sesi yang sudah berjalan.

​

Di mana setiap mekanisme menyimpan kebijakan

• Terkelola server: server Anthropic, atau gateway Anda, menyimpan kebijakan. Claude Code menyimpan cache lokal yang diterapkannya saat startup dan diganti pada setiap pengambilan yang berhasil.
• Profil konfigurasi macOS: domain preferensi terkelola com.anthropic.claudecode. Gunakan kunci tingkat atas yang sama dengan managed-settings.json, dengan pengaturan bersarang sebagai kamus dan daftar sebagai array plist.
• Registry HKLM Windows: JSON sebagai nilai REG_SZ atau REG_EXPAND_SZ bernama Settings di bawah HKLM\SOFTWARE\Policies\ClaudeCode.
• Berbasis file: managed-settings.json, direktori opsional managed-settings.d/, dan managed-mcp.json di direktori sistem: /Library/Application Support/ClaudeCode/ di macOS, /etc/claude-code/ di Linux dan WSL, dan C:\Program Files\ClaudeCode\ di Windows. Claude Code tidak membaca jalur Windows warisan C:\ProgramData\ClaudeCode\managed-settings.json. Anda dapat menerapkan file mana pun dari file-file ini sebagai tautan simbolis, dan Claude Code membaca file yang dituju oleh tautan tersebut. Kebijakan tetap berlaku ketika tautan mengarah ke luar direktori sistem atau Claude Code tidak dapat memastikan bahwa tautan tersebut tetap berada di dalamnya. Peringatan yang menyebutkan nama file tersebut kemudian muncul di /status dan claude doctor. Untuk menghapus peringatan, arahkan tautan ke target di dalam direktori sistem.
• Registry HKCU Windows: nilai Settings yang sama di bawah HKCU\SOFTWARE\Policies\ClaudeCode.

​

Pisahkan kebijakan berbasis file di seluruh tim

• Nilai tunggal, seperti "model": "opus" atau "cleanupPeriodDays": 7: nilai file yang lebih baru menggantikan yang lebih lama
• Daftar, seperti permissions.deny atau sandbox.network.allowedDomains: dua daftar digabungkan, dengan duplikat dihapus
• Blok bersarang, seperti env atau sandbox: dua blok digabungkan kunci demi kunci, dan setiap kunci di dalamnya mengikuti aturan yang sama ini
• fallbackModel: rantai yang lebih baru menggantikan yang lebih lama secara keseluruhan
• extraKnownMarketplaces dan managedMcpServers: entri yang lebih baru dengan nama yang sama menggantikan yang lebih lama secara keseluruhan
• modelPicker: lineup yang lebih baru menggantikan yang lebih lama secara keseluruhan

​

Bagaimana Claude Code menggabungkan sumber terkelola

• "first-wins", pengaturan default: Claude Code menggunakan sumber dengan peringkat tertinggi yang mengirimkan setidaknya satu kunci kebijakan dan mengabaikan sisanya daripada menggabungkannya, kecuali untuk kunci dalam Kunci yang dibaca dari setiap sumber admin. Claude Code tidak menampilkan peringatan untuk sumber yang dilewati; /status menamai sumber yang digunakan dan yang dilewati.
• "merge": Claude Code menerapkan setiap sumber admin yang mengirimkan kunci kebijakan dan menggabungkannya berdasarkan jenis kunci: pada sebagian besar kunci nilai sumber dengan peringkat lebih tinggi berlaku, daftar bersatu, dan kunci mengambil nilai paling ketat. Susun setiap sumber terkelola mengatakan di mana menetapkan kunci dan bagaimana setiap jenis kunci menggabungkan. Memerlukan Claude Code v2.1.242 atau lebih baru.

• Kunci kebijakan: kunci pengaturan apa pun selain dua kunci kontrol, wslInheritsWindowsSettings dan managedSourcesBehavior. File pengaturan terkelola atau kebijakan MDM yang hanya berisi yang tersebut tidak dihitung, dan Claude Code melanjutkan ke sumber berikutnya.
• Sumber admin: salah satu dari tiga sumber pertama di bawah. Registri HKCU dapat ditulis pengguna dan bukan salah satunya.

1. Pengaturan jarak jauh, dikirimkan dari claude.ai sebagai pengaturan terkelola server atau oleh gateway aplikasi Claude. Claude Code mengambil sumber ini hanya ketika sesi mengautentikasi ke API Anthropic secara langsung dengan kredensial yang memenuhi syarat, masuk ke gateway dengan /login, atau berjalan di tab Code Claude Desktop di belakang gateway yang menyajikan pengaturan ke sesi tersebut. Pada penyedia lain, atau ketika ANTHROPIC_BASE_URL menunjuk ke tempat lain selain API Anthropic, dimulai dari sumber berikutnya
2. Kebijakan MDM atau tingkat OS: plist macOS atau kunci registri HKLM
3. File pengaturan terkelola, managed-settings.d/*.json dan managed-settings.json digabungkan bersama
4. Registri HKCU, di Windows, dan di WSL setelah registri HKLM atau file pengaturan terkelola Windows mengaktifkan wslInheritsWindowsSettings dan nilai HKCU juga menetapkannya. Claude Code membacanya hanya ketika tidak ada dokumen admin yang ada di atasnya dan tidak ada pengaturan induk yang disediakan host yang menyediakan kunci pembatasan

​

Kapan dokumen admin dihitung sebagai ada

• Dokumen tersebut menetapkan kunci kebijakan apa pun ke nilai selain null, bahkan nilai yang tidak dapat dibaca Claude Code
• Dokumen tersebut adalah nilai HKLM, file pengaturan terkelola, atau direktori managed-settings.d yang ada tetapi tidak dapat dibaca

​

Kunci yang dibaca dari setiap sumber admin

• sandbox.network.allowManagedDomainsOnly dan sandbox.filesystem.allowManagedReadPathsOnly: true dalam sumber admin apa pun mengaktifkan kunci. Saat kunci aktif, Claude Code menyatukan allowlist yang dikunci, sandbox.network.allowedDomains bersama dengan aturan izin WebFetch(domain:...), atau sandbox.filesystem.allowRead, di seluruh setiap sumber admin. Tanpa kunci, Claude Code memperlakukan allowlist seperti kunci lainnya, jadi di bawah "first-wins" allowlist sumber admin yang tidak dipilih diabaikan
• allowAllClaudeAiMcps
• allowManagedMcpServersOnly: true dalam sumber admin apa pun mengaktifkan kunci allowlist MCP. Saat kunci aktif, daftar allowedMcpServers terkelola berasal dari sumber admin dengan peringkat tertinggi yang menetapkan satu. Daftar terkelola server menggantikan daftar sumber yang lebih rendah daripada menggabungkannya. Jika tidak ada sumber admin yang menetapkan daftar, setiap server yang melewati denylist dimuat, kecuali pengaturan induk menyediakan daftar. Tanpa kunci, Claude Code membaca allowedMcpServers dari sumber terkelola yang diterapkannya, jadi di bawah "first-wins" daftar sumber admin yang tidak dipilih diabaikan. Memerlukan Claude Code v2.1.273 atau lebih baru
• deniedMcpServers dan disableClaudeAiConnectors: entri atau true dalam sumber admin apa pun berlaku. Memerlukan Claude Code v2.1.273 atau lebih baru
• Jalur biner sandbox sandbox.bwrapPath dan sandbox.socatPath
• Biner sandbox ripgrep, sandbox.ripgrep
• sandbox.filesystem.disabled dan sandbox.network.strictAllowlist
• useAutoModeDuringPlan, syncClaudeAiSkills, dan syncClaudeAiPlugins, di mana false dari sumber admin apa pun mematikan perilaku. false dalam pengaturan pengguna atau lokal pengembang juga mematikannya; setiap kunci hanya dapat menolak
• enableArtifact, di mana false dari sumber admin apa pun mematikan tool Artifact. false dalam pengaturan pengguna, proyek, atau lokal pengembang juga mematikannya, dan tidak ada sumber yang mengaktifkannya kembali; lihat nilai tingkat lebih rendah mana yang masih dihitung. Memerlukan Claude Code v2.1.242 atau lebih baru
• maxEffortLevel, di mana batas terendah dalam sumber admin apa pun berlaku. Jika pengembang menetapkan batas lebih rendah dalam pengaturan mereka sendiri atau dengan --settings, Claude Code menerapkan yang itu; tidak ada sumber yang dapat menaikkan batas. Memerlukan Claude Code v2.1.267 atau lebih baru
• Opt-out trailer komit dalam attribution, atau dalam includeCoAuthoredBy yang sudah deprecated, dari tingkat apa pun
• forceRemoteSettingsRefresh
• env, digabungkan per variabel di seluruh sumber admin: setiap variabel berasal dari sumber prioritas tertinggi yang mendefinisikannya, sehingga sumber yang lebih rendah mengisi variabel yang tidak ditetapkan oleh sumber yang lebih tinggi. Beberapa variabel mengikuti aturan mereka sendiri; Pengecualian per kunci di seluruh sumber terkelola menamai masing-masing. Memerlukan Claude Code v2.1.223 atau lebih baru. Sebelum v2.1.223, Claude Code menerapkan blok env seluruh sumber yang dipilih saja

​

Susun setiap sumber terkelola

​

Hitung kebijakan dengan program pembantu

• Objek managedSettings yang dipancarkan adalah satu-satunya pengaturan terkelola untuk sesi, termasuk untuk kunci yang sebaliknya dibacanya dari setiap sumber admin, kecuali forceRemoteSettingsRefresh, yang memiliki aturan startup sendiri

​

Biarkan host penyematan menambahkan kebijakan

• Ketika sumber admin apa pun menetapkan allowManagedPermissionRulesOnly, Claude Code menghapus aturan izin allow yang disediakan induk dan additionalDirectories saat membacanya, bahkan ketika sumber prioritas lebih tinggi membiarkan kunci tidak diatur. Efek kunci pada aturan izin Anda sendiri berasal dari pengaturan terkelola yang diterapkan Claude Code, atau dari pengaturan induk yang telah Anda pilih untuk digabungkan
• Claude Code memberlakukan nilai forceLoginOrgUUID atau allowedMcpServers dalam pengaturan terkelola yang diterapkannya dan memblokir yang disediakan induk. Di luar kunci allowlist MCP, nilai dalam sumber admin yang lebih rendah yang tidak diterapkan Claude Code tidak berlaku atau memblokir yang disediakan induk. Pada Claude Code v2.1.273 atau lebih baru, saat allowManagedMcpServersOnly aktif, daftar allowedMcpServers dari sumber admin dengan peringkat tertinggi yang menetapkan satu berlaku dan memblokir yang disediakan induk, sebagai kunci lintas sumber. Daftar induk berlaku hanya ketika tidak ada sumber admin yang menetapkan satu. Entri managedSourcesBehavior mengatakan sumber mana yang menyediakan setiap kunci di bawah "merge". Sebelum v2.1.223, nilai dalam sumber admin apa pun memblokir yang disediakan induk
• Untuk availableModels, Claude Code memberlakukan nilai dalam pengaturan terkelola yang diterapkannya dan memblokir daftar yang disediakan induk
• Untuk strictKnownMarketplaces, Claude Code demikian juga memberlakukan daftar dalam pengaturan terkelola yang diterapkannya dan memblokir yang disediakan induk. Daftar induk berlaku hanya ketika tidak ada sumber terkelola yang diterapkan menetapkan satu. Memerlukan Claude Code v2.1.282 atau lebih baru
• Untuk allowedProviders, daftar dalam sumber terkelola yang dipilih memblokir yang disediakan induk, dan di bawah opt-in "merge" managedSourcesBehavior, daftar dalam sumber admin apa pun juga memblokirnya. Memerlukan Claude Code v2.1.285 atau lebih baru
• blockedMarketplaces yang disediakan induk berlaku selain denylist apa pun yang ditetapkan sumber terkelola. Memerlukan Claude Code v2.1.282 atau lebih baru

​

Pertahankan akses folder Cowork ketika hanya aturan terkelola yang berlaku

{
  "allowManagedPermissionRulesOnly": true,
  "permissions": {
    "allow": [
      "Edit(~/CoworkProjects/**)"
    ]
  }
}

​

Apa yang dapat diubah pengembang

• Model untuk sesi: model terkelola adalah default, bukan kunci. --model dan ANTHROPIC_MODEL masih memilih model untuk sesi itu, jadi terapkan availableModels untuk membatasi pilihan.
• Jendela auto-compact untuk sesi: autoCompactWindow terkelola juga merupakan default. Flag --autocompact dan variabel CLAUDE_CODE_AUTO_COMPACT_WINDOW masih menetapkan jendela auto-compact untuk sesi itu.
• Hak admin lokal: pengembang yang merupakan administrator di mesin dapat mengedit sumber terkelola itu sendiri, itulah mengapa alat MDM dapat menerapkan kembali profil atau file sesuai jadwal dan mengapa registri HKLM dan domain preferensi terkelola macOS ada.
• Cache terkelola server: pengaturan terkelola server berasal dari server Anthropic, dan edit ke cache lokal berlangsung hanya sampai pengambilan berikutnya yang berhasil.
• Alat lain: pengaturan terkelola mengikat Claude Code saja. Pengembang yang memanggil API dari alat lain tidak berada di bawahnya.

​

Periksa bahwa kebijakan sedang berlaku

​

Baca sumber di /status

• (remote): pengaturan yang dikelola server dari claude.ai atau gateway
• (plist) atau (HKLM): kebijakan MDM atau OS
• (file), (drop-ins), atau (file + drop-ins): managed-settings.json, direktori drop-in, atau keduanya
• (remote + file, merged), atau daftar lain yang diakhiri dengan , merged: organisasi Anda menyusun setiap sumber terkelola, dan Claude Code menggabungkan sumber yang tercantum ke dalam kebijakan. Sumber yang lebih rendah masih dapat menyediakan variabel env tanpa muncul dalam daftar. Memerlukan Claude Code v2.1.242 atau lebih baru
• (HKCU): fallback registri yang dapat ditulis pengguna
• (parent process): host penyematan menyediakan pengaturan pembatasan
• (helper): policyHelper yang dikonfigurasi oleh sumber MDM atau file yang dipilih

• Baris hilang: Claude Code tidak menemukan sumber terkelola yang memberikan kunci kebijakan. Jika Anda menerapkan file pengaturan terkelola, periksa bahwa file tersebut berada di jalur untuk OS dan bahwa file tersebut berisi kunci kebijakan daripada hanya kunci kontrol. File yang bukan JSON yang valid tidak menghasilkan status ini; Claude Code menolak untuk memulai sebagai gantinya. Ketika Anda justru menerapkan melalui pengaturan yang dikelola server, jalankan claude doctor, yang melaporkan hasil pengambilan.
• Baris menamai sumber selain yang Anda terapkan: sumber prioritas lebih tinggi ada dan Claude Code mengabaikan milik Anda, dan Skipped sources mencantumkannya. Bagaimana Claude Code menggabungkan sumber terkelola memberikan urutan.

​

Temukan entri yang Claude Code jatuhkan

• File pengaturan terkelola atau file drop-in: file bukan JSON yang valid, atau tingkat atasnya bukan objek
• Plist MDM: plutil macOS melaporkan plist yang salah bentuk, atau konten yang dikonversi bukan objek JSON
• Nilai registri HKLM: nilai Settings bukan string, kosong, atau tidak menyimpan objek JSON

• File, profil, atau nilai registri yang tidak ada bukan kegagalan; Claude Code berjalan tanpa sumber tersebut.
• File pengaturan terkelola yang kosong dihitung sebagai {}.
• Nilai yang salah bentuk dalam kunci registri HKCU yang dapat ditulis pengguna tidak pernah memblokir peluncuran. Claude Code melaporkannya sebagai pemberitahuan di /status dan claude doctor sebagai gantinya.

• Jika sistem operasi menolak pembacaan, misalnya pada file hanya root, setiap sesi dimulai tanpa kebijakan sumber tersebut. /status dan claude doctor mencatat kegagalan, dan jalankan dengan -p juga mencetaknya ke stderr.
• Untuk kegagalan pembacaan lainnya, seperti kesalahan I/O, setiap sesi keluar saat startup dengan pesan untuk menghubungi administrator.

• Sesi interaktif menampilkan dialog saat startup yang mencantumkan entri yang tidak valid.
• Jalankan non-interaktif dengan -p mencetak ringkasan ke stderr.
• claude doctor mencantumkan setiap entri yang tidak valid dengan sumber dan bidangnya.

​

Kunci yang gagal tertutup

• null menghapus kunci.
• disableAllHooks yang tidak valid, bahkan boolean yang dikutip, dijatuhkan dengan peringatan, karena memberlakukan true juga akan membongkar hook yang pengaturan terkelola Anda sendiri terapkan.
• Untuk setiap kunci boolean lainnya yang aturan cakup, string "true" atau "false" membaca sebagai boolean tersebut, dengan pemberitahuan di /status meminta Anda untuk menghapus tanda kutip.

• Kunci kunci di dalamnya, seperti permissions.disableBypassPermissionsMode, membaca sebagai nilai pembatasannya.
• permissions.defaultMode yang tidak valid membaca sebagai default.
• Sementara daftar deny atau ask di permissions tidak dapat dibaca sama sekali, Claude Code menahan allow dan additionalDirectories, sehingga hibah tidak pernah diterapkan tanpa pembatasan yang ditulis di sebelahnya. Laporan menamai setiap hibah yang ditahan dan daftar yang tidak dapat dibaca.
• Di autoMode, daftar soft_deny atau hard_deny yang tidak dapat dibaca, atau yang kehilangan entri yang tidak valid, menahan allow dan environment dengan cara yang sama.

​

Nilai yang tidak valid di dalam sandbox

• Jika Anda menetapkan kunci Boolean ke "true" atau "false" yang dikutip, nilai dihitung sebagai Boolean tersebut. Alih-alih peringatan, /status menampilkan pemberitahuan meminta Anda untuk menghapus tanda kutip.
• Jika failIfUnavailable tidak valid, Claude Code menjatuhkan nilai daripada memperlakukannya sebagai true, sehingga nilai yang tidak dapat dibaca tidak pernah menghentikan sesi dari memulai di seluruh armada Anda.
• Claude Code memperlakukan setiap Boolean yang tidak valid lainnya sebagai nilai yang membuat sandbox paling ketat sampai Anda memperbaikinya. Kunci yang mengaktifkan sandbox atau salah satu pembatasannya, seperti enabled atau network.allowManagedDomainsOnly, dihitung sebagai true. Kunci yang melonggarkannya, seperti allowUnsandboxedCommands, dihitung sebagai false.
• Dalam daftar di luar credentials, seperti excludedCommands atau network.allowedDomains, Claude Code menjatuhkan entri yang tidak valid dan menyimpan sisa daftar. Daftar yang bukan array, atau yang tidak memiliki entri yang valid, tidak berlaku sama sekali.
• Sementara network.deniedDomains atau entri apa pun di dalamnya tidak valid, Claude Code juga menahan network.allowedDomains, sehingga allowlist terkelola tidak memberikan apa pun sampai Anda memperbaiki daftar penolakan.
• Sementara filesystem.denyRead, filesystem.denyWrite, atau entri apa pun di salah satu tidak valid, Claude Code juga menahan filesystem.allowRead dan filesystem.allowWrite sampai Anda memperbaiki daftar penolakan.

​

Kunci yang hanya sumber terkelola yang dapat atur

​

Matikan telemetri untuk organisasi Anda

{
  "env": {
    "DISABLE_TELEMETRY": "1"
  }
}

​

Lihat juga

• Siapkan Claude Code untuk organisasi Anda: tentukan apa yang akan diberlakukan dan bagaimana
• Pengaturan terkelola server: kirimkan kebijakan dari konsol claude.ai atau gateway
• Konfigurasi MCP terkelola: kontrol server MCP mana yang dapat digunakan pengembang
• Semua pengaturan: setiap kunci, dengan apakah sumber terkelola dapat menetapkannya
• File pengaturan contoh: managed-settings.json lengkap yang menunjukkan bentuk kunci terkelola