Pengaturan Claude Code

​

Cakupan konfigurasi

​

Cakupan yang tersedia

​

Kapan menggunakan setiap cakupan

• Kebijakan keamanan yang harus diterapkan di seluruh organisasi
• Persyaratan kepatuhan yang tidak dapat ditimpa
• Konfigurasi standar yang digunakan oleh IT/DevOps

• Preferensi pribadi yang Anda inginkan di mana-mana (tema, pengaturan editor)
• Tools dan plugins yang Anda gunakan di semua proyek
• Kunci API dan autentikasi (disimpan dengan aman)

• Pengaturan bersama tim (izin, hooks, MCP servers)
• Plugins yang harus dimiliki seluruh tim
• Standardisasi tooling di seluruh kolaborator

• Penggantian pribadi untuk proyek tertentu
• Pengaturan pengujian sebelum dibagikan dengan tim
• Pengaturan spesifik mesin yang tidak akan berfungsi untuk orang lain

​

Bagaimana cakupan berinteraksi

1. Managed (tertinggi): tidak dapat ditimpa oleh apa pun
2. Argumen baris perintah: penggantian sesi sementara
3. Local: menimpa pengaturan proyek dan pengguna
4. Project: menimpa pengaturan pengguna
5. User (terendah): berlaku ketika tidak ada yang menentukan pengaturan

​

Apa yang menggunakan cakupan

​

File pengaturan

• Pengaturan pengguna didefinisikan dalam ~/.claude/settings.json dan berlaku untuk semua proyek.
• Pengaturan proyek disimpan di direktori proyek Anda:
  • .claude/settings.json untuk pengaturan yang diperiksa ke dalam kontrol sumber dan dibagikan dengan tim Anda
  • .claude/settings.local.json untuk pengaturan yang tidak diperiksa, berguna untuk preferensi pribadi dan eksperimen. Ketika Claude Code membuat .claude/settings.local.json, Claude Code mengonfigurasi git untuk mengabaikan file tersebut. Jika Anda membuat file sendiri, tambahkan ke gitignore secara manual. Karena file ini milik Anda daripada repositori, aturan izin allow miliknya berlaku tanpa langkah kepercayaan workspace yang diperlukan oleh aturan allow .claude/settings.json. Jika repositori menyediakan file, misalnya dengan melakukan commit, kepercayaan workspace masih berlaku.
