Konfigurasi pengaturan yang dikelola server

​

Persyaratan

• Paket Claude for Teams atau Claude for Enterprise
• Peran Owner atau Primary Owner di organisasi Claude Anda, untuk melihat dan mengedit konfigurasi
• Akses jaringan ke api.anthropic.com

​

Pilih antara pengaturan yang dikelola server dan endpoint

​

Konfigurasi pengaturan yang dikelola server

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

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "/usr/local/bin/audit-edit.sh" }
        ]
      }
    ]
  }
}

​

Verifikasi pengiriman pengaturan

• Pengaturan yang dikirimkan dimuat
• Organisasi Anda tidak memiliki pengaturan yang dikelola server yang dikonfigurasi
• Pengambilan gagal, dengan penyebab dan apakah kebijakan yang di-cache masih berlaku
• Claude Code melewati pengambilan, dengan alasannya. Lihat Ketersediaan platform untuk penyedia dan konfigurasi yang melewatinya

​

Kontrol akses

• Primary Owner
• Owner

​

Pengaturan yang hanya dikelola

​

Batasan saat ini

• Pengaturan berlaku secara seragam untuk semua pengguna dalam organisasi. Konfigurasi per-grup belum didukung.
• Anda tidak dapat mendistribusikan file managed-mcp.json melalui pengaturan yang dikelola server. Berikan kunci kebijakan allowedMcpServers dan deniedMcpServers di sana sebagai gantinya. Pada Claude Code v2.1.259 atau lebih baru, Anda juga dapat menyediakan server jarak jauh dengan managedMcpServers, yang menerima server http dan sse saja dan tidak mengambil kontrol eksklusif seperti yang dilakukan file. Claude Code membaca file managed-mcp.json yang digunakan di jalur sistemnya secara terpisah dari tingkat pengaturan terkelola, jadi file masih berlaku ketika pengaturan yang dikelola server berlaku.
• Pengaturan yang dibatasi untuk sumber kebijakan tingkat OS, seperti policyHelper dan wslInheritsWindowsSettings, tidak dihormati. Terapkan melalui MDM atau file managed-settings.json sistem sebagai gantinya. policyHelper yang digunakan dengan cara itu berjalan hanya ketika sumbernya adalah yang dipilih di bawah prioritas dalam tingkat terkelola.

​

Pengiriman pengaturan

​

Prioritas pengaturan

​

Pengecualian per key di seluruh sumber terkelola

• Key penguncian lintas sumber: sekumpulan kecil key, seperti kunci allowlist sandbox, yang tercantum di halaman pengaturan terkelola. Claude Code mematuhinya ketika sumber terkelola mana pun yang dikendalikan admin menetapkannya; tingkat registry HKCU yang dapat ditulis pengguna dikecualikan. Ketika policyHelper menyediakan pengaturan terkelola, output-nya adalah satu-satunya sumber yang dibaca oleh pemeriksaan ini, kecuali forceRemoteSettingsRefresh, yang dibaca Claude Code langsung dari sumber admin saat startup.
• Blok env: selain unit telemetri dan variabel routing yang dipasangkan dengan key kredensial, yang keduanya dibahas di bawah, blok ini digabungkan per key di seluruh sumber yang dikendalikan admin. Untuk setiap environment variable, sumber dengan prioritas tertinggi yang mendefinisikannya menang, dan sumber admin yang lebih rendah mengisi variabel yang tidak ditetapkan oleh sumber yang lebih tinggi. Dengan demikian, entri env yang dikelola endpoint berlaku setiap kali konfigurasi yang dikelola server tidak menetapkan variabel tersebut, atau selama nilai server yang di-cache untuk variabel tersebut ditahan menunggu konfirmasi server. Memerlukan Claude Code v2.1.223 atau yang lebih baru. Sebelum v2.1.223, Claude Code hanya menerapkan seluruh blok env dari sumber yang dipilih.
  • Unit telemetri: key exporter OTEL_EXPORTER_OTLP_*, toggle penangkapan konten OTEL_LOG_*, OTEL_LOGS_EXPORTER, serta variabel tracing beta ENABLE_BETA_TRACING_DETAILED dan BETA_TRACING_ENDPOINT mengikuti sumber tertinggi yang menetapkan salah satunya sebagai satu unit. Sumber yang mengirimkan key kredensial otelHeadersHelper juga mengklaim unit ini, tetapi hanya menerapkan variabel-variabel ini ketika sumber tersebut adalah sumber yang dipilih: sumber yang tidak dipilih tetapi mengirimkan key tersebut tidak menyumbangkan satu pun variabel ini dan tetap mencegah sumber yang lebih rendah mengisinya. Bagaimanapun, endpoint exporter dari satu sumber tidak pernah dapat dipasangkan dengan kredensial dari sumber lain.
  • Routing yang dipasangkan dengan kredensial: sumber yang memasangkan variabel routing dengan key kredensial yang hanya berlaku untuk sumber terpilih, seperti apiKeyHelper atau otelHeadersHelper, menyumbangkan variabel routing tersebut hanya ketika sumber itu memenangkan slot.
