Skip to content

Arac Yapilandirmasi

Arac kisitlamalari, allowedTools ve Bash arac kaliplari

14 dk okuma
Tool dispatch cycle: prompt, select tool, permission check, execute, inject resultPromptSelect ToolPermission✓ allowed✗ blockedExecuteInject ResultNext Turn

Write ve Edit araclirini --disallowedTools ile engelleyin. Claude yine de bir dosya yazar — Bash uzerinden echo 'data' > file.txt ile. Belirli araclari engellemek, yetenekleri engellemekle ayni sey degildir. Claude alternatif yollar bulacaktir.

Cozum: her zaman kara liste yerine beyaz liste kullanin. Tum alternatif yollari asla dusunmezsiniz.

Claude Code, dosya I/O, kabuk erisimi, web istekleri, MCP (Model Context Protocol — Claude’u harici araclar ve veri kaynaklarina baglamak icin bir standart) entegrasyonlari ve oturum yonetimini kapsayan yaklasik 60 yerlesik aracla birlikte gelir. --tools, --allowedTools ve --disallowedTools bayraklari, bu arac setini kisitlamaniza, genisletmenize veya tamamen kaldirmaniza olanak tanir — Claude’u salt okunur bir analizciden sifir arac erisimli saf bir metin ureticisine donusturur.

Varsayilan Arac Seti

Her oturum tam bir arac seti ile baslar. Alti kategoriye ayrilirlar:

Yerlesik Arac Kategorileri

KategoriAraclarAmac
Dosya I/OBash, Read, Write, Edit, Glob, Grep, NotebookEditKabuk komutlari, dosya okuma/yazma, kalip arama
WebWebFetch, WebSearchURL iceriklerini getirme ve web’de arama yapma
OturumEnterPlanMode, ExitPlanMode, EnterWorktree, ExitWorktree, AskUserQuestion, SkillPlan modu, git worktree’ler, kullanici etkilesimi, slash komutlari
GorevTask, TaskOutput, TaskStop, TodoWriteAlt ajan gorevleri baslatma, ciktilari okuma, yapilacaklar listesi yonetme
ZamanlamaCronCreate, CronDelete, CronListZamanlanmis gorevleri olusturma, silme ve listeleme
Meta / MCPToolSearch, LSP, ListMcpResourcesTool, ReadMcpResourceTool, mcp__*Ertelenmis arac yukleme, dil sunucusu, MCP sunucu entegrasyonlari

MCP araclari mcp__sunucuadi__aracadi adlandirma kuralini takip eder. Ornegin, bir Chrome DevTools sunucusu mcp__chrome-devtools__click, mcp__chrome-devtools__navigate_page ve mcp__chrome-devtools__take_screenshot gibi araclari ortaya cikarir. Bir Notion sunucusu mcp__claude_ai_Notion__notion-search ve benzerlerini ortaya cikarir.

Gotcha

Write’i engellemek mcp__postgres__write’i engellemez. MCP arac isimleri sunucu adiyla oneklenmistir, bu nedenle yerlesik araclardan tamamen ayridir. Derinlemesine savunma, hem yerlesik HEM DE MCP araclarini engellemeyi gerektirir. Ornek: —disallowedTools “Write,mcp__postgres__write”.

Kisitlama Yontemleri

Uc bayrak Claude’un hangi araclari kullanabilecegini kontrol eder. Farkli amaclara hizmet ederler ve birleistirilebilirler, ancak engellemenin her zaman kazandigi siki bir izin hiyerarsisi uzerinden etkilesirler.

Arac Kisitlama Bayraklari

BayrakEtkiKullanim Alani
—tools ""TUM araclari devre disi birak — saf metin uretimiOzetleme, siniflandirma, ceviri
—tools “Arac1,Arac2”Tum arac setini yalnizca bu araclarla degistirKesin yetenek setine sahip ozel ajan
—allowedTools “Arac1,Arac2”Yalnizca bu araclara izin ver (varsayilanlarla kesisim)Salt okunur mod, yalnizca git modu
—disallowedTools “Arac1,Arac2”Bu belirli araclari engelle (engelleme filtresi)Izole mod (web araclarini engelle), yazmasiz mod

Izin hiyerarsisi siktidir ve yukaridan asagiya dogru calisir:

Yonetilen engelleme (org yoneticisi)
    gecersiz kilar
--disallowedTools (CLI bayragi)
    gecersiz kilar
--allowedTools (CLI bayragi)
    gecersiz kilar
