Kratka povzetek: Claude Code kljuke so skripti za avtomatizacijo, ki se izvajajo v določenih življenjskih ciklusih med sejami kodiranja AI, kar razvijalcem omogoča izvajanje ukazov po meri, potrjevanje dejanj, oblikovanje kode, pošiljanje obvestil in uveljavljanje pravil projekta. Te kljuke se integrirajo s potekom dela Claude prek dogodkov, kot so SessionStart, PreToolUse in PostToolUse, ter podpirajo vzorce izvajanja, ki temeljijo na ukazih, HTTP-ju in pozivih, z nastavljivimi časovnimi omejitvami in vedenjem izhodne kode.
Sistem kljuk Claude Code pretvori asistenta za kodiranje AI iz koristnega orodja v popolnoma avtomatizirano razvojno okolje. Večina razvijalcev se ne zaveda obsega nadzora, ki je na voljo prek kljuk.
Tukaj je bistvo – kljuke niso samo za izvajanje skriptov po urejanju datotek. Zagotavljajo vmesne točke v celotnem procesu odločanja Claude. Preden izvrši ukaz. Po neuspelem klicu orodja. Ko potrebuje dovoljenje. Celo pred obdelavo uporabniških pozivov.
Ta vodnik pokriva vse, kar ponuja uradna dokumentacija, poleg praktičnih vzorcev, ki jih razkrivajo razprave v skupnosti in dejansko delujejo v produkcijskih okoljih.
Kaj Claude Code kljuke dejansko počnejo
Po uradni dokumentaciji Claude Code so kljuke uporabniško določeni lupinski ukazi, končne točke HTTP ali injekcije pozivov, ki se izvajajo v določenih točkah življenjskega cikla Claude Code. Prejmejo strukturiran JSON vhod prek stdin in nadzorujejo potek dela z izhodnimi kodami ali odzivi HTTP.
Avtomatizacija gre globlje, kot predvideva večina vodnikov. Kljuke lahko v celoti blokirajo izvajanje orodij, injicirajo dodatno kontekst v razmišljanje Claude, sprožijo zunanje storitve in uveljavijo pravila validacije, ki jih mora Claude spoštovati.
Obstajajo tri glavne vrste kljuk:
- Kljuke za ukaze: Lupinski skripti, ki komunicirajo prek stdout, stderr in izhodnih kod
- HTTP kljuke: Oddaljene končne točke, ki prejemajo zahteve POST in vračajo odzive JSON
- Kljuke za pozive: Dinamična navodila, injicirana v kontekst Claude v določenih dogodkih
Vsaka vrsta služi različnim vzorcem avtomatizacije. Kljuke za ukaze obravnavajo lokalno validacijo in oblikovanje. HTTP kljuke se integrirajo z zunanjimi storitvami in bazami podatkov. Kljuke za pozive spreminjajo vedenje Claude brez zunanjih procesov.
Življenjski cikel kljuk in sistem dogodkov
Uradna dokumentacija definira več dogodkov kljuk (SessionStart, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, Notification in drugi), ki se sprožijo med potekom izvajanja Claude Code. Razumevanje, kdaj se vsak sproži, določa, kakšna avtomatizacija je možna.
| Dogodek | Kdaj se sproži | Lahko blokira |
|---|---|---|
| SessionStart | Ko se seja začne ali nadaljuje | Ne |
| UserPromptSubmit | Ko oddate poziv, preden ga Claude obdela | Da |
| PreToolUse | Preden se izvede klic orodja | Da |
| PermissionRequest | Ko se prikaže pogovorno okno za dovoljenje | Da |
| PostToolUse | Po uspešnem klicu orodja | Ne |
| PostToolUseFailure | Po neuspelem klicu orodja | Ne |
| Notification | Ko Claude Code pošlje obvestilo | Ne |
| SubmitMessage | Ko Claude uporabniku pošlje sporočilo | Ne |
| ContextCompaction | Ko okno s kontekstom doseže omejitve | Ne |
Zmožnost blokiranja je najbolj pomembna. Kljuke PreToolUse lahko preprečijo nevarne operacije, preden se izvedejo. Izhodna koda 1 blokira dejanje. Izhodna koda 0 omogoči. Izhodna koda 2 spodbudi Claude k ponovnemu premisleku.
Ampak počakajte. Kljuke PostToolUse ne morejo razveljaviti dejanj, saj je bilo orodje že izvedeno. Ta omejitev oblikuje, kako je strukturirana logika validacije. Ključne preveritve pripadajo PreToolUse. Čiščenje in oblikovanje pripadajo PostToolUse.
Preglejte ugodnosti orodij AI med nastavljanjem Claude Code
Če delate s kljukami Claude Code, verjetno izbirate tudi druga orodja AI okoli svojega poteka dela. Get AI Perks zbira zagonske kredite in popuste na programsko opremo za orodja AI in oblaka na enem mestu. Platforma vključuje več kot 200 ponudb, z pogoji za ugodnosti in navodili za pridobitev za vsako od njih.
Iščete ugodnosti za Claude ali druga orodja AI?
Preverite Get AI Perks za:
- pregled ponudb za Claude in druga orodja AI
- primerjavo pogojev za ugodnosti pred uporabo
- poiščite popuste za zagonska podjetja v svojem naboru orodij
👉 Obiščite Get AI Perks in si oglejte trenutne ugodnosti programske opreme AI.
Konfiguracija in struktura datotek
Kljuke so definirane v datoteki .claude/settings.json znotraj projekta. Shema konfiguracije podpira globalne kljuke in ujemalce, specifične za orodja, ki filtrirajo, kdaj se kljuke izvajajo.
Osnovna struktura kljuk za ukaze:
| { “hooks”: [ { “event”: “PostToolUse”, “command”: “prettier –write”, “args”: [“${file}”] } ] } |
Spremenljivka ${file} se razširi v dejansko pot datoteke iz vhoda orodja. Po uradni dokumentaciji kljuke podpirajo te razširitve spremenljivk v poljih command in args.
Hierarhija lokacij kljuk
Claude Code preverja več lokacij za definicije kljuk z jasnim vrstnim redom prednosti:
- Raven projekta: .claude/settings.json v trenutnem delovnem prostoru
- Raven uporabnika: ~/.claude/settings.json za vse seje
- Priloženo s vtičniki: Kljuke, priložene nameščenim vtičnikom
Projektne kljuke nadomestijo uporabniške kljuke za isti dogodek. To omogoča pravila oblikovanja, specifična za projekt, hkrati pa ohranja globalne obravnavo obvestil.
Vzorci ujemalcev za selektivno izvajanje
Sistem ujemalcev filtrira kljuke na določena orodja ali pogoje. Brez ujemalcev se kljuke sprožijo za vsak pojav njihovega dogodka.
| { “hooks”: [ { “event”: “PreToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “src/**/*.ts” }, “command”: “./scripts/validate-typescript.sh” } ] } |
Polje pathPattern sprejema sintakso glob. Polje toolName se ujema z vgrajenimi orodji Claude, kot so edit_file, execute_command, read_file in create_directory.
Razprave v skupnosti razkrivajo, da kombinacije ujemalcev delujejo z logiko IN. Vsi določeni ujemalci se morajo ujemati, da se kljuka izvede.
Kljuke za ukaze: Integracija lupinskih skriptov
Kljuke za ukaze izvajajo lupinske ukaze ali skripte s strukturiranim JSON vhodom. Predstavljajo najbolj pogosto vrsto kljuk za lokalno avtomatizacijo.
Uradna dokumentacija določa, da kljuke za ukaze prejmejo JSON prek stdin s to strukturo:
| { “event”: “PreToolUse”, “toolName”: “edit_file”, “toolInput”: { “path”: “src/app.ts”, “content”: “…” }, “sessionId”: “abc123”, “turnId”: “turn-456” }Skripti razčlenijo ta vhod, da sprejmejo odločitve. Python kljuka za validacijo bi lahko izgledala takole:#!/usr/bin/env python3 import sys import json input_data = json.load(sys.stdin) tool_input = input_data.get(‘toolInput’, {}) file_path = tool_input.get(‘path’, ”) if file_path.startswith(‘protected/’): print(“Cannot edit protected files”, file=sys.stderr) sys.exit(1) sys.exit(0) |
Izhodna koda 0 omogoči operacijo. Izhodna koda 1 jo blokira in prikaže sporočilo stderr Claude. Izhodna koda 2 sproži posebno vedenje, odvisno od dogodka.
Vedenje izhodne kode 2
Glede na uradno dokumentacijo za sklicevanje na kljuke, ima izhodna koda 2 pomen, specifičen za dogodek (PreToolUse: blokira in predlaga ponovni premislek; UserPromptSubmit: zagotavlja kontekst brez blokiranja; PermissionRequest: blokira dovoljenje):
- PreToolUse: Blokira orodje in spodbudi Claude k ponovnemu premisleku s sporočilom stderr kot kontekstom
- UserPromptSubmit: Zagotavlja izhod stderr kot dodaten kontekst brez blokiranja
- PermissionRequest: Blokira dodelitev dovoljenja
To ustvari srednjo pot med trdim blokiranjem in dovoljenjem. Claude prejme povratne informacije o tem, zakaj je dejanje lahko problematično, in lahko prilagodi svoj pristop.
Asinhrona kljuka za ukaze
Zastavica async: true izvaja kljuke v ozadju, ne da bi blokirala potek dela Claude. To je pomembno za počasne operacije, kot so obvestila o uvajanju ali zbiranje metrik.
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “execute_command” }, “command”: “./scripts/log-to-analytics.sh”, “async”: true, “timeout”: 30 } |
Ko se sproži asinhrona kljuka, Claude Code zažene postopek in nadaljuje takoj. Polje timeout določa najdaljši čas izvajanja v sekundah. Če ni določeno, asinhrona kljuka uporablja privzeti timeout 10 minut.
Realno gledano: asinhrona kljuka ne more blokirati operacij, saj se izvedejo, ko Claude nadaljuje. Delujejo za beleženje, obvestila in čiščenje – ne za validacijo.
HTTP kljuke: Integracija zunanjih storitev
HTTP kljuke pošiljajo JSON pakete na oddaljene končne točke in razčlenjujejo odzive za nadzor odločitev. Omogočajo integracijo s storitvami za validacijo, bazami podatkov in orodji tretjih oseb.
Osnovna konfiguracija HTTP kljuke:
| { “event”: “PreToolUse”, “url”: “api.example.com/validate”, “headers”: { “Authorization”: “Bearer ${API_TOKEN}” }, “timeout”: 5 } |
Struktura paketa se ujema z vhodom kljuke za ukaze, vendar prispe kot telo zahteve HTTP POST. Odziv določa naslednje dejanje Claude.
Obravnava odzivov HTTP
Glede na uradno dokumentacijo, HTTP kljuke interpretirajo odzive na podlagi statusne kode in vsebine telesa:
| Statusna koda | Učinek | Vir sporočila |
|---|---|---|
| 200 | Dovoli operacijo | Telo odziva (neobvezno) |
| 400 | Blokiraj operacijo | Telo odziva prikazano Claude |
| 500 | Napaka kljuke, dovoli operacijo | Zabeleženo, vendar ni prikazano Claude |
| Drugo | Dovoli operacijo | Napaka kljuke ne blokira poteka dela |
Telo odziva lahko vsebuje polje sporočila, ki ga Claude vidi kot kontekst. To omogoča storitvam za validacijo, da pojasnijo, zakaj je bila operacija blokirana.
Interpolacija okoljskih spremenljivk
HTTP kljuke podpirajo sintakso ${VAR} v poljih url, headers in drugih poljih z besedilom. Spremenljivke se razširijo iz okolja, kjer deluje Claude Code.
Glede na uradno dokumentacijo MCP, razširitev okoljskih spremenljivk vključuje privzeto nadomestno sintakso: ${VAR:-privzeto} se razširi v VAR, če je nastavljeno, sicer uporabi privzeto vrednost.
Varnostna omejitev: Glede na težavo na GitHub #28044, HTTP kljuke lahko dostopajo samo do okoljskih spremenljivk, ki so izrecno navedene v polju konfiguracije allowedEnvVars. To preprečuje nenamerno razkritje poverilnic.
Kljuke za pozive: Injekcija konteksta
Kljuke za pozive injicirajo dinamična navodila v kontekst Claude v določenih dogodkih. Spreminjajo vedenje brez zunanjih procesov ali klicov API.
| { “event”: “SessionStart”, “prompt”: “Delate na projektu TypeScript. Vedno uporabljajte stroge preverbe null in dajte prednost async/await pred »promises«.” } |
Injektirano besedilo postane del sistemskih navodil Claude za to sejo. Kljuke za pozive lahko uporabljajo tudi predloge spremenljivk, ki se razširijo glede na podatke dogodka.
Dinamično generiranje pozivov
Glede na uradno dokumentacijo, kljuke za pozive podpirajo polja ukazov, ki ustvarjajo dinamične pozive:
| { “event”: “ContextCompaction”, “type”: “prompt”, “command”: “./scripts/generate-context-summary.sh” } |
Ukaz prejme standardni JSON vhod prek stdin in izvede besedilo poziva na stdout. To omogoča generiranje pozivov, ki so odzivni na kontekst, na podlagi stanja projekta.
Kljuke na osnovi agentov
Kljuke agentov določajo podagenta, ki obravnava dogodek, namesto neposredne injekcije poziva. Podagent prejme kontekst o dogodku in lahko izvaja večstopenjsko sklepanje.
| { “event”: “PostToolUseFailure”, “agent”: “debugger”, “agentPrompt”: “Klic orodja je spodletel. Analizirajte napako in predlagajte popravke.” } |
Imenovani podagent mora biti definiran v konfiguraciji projekta. Kljuke agentov omogočajo kompleksno logiko odločanja, ki je preprosta injekcija poziva ne more zagotoviti.
Praktični vzorci kljuk
Razprave v skupnosti in uradni primeri razkrivajo specifične vzorce avtomatizacije, ki zanesljivo delujejo v produkciji.
Samodejno oblikovanje kode po urejanju
Najpogostejši vzorec samodejno oblikuje kodo po urejanju datotek s strani Claude:
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “**/*.{js,ts,jsx,tsx}” }, “command”: “prettier”, “args”: [“–write”, “${toolInput.path}”] } |
Spremenljivka ${toolInput.path} se razširi v pot urejene datoteke. PostToolUse zagotavlja, da se oblikovanje izvede po uspešnih urejanjih, vendar ne blokira poteka dela Claude.
Blokiraj spremembe zaščitenih datotek
Kljuke PreToolUse uveljavljajo pravila za zaščito datotek:
| { “event”: “PreToolUse”, “matcher”: { “toolName”: “edit_file” }, “command”: “./scripts/check-protected.sh” } |
Skript preveri ciljno pot glede na zaščitene vzorce in se zaključi s kodo 1, da blokira prepovedana urejanja.
Prejmite obvestilo, ko Claude potrebuje vnos
Glede na uradni vodnik po poteku dela, kljuke Notification lahko sprožijo namizna opozorila ali pošljejo sporočila zunanjim storitvam:
| { “event”: “Notification”, “command”: “osascript”, “args”: [“-e”, “display notification \”${message}\” with title \”Claude Code\””] } |
To se sproži vsakič, ko Claude Code pošlje obvestilo, vključno s čakanjem na uporabniški vnos ali po končani nalogi.
Ponovno injicirajte kontekst po kompakciji
Kljuke ContextCompaction obnovijo pomemben kontekst, ko se pogovorno okno napolni:
| { “event”: “ContextCompaction”, “type”: “prompt”, “command”: “cat .claude/critical-context.md” } |
Izhod ukaza se injicira nazaj v kontekst Claude po tem, ko kompakcija odstrani starejša sporočila. To preprečuje izgubo ključnih navodil, specifičnih za projekt.
Pregled sprememb konfiguracije
Sledite, kdaj Claude spremeni konfiguracijske datoteke:
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “**/{package.json,.env,*.config.*}” }, “command”: “git”, “args”: [“add”, “${toolInput.path}”], “async”: true } |
Asinhrona izvedba preprečuje blokiranje Claude med dokončanjem operacij git. To ustvari revizijski zapis sprememb konfiguracije brez ročnega stopnjevanja.
Izhod JSON in nadzor odločitev
Kljuke za ukaze lahko izvajajo strukturiran JSON, da zagotovijo podrobne povratne informacije poleg preprostih izhodnih kod. Glede na uradni sklic, izhod JSON omogoča odzive z več polji, ki jih Claude interpretira za odločanje.
| { “allowed”: false, “message”: “Ta datoteka je zaščitena s pravilnikom ekipe”, “suggestion”: “Ustvarite novo datoteko v src/features/ namesto tega” } |
Polje allowed nadzoruje, ali se operacija nadaljuje. Sporočilo se prikaže Claude kot kontekst. Polje suggestion zagotavlja alternativne pristope.
Da bi kljuke izvajale JSON, morajo:
- Veljaven JSON zapišite na stdout
- Zaključite s kodo 0 (za dovoljeno) ali 1 (za blokirano)
- Vključite vsaj booleansko polje allowed
Claude Code razčleni JSON in ga uporabi za izboljšanje povratne zanke. Izhodne kode še vedno določajo glavno odločitev, vendar JSON zagotavlja bogatejši kontekst.
Referenca polj za vnos kljuk
Vse kljuke prejmejo JSON objekt prek stdin s skupnimi polji in podatki, specifičnimi za dogodek. Razumevanje celotne sheme omogoča bolj sofisticirano logiko kljuk.
Skupna polja za vnos
Vsaka kljuka prejme ta osnovna polja:
- event: Ime dogodka kljuke (npr. “PreToolUse”)
- sessionId: Edinstven identifikator trenutne seje Claude
- turnId: Identifikator trenutnega kroga pogovora
- timestamp: Časovni žig ISO 8601, ko se je sprožil dogodek
Polja dogodkov orodij
Dogodki PreToolUse, PostToolUse in PostToolUseFailure vključujejo:
- toolName: Ime klicanega orodja (edit_file, execute_command itd.)
- toolInput: Objekt, ki vsebuje vhodne parametre orodja
- toolResponse: Izhodni podatki orodja (samo PostToolUse)
- error: Podrobnosti napake, vključno s sporočilom in kodo (samo PostToolUseFailure)
Struktura toolInput se razlikuje glede na orodje. Za edit_file vsebuje pot in vsebino. Za execute_command vsebuje ukaz in argumente.
Polja dogodka dovoljenja
Dogodki PermissionRequest vključujejo:
- permissionType: Vrsta zahtevanega dovoljenja (file_write, command_execute itd.)
- requestedAction: Specifično dejanje, ki zahteva dovoljenje
- resourcePath: Pot datoteke ali identifikator vira, na katerega vpliva
Kljuke orodij MCP
Glede na uradni sklic kljuk se lahko kljuke ujemajo z orodji protokola za kontekst modela (MCP) z uporabo polja ujemalca mcpTool. To omogoča izvajanje kljuk, ko Claude uporablja zunanja orodja, ki jih zagotavljajo MCP strežniki.
| { “event”: “PreToolUse”, “matcher”: { “mcpTool”: “database/query” }, “command”: “./scripts/validate-sql.sh” } |
Vrednost mcpTool se ujema z imenom orodja v obliki ime-strežnika/ime-orodja. To omogoča logiko validacije za poizvedbe v bazo podatkov, klice API ali druge zunanje operacije.
Zahteve za funkcije na GitHub kažejo na naraščajoče zanimanje za globljo integracijo MCP, vključno s kljukami, ki lahko pregledajo obvestila MCP strežnika in se odzovejo na zunanje dogodke.
Varnostne pozornosti
Kljuke se izvajajo z enakimi dovoljenji kot sam Claude Code. To ustvarja varnostne posledice za večuporabniška okolja in deljene konfiguracije.
Peskovnik za izvajanje ukazov
Glede na težavo na GitHub #28044, HTTP kljuke potekajo skozi peskovni posrednik, ki omejuje omrežni dostop in filtrira okoljske spremenljivke. Kljuke za ukaze nimajo takih omejitev – izvajajo se z polnim lupinskim dostopom.
Dokumentacija priporoča te prakse:
- Nikoli ne shranjujte poverilnic v ukaze kljuk
- Uporabite okoljske spremenljivke za občutljive podatke
- Validirajte ves vnos iz razširitev ${...}
- Uvedite omejitve časa izvajanja za zunanje storitve
- Uporabite asinhrona kljuka za nekritične operacije, da preprečite blokiranje ob napakah
Izolacija izvajanja kljuk
Kljuke na ravni uporabnika v ~/.claude/settings.json veljajo za vse projekte. To ustvarja tveganja pri delu med različnimi mejami zaupanja. Projektne kljuke nadomestijo uporabniške kljuke, vendar jih ne morejo popolnoma onemogočiti.
Meni /hooks v Claude Code prikazuje vse aktivne kljuke za trenutno sejo. Pregled tega seznama pred delom na občutljivih projektih pomaga prepoznati potencialne varnostne pomisleke.
Odstranjevanje napak in odpravljanje težav
Napake kljuk se ne vedno jasno prikažejo v pogovoru Claude. Uradna dokumentacija ponuja več pristopov za odpravljanje napak.
Logi izvajanja kljuk
Claude Code beleži izvajanje kljuk v debug izhod seje. Glede na vodnik za odpravljanje težav, omogočanje debug beleženja razkriva:
- Katere kljuke so se ujemale za vsak dogodek
- JSON vnos, poslan vsaki kljuki
- Izhod stdout in stderr iz procesov kljuk
- Izhodne kode in čas izvajanja
- HTTP kode odzivov in telesa za HTTP kljuke
Omogočite debug beleženje z nastavitvijo CLAUDE_DEBUG=1 v okolju pred zagonom Claude Code.
Neodvisno testiranje kljuk
Kljuke za ukaze je mogoče testirati izven Claude Code z ročno konstrukcijo JSON vhoda:
| echo ‘{“event”:”PreToolUse”,”toolName”:”edit_file”,”toolInput”:{“path”:”test.txt”}}’ | ./scripts/my-hook.sh |
To preverja logiko kljuk, ne da bi sprožili dejanske operacije Claude. Izhodna koda in izhod stdout/stderr bi morala ustrezati pričakovanemu vedenju.
Pogoste napake kljuk
Razprave v skupnosti identificirajo te pogoste težave:
- Napake časa izvajanja: Privzeti 10-minutni timeout prekratek za počasne operacije – povečajte s poljem timeout
- Napake razširitve poti: Spremenljivke, kot je ${file}, niso definirane za dogodke, ki ne vključujejo konteksta datoteke
- Napake dovoljenj: Skripti kljuk nimajo dovoljenj za izvajanje – zaženite chmod +x script.sh
- Napake razčlenjevanja JSON: Nepravilno oblikovan JSON izhod iz kljuk – validirajte z jq pred vrnitvijo
- Nedostopnost okoljskih spremenljivk: Spremenljivke niso posredovane procesu kljuke – preverite okolje Claude Code
Vplivi na delovanje kljuk
Sinhrona kljuka blokira potek dela Claude do dokončanja. Privzeti 10-minutni timeout preprečuje neskončne zastoje, vendar se tudi kratke zamude seštevajo pri več operacijah.
Praktiki poročajo, da imajo kljuke za preprosto validacijo zanemarljiv vpliv na delovanje. Kljuke za oblikovanje datotek povzročajo opazen, vendar sprejemljiv vpliv na delovanje. Klici zunanjih API-jev lahko povzročijo trenje v poteku dela. Močna računalska opravila imajo koristi od asinhronaga izvajanja.
Paket kljuk
Več kljuk se lahko ujema z istim dogodkom. Glede na referenčno dokumentacijo se kljuke izvajajo zaporedno v vrstnem redu definicije. Če katera koli kljuka blokira operacijo, se preostale kljuke ne izvedejo.
To je pomembno za delovanje. Pet sinhronih kljuk po 200 ms vsaka doda eno sekundo na dogodek. Združevanje povezanih validacij v eno kljuko zmanjša režijske stroške.
Napredni vzorci
Poleg osnovne avtomatizacije, kljuke omogočajo sofisticirano prilagoditev poteka dela.
Verige kljuk s stanjem
Kljuke lahko vzdržujejo stanje med izvajanjem z uporabo datotek ali baz podatkov. Kljuka PostToolUse lahko zabeleži uspešne operacije, ki jih kljuka PreToolUse kasneje validira:
| #!/bin/bash # Zabeleži uspešne urejanja echo “${toolInput.path}” >> .claude/edit-history.txt |
Spremljevalna kljuka PreToolUse lahko preveri to zgodovino, da prepreči podvojene operacije ali uveljavi omejitve vrstnega reda.
Pogojna aktivacija kljuk
Okoljske spremenljivke nadzorujejo vedenje kljuk med izvajanjem. Nastavitev CLAUDE_SKIP_HOOKS=1 onemogoči kljuke za nujne situacije.
Same kljuke lahko preverijo okoljske zastavice:
| #!/bin/bash if [ “$STRICT_MODE” = “1” ]; then # Uveljavi strogo validacijo exit 1 fi exit 0 |
To omogoča vedenje v razvojnem načinu v primerjavi s produkcijskim načinom brez sprememb konfiguracije.
Večstopenjska validacija
Kljuke PreToolUse lahko izvajajo večstopenjsko validacijo, kjer izhodna koda 2 omogoča Claudeu nadaljevanje z opozorili:
- Trde napake (izhod 1): Blokiraj nevarne operacije
- Mehka opozorila (izhod 2): Opozori Claude, naj ponovno premisli
- Uspešno s kontekstom (izhod 0 + JSON): Zagotovi dodatne informacije
To ustvari spekter validacije, ki je bolj nianciran kot binarno dovoli/zavrni.
Integracija z CI/CD
Glede na uradno dokumentacijo o integraciji platforme, Claude Code deluje v okoljih CI/CD za avtomatizirano pregledovanje kode in obravnavo napak. Kljuke razširijo to avtomatizacijo.
Delovni tokovi GitHub Actions lahko definirajo kljuke, ki uveljavljajo pravilnike ekipe med avtomatiziranimi sejami:
| – name: Run Claude Code with strict hooks env: STRICT_MODE: 1 run: | claude “Review this PR and suggest improvements” |
Zastavica STRICT_MODE aktivira pogojno logiko validacije v skriptih kljuk. To zagotavlja, da avtomatizirane seje sledijo bolj strogim pravilom kot interaktivni razvoj.
Generiranje revizijskega zapisa
Kljuke PostToolUse v okoljih CI ustvarijo podrobne revizijske loge vseh operacij Claude:
| { “event”: “PostToolUse”, “command”: “./scripts/log-to-database.sh”, “async”: true } |
Beleženje v ozadju ne vpliva na delovanje, vendar zagotavlja popolno zgodovino operacij za skladnost in odpravljanje napak.
Meni /hooks
Claude Code zagotavlja ukaz /hooks, ki prikaže vse aktivne kljuke za trenutno sejo. Glede na uradno dokumentacijo, ta meni prikazuje:
- Vrsta dogodka kljuke
- Vzorci ujemalcev
- Končni točka ukaza ali URL-ja
- Ali se kljuka izvaja asinhrono
- Vir konfiguracije (projekt, uporabnik ali vtičnik)
Izbira kljuke prikaže njeno popolno konfiguracijo in omogoča začasno onemogočanje za trenutno sejo.
Onemogoči ali odstrani kljuke
Kljuke je mogoče onemogočiti, ne da bi odstranili konfiguracijo, tako da dodate "enabled": false v definicijo kljuke. To ohrani konfiguracijo, hkrati pa preprečuje izvajanje.
Če želite kljuko trajno odstraniti, izbrišite njen vnos iz ustrezne datoteke settings.json. Spremembe začnejo veljati ob naslednjem ponovnem zagonu seje ali ob izvajanju /reload.
Kljuke v veščinah in agentih
Glede na uradno dokumentacijo, kljuke, definirane v konfiguracijah veščin ali podagentov, veljajo samo, ko se ta veščina ali agent izvede. To omogoča specializirano avtomatizacijo za specifične poteke dela.
Podagent za odpravljanje napak lahko vključi kljuke, ki beležijo vse klice orodij:
| { “name”: “debugger”, “hooks”: [ { “event”: “PostToolUse”, “command”: “./scripts/log-debug.sh”, “async”: true } ] } |
Te kljuke se sprožijo samo med sejami agenta za odpravljanje napak, ne med običajnim delovanjem Claude Code.
Sklicevanje na skripte po poti
Ukazi kljuk podpirajo tako relativne kot absolutne poti. Relativne poti se razrešijo iz korenskega direktorija projekta, kjer deluje Claude Code.
Najboljše prakse iz razprav v skupnosti:
- Shranjujte skripte kljuk v mapo .claude/hooks/
- Uporabljajte opisna imena: validate-typescript.sh, ne hook1.sh
- Omogočite izvajanje skriptov: chmod +x .claude/hooks/*.sh
- Vključite shebang vrstico: #!/usr/bin/env bash ali #!/usr/bin/env python3
- Dodajte obravnavo napak z set -e v skripte bash
Prihodnje zmogljivosti kljuk
Zahteve za funkcije na GitHub razkrivajo načrtovane in zahtevane izboljšave kljuk:
- Inline skriptne kljuke: Definirajte logiko kljuk neposredno v settings.json brez zunanjih datotek
- Integracija orodij MCP: Klicanje orodij strežnika MCP iz kljuk namesto lupinskih ukazov
- Sodelovanje več agentov: Kljuke, ki se usklajujejo med instancami Claude na različnih strojih
- Izboljšane tipizacije: TypeScript definicije tipov za sheme vhoda/izhoda kljuk
Glede na težavo na GitHub #4274, zahteva po integriranih vrstah kljuk (orodje MCP, inline skript, klic API) cilja na poenostavitev konfiguracije in izboljšanje izkušnje razvijalcev.
Pogosta vprašanja
Ali lahko kljuke preprečijo, da bi Claude izvajal nevarne ukaze?
Da. Kljuke PreToolUse lahko blokirajo izvajanje katerega koli orodja z izhodno kodo 1. To vključuje urejanje datotek, izvajanje ukazov in klice orodij MCP. Kljuka prejme celoten vnos orodja in lahko validira glede na katera koli merila, preden dovoli operacijo.
Kako odpravim napako kljuke, ki ne deluje?
Omogočite debug beleženje z CLAUDE_DEBUG=1 pred zagonom Claude Code. Preverite loge seje za podrobnosti izvajanja kljuk, vključno s tem, katere kljuke so se ujemale, poslan JSON vnos, izhod stdout/stderr in izhodne kode. Testirajte kljuke neodvisno tako, da preusmerite vzorčni JSON v skript kljuke.
Ali kljuke delujejo z vsemi platformami Claude Code?
Kljuke delujejo v CLI, namizni aplikaciji in razširitvi VS Code. Glede na uradno dokumentacijo, kljuke delujejo povsod, kjer deluje Claude Code z dostopom do datotečnega sistema. Brskalniški Claude in mobilne aplikacije ne podpirajo kljuk zaradi omejitev peskovnika.
Ali lahko kljuke spreminjajo odzive ali vedenje Claude?
Kljuke za pozive injicirajo navodila, ki vplivajo na vedenje Claude. Kljuke agentov dodelijo obravnavo dogodkov specializiranim podagentom. Vendar kljuke ne morejo neposredno spremeniti besedila ali procesa sklepanja, ki ga ustvari Claude – delujejo tako, da zagotavljajo kontekst in blokirajo operacije.
Kakšna je razlika med asinhronimi in sinhronimi kljukami?
Sinhroni kljuke blokirajo potek dela Claude do dokončanja ali časa izteka. Asinhroni kljuke delujejo v ozadju, ne da bi blokirali. Sinhroni kljuke lahko preprečijo operacije z izhodnimi kodami. Asinhroni kljuke ne morejo blokirati, saj Claude nadaljuje pred dokončanjem kljuke. Uporabite asinhrono za beleženje in obvestila, sinhrono za validacijo.
Kako lahko delim kljuke med ekipo?
Datoteko .claude/settings.json vključite v nadzor različic. Projektne kljuke veljajo za vse člane ekipe, ki klonirajo repozitorij. Za pravilnike vseh organizacij lahko ekipe vzdržujejo skupno datoteko z nastavitvami na ravni uporabnika, ki jo člani kopirajo v ~/.claude/settings.json.
Ali lahko HTTP kljuke kličejo notranje API-je za požarnimi zidovi?
Da, če Claude Code deluje v okolju z omrežnim dostopom do teh API-jev. HTTP kljuke izvajajo standardne zahteve POST iz stroja, ki izvaja Claude Code. Korporativni požarni zidovi in VPN-ji se uporabljajo normalno. Peskovni posrednik, omenjen v dokumentaciji, nadzoruje izpostavljenost okoljskih spremenljivk, ne usmerjanje omrežja.
Ali kljuke povečajo porabo žetonov Claude Code?
Kljuke za pozive injicirajo besedilo v kontekst Claude, kar porablja žetone. Kljuke za ukaze in HTTP neposredno ne vplivajo na porabo žetonov, vendar njihov izhod (sporočila o napakah, predlogi) postane del pogovornega konteksta. Izhodna koda 2 z razlagalnimi sporočili doda več konteksta kot izhodna koda 1 s preprostim blokiranjem.
Zaključek
Kljuke Claude Code pretvorijo asistenta AI iz zmogljivega orodja v popolnoma avtomatizirano razvojno platformo. Sistem dogodkov zagotavlja vmesne točke skozi potek dela Claude – od inicializacije seje do kompakcije konteksta.
Kljuke za ukaze obravnavajo lokalno validacijo in oblikovanje. HTTP kljuke integrirajo zunanje storitve in baze podatkov. Kljuke za pozive spreminjajo vedenje skozi injekcijo konteksta. Skupaj omogočajo vzorce avtomatizacije, ki uveljavljajo pravilnike ekipe, vzdržujejo kakovost kode in se integrirajo z obstoječo razvojno infrastrukturo.
Sistem ujemalcev filtrira kljuke na specifična orodja in vzorce datotek. Izhodne kode in izhod JSON nadzorujejo pretok odločitev. Asinhrono izvajanje preprečuje blokiranje počasnih operacij. Celotna shema konfiguracije podpira vse od preprostega samodejnega oblikovanja do kompleksne večstopenjske validacije.
Začnite s preprostimi kljukami PostToolUse za oblikovanje kode. Dodajte validacijo PreToolUse, ko se pojavijo pravilniki. Eksperimentirajte s kljukami za pozive za spreminjanje vedenja. Zgradite integracije HTTP za izvajanje v celotni ekipi.
Preverite uradno dokumentacijo Claude Code za popoln sklic kljuk in posodobljeno shemo konfiguracije, ko se izdajajo nove zmogljivosti.
