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 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, terlepas dari kunci yang Claude Code baca dari setiap sumber admin. Bagaimana Claude Code menggabungkan sumber terkelola mencakup opt-in yang menerapkan keduanya.
• 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.
  Tabel cakupan permukaan membandingkan Cowork dengan permukaan lainnya.
• Sesi yang berjalan: sesi mengambil sebagian besar perubahan sesuai jadwal dalam tabel tanpa restart. Claude Code membaca forceRemoteSettingsRefresh dan requiredMinimumVersion hanya saat startup sesi, mengaktifkan entri policyHelper yang baru atau berubah saat peluncuran berikutnya, dan membaca beberapa kunci yang dapat diedit pengguna sekali saat startup sesi.
• Perubahan yang memerlukan persetujuan: terlepas dari 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.
• 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: 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", default: Claude Code menggunakan sumber peringkat tertinggi yang mengirimkan setidaknya satu kunci kebijakan dan mengabaikan sisanya daripada menggabungkannya, terlepas dari beberapa kunci dalam Kunci yang dibaca dari setiap sumber admin. Claude Code tidak menunjukkan peringatan untuk sumber yang dilewatkan; /status menamai sumber yang digunakan dan yang dilewatkan.
• "merge": Claude Code menerapkan setiap sumber admin yang mengirimkan kunci kebijakan dan menggabungkannya berdasarkan jenis kunci: pada sebagian besar kunci nilai sumber 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 digabungkan. 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 itu tidak dihitung, dan Claude Code melanjutkan ke sumber berikutnya.
• Sumber admin: salah satu dari tiga sumber pertama di bawah. Registry HKCU yang dapat ditulis pengguna bukan satu.

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 login atau kunci yang memenuhi syarat, atau masuk ke gateway dengan /login. 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 registry HKLM
3. File pengaturan terkelola, managed-settings.d/*.json dan managed-settings.json digabungkan bersama
4. Registry HKCU, di Windows, dan di WSL setelah registry HKLM atau file pengaturan terkelola Windows mengaktifkan wslInheritsWindowsSettings dan nilai HKCU juga menetapkannya. Claude Code membacanya hanya ketika tidak ada sumber di atasnya yang mengirimkan kunci kebijakan dan tidak ada pengaturan induk yang disediakan host yang menyediakan kunci yang ketat

​

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 daftar 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 daftar seperti kunci lainnya, jadi di bawah "first-wins" daftar sumber admin yang tidak dipilih diabaikan
• allowAllClaudeAiMcps
• Jalur biner sandbox sandbox.bwrapPath dan sandbox.socatPath
• Biner sandbox ripgrep, sandbox.ripgrep
• sandbox.filesystem.disabled dan sandbox.network.strictAllowlist
• useAutoModeDuringPlan dan syncClaudeAiSkills, 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 alat 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 berlaku. Memerlukan Claude Code v2.1.242 atau lebih baru
• Opt-out trailer commit dalam attribution, atau dalam includeCoAuthoredBy yang sudah usang, dari tingkat apa pun
• forceRemoteSettingsRefresh
• env, digabungkan per variabel di seluruh sumber admin: setiap variabel berasal dari sumber prioritas tertinggi yang mendefinisikannya, jadi sumber lebih rendah mengisi variabel yang sumber lebih tinggi biarkan tidak diatur. 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 sumber yang dipilih secara keseluruhan 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, terlepas dari forceRemoteSettingsRefresh, yang Claude Code periksa di setiap sumber admin saat startup sebelum pembantu berjalan. Untuk pembantu mana yang gagal, dan apa yang Claude Code lakukan ketika satu gagal, lihat Kegagalan pembantu

​

Biarkan host embedding 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 Claude Code terapkan, atau dari pengaturan induk yang telah Anda pilih untuk merge
• Claude Code memberlakukan nilai forceLoginOrgUUID atau allowedMcpServers dalam pengaturan terkelola yang diterapkannya dan memblokir yang disediakan induk. Nilai dalam sumber admin lebih rendah yang Claude Code tidak terapkan tidak berlaku atau memblokir yang disediakan induk. 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
• Nilai availableModels mengikuti aturan yang sama dengan allowedMcpServers

​

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.
• 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 registry HKLM dan domain preferensi terkelola macOS ada.
• Cache terkelola server: pengaturan terkelola server berasal dari server Anthropic, dan edit ke cache lokal berlaku hanya sampai pengambilan berhasil berikutnya.
• Alat lain: pengaturan terkelola mengikat Claude Code saja. Pengembang yang memanggil API dari alat lain tidak berada di bawahnya.

​

Periksa bahwa kebijakan berlaku

​

Baca sumber dalam /status

• (remote): pengaturan terkelola 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 lebih rendah masih dapat menyediakan variabel env tanpa muncul dalam daftar. Memerlukan Claude Code v2.1.242 atau lebih baru
• (HKCU): fallback registry yang dapat ditulis pengguna
• (parent process): host embedding menyediakan pengaturan yang ketat
• (helper): policyHelper dikonfigurasi oleh sumber MDM atau file yang dipilih

• Baris hilang: Claude Code tidak menemukan sumber terkelola yang mengirimkan kunci kebijakan. Jika Anda terapkan file pengaturan terkelola, periksa bahwa itu duduk di jalur untuk OS dan bahwa itu berisi kunci kebijakan daripada hanya kunci kontrol. File yang bukan JSON yang valid tidak menghasilkan keadaan ini; Claude Code menolak untuk memulai sebagai gantinya. Ketika Anda terapkan melalui pengaturan terkelola server sebagai gantinya, 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 hapus

• 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 registry HKLM: nilai Settings bukan string, kosong, atau tidak menyimpan objek JSON

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

• Sesi interaktif menunjukkan 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

​

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