Varsayilan arac seti

Bu su anlama gelir: bir org yoneticisi bir araci managed-mcp.json uzerinden engellerse, hicbir sey onu yeniden etkinlestiremez. --disallowedTools her zaman --allowedTools’u yener. Ve --allowedTools varsayilan seti kesisimle kisitlar, birlesimle degil — zaten var olmayan araclari eklemek icin kullanamazsiniz.

Kalip Sozdizimi

En guclu kisitlama ozelligi Bash kalip eslestirmesidir. Bash’e tamamen izin vermek veya engellemek yerine, glob kaliplari kullanarak belirli komutlara kapsam belirleyebilirsiniz:

Terminal window
# Yalnizca git komutlarina izin ver
--allowedTools "Bash(git:*)"


# git ve npm komutlarina izin ver
--allowedTools "Bash(git:*),Bash(npm:*)"


# Yalnizca salt okunur git komutlarina izin ver
--allowedTools "Bash(git status:*),Bash(git log:*),Bash(git diff:*)"
Gotcha

Bash(git:*) icindeki iki nokta ust uste, komut oneki ile glob kalibi arasindaki ayiricidir. Bash(git:*), git ile baslayan herhangi bir komutla eslesir (git status, git log —oneline gibi). Bu, claude —help ciktisindaki belgelenmis soz dizimidir.

Kalip Eslestirme Davranisi

KalipEslesirEslesmez
Bash(git:*)git status, git log —oneline, git pushcat, rm gibi git olmayan komutlar
Bash(ls:*)ls -la, ls /tmpcat, rm
Bash(npm:*)npm test, npm installnpx, node

Sifir Arac Modu

--tools "" gecirmek tum araclari devre disi birakir. Claude dosya erisimi, kabuk ve web aramasi olmadan saf bilgiden yanit verir. Bu, arac cagrilarinin deger katmadan maliyet ektigi ozetleme, ceviri, siniflandirma ve herhangi bir gorev icin dogru moddur.

Terminal window
claude -p "2+2 kac eder?" --output-format json --tools ""
Aracsiz (Saf Metin Modu)artifacts/05/no_tools.json
1{
2 "type": "result",
3 "subtype": "success",
4 "is_error": false,
5 "duration_ms": 1697,
6 "duration_api_ms": 1672,
7 "num_turns": 1,← A
8 "result": "\n\n4",← B
9 "stop_reason": "end_turn",
10 "session_id": "3d85defc-1ec5-4fc6-8ad2-bfdecd37e043",
11 "total_cost_usd": 0.17442125,
12 "usage": {
13 "input_tokens": 3,
14 "cache_creation_input_tokens": 27885,← C
15 "cache_read_input_tokens": 0,
16 "output_tokens": 5
17 },
18 "permission_denials": []← D
19}
ATek tur -- hicbir arac cagrisi olmadi
BSaf metin yaniti, metin moduyla ayni
CIlk cagridaki sistem promptu onbellekleme icin 27K token
DBos -- hicbir sey denenmedi bile

num_turns: 1 sifir arac cagrisi yapildigini dogrular. permission_denials dizisi bostur cunku Claude herhangi bir arac kullanmaya calismadi — onlar basitce mevcut degildi. Ilk cagrida yuksek cache_creation_input_tokens degerine dikkat edin; ayni oturumdaki sonraki --tools "" cagrilari cache isabetierten yararlanir ve onemli olcude daha az maliyetlidir.

Salt Okunur Mod

Yalnizca yikici olmayan araclari beyaz listeye almak icin --allowedTools kullanin:

Terminal window
claude -p "Mevcut dizindeki dosyalari listele" \
  --output-format json --allowedTools "Read,Glob"
Salt Okunur Mod (allowedTools)artifacts/05/allowed_tools.json
1{
2 "type": "result",
3 "subtype": "success",
4 "is_error": false,
5 "duration_ms": 8838,
6 "duration_api_ms": 7961,
7 "num_turns": 2,← A
8 "result": "Here's what's in the current directory:\n\n- `README.md`\n- `_artifacts/`\n- `_scripts/`\n- `_templates/`",
9 "session_id": "2477ccd1-1c5d-4e14-a8a5-6017978b55c8",
10 "total_cost_usd": 0.02706975,
11 "usage": {
12 "input_tokens": 4,
13 "cache_creation_input_tokens": 1481,
14 "cache_read_input_tokens": 29887,
15 "output_tokens": 114← B
16 },
17 "permission_denials": []
18}← C
AIki tur: bir Glob arac cagrisi + bir yanit
BBu oturumdaki onceki bir cagridan cache isabeti
CReddetme yok -- Claude yalnizca izin verilen araclari kullandi