• Pengaturan Managed: Untuk organisasi yang memerlukan kontrol terpusat, Claude Code mendukung beberapa mekanisme pengiriman untuk pengaturan yang dikelola. Semua menggunakan format JSON yang sama dan tidak dapat ditimpa oleh pengaturan pengguna atau proyek:
  • Pengaturan yang dikelola server: dikirimkan dari jarak jauh saat sign-in, baik dari server Anthropic melalui konsol admin claude.ai atau dari Claude apps gateway yang di-host sendiri. Lihat pengaturan yang dikelola server.
  • Kebijakan tingkat MDM/OS: dikirimkan melalui manajemen perangkat asli di macOS dan Windows:
    • macOS: domain preferensi terkelola com.anthropic.claudecode. Kunci tingkat atas plist mencerminkan managed-settings.json, dengan pengaturan bersarang sebagai kamus dan array sebagai array plist. Terapkan melalui profil konfigurasi di Jamf, Iru (Kandji), atau alat MDM serupa.
    • Windows: kunci registry HKLM\SOFTWARE\Policies\ClaudeCode dengan nilai Settings (REG_SZ atau REG_EXPAND_SZ) berisi JSON (digunakan melalui Group Policy atau Intune)
    • Windows (tingkat pengguna): HKCU\SOFTWARE\Policies\ClaudeCode (prioritas kebijakan terendah, hanya digunakan ketika tidak ada sumber tingkat admin)
  • Berbasis file: managed-settings.json dan managed-mcp.json digunakan ke direktori sistem:
    • macOS: /Library/Application Support/ClaudeCode/
    • Linux dan WSL: /etc/claude-code/
    • Windows: C:\Program Files\ClaudeCode\
    Jalur Windows warisan C:\ProgramData\ClaudeCode\managed-settings.json tidak lagi didukung sejak v2.1.75. Administrator yang menggunakan pengaturan ke lokasi tersebut harus memigrasikan file ke C:\Program Files\ClaudeCode\managed-settings.json.
    Pengaturan yang dikelola berbasis file juga mendukung direktori drop-in di managed-settings.d/ dalam direktori sistem yang sama bersama managed-settings.json. Ini memungkinkan tim terpisah untuk menggunakan fragmen kebijakan independen tanpa mengoordinasikan pengeditan ke file tunggal. Mengikuti konvensi systemd, managed-settings.json digabungkan terlebih dahulu sebagai dasar, kemudian semua file *.json dalam direktori drop-in diurutkan secara alfabetis dan digabungkan di atas. File yang lebih baru menimpa yang lebih awal untuk nilai skalar; array digabungkan dan dihilangkan duplikatnya; objek digabungkan secara mendalam. File tersembunyi yang dimulai dengan . diabaikan. Gunakan prefiks numerik untuk mengontrol urutan penggabungan, misalnya 10-telemetry.json dan 20-security.json.
  Lihat pengaturan yang dikelola dan Konfigurasi MCP yang Dikelola untuk detail. Repositori ini mencakup template penyebaran pemula untuk Jamf, Iru (Kandji), Intune, dan Group Policy. Gunakan ini sebagai titik awal dan sesuaikan dengan kebutuhan Anda.
  Penyebaran yang dikelola juga dapat membatasi penambahan marketplace plugin menggunakan strictKnownMarketplaces. Untuk informasi lebih lanjut, lihat Pembatasan marketplace yang dikelola.
• Konfigurasi lainnya disimpan dalam ~/.claude.json. File ini berisi sesi OAuth, konfigurasi MCP server untuk cakupan pengguna dan lokal, status per-proyek (tools yang diizinkan, pengaturan kepercayaan), dan berbagai cache. MCP servers dengan cakupan proyek disimpan secara terpisah dalam .mcp.json.

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)",
      "Read(~/.zshrc)"
    ],
    "deny": [
      "Bash(curl *)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  },
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp"
  },
  "companyAnnouncements": [
    "Welcome to Acme Corp! Review our code guidelines at docs.acme.com",
    "Reminder: Code reviews required for all PRs",
    "New security policy in effect"
  ]
}

​

Saat pengeditan berlaku

• model: gunakan /model untuk beralih di tengah sesi
• outputStyle: bagian dari prompt sistem, yang dibangun kembali pada /clear atau restart

​

Entri tidak valid dalam pengaturan yang dikelola

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

​

Pengaturan yang tersedia

​

Pengaturan konfigurasi global

​

Pengaturan worktree

​

Pengaturan izin

​

Sintaks aturan izin

​

Pengaturan sandbox

​

Prefiks jalur sandbox

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["docker *"],
    "filesystem": {
      "allowWrite": ["/tmp/build", "~/.kube"],
      "denyRead": ["~/.aws/credentials"]
    },
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org", "registry.yarnpkg.com"],
      "deniedDomains": ["uploads.github.com"],
      "allowUnixSockets": [
        "/var/run/docker.sock"
      ],
      "allowLocalBinding": true
    }
  }
}

• Pengaturan sandbox.filesystem (ditampilkan di atas): Kontrol jalur pada batas sandbox tingkat OS. Pembatasan ini berlaku untuk semua perintah subprocess (misalnya, kubectl, terraform, npm), bukan hanya tools file Claude.
• Aturan izin: Gunakan aturan allow/deny Edit untuk mengontrol akses tools file Claude, aturan deny Read untuk memblokir pembacaan, dan aturan allow/deny WebFetch untuk mengontrol domain jaringan. Jalur dari aturan ini juga digabungkan ke dalam konfigurasi sandbox.