• allowedProviders: daftar yang ditetapkan di mesin dan daftar yang dikelola server digabungkan sebagaimana dinyatakan dalam catatan Cakupan pada entrinya. Memerlukan Claude Code v2.1.285 atau yang lebih baru
• Key masuk first-party: forceLoginOrgUUID serta nilai "claudeai" dan "console" dari forceLoginMethod. Jika Anda juga men-deploy kebijakan MDM atau file pengaturan terkelola, tetapkan key tersebut di sana dan di pengaturan yang dikelola server dari claude.ai hingga setiap klien menjalankan v2.1.299 atau yang lebih baru. Untuk mengetahui tempat menetapkan key tersebut setelahnya, dan nilai dari sumber mana yang berlaku, lihat Sumber terkelola mana yang menyediakan key login.
• Key masuk gateway: Claude Code tidak pernah membaca forceLoginGatewayUrl, gatewayInternalNetworks, atau nilai "gateway" dari forceLoginMethod dari pengaturan yang dikelola server, sehingga nilai di sana tidak berlaku maupun menyembunyikan nilai yang ditetapkan dalam kebijakan MDM atau file pengaturan terkelola. Entri managedSourcesBehavior menjelaskan sumber admin mana di mesin yang menyediakannya.

​

Perilaku pengambilan dan caching

• Ketika pengembang masuk saat startup, misalnya pada eksekusi pertama atau setelah /logout, Claude Code menunggu hingga lima detik untuk pengambilan sebelum membuka sesi. Ketika kebijakan tiba tepat waktu, Claude Code menerapkannya sejak layar pertama dan menampilkan companyAnnouncements Anda di sana. Ketika payload memerlukan persetujuan keamanan, Claude Code mengakhiri penantian dan menerapkan payload setelah pengembang menyetujuinya
• Pada startup lainnya, dan ketika penantian lima detik tersebut habis, Claude Code membuka sesi sementara pengambilan berlanjut, sehingga ada jeda singkat sebelum pengaturan dimuat dan pembatasan berlaku
• Jika pengambilan gagal, Claude Code melanjutkan tanpa pengaturan yang dikelola server dan memperingatkan dalam sesi interaktif bahwa tidak ada kebijakan jarak jauh yang berlaku; pengaturan yang dikelola endpoint tetap berlaku. Jika sumber terkelola menetapkan forceRemoteSettingsRefresh, Claude Code akan keluar