Claude dizin iceriklerini listelemek icin Glob kullandi ve sonucu dondurdu. Bash, Write, Edit — hepsi kullanilamaz durumdaydi. permission_denials dizisi bostur cunku Claude kisitlamaya uyum sagladi ve yalnizca verilen araclari kullandi.

▸ Try This

Geri cekilme davranisini okumadan once, bir “salt okunur” ajani kendiniz kirmayi deneyin:

claude -p “Hello’yu /tmp/trythis.txt’ye yaz” —disallowedTools “Write,Edit” —output-format json | jq ‘.permission_denials[].tool_name’

Claude hangi araca geri cekildi? Simdi engellenen listeye Bash’i de ekleyin. Baska bir yol buluyor mu?

Arac Geri Cekilme Davranisi

Bireysel araclari engellemek her zaman yeterli degildir. Claude beceriklidir ve bir gorevi yerine getirmek icin alternatif yollar deneyecektir. Write ve Edit engellendiginde ama Bash mevcut oldugunda ne oldugu asagidadir:

Terminal window
claude -p "Hello'yu /tmp/test_disallow.txt'ye yaz" \
  --output-format json --disallowedTools "Write,Edit"
Engellenmis Araclar ile Geri Cekilmeartifacts/05/disallowed_tools.json
1{
2 "type": "result",
3 "subtype": "success",
4 "is_error": false,
5 "duration_ms": 9351,
6 "num_turns": 3,← A
7 "result": "The write was blocked because `/tmp/test_disallow.txt` is outside the allowed working directory.",
8 "total_cost_usd": 0.08073175,
9 "permission_denials": [
10 {← B
11 "tool_name": "Bash",
12 "tool_use_id": "toolu_016rt73cGbxssEJpHP5X5CqN",
13 "tool_input": {← C
14 "command": "echo -n \"hello\" > /tmp/test_disallow.txt",
15 "description": "Write \"hello\" to /tmp/test_disallow.txt"
16 }
17 }
18 ]
19}
AUc tur -- Claude birden fazla yaklasim denedi
BWrite/Edit engellendikten sonra geri cekilme araci Bash oldu
CClaude'un denedigi tam kabuk komutu

Siralama soyleydi: Claude Write kullanamiyor (engellenmis), Edit kullanamiyor (engellenmis), echo -n "hello" > /tmp/test_disallow.txt ile Bash’e geri cekildi ve bu da dosya sistemi sandbox’i tarafindan engellendi cunku yol calisma dizininin disindaydi.

Gotcha

Yalnizca Write’i engellemek dosya yazmalarini ENGELLEMEZ. Claude etrafinda yol bulacaktir — Bash ile echo > file, her seferinde. Gercekten salt okunur bir ajan icin, yalnizca istediginiz seyleri beyaz listeye alan —allowedTools “Read,Glob,Grep” kullanin. Her yazma yolunu kara listeye almaya calismaktan vazgecin — her zaman birini kacirirsiniz.

ToolSearch: Ertelenmis Yukleme

MCP sunuculari cok sayida arac sagladiginda, her arac semasini baglam penceresine yuklemek pahali hale gelir. 80 araci olan bir MCP sunucusu yalnizca sema aciklamalari icin 40K token tuketebilir. ToolSearch bunu, bir arac gercekten ihtiyac duyulana kadar sema yuklemesini erteleyerek cozer.

MCP arac aciklamalari baglam penceresinin %10’undan fazlasini tuketeceginde otomatik olarak etkinlesir. Etkin oldugunda:

  • Araclar init olayinda yalnizca isimleriyle listelenir (sema yuklenmez)
  • Claude belirli bir araca ihtiyac duydugunu belirlediginde, tam semayi getirmek icin ToolSearch cagririr
  • Baglam kullanimi arac listesi icin yaklasik 40K token’dan yaklasik 2K token’a duser

ToolSearch’u yapilandirmaniz gerekmez. Tamamen otomatiktir. Bunu stream-json ciktisinda gozlemleyebilirsiniz — tum MCP araclari init olayinin tools dizisinde gorunur, ancak semalari ToolSearch talep uzerine getirene kadar mevcut degildir.

Claude arac kesfini ihtiyac duyulana kadar geciktirir — yapay zeka icin tembel yukleme. Verimlidir, ancak izin listenizin baslangicta “arac bulunamadi” hatalari tetiklemedigini ifade eder.