​

Pengaturan atribusi

• Komit menggunakan git trailers (seperti Co-Authored-By) secara default, yang dapat disesuaikan atau dinonaktifkan
• Deskripsi pull request adalah teks biasa

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

🤖 Generated with [Claude Code](https://claude.com/claude-code)

{
  "attribution": {
    "commit": "Generated with AI\n\nCo-Authored-By: AI <ai@example.com>",
    "pr": ""
  }
}

​

Pengaturan saran file

{
  "fileSuggestion": {
    "type": "command",
    "command": "~/.claude/file-suggestion.sh"
  }
}

{"query": "src/comp"}

src/components/Button.tsx
src/components/Modal.tsx
src/components/Form.tsx

#!/bin/bash
query=$(cat | jq -r '.query')
# Ganti your-repo-file-index dengan perintah pencarian file Anda sendiri
your-repo-file-index --query "$query" | head -20

​

Lencana tautan footer

{
  "footerLinksRegexes": [
    {
      "type": "regex",
      "pattern": "\\b(?<key>PROJ-\\d+)\\b",
      "url": "https://issues.example.com/browse/{key}",
      "label": "{key}"
    }
  ]
}

​

Konfigurasi hook

• Hooks yang dikelola dan hooks SDK dimuat
• Hooks dari plugins yang dipaksa diaktifkan dalam pengaturan yang dikelola enabledPlugins dimuat. Ini memungkinkan administrator mendistribusikan hooks yang disaring melalui marketplace organisasi sambil memblokir segalanya. Kepercayaan diberikan oleh ID plugin@marketplace penuh, jadi plugin dengan nama yang sama dari marketplace berbeda tetap diblokir
• Hooks pengguna, hooks proyek, dan semua plugin hooks lainnya diblokir

{
  "allowedHttpHookUrls": ["https://hooks.example.com/*", "http://localhost:*"]
}

{
  "httpHookAllowedEnvVars": ["MY_TOKEN", "HOOK_SECRET"]
}

​

Hitung pengaturan yang dikelola dengan policy helper

{
  "managedSettings": {
    "permissions": { "deny": ["Read(//etc/secrets/**)"] }
  },
  "claudeMd": "# Organization context\n...",
  "appendSystemPrompt": "Always cite the internal style guide."
}

​

Prioritas pengaturan

1. Pengaturan yang dikelola (yang dikelola server, kebijakan tingkat MDM/OS, atau pengaturan yang dikelola)
   • Kebijakan yang digunakan oleh IT melalui pengiriman server, profil konfigurasi MDM, kebijakan registry, atau file pengaturan yang dikelola
   • Tidak dapat ditimpa oleh tingkat apa pun, termasuk argumen baris perintah
   • Dalam tingkat yang dikelola, hanya satu sumber yang digunakan dan yang lain diabaikan daripada digabungkan. Prioritas, tertinggi terlebih dahulu:
     • Output policyHelper: ketika dikonfigurasi, ini adalah satu-satunya sumber yang dikelola yang digunakan
     • Remote (pengaturan yang dikelola server claude.ai atau kebijakan yang dikirimkan Claude apps gateway)
     • Kebijakan tingkat MDM/OS
     • Berbasis file (managed-settings.d/*.json dan managed-settings.json, digabungkan bersama)
     • Registry HKCU (Windows saja)
   • Beberapa kunci adalah pengecualian, dihormati ketika sumber yang dikelola yang dikontrol admin apa pun menetapkannya daripada hanya sumber pemenang. Sumber registry HKCU yang dapat ditulis pengguna dikecualikan. Kunci pengecualian adalah:
     • kunci sandbox lock sandbox.network.allowManagedDomainsOnly dan sandbox.filesystem.allowManagedReadPathsOnly, dengan daftar putih terkait mereka
     • allowAllClaudeAiMcps
     • jalur binary sandbox sandbox.bwrapPath dan sandbox.socatPath
     • forceRemoteSettingsRefresh
   • Host penyematan seperti Claude Desktop dapat memasok kebijakan melalui opsi SDK managedSettings. Secara default ini diabaikan ketika ada sumber yang dikelola yang digunakan admin: pengaturan yang dikelola server, kebijakan MDM atau OS-level, atau file pengaturan yang dikelola. Fallback registry HKCU yang dapat ditulis pengguna tidak dihitung sebagai sumber yang dikelola yang digunakan admin. Administrator dapat memilih dengan menetapkan parentSettingsBehavior ke "merge". Nilai embedder disaring sehingga mereka dapat mengencangkan kebijakan yang dikelola tetapi tidak melonggarkannya.
2. Argumen baris perintah
   • Penggantian sementara untuk sesi tertentu. JSON yang dilewatkan melalui --settings <file-or-json> digabungkan dengan pengaturan berbasis file menggunakan aturan yang sama seperti lapisan lainnya: kunci yang diatur di sini menimpa kunci yang sama dalam pengaturan lokal, proyek, atau pengguna, dan menghilangkan kunci membiarkan nilai lapisan lebih rendah tetap ada
3. Pengaturan proyek lokal (.claude/settings.local.json)
   • Pengaturan proyek pribadi
4. Pengaturan proyek bersama (.claude/settings.json)
   • Pengaturan proyek bersama tim dalam kontrol sumber
5. Pengaturan pengguna (~/.claude/settings.json)
   • Pengaturan global pribadi

​

Verifikasi pengaturan aktif

​

Poin kunci tentang sistem konfigurasi

• File memori (CLAUDE.md): Berisi instruksi dan konteks yang dimuat Claude saat startup
• File pengaturan (JSON): Konfigurasikan izin, variabel lingkungan, dan perilaku tool
• Skills: Prompt khusus yang dapat dipanggil dengan /skill-name atau dimuat oleh Claude secara otomatis
• MCP servers: Perluas Claude Code dengan tools dan integrasi tambahan
• Prioritas: Konfigurasi tingkat lebih tinggi (Managed) menimpa yang tingkat lebih rendah (User/Project)
• Warisan: Pengaturan digabungkan di seluruh cakupan; nilai skalar dari cakupan prioritas lebih tinggi menimpa, dan array digabungkan, dengan dua pengecualian yang dijelaskan dalam Catatan penggabungan array

​

Prompt sistem

​

Mengecualikan file sensitif

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      
      "Read(./config/credentials.json)",
      "Read(./build)"
    ]
  }
}

​

Konfigurasi subagent

• Subagents pengguna: ~/.claude/agents/, tersedia di semua proyek Anda
• Subagents proyek: .claude/agents/, spesifik untuk proyek Anda dan dapat dibagikan dengan tim Anda

​

Konfigurasi plugin

​

Pengaturan plugin

{
  "enabledPlugins": {
    "formatter@acme-tools": true,
    "deployer@acme-tools": true,
    "analyzer@security-plugins": false
  },
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": {
        "source": "github",
        "repo": "acme-corp/claude-plugins"
      }
    }
  }
}

​

enabledPlugins

• Pengaturan pengguna (~/.claude/settings.json): Preferensi plugin pribadi
• Pengaturan proyek (.claude/settings.json): Plugin spesifik proyek yang dibagikan dengan tim
• Pengaturan lokal (.claude/settings.local.json): Penggantian per-mesin, diabaikan saat Claude Code membuatnya
• Pengaturan yang dikelola (managed-settings.json): Penggantian kebijakan organisasi yang memblokir instalasi di semua cakupan dan menyembunyikan plugin dari marketplace

{
  "enabledPlugins": {
    "code-formatter@team-tools": true,
    "deployment-tools@team-tools": true,
    "experimental-features@personal": false
  }
}

​

pluginConfigs

{
  "pluginConfigs": {
    "deployer@acme-tools": {
      "options": {
        "api_endpoint": "https://api.example.com"
      }
    }
  }
}

​

extraKnownMarketplaces

1. Anggota tim diminta untuk menginstal marketplace saat mereka mempercayai folder
2. Anggota tim kemudian diminta untuk menginstal plugin dari marketplace tersebut
3. Pengguna dapat melewati marketplace atau plugin yang tidak diinginkan (disimpan dalam pengaturan pengguna)
4. Instalasi menghormati batas kepercayaan dan memerlukan persetujuan eksplisit

{
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": {
        "source": "github",
        "repo": "acme-corp/claude-plugins"
      }
    },
    "security-plugins": {
      "source": {
        "source": "git",
        "url": "https://git.example.com/security/plugins.git"
      }
    }
  }
}

• github: Repositori GitHub (menggunakan repo)
• git: URL git apa pun (menggunakan url)
• directory: Jalur sistem file lokal (menggunakan path, hanya untuk pengembangan)
• hostPattern: Pola regex untuk mencocokkan host marketplace (menggunakan hostPattern)
• settings: marketplace inline yang dideklarasikan langsung dalam settings.json tanpa repositori yang dihosting terpisah (menggunakan name dan plugins)

{
  "extraKnownMarketplaces": {
    "team-tools": {
      "source": {
        "source": "settings",
        "name": "team-tools",
        "plugins": [
          {
            "name": "code-formatter",
            "source": {
              "source": "github",
              "repo": "acme-corp/code-formatter"
            }
          }
        ]
      }
    }
  }
}

​

strictKnownMarketplaces

• macOS: /Library/Application Support/ClaudeCode/managed-settings.json
• Linux dan WSL: /etc/claude-code/managed-settings.json
• Windows: C:\Program Files\ClaudeCode\managed-settings.json

• Hanya tersedia dalam pengaturan yang dikelola (managed-settings.json)
• Tidak dapat ditimpa oleh pengaturan pengguna atau proyek (prioritas tertinggi)
• Diterapkan sebelum operasi jaringan dan sistem file, sehingga sumber yang diblokir tidak pernah dijalankan
• Menggunakan pencocokan tepat untuk spesifikasi sumber (termasuk ref, path untuk sumber git), kecuali hostPattern dan pathPattern, yang menggunakan pencocokan regex

• undefined (default): tidak ada pembatasan, sehingga pengguna dapat menambahkan marketplace apa pun
• Array kosong []: lockdown lengkap, sehingga pengguna tidak dapat menambahkan marketplace baru apa pun
• Daftar sumber: pengguna hanya dapat menambahkan marketplace yang cocok dengan tepat

1. Repositori GitHub:

{ "source": "github", "repo": "acme-corp/approved-plugins" }
{ "source": "github", "repo": "acme-corp/security-tools", "ref": "v2.0" }
{ "source": "github", "repo": "acme-corp/plugins", "ref": "main", "path": "marketplace" }

2. Repositori Git:

{ "source": "git", "url": "https://gitlab.example.com/tools/plugins.git" }
{ "source": "git", "url": "https://bitbucket.org/acme-corp/plugins.git", "ref": "production" }
{ "source": "git", "url": "ssh://git@git.example.com/plugins.git", "ref": "v3.1", "path": "approved" }

3. Marketplace berbasis URL:

{ "source": "url", "url": "https://plugins.example.com/marketplace.json" }
{ "source": "url", "url": "https://cdn.example.com/marketplace.json", "headers": { "Authorization": "Bearer ${TOKEN}" } }

4. Paket NPM:

{ "source": "npm", "package": "@acme-corp/claude-plugins" }
{ "source": "npm", "package": "@acme-corp/approved-marketplace" }

5. Jalur file:

{ "source": "file", "path": "/usr/local/share/claude/acme-marketplace.json" }
{ "source": "file", "path": "/opt/acme-corp/plugins/marketplace.json" }

6. Jalur direktori:

{ "source": "directory", "path": "/usr/local/share/claude/acme-plugins" }
{ "source": "directory", "path": "/opt/acme-corp/approved-marketplaces" }

7. Pencocokan pola host:

{ "source": "hostPattern", "hostPattern": "^github\\.example\\.com$" }
{ "source": "hostPattern", "hostPattern": "^gitlab\\.internal\\.example\\.com$" }

• github: selalu cocok dengan github.com
• git: mengekstrak nama host dari URL (mendukung format HTTPS dan SSH)
• url: mengekstrak nama host dari URL
• npm, file, directory: tidak didukung untuk pencocokan pola host

8. Pencocokan pola jalur:

{ "source": "pathPattern", "pathPattern": "^/opt/approved/" }
{ "source": "pathPattern", "pathPattern": ".*" }

{
  "strictKnownMarketplaces": [
    {
      "source": "github",
      "repo": "acme-corp/approved-plugins"
    },
    {
      "source": "github",
      "repo": "acme-corp/security-tools",
      "ref": "v2.0"
    },
    {
      "source": "url",
      "url": "https://plugins.example.com/marketplace.json"
    },
    {
      "source": "npm",
      "package": "@acme-corp/compliance-plugins"
    }
  ]
}

{
  "strictKnownMarketplaces": []
}

{
  "strictKnownMarketplaces": [
    {
      "source": "hostPattern",
      "hostPattern": "^github\\.example\\.com$"
    }
  ]
}

• repo atau url harus cocok dengan tepat
• Bidang ref harus cocok dengan tepat (atau keduanya tidak terdefinisi)
• Bidang path harus cocok dengan tepat (atau keduanya tidak terdefinisi)

// Ini adalah sumber BERBEDA:
{ "source": "github", "repo": "acme-corp/plugins" }
{ "source": "github", "repo": "acme-corp/plugins", "ref": "main" }

// Ini juga BERBEDA:
{ "source": "github", "repo": "acme-corp/plugins", "path": "marketplace" }
{ "source": "github", "repo": "acme-corp/plugins" }

{
  "strictKnownMarketplaces": [
    { "source": "github", "repo": "acme-corp/plugins" }
  ]
}

{
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": { "source": "github", "repo": "acme-corp/plugins" }
    }
  }
}

{
  "strictKnownMarketplaces": [
    { "source": "github", "repo": "acme-corp/plugins" }
  ],
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": { "source": "github", "repo": "acme-corp/plugins" }
    }
  }
}

• Pembatasan diperiksa sebelum permintaan jaringan atau operasi sistem file apa pun
• Saat diblokir, pengguna melihat pesan kesalahan yang jelas menunjukkan sumber diblokir oleh kebijakan yang dikelola
• Pembatasan diterapkan pada penambahan marketplace dan pada instalasi plugin, pembaruan, penyegaran, dan pembaruan otomatis. Marketplace yang ditambahkan sebelum kebijakan ditetapkan tidak dapat digunakan untuk menginstal atau memperbarui plugin setelah sumbernya tidak lagi cocok dengan daftar putih
• Pengaturan yang dikelola memiliki prioritas tertinggi dan tidak dapat ditimpa

​

strictPluginOnlyCustomization

{
  "strictPluginOnlyCustomization": ["skills", "hooks"]
}

​

Mengelola plugin

• Jelajahi plugin yang tersedia dari marketplace
• Instal/copot plugin
• Aktifkan/nonaktifkan plugin
• Lihat detail plugin (skills, agents, hooks yang disediakan)
• Tambah/hapus marketplace

​

Variabel lingkungan

​

Tools yang tersedia untuk Claude

​

Lihat juga

• Permissions: sistem izin, sintaks aturan, pola spesifik tool, dan kebijakan yang dikelola
• Authentication: atur akses pengguna ke Claude Code
• Debug your configuration: diagnosis mengapa pengaturan, hook, atau server MCP tidak berlaku
• Troubleshoot installation and login: instalasi, autentikasi, dan masalah platform