• Pengaturan yang di-cache langsung berlaku saat startup, kecuali nilai modelPricing dan managedMcpServers yang di-cache; environment variable yang ditahan Claude Code hingga server mengonfirmasi payload; penghapusan, perubahan posisi, atau penonaktifan penjaga bawaan oleh daftar plugin yang di-cache; dan, pada mesin tempat sumber yang dikelola endpoint mencantumkan atau mengaktifkan plugin-nya sendiri, status organisasi dari plugin yang hanya diaktifkan oleh daftar yang di-cache
• modelPricing yang di-cache tidak berlaku hingga pengambilan sesi mengonfirmasi payload. Sampai saat itu, angka biaya yang dilihat pengembang di /usage dan baris status menggunakan harga daftar
• Blok managedMcpServers yang di-cache tidak berlaku hingga pengambilan sesi mengonfirmasi payload. Claude Code menunggu hingga 30 detik untuk pengambilan tersebut sebelum menghubungkan server MCP. Jika pengambilan gagal atau mengalami timeout, sesi dimulai tanpa server milik organisasi, /status menyatakan hal tersebut, dan server-server tersebut terhubung setelah pengambilan berikutnya mengonfirmasinya. Lihat Kapan server yang disediakan terhubung untuk perilaku lengkapnya, termasuk peluncuran pertama. Memerlukan Claude Code v2.1.259 atau yang lebih baru
• Nilai prependPlugins, appendPlugins, atau enabledPlugins yang di-cache tidak dapat menghapus penjaga bawaan, mengubah posisinya, atau mematikannya hingga pengambilan sesi mengonfirmasi payload
• Pada mesin tempat sumber yang dikelola endpoint mencantumkan atau mengaktifkan plugin-nya sendiri, plugin yang hanya diaktifkan oleh daftar yang di-cache dianggap sebagai milik pengguna, bukan milik organisasi Anda, hingga pengambilan mengonfirmasi payload
• Claude Code mengambil pengaturan terbaru di latar belakang
• Pengaturan yang di-cache tetap bertahan saat terjadi kegagalan jaringan. Jika pengambilan saat startup gagal, Claude Code memperingatkan dalam sesi interaktif bahwa kebijakan yang di-cache sedang berlaku
• Hingga pengambilan berhasil, nilai yang ditahan saat startup tetap ditahan

• Konfigurasi proxy dan TLS, seperti HTTPS_PROXY, NODE_EXTRA_CA_CERTS, serta variabel sertifikat klien mTLS CLAUDE_CODE_CLIENT_CERT dan CLAUDE_CODE_CLIENT_KEY
• Routing API dan pemilihan penyedia, termasuk ANTHROPIC_BASE_URL, variabel pemilihan penyedia seperti CLAUDE_CODE_USE_BEDROCK dan CLAUDE_CODE_USE_VERTEX, serta URL endpoint penyedia seperti ANTHROPIC_BEDROCK_BASE_URL
• Kredensial autentikasi, seperti ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, dan CLAUDE_CODE_OAUTH_TOKEN
• Pemilih direktori konfigurasi CLAUDE_CONFIG_DIR
• Pemilih sumber kredensial dan direktori konfigurasi, di Claude Code v2.1.223 atau yang lebih baru: variabel Workload Identity Federation seperti ANTHROPIC_FEDERATION_RULE_ID dan ANTHROPIC_IDENTITY_TOKEN, pemilih profil dan direktori konfigurasi ANTHROPIC_PROFILE dan ANTHROPIC_CONFIG_DIR, serta variabel direktori sistem operasi HOME, XDG_CONFIG_HOME, APPDATA, dan USERPROFILE

​

Entri tidak valid dalam pengaturan yang dikirim

• Startup yang berjalan menggunakan cache di ~/.claude/remote-settings.json memperlakukan entri tidak valid dengan cara yang sama seperti pengambilan yang menulis cache tersebut:
  • Entri yang gagal validasi tetap dibuang.
  • Key yang fail closed mempertahankan nilai yang lebih ketat.
  • Nilai cleanupPeriodDays atau desktopSessionCleanupPeriodDays yang tidak valid tetap berada dalam salinan yang di-cache dan tidak pernah diterapkan.
• Claude Code tidak menerapkan apa pun dari payload dan membiarkan cache tidak berubah ketika ketiga kondisi berikut terpenuhi:
  • Setiap pengaturan dalam payload gagal validasi.
  • Tidak satu pun di antaranya beralih ke nilai yang lebih ketat.
  • Payload berisi key selain kedua key retensi tersebut.
  Pemberitahuan startup, /status, dan claude doctor kemudian melaporkan kegagalan pemuatan dengan penyebab no setting in the server response could be applied as written, dan entri tersebut menjelaskan kebijakan mana yang digunakan sesi. Klien yang menerapkan startup fail-closed akan keluar saat startup.
• Dialog persetujuan keamanan mengevaluasi payload yang telah diselamatkan, sehingga entri tidak valid yang dihapus tidak pernah ditampilkan untuk persetujuan dan tidak pernah dieksekusi.

​

Menerapkan startup fail-closed

• Jika gateway menjawab peluncuran interaktif yang diawasi dengan 401 dan pengaturan ini nonaktif, gateway telah mengakhiri proses masuk tersebut. Claude Code mencetak Cloud gateway session expired — run /login to reconnect. dan membuka sesi dalam keadaan keluar dari gateway hingga pengguna menjalankan /login.
• Ketika pengambilan gagal dengan cara lain, atau pada jenis peluncuran lainnya kecuali subperintah claude auth, klien keluar dengan kesalahan.