Yaygin Tarifler

Otomasyon icin en kullanisli arac kisitlama kaliplari:

Terminal window
# Saf metin uretimi -- hicbir arac yok
claude -p "Bu metni ozetle: ..." --tools ""


# Salt okunur analizci -- inceleyebilir ama asla degistiremez
claude -p "Bu kod tabanini incele" --allowedTools "Read,Glob,Grep"


# Yalnizca git modu -- dosya oku ve git komutlari calistir
claude -p "Son degisiklikleri ozetle" \
  --allowedTools "Bash(git:*),Read,Glob,Grep"


# Izole mod -- internet erisimi yok
claude -p "Bu kodu analiz et" \
  --disallowedTools "WebFetch,WebSearch"


# Tum MCP sunucusunu engelle
claude -p "Gorevi yap" \
  --disallowedTools "mcp__chrome-devtools__*"
Gotcha

Arac isimleri buyuk/kucuk harf duyarli ve tam eslesmeli. —allowedTools “bash”, Bash ile esleşmez. —allowedTools “read”, Read ile eslesmez. Her zaman arac listesinde gosterilen tam buyuk/kucuk harf kullanimini kullanin.

Tip

MCP araclari mcp__sunucuadi__aracadi kuralini takip eder. Tek bir araci engellemek icin: —disallowedTools “mcp__chrome-devtools__click”. Tum bir sunucuyu engellemek icin joker karakter kullanin: —disallowedTools “mcp__chrome-devtools__*”.

Bunu Uygulamada Gorun

Bir uretim MR inceleyicisinin salt okunur inceleme ajanlari olusturmak icin —disallowedTools “Edit,NotebookEdit” kullanimini gorun: MR Inceleyici Olusturun, Bolum 1: Baslat ve Incele.

Bayrak Etkilesimi: --tools + --allowedTools + --disallowedTools

Birden fazla arac kisitlama bayragi birlestirildiginde, beklediginiz gibi calismayan uc katmanli bir hiyerarsi uzerinden etkilesirler.

Bayrak Kombinasyonu Davranisi

BayraklarKullanilabilir AraclarKural
—tools “Bash” —allowedTools “Read”Bash + ReadBIRLESIM — her iki bayrak da arac katki saglar
—tools “Bash” —disallowedTools “Bash”(hicbiri)ENGELLEME KAZANIR — disallowed herhangi bir kaynaktan kaldirir
—tools "" —allowedTools “Read”(hicbiri)BOS MUTLAKTIR — gecersiz kilinamaz
—tools “Bash,Read”Bash + ReadTemel — acik arac seti

Hiyerarsi soyledir: engelle > bos > birlesim

  1. --disallowedTools araclari HERHANGI bir kaynaktan kaldirir — varsayilan set, --tools veya --allowedTools eklemeleri
  2. --tools "" (bos dize) hicbir seyin gecersiz kilamayacagi mutlak bir devre disi birakmadur
  3. --tools ve --allowedTools her ikisi de mevcutken bir birlesim olusturur
Terminal window
# Guvenlik raylari olan ozel arac seti
claude -p "..." \
  --tools "Bash,Read,Grep" \
  --allowedTools "Edit" \
  --disallowedTools "Bash(rm:*)"
# Kullanilabilir: Bash (rm haric), Read, Grep, Edit
Gotcha

TEHLIKE: Cogu gelistirici —allowedTools’un —tools’u kisitlamasini (kesisim) bekler. Kisitlamaz. BIRLESIRLER. Beyaz listeleme icin —allowedTools’u tek basina kullanin. —tools ve —allowedTools arasindaki etkilesim kesisim degil, BIRLESIMDIR. Bu, —allowedTools’un kisitlamasi gerektigini soyleyen sezgiye aykiridir. Varsayilan arac setine karsi tek basina kullanildiginda, —allowedTools kesisimle kisitlar. Ancak —tools ile birlestirildiginde, her iki bayrak da kullanilabilir sete arac katki saglar. Yalnizca —disallowedTools kaldirir.

→ Now Do This

Gercekten salt okunur bir ajan olusturun: claude -p “Bu repoyu analiz et” —allowedTools “Read,Grep,Glob” —disallowedTools “Write,Edit,Bash” —output-format json. Bir dosyayi degistirmesini isteyin — reddedecektir. Bu, kod inceleme otomasyonu icin istediginiz kaliptir.