Gyorsösszefoglaló: A Claude Code hookok olyan automatizálási szkriptek, amelyek az AI kódolási munkamenetek bizonyos életciklus-pontjain futnak le, lehetővé téve a fejlesztők számára egyéni parancsok futtatását, műveletek érvényesítését, kód formázását, értesítések küldését és projekt szabályok betartatásá. Ezek a hookok integrálódnak a Claude munkafolyamatába olyan eseményeken keresztül, mint a SessionStart, PreToolUse és PostToolUse, támogatva a parancs-, HTTP- és prompt-alapú végrehajtási mintákat konfigurálható időtúllépésekkel és kilépési kód viselkedéssel.
A Claude Code hook rendszere átalakítja az AI kódolási asszisztenst egy hasznos eszköztől egy teljesen automatizált fejlesztői környezetté. A legtöbb fejlesztő nem ismeri fel a hookokon keresztül elérhető vezérlés mértékét.
A helyzet viszont az, hogy a hookok nem csak fájl módosítások után futtatnak szkripteket. Interceptálási pontokat biztosítanak a Claude teljes döntéshozatali folyamata során. Mielőtt egy parancsot végrehajtana. Miután egy eszközhívás sikertelen volt. Amikor engedélyre van szüksége. Még a felhasználói promptok feldolgozása előtt is.
Ez az útmutató mindent lefed, amit a hivatalos dokumentáció tartalmaz, plusz gyakorlati mintákat, amelyeket a közösségi megbeszélések kimutatnak, hogy valóban működnek éles környezetekben.
Mit csinálnak valójában a Claude Code hookok
A hivatalos Claude Code dokumentáció szerint a hookok felhasználó által definiált shell parancsok, HTTP végpontok vagy prompt injekciók, amelyek a Claude Code életciklusának meghatározott pontjain futnak le. Strukturált JSON bemenetet kapnak stdin keresztül, és kilépési kódok vagy HTTP válaszok révén vezérlik a munkafolyamatot.
Az automatizálás mélyebb, mint amit a legtöbb útmutató sugall. A hookok teljesen blokkolhatják az eszközök végrehajtását, extra kontextust injektálhatnak a Claude érvelésébe, külső szolgáltatásokat indíthatnak el, és olyan érvényesítési szabályokat kényszeríthetnek ki, amelyeket a Claude-nak tiszteletben kell tartania.
Három alapvető hook típus létezik:
- Parancshookok: Shell szkriptek, amelyek stdout, stderr és kilépési kódokon keresztül kommunikálnak
- HTTP hookok: Távoli végpontok, amelyek POST kéréseket fogadnak és JSON válaszokat adnak
- Prompt hookok: Dinamikus utasítások, amelyeket a Claude kontextusába injektálnak meghatározott eseményekkor
Minden típus különböző automatizálási mintákat szolgál. A parancshookok helyi érvényesítést és formázást kezelnek. A HTTP hookok integrálódnak külső szolgáltatásokkal és adatbázisokkal. A prompt hookok a Claude viselkedését módosítják külső folyamatok nélkül.
Hook életciklus és eseményrendszer
A hivatalos dokumentáció több hook eseményt definiál (SessionStart, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, Notification és mások), amelyek a Claude Code végrehajtási folyamata során aktiválódnak. Az, hogy mikor melyik aktiválódik, meghatározza, hogy milyen automatizálás válik lehetővé.
| Esemény | Mikor fut le | Blokkolható |
|---|---|---|
| SessionStart | Amikor egy munkamenet elindul vagy folytatódik | Nem |
| UserPromptSubmit | Amikor beküldesz egy promptot, mielőtt a Claude feldolgozná | Igen |
| PreToolUse | Mielőtt egy eszközhívás végrehajtódna | Igen |
| PermissionRequest | Amikor egy engedélykérés párbeszédablak jelenik meg | Igen |
| PostToolUse | Miután egy eszközhívás sikeres volt | Nem |
| PostToolUseFailure | Miután egy eszközhívás sikertelen volt | Nem |
| Notification | Amikor a Claude Code értesítést küld | Nem |
| SubmitMessage | Amikor a Claude üzenetet küld a felhasználónak | Nem |
| ContextCompaction | Amikor a kontextusablak eléri a limiteket | Nem |
A blokkolási képesség a legfontosabb. A PreToolUse hookok megakadályozhatnak veszélyes műveleteket a végrehajtásuk előtt. Az 1-es kilépési kód blokkolja a műveletet. A 0-s kilépési kód lehetővé teszi azt. A 2-es kilépési kód arra kéri a Claude-t, hogy gondolja át újra.
De várj. A PostToolUse hookok nem tudják visszavonni a műveleteket, mivel az eszköz már végrehajtódott. Ez a korlátozás alakítja ki, hogyan kell felépíteni az érvényesítési logikát. A kritikus ellenőrzések a PreToolUse-ba tartoznak. A tisztítás és a formázás a PostToolUse-ba.
AI Eszköz Perk-ek böngészése a Claude Code beállítása közben
Ha Claude Code hookokkal dolgozol, akkor valószínűleg más AI eszközöket is választasz a munkafolyamatod köré. A Get AI Perks startup krediteket és szoftverkedvezményeket gyűjt össze AI és cloud eszközökhöz egy helyen. A platform több mint 200 ajánlatot tartalmaz, mindegyikhez perk feltételekkel és igénylési útmutatóval.
Claude vagy más AI Eszköz Perk-eket keres?
Nézd meg a Get AI Perks-t, hogy:
- böngészhesd a Claude és más AI eszköz ajánlatokat
- összehasonlíthasd a perk feltételeket igénylés előtt
- startup kedvezményeket találj a teljes eszközparkodon
👉 Látogass el a Get AI Perks-re, hogy felfedezd az aktuális AI szoftver perk-eket.
Konfiguráció és fájlstruktúra
A hookokat a .claude/settings.json fájlban definiálják egy projekten belül. A konfigurációs séma támogatja az általános hookokat és az eszközspecifikus illesztőket, amelyek szűrik, hogy mikor futnak le a hookok.
Alapvető parancshook struktúra:
| { “hooks”: [ { “event”: “PostToolUse”, “command”: “prettier –write”, “args”: [“${file}”] } ] } |
A ${file} változó a eszközbemenetből származó tényleges fájlelérésre bővül. A hivatalos dokumentáció szerint a hookok támogatják ezeket a változó kibővítéseket a command és args mezőkben.
Hook helyszín hierarchia
A Claude Code több helyet ellenőriz hook definíciókhoz, egyértelmű prioritási sorrenddel:
- Projekt szintű: .claude/settings.json az aktuális munkaterületen
- Felhasználói szintű: ~/.claude/settings.json minden munkamenethez
- Plugin által biztosított: A telepített pluginokhoz csomagolt hookok
A projekt hookok felülírják a felhasználói hookokat ugyanarra az eseményre. Ez lehetővé teszi a projekt-specifikus formázási szabályokat, miközben fenntartjuk az általános értesítési kezelőket.
Illesztőminták szelektív végrehajtáshoz
Az illesztőrendszer szűri a hookokat specifikus eszközökhöz vagy feltételekhez. Illesztők nélkül a hookok minden előfordulásnál lefutnak az eseményükből.
| { “hooks”: [ { “event”: “PreToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “src/**/*.ts” }, “command”: “./scripts/validate-typescript.sh” } ] } |
A pathPattern mező glob szintaxis-t fogad el. A toolName mező a Claude beépített eszközeihez illeszkedik, mint az edit_file, execute_command, read_file és create_directory.
A közösségi megbeszélések kimutatják, hogy az illesztő kombinációk AND logikával működnek. Minden megadott illesztőnek meg kell felelnie ahhoz, hogy a hook végrehajtódjon.
Parancshookok: Shell szkript integráció
A parancshookok shell parancsokat vagy szkripteket futtatnak strukturált JSON bemenettel. Ezek a leggyakoribb hook típusok a helyi automatizáláshoz.
A hivatalos dokumentáció előírja, hogy a parancshookok JSON-t kapnak stdin keresztül a következő struktúrában:
| { “event”: “PreToolUse”, “toolName”: “edit_file”, “toolInput”: { “path”: “src/app.ts”, “content”: “…” }, “sessionId”: “abc123”, “turnId”: “turn-456” }A szkriptek elemzik ezt a bemenetet a döntéshozatalhoz. Egy Python érvényesítő hook így nézhet ki:#!/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(“Nem lehet védett fájlokat szerkeszteni”, file=sys.stderr) sys.exit(1) sys.exit(0) |
A 0-s kilépési kód lehetővé teszi a műveletet. Az 1-es kilépési kód blokkolja azt, és stderr üzenetet mutat a Claude-nak. A 2-es kilépési kód speciális viselkedést vált ki az eseménytől függően.
2-es kilépési kód viselkedése
A hivatalos hook referens dokumentáció szerint a 2-es kilépési kód esemény-specifikus jelentéssel bír (PreToolUse: blokkolja és újragondolásra készteti a Claude-t; UserPromptSubmit: kontextust biztosít blokkolás nélkül; PermissionRequest: blokkolja az engedélyt):
- PreToolUse: Blokkolja az eszközt és a stderr üzenetet kontextusként használva újragondolásra készteti a Claude-t
- UserPromptSubmit: A stderr kimenetet extra kontextusként biztosítja blokkolás nélkül
- PermissionRequest: Blokkolja az engedély megadását
Ez egy köztes megoldást teremt a kemény blokkolás és az engedélyezés között. A Claude visszajelzést kap arról, hogy miért lehet problémás a művelet, és módosíthatja a megközelítését.
Aszinkron parancshookok
Az async: true zászló a hookokat a háttérben futtatja anélkül, hogy blokkolná a Claude munkafolyamatát. Ez fontos lassú műveletek esetén, mint a telepítési értesítések vagy metrikagyűjtés.
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “execute_command” }, “command”: “./scripts/log-to-analytics.sh”, “async”: true, “timeout”: 30 } |
Amikor egy aszinkron hook aktiválódik, a Claude Code elindítja a folyamatot, és azonnal folytatja. A timeout mező határozza meg a maximális végrehajtási időt másodpercben. Ha nincs megadva, az aszinkron hookok 10 perces alapértelmezett időtúllépést használnak.
Igaz beszéd: az aszinkron hookok nem blokkolhatják a műveleteket, mivel a Claude továbbhaladása után futnak le. Naplózásra, értesítésekre és tisztításra használhatók – nem érvényesítésre.
HTTP hookok: Külső szolgáltatás integráció
A HTTP hookok JSON payloadokat küldenek távoli végpontokra, és elemzik a válaszokat a döntés vezérléséhez. Ezek lehetővé teszik az integrációt érvényesítő szolgáltatásokkal, adatbázisokkal és harmadik féltől származó eszközökkel.
Alapvető HTTP hook konfiguráció:
| { “event”: “PreToolUse”, “url”: “api.example.com/validate”, “headers”: { “Authorization”: “Bearer ${API_TOKEN}” }, “timeout”: 5 } |
A payload struktúrája megegyezik a parancshook bemenetével, de HTTP POST törzsként érkezik. A válasz határozza meg a Claude következő lépését.
HTTP válaszkezelés
A hivatalos dokumentáció szerint a HTTP hookok a válaszokat állapotkód és a válasz törzs tartalmának alapján értelmezik:
| Állapotkód | Hatás | Üzenet forrása |
|---|---|---|
| 200 | Művelet engedélyezése | Válasz törzs (opcionális) |
| 400 | Művelet blokkolása | Válasz törzse a Claude-nak megjelenítve |
| 500 | Hook hiba, művelet engedélyezése | Naplózva, de nem jelenik meg a Claude-nak |
| Egyéb | Művelet engedélyezése | A hook hiba nem blokkolja a munkafolyamatot |
A válasz törzs tartalmazhat egy message mezőt, amelyet a Claude kontextusként lát. Ez lehetővé teszi az érvényesítő szolgáltatások számára, hogy magyarázatot adjanak arra, miért lett blokkolva egy művelet.
Környezeti változó interpoláció
A HTTP hookok támogatják a ${VAR} szintaxist az url, headers és egyéb string mezőkben. A változók a környezetből bővülnek, ahol a Claude Code fut.
A hivatalos MCP dokumentáció szerint a környezeti változó kibontás tartalmaz egy alapértelmezett tartalék szintaxist: ${VAR:-default} kibővül VAR-ra, ha be van állítva, különben az alapértelmezett értéket használja.
Biztonsági korlátozás: A GitHub #28044 számú issue szerint a HTTP hookok csak az allowedEnvVars konfigurációs mezőben explicit módon felsorolt környezeti változókat érhetnek el. Ez megakadályozza a véletlen hitelesítő adatok kiszivárgását.
Prompt hookok: Kontextus injekció
A prompt hookok dinamikus utasításokat injektálnak a Claude kontextusába meghatározott eseményekkor. Módosítják a viselkedést külső folyamatok vagy API hívások nélkül.
| { “event”: “SessionStart”, “prompt”: “TypeScript projekten dolgozol. Mindig használd a szigorú null-ellenőrzéseket, és a promise-ok helyett részesítsd előnyben az async/await használatát.” } |
Az injektált szöveg a Claude rendszerutasításainak részévé válik az adott munkamenethez. A prompt hookok sablonváltozókat is használhatnak, amelyek az eseményadatok alapján bővülnek.
Dinamikus prompt generálás
A hivatalos dokumentáció szerint a prompt hookok támogatják a command mezőket, amelyek dinamikus promptokat generálnak:
| { “event”: “ContextCompaction”, “type”: “prompt”, “command”: “./scripts/generate-context-summary.sh” } |
A parancs a szabványos JSON bemenetet kapja stdin keresztül, és a prompt szövegét stdout-ra adja ki. Ez lehetővé teszi a kontextus-alapú utasításgenerálást a projekt állapotától függően.
Ügynök-alapú hookok
Az ügynök hookok egy al-ügynököt határoznak meg, amely ahelyett, hogy közvetlen prompt injekciót végezne, kezeli az eseményt. Az al-ügynök kontextust kap az eseményről, és több lépéses érvelést végezhet.
| { “event”: “PostToolUseFailure”, “agent”: “debugger”, “agentPrompt”: “Egy eszközhívás meghiúsult. Elemezd a hibát, és javasolj javításokat.” } |
A megnevezett al-ügynököt a projektkonfigurációban kell definiálni. Az ügynök hookok komplex döntési logikát tesznek lehetővé, amit az egyszerű prompt injekció nem tud biztosítani.
Gyakorlati hook minták
A közösségi megbeszélések és a hivatalos példák olyan specifikus automatizálási mintákat tárnak fel, amelyek megbízhatóan működnek éles környezetben.
Kód automatikus formázása szerkesztések után
A leggyakoribb minta automatikusan formázza a kódot, miután a Claude szerkesztette a fájlokat:
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “**/*.{js,ts,jsx,tsx}” }, “command”: “prettier”, “args”: [“–write”, “${toolInput.path}”] } |
A ${toolInput.path} változó a szerkesztett fájl elérésére bővül. A PostToolUse biztosítja, hogy a formázás sikeres szerkesztések után történjen, de nem blokkolja a Claude munkafolyamatát.
Védett fájlmódosítások blokkolása
A PreToolUse hookok érvényesítik a fájlvédelmi szabályokat:
| { “event”: “PreToolUse”, “matcher”: { “toolName”: “edit_file” }, “command”: “./scripts/check-protected.sh” } |
A szkript ellenőrzi a célútvonalat a védett minták ellen, és 1-es kilépési kóddal blokkolja a tiltott szerkesztéseket.
Értesítést kapni, amikor a Claude-nak bemenetre van szüksége
A hivatalos munkafolyamat útmutató szerint a Notification hookok asztali figyelmeztetéseket indíthatnak vagy üzeneteket küldhetnek külső szolgáltatásoknak:
| { “event”: “Notification”, “command”: “osascript”, “args”: [“-e”, “display notification \”${message}\” with title \”Claude Code\””] } |
Ez minden alkalommal aktiválódik, amikor a Claude Code értesítést küld, beleértve az olyan eseteket is, amikor felhasználói bemenetre vár, vagy feladat befejezése után.
Kontextus újra injektálása tömörítés után
A ContextCompaction hookok visszaállítják a fontos kontextust, amikor a beszélgetési ablak megtelik:
| { “event”: “ContextCompaction”, “type”: “prompt”, “command”: “cat .claude/critical-context.md” } |
A parancs kimenete visszakerül a Claude kontextusába a tömörítés után, amely eltávolítja a régebbi üzeneteket. Ez megakadályozza a kritikus projekt-specifikus utasítások elvesztését.
Konfigurációs változások auditálása
Kövesd nyomon, mikor módosítja a Claude a konfigurációs fájlokat:
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “**/{package.json,.env,*.config.*}” }, “command”: “git”, “args”: [“add”, “${toolInput.path}”], “async”: true } |
Az aszinkron végrehajtás megakadályozza a Claude blokkolását, miközben a git műveletek befejeződnek. Ez audit trail-t hoz létre a konfigurációs változásokról kézi színpadra állítás nélkül.
JSON kimenet és döntésvezérlés
A parancshookok strukturált JSON-t adhatnak ki, hogy részletes visszajelzést nyújtsanak az egyszerű kilépési kódokon túl. A hivatalos referenciák szerint a JSON kimenet lehetővé teszi a többmezős válaszokat, amelyeket a Claude döntéshozatalhoz értelmez.
| { “allowed”: false, “message”: “Ez a fájl csapatirányelv által védett”, “suggestion”: “Hozz létre egy új fájlt a src/features/ mappában helyette” } |
Az allowed mező szabályozza, hogy a művelet folytatódik-e. Az üzenet kontextusként jelenik meg a Claude számára. A suggestion mező alternatív megközelítéseket kínál.
Ahhoz, hogy a hookok JSON-t adjanak ki, a következőket kell tenniük:
- Érvényes JSON-t írni stdout-ra
- Kilépni 0-s (engedélyezett) vagy 1-es (blokkolt) kóddal
- Legalább az allowed boolean mezőt tartalmazni
A Claude Code elemzi a JSON-t, és felhasználja a visszacsatolási hurkok javítására. A kilépési kódok továbbra is meghatározzák a fő döntést, de a JSON gazdagabb kontextust biztosít.
Hook bemeneti mezők referenciája
Minden hook JSON objektumot kap stdin keresztül, amely tartalmazza a közös mezőket és az esemény-specifikus adatokat. A teljes séma megértése kifinomultabb hook logikát tesz lehetővé.
Közös bemeneti mezők
Minden hook megkapja ezeket az alap mezőket:
- event: A hook esemény neve (pl. "PreToolUse")
- sessionId: Az aktuális Claude munkamenet egyedi azonosítója
- turnId: Az aktuális beszélgetési forduló azonosítója
- timestamp: ISO 8601 időbélyegző, amikor az esemény lefutott
Eszköz esemény mezők
A PreToolUse, PostToolUse és PostToolUseFailure események tartalmazzák:
- toolName: A meghívott eszköz neve (edit_file, execute_command, stb.)
- toolInput: Az eszköz bemeneti paramétereit tartalmazó objektum
- toolResponse: Az eszköz kimeneti adatai (csak PostToolUse esetén)
- error: Hiba részletei, beleértve az üzenetet és a kódot (csak PostToolUseFailure esetén)
A toolInput struktúra eszközenként változik. Az edit_file esetében tartalmazza a path és content mezőket. Az execute_command esetében a command és args mezőket.
Engedély esemény mezők
A PermissionRequest események tartalmazzák:
- permissionType: Az engedély kérésének típusa (file_write, command_execute, stb.)
- requestedAction: Az engedélyt kérő specifikus művelet
- resourcePath: A fájlelérés vagy erőforrás azonosító, amely érintett
MCP Eszköz Hookok
A hivatalos hook referens dokumentáció szerint a hookok illeszkedhetnek a Model Context Protocol (MCP) eszközökhöz az mcpTool illesztő mező használatával. Ez lehetővé teszi a hook végrehajtást, amikor a Claude MCP szerverek által biztosított külső eszközöket használ.
| { “event”: “PreToolUse”, “matcher”: { “mcpTool”: “database/query” }, “command”: “./scripts/validate-sql.sh” } |
Az mcpTool értéke a szervernév/eszköznév formátumú eszköznévhez illeszkedik. Ez lehetővé teszi az érvényesítési logikát adatbázis lekérdezésekhez, API hívásokhoz vagy más külső műveletekhez.
A GitHub funkciókérések növekvő érdeklődést mutatnak a mélyebb MCP integráció iránt, beleértve azokat a hookokat, amelyek képesek vizsgálni az MCP szerver értesítéseket és reagálni külső eseményekre.
Biztonsági megfontolások
A hookok ugyanazokkal a jogosultságokkal futnak, mint maga a Claude Code. Ez biztonsági következményekkel jár több felhasználós környezetekben és megosztott konfigurációkban.
Parancsvégrehajtási homokozó
A GitHub #28044 számú issue szerint az HTTP hookok egy homokozó proxy-n keresztül futnak, amely korlátozza a hálózati hozzáférést és szűri a környezeti változókat. A parancshookoknak nincs ilyen korlátozása – teljes shell hozzáféréssel futnak.
A dokumentáció ezeket a gyakorlatokat javasolja:
- Soha ne tárolj hitelesítő adatokat hook parancsokban
- Használj környezeti változókat érzékeny adatokhoz
- Érvényesíts minden bemenetet a ${…} kibontásokból
- Implementálj időtúllépési limiteket külső szolgáltatásokhoz
- Használj aszinkron hookokat nem kritikus műveletekhez, hogy elkerüld a hibák miatti blokkolást
Hook végrehajtás elkülönítése
A felhasználói szintű hookok a ~/.claude/settings.json fájlban minden projektre érvényesek. Ez kockázatot jelent, amikor különböző bizalmi határokon dolgozol. A projekt szintű hookok felülírják a felhasználói hookokat, de nem tudják teljesen kikapcsolni őket.
A Claude Code /hooks menüje megjeleníti az összes aktív hookot az aktuális munkamenethez. Ennek a listának a megtekintése érzékeny projekteken való munka előtt segít azonosítani a potenciális biztonsági aggályokat.
Hibakeresés és problémamegoldás
A hook hibák nem mindig jelennek meg egyértelműen a Claude beszélgetésében. A hivatalos dokumentáció több hibakeresési megközelítést kínál.
Hook végrehajtási naplók
A Claude Code a hook végrehajtását a munkamenet hibakeresési kimenetébe naplózza. A hibaelhárítási útmutató szerint a hibakeresési naplózás engedélyezése feltárja:
- Mely hookok illeszkedtek minden eseményhez
- A JSON bemenet, amelyet minden hooknak küldtek
- A hook folyamatok stdout és stderr kimenete
- Kilépési kódok és végrehajtási idő
- HTTP válasz kódok és törzsek HTTP hookok esetén
A hibakeresési naplózás engedélyezéséhez állítsd be a CLAUDE_DEBUG=1 környezeti változót, mielőtt elindítanád a Claude Code-ot.
Hookok független tesztelése
A parancshookokat a Claude Code-on kívül is lehet tesztelni JSON bemenet manuális összeállításával:
| echo ‘{“event”:”PreToolUse”,”toolName”:”edit_file”,”toolInput”:{“path”:”test.txt”}}’ | ./scripts/my-hook.sh |
Ez ellenőrzi a hook logikát a tényleges Claude műveletek triggerelése nélkül. A kilépési kódnak és az stdout/stderr kimenetnek meg kell egyeznie a várt viselkedéssel.
Gyakori hook hibák
A közösségi megbeszélések az alábbi gyakori problémákat azonosítják:
- Időtúllépési hibák: Az alapértelmezett 10 perces időtúllépés túl rövid lassú műveletekhez – növeld a timeout mezővel
- Elérés kibontási hibák: Olyan változók, mint a ${file}, nem definiáltak olyan eseményekhez, amelyek nem tartalmaznak fájlkontextust
- Engedélyhibák: A hook szkriptekből hiányzik a végrehajtási engedély – futtasd a chmod +x script.sh parancsot
- JSON elemzési hibák: Hibás JSON kimenet a hookoktól – ellenőrizd jq-val visszatérés előtt
- Környezeti változó nem elérhetősége: A változók nem terjesztődnek át a hook folyamatra – ellenőrizd a Claude Code környezetét
Hook teljesítményre gyakorolt hatása
A szinkron hookok blokkolják a Claude munkafolyamatát a befejezésig. Az alapértelmezett 10 perces időtúllépés megakadályozza a végtelen akadozást, de még a rövid késések is felhalmozódnak több művelet során.
A szakemberek szerint az egyszerű érvényesítő hookok elhanyagolható teljesítményhatással bírnak. A fájlformázó hookok észrevehető, de elfogadható teljesítményhatással járnak. Külső API hívások munkafolyamat-súrlódást okozhatnak. A nagy számítási műveletek profitálnak az aszinkron végrehajtásból.
Hook kötegelés
Több hook is illeszkedhet ugyanarra az eseményre. A referens dokumentáció szerint a hookok egymás után futnak a definíciós sorrendben. Ha bármelyik hook blokkolja a műveletet, a fennmaradó hookok nem futnak le.
Ez számít a teljesítmény szempontjából. Öt szinkron hook, mindegyik 200 ms-os futási idővel, másodpercenként eseményenként egy másodpercet ad hozzá. A kapcsolódó érvényesítések kombinálása egyetlen hookba csökkenti a túlzott terhelést.
Haladó minták
Az alapvető automatizáláson túl a hookok kifinomult munkafolyamat testreszabást tesznek lehetővé.
Állapotot tartó hook láncok
A hookok fájlokon vagy adatbázisokon keresztül állapotot tarthatnak fenn az exekúciók között. Egy PostToolUse hook rögzíthet sikeres műveleteket, amelyeket egy PreToolUse hook később ellenőrizhet:
| #!/bin/bash # Sikeres szerkesztések rögzítése echo “${toolInput.path}” >> .claude/edit-history.txt |
Egy kísérő PreToolUse hook ellenőrizhetné ezt a történelmet a redundáns műveletek megelőzése vagy a sorrendi korlátozások betartatása érdekében.
Feltételes hook aktiválás
Környezeti változók vezérlik a hook viselkedését futásidőben. A CLAUDE_SKIP_HOOKS=1 beállítása kikapcsolja a hookokat vészhelyzetek esetén.
Maguk a hookok is ellenőrizhetnek környezeti zászlókat:
| #!/bin/bash if [ “$STRICT_MODE” = “1” ]; then # Szigorú érvényesítés alkalmazása exit 1 fi exit 0 |
Ez lehetővé teszi a fejlesztői mód és az éles üzemmód közötti viselkedés közötti különbségtételt konfigurációs változtatások nélkül.
Több szakaszos érvényesítés
A PreToolUse hookok többszintű érvényesítést implementálhatnak, ahol a 2-es kilépési kód lehetővé teszi a Claude számára, hogy figyelmeztetésekkel folytassa:
- Súlyos hibák (kilépés 1): Veszélyes műveletek blokkolása
- Lágy figyelmeztetések (kilépés 2): Figyelmeztetés a Claude-nak, hogy gondolja át újra
- Kontextussal történő átadás (kilépés 0 + JSON): További információ biztosítása
Ez egy érvényesítési spektrumot hoz létre, amely árnyaltabb, mint a bináris engedélyezés/megtagadás.
Integráció CI/CD-vel
A hivatalos platform integrációs dokumentáció szerint a Claude Code CI/CD környezetben fut az automatizált kód felülvizsgálat és a probléma-triázs érdekében. A hookok kibővítik ezt az automatizálást.
A GitHub Actions munkafolyamatok definiálhatnak hookokat, amelyek betartatják a csapatirányelveket automatizált munkamenetek során:
| -- name: Futasd a Claude Code-ot szigorú hookokkal env: STRICT_MODE: 1 run: | claude “Tekintsd át ezt a PR-t, és javasolj fejlesztéseket” |
A STRICT_MODE zászló aktiválja a feltételes érvényesítési logikát a hook szkriptekben. Ez biztosítja, hogy az automatizált munkamenetek szigorúbb szabályokat kövessenek, mint az interaktív fejlesztés.
Audit trail generálás
A CI környezetben lévő PostToolUse hookok részletes audit naplókat hoznak létre minden Claude műveletről:
| { “event”: “PostToolUse”, “command”: “./scripts/log-to-database.sh”, “async”: true } |
A háttérben történő naplózás nem befolyásolja a teljesítményt, de teljes műveleti előzményeket biztosít a megfelelés és a hibaelhárítás érdekében.
A /hooks menü
A Claude Code biztosít egy /hooks parancsot, amely megjeleníti az összes aktív hookot az aktuális munkamenethez. A hivatalos dokumentáció szerint ez a menü mutatja:
- Hook esemény típusa
- Illesztő minták
- Parancs vagy URL végpont
- A hook fut-e aszinkron módon
- Konfigurációs forrás (projekt, felhasználó vagy plugin)
Egy hook kiválasztása megmutatja annak teljes konfigurációját, és lehetővé teszi az ideiglenes letiltását az aktuális munkamenethez.
Hookok letiltása vagy eltávolítása
A hookok letilthatók a konfiguráció eltávolítása nélkül az "enabled": false hozzáadásával a hook definícióhoz. Ez megőrzi a konfigurációt, miközben megakadályozza a végrehajtást.
Egy hook végleges eltávolításához töröld az elemét a megfelelő settings.json fájlból. A változások a következő munkamenet újraindításakor vagy a /reload futtatásakor lépnek életbe.
Hookok készségekben és ügynökökben
A hivatalos dokumentáció szerint a készség vagy al-ügynök konfigurációkon belül definiált hookok csak akkor érvényesek, amikor az a készség vagy ügynök fut. Ez lehetővé teszi a specifikus munkafolyamatokhoz tartozó specializált automatizálást.
Egy hibakereső al-ügynök tartalmazhat hookokat, amelyek naplózzák az összes eszközhívást:
| { “name”: “debugger”, “hooks”: [ { “event”: “PostToolUse”, “command”: “./scripts/log-debug.sh”, “async”: true } ] } |
Ezek a hookok csak a debugger ügynök munkamenetei során futnak le, nem a normál Claude Code működés közben.
Szkriptek hivatkozása elérési úton
A hook parancsok támogatják a relatív és abszolút elérési utakat is. A relatív elérési utak a projekt gyökeréből oldódnak meg, ahol a Claude Code fut.
A közösségi megbeszélésekből származó legjobb gyakorlatok:
- Hook szkriptek tárolása a .claude/hooks/ könyvtárban
- Használj leíró neveket: validate-typescript.sh, nem hook1.sh
- Tedd a szkripteket futtathatóvá: chmod +x .claude/hooks/*.sh
- Tartalmazzon shebang sort: #!/usr/bin/env bash vagy #!/usr/bin/env python3
- Hibakezelés hozzáadása a set -e paranccsal bash szkriptekben
Jövőbeli hook képességek
A GitHub funkciókérések tervezett és kért hook fejlesztéseket tárnak fel:
- Inline szkript hookok: Hook logika definiálása közvetlenül a settings.json fájlban külső fájlok nélkül
- MCP eszköz integráció: MCP szerver eszközök meghívása hookokból shell parancsok helyett
- Több ügynök együttműködés: Hookok, amelyek koordinálnak a különböző gépeken futó Claude példányok között
- Fejlettebb típusok: TypeScript típusdefiníciók a hook bemeneti/kimeneti sémákhoz
A GitHub #4274 számú issue szerint az integrált hook típusok (MCP eszköz, inline szkript, API hívás) iránti kérés a konfiguráció egyszerűsítését és a fejlesztői élmény javítását célozza.
Gyakran Ismételt Kérdések
Meg tudják akadályozni a hookok, hogy a Claude veszélyes parancsokat hajtson végre?
Igen. A PreToolUse hookok blokkolhatnak bármilyen eszköz végrehajtást az 1-es kilépési kóddal. Ez magában foglalja a fájlszerkesztéseket, parancsvégrehajtást és MCP eszközhívásokat. A hook megkapja a teljes eszközbemenetet, és bármilyen kritérium szerint érvényesíthet a művelet engedélyezése előtt.
Hogyan debuggolhatok egy nem működő hookot?
Engedélyezd a hibakeresési naplózást a CLAUDE_DEBUG=1 beállítással a Claude Code elindítása előtt. Ellenőrizd a munkamenet naplókat a hook végrehajtási részleteiért, beleértve azt is, hogy mely hookok illeszkedtek, a JSON bemenet, stdout/stderr kimenet és kilépési kódok. Teszteld a hookokat függetlenül azáltal, hogy mintát küldesz JSON formátumban a hook szkriptnek.
A hookok működnek minden Claude Code platformon?
A hookok működnek a CLI-ben, az asztali alkalmazásban és a VS Code bővítményben. A hivatalos dokumentáció szerint a hookok ott futnak, ahol a Claude Code fut, és hozzáféréssel rendelkezik a fájlrendszerhez. A böngésző alapú Claude és a mobilalkalmazások homokozási korlátozások miatt nem támogatják a hookokat.
Módosíthatják a hookok a Claude válaszait vagy viselkedését?
A prompt hookok utasításokat injektálnak, amelyek befolyásolják a Claude viselkedését. Az ügynök hookok az eseménykezelést specializált al-ügynökökre delegálják. A hookok azonban nem tudják közvetlenül módosítani a Claude által generált szöveget vagy az érvelési folyamatot – a kontextus biztosításával és a műveletek blokkolásával működnek.
Mi a különbség az aszinkron és a szinkron hookok között?
A szinkron hookok blokkolják a Claude munkafolyamatát a befejezésig vagy az időtúllépésig. Az aszinkron hookok a háttérben futnak anélkül, hogy blokkolnának. A szinkron hookok kilépési kódokon keresztül akadályozhatnak meg műveleteket. Az aszinkron hookok nem tudnak blokkolni, mivel a Claude továbbhalad, mielőtt a hook befejeződik. Használj aszinkront naplózásra és értesítésekre, szinkront pedig érvényesítésre.
Hogyan oszthatok meg hookokat egy csapatban?
Commit-old a .claude/settings.json fájlt a verziókövetésbe. A projekt szintű hookok minden csapattagra érvényesek, akik klónozzák a tárat. Szervezetszintű irányelvek esetén a csapatok fenntarthatnak egy megosztott felhasználói szintű beállításfájlt, amelyet a tagok átmásolnak a ~/.claude/settings.json fájlba.
Az HTTP hookok tudnak belső API-kat hívni tűzfalak mögött?
Igen, ha a Claude Code egy olyan környezetben fut, amely rendelkezik hálózati hozzáféréssel ezekhez az API-khoz. Az HTTP hookok szabványos POST kéréseket küldenek a Claude Code-ot futtató gépről. A vállalati tűzfalak és VPN-ek általában érvényesek. A dokumentációban említett homokozó proxy a környezeti változók expozícióját szabályozza, nem a hálózati útválasztást.
Növelik a hookok a Claude Code token használatát?
A prompt hookok szöveget injektálnak a Claude kontextusába, ami tokeneket fogyaszt. A parancs- és HTTP hookok nem befolyásolják közvetlenül a token használatot, de kimenetük (hibák, javaslatok) a beszélgetési kontextus részévé válik. A 2-es kilépési kód magyarázó üzenetekkel több kontextust ad hozzá, mint az 1-es kilépési kód egyszerű blokkolással.
Következtetés
A Claude Code hookok átalakítják az AI asszisztenst egy nagy teljesítményű eszköztől egy teljesen automatizált fejlesztői platformmá. Az eseményrendszer interceptálási pontokat biztosít a Claude munkafolyamata során – a munkamenet inicializálásától a kontextus tömörítéséig.
A parancshookok helyi érvényesítést és formázást kezelnek. A HTTP hookok külső szolgáltatásokat és adatbázisokat integrálnak. A prompt hookok a kontextus injekció révén módosítják a viselkedést. Együttesen lehetővé teszik az automatizálási mintákat, amelyek betartatják a csapatirányelveket, fenntartják a kódminőséget és integrálódnak a meglévő fejlesztői infrastruktúrával.
Az illesztőrendszer szűri a hookokat specifikus eszközökhöz és fájlmintákhoz. A kilépési kódok és a JSON kimenet vezérlik a döntésfolyamatot. Az aszinkron végrehajtás megakadályozza a blokkolást lassú műveletek esetén. A teljes konfigurációs séma mindent támogat az egyszerű automatikus formázástól a komplex több szakaszos érvényesítésig.
Kezdd alapvető PostToolUse hookokkal a kódformázáshoz. Adj hozzá PreToolUse érvényesítést az irányelvek megjelenésével. Kísérletezz prompt hookokkal a viselkedés módosításához. Építs HTTP integrációkat csapat-szintű érvényesítéshez.
Ellenőrizd a hivatalos Claude Code dokumentációt a teljes hook referenciáért és a frissített konfigurációs sémáért, ahogy új képességek jelennek meg.