{
  "forceRemoteSettingsRefresh": true
}

​

Dialog persetujuan keamanan

• Pengaturan perintah shell: pengaturan yang mengeksekusi perintah shell, seperti apiKeyHelper, statusLine, dan otelHeadersHelper
• Pengaturan biner sandbox: sandbox.bwrapPath, sandbox.socatPath, dan sandbox.ripgrep. Masing-masing pengaturan ini menunjuk ke sebuah executable, dan Claude Code menjalankan executable tersebut
• Pengaturan jaringan dan isolasi sandbox: pengaturan sandbox yang memungkinkan proxy sandbox membaca, mengalihkan, atau mengautentikasi lalu lintas, atau yang melemahkan isolasi sandbox: sandbox.network.tlsTerminate, sandbox.network.httpProxyPort, sandbox.network.socksProxyPort, sandbox.credentials, sandbox.allowAppleEvents, sandbox.allowNestedUserNamespaces, sandbox.enableWeakerNestedSandbox, sandbox.enableWeakerNetworkIsolation, sandbox.filesystem.disabled, sandbox.network.allowAllUnixSockets, sandbox.network.allowUnixSockets, dan sandbox.network.allowMachLookup. Blok sandbox.credentials yang hanya berisi aturan deny tidak memerlukan persetujuan, karena blok tersebut membatasi sandbox tanpa memberikan kredensial kepada proxy. Sebelum v2.1.251, Claude Code menerapkan pengaturan ini tanpa persetujuan
• Environment variable kustom: variabel env yang dikirim dan memerlukan persetujuan pengguna, seperti variabel proxy dan base-URL; lihat Environment variable dan dialog persetujuan
• Konfigurasi hook: definisi hook apa pun

​

Memori persetujuan

• Login claude.ai yang disimpan oleh /login atau claude auth login, atau proses masuk Console tanpa kunci: satu persetujuan per organisasi, dipegang oleh akun yang terakhir menyetujuinya.
• Proses masuk Claude apps gateway: satu persetujuan per gateway. Jika Anda keluar lalu masuk kembali ke gateway yang sama, Claude Code tidak menampilkan dialog lagi selama pengaturan yang memerlukan persetujuan tidak berubah. Claude Code menampilkannya lagi ketika pengaturan tersebut berubah, ketika Anda masuk ke gateway yang berbeda, dan ketika Anda menerima sertifikat baru untuk gateway yang sama. Claude Code tidak menyimpan persetujuan untuk gateway pengembangan loopback yang dijangkau melalui HTTP biasa, sehingga dialog muncul lagi setelah setiap proses masuk.
• Kredensial lainnya, seperti kunci API atau CLAUDE_CODE_OAUTH_TOKEN: satu persetujuan untuk pengaturan yang dikirim, disimpan bersama salinan pengaturan yang di-cache di direktori konfigurasi tersebut. Claude Code menampilkan dialog lagi ketika pengaturan yang memerlukan persetujuan berubah, dan setelah Anda menjalankan /logout atau claude auth logout, yang masing-masing menghapus salinan yang di-cache.

• Jika Anda keluar lalu masuk kembali, atau beralih ke organisasi lain lalu kembali, Claude Code tidak menampilkan dialog lagi selama pengaturan tersebut tidak berubah, kecuali akun lain menyetujuinya untuk organisasi tersebut di direktori konfigurasi yang sama di antara waktu tersebut.
• Jika Anda masuk ke organisasi yang sama dengan akun yang berbeda, Claude Code menampilkan dialog lagi meskipun pengaturannya tidak berubah. Persetujuan akun tersebut menggantikan persetujuan sebelumnya, sehingga ketika Anda beralih kembali, Claude Code menampilkan dialog sekali lagi.

• Sesi interaktif yang tidak dapat menampilkan dialog: Claude Code tidak menerapkan pengaturan yang dikirim dan mempertahankan pengaturan yang terakhir disetujui. Dialog muncul di sesi berikutnya yang dapat menampilkannya.
• claude install atau claude update: Claude Code tidak menampilkan dialog selama kedua perintah tersebut. Perintah berjalan dengan pengaturan yang terakhir disetujui, dan dialog muncul di sesi interaktif Anda berikutnya. Jika Claude Code menunggu pengambilan pengaturan saat startup, seperti ketika forceRemoteSettingsRefresh ditetapkan atau pada deployment Claude apps gateway, Claude Code menampilkan dialog selama perintah tersebut, dan instalasi yang dijalankan dari pipe akan gagal; lihat Raw mode is not supported selama instalasi. Sebelum v2.1.246, Claude Code juga mencoba menampilkan dialog selama perintah-perintah ini.
• Perintah claude plugin yang mencetak ke terminal tetapi tidak dapat membaca dari keyboard: ketika Claude Code tidak menunggu pengambilan pengaturan saat startup, perintah tersebut tidak menerapkan pengaturan yang dikirim. Tanpa pengaturan yang di-cache, perintah yang mengubah plugin atau marketplace Anda berhenti dengan kesalahan. Dengan pengaturan yang di-cache, perintah berjalan dengan pengaturan yang terakhir disetujui. Dialog muncul saat Anda berikutnya menjalankan claude di terminal. Perintah tersebut tidak dapat membaca dari keyboard ketika Anda melakukan pipe atau mengalihkan input-nya dan, di macOS dan Linux, perintah tersebut juga tidak dapat membuka /dev/tty. Jika Anda juga melakukan pipe atau mengalihkan output-nya, eksekusi tersebut menjadi non-interaktif, dan pengaturan yang dikirim hanya berlaku untuk eksekusi tersebut.
• Kesalahan menutup dialog sebelum Anda menjawab: Claude Code tidak menerapkan pengaturan yang dikirim dan mempertahankan pengaturan yang terakhir disetujui. Claude Code menampilkan dialog lagi di sesi berikutnya yang dapat menampilkannya.
• Eksekusi non-interaktif, seperti claude -p, sesi Agent SDK, atau sesi di panel chat ekstensi VS Code atau tab Code aplikasi desktop: Claude Code tidak dapat menampilkan dialog. Ketika pengaturan yang dikirim memerlukan persetujuan, pengaturan tersebut hanya berlaku untuk eksekusi tersebut. Claude Code tidak mencatat pengaturan tersebut sebagai disetujui atau menuliskannya ke cache lokal, dan sesi interaktif berikutnya menampilkan dialog. Hingga pengguna menyetujui dalam sesi interaktif, setiap eksekusi non-interaktif mengambil pengaturan lagi saat startup.

​

Environment variable dan dialog persetujuan

• Toggle fitur dan perintah
• Pengaturan pemilihan dan perilaku model, seperti ANTHROPIC_MODEL, DISABLE_PROMPT_CACHING, dan CLAUDE_CODE_EFFORT_LEVEL
• Pengaturan context window dan compaction, seperti DISABLE_AUTO_COMPACT, tetapi tidak termasuk CLAUDE_CODE_DISABLE_1M_CONTEXT
• Opsi UI terminal dan aksesibilitas
• Batas numerik, anggaran, dan timeout

• Variabel proxy atau base-URL
• OTEL_EXPORTER_OTLP_ENDPOINT
• CLAUDE_CODE_DISABLE_1M_CONTEXT

​

Ketersediaan platform

• Login OAuth Team atau Enterprise
• Token OAuth yang disediakan melalui CLAUDE_CODE_OAUTH_TOKEN
• Kunci API yang dikonfigurasi secara langsung
• Profil user_oauth Anthropic, kecuali profil menetapkan base_url selain API Anthropic. Memerlukan Claude Code v2.1.257 atau lebih baru.

• Token OAuth: buat token dengan claude setup-token, otorisasi token tersebut untuk organisasi Team atau Enterprise Anda, dan atur sebagai CLAUDE_CODE_OAUTH_TOKEN di environment job. Hapus kredensial apa pun yang diutamakan daripada token dari environment tersebut, seperti ANTHROPIC_API_KEY.
• Pengaturan terkelola endpoint: deploy file pengaturan terkelola ke mesin yang menjalankan job.

​

Audit logging

​

Pertimbangan keamanan

​

Lihat juga

• Semua pengaturan: setiap kunci pengaturan
• Pengaturan yang dikelola endpoint: pengaturan terkelola yang digunakan ke perangkat oleh IT
• Authentication: atur akses pengguna ke Claude Code
• Security: perlindungan keamanan dan praktik terbaik