Documentation 2026-05-13 23:01 UTC to 2026-05-14 17:02 UTC

331 331 

332### 컨텍스트 추가 및 도구 차단332### 컨텍스트 추가 및 도구 차단

333 333 

334이 예제는 `/etc` 디렉토리에 쓰려는 모든 시도를 차단하고 두 개의 출력 필드를 함께 사용합니다. `permissionDecision: 'deny'`는 도구 호출을 중지하고, `systemMessage`는 대화에 미리 알림을 주입하여 에이전트가 작업이 차단된 이유에 대한 컨텍스트를 받고 재시도를 피합니다.334이 예제는 `/etc` 디렉토리에 쓰려는 시도를 차단하고 모델과 사용자 모두에게 이유를 설명합니다.

335 

336* `permissionDecision: 'deny'`는 도구 호출을 중지합니다.

337* `permissionDecisionReason`은 모델에 이유를 알려주므로 재시도를 피합니다.

338* `systemMessage`는 사용자에게 발생한 상황을 보여줍니다.

335 339 

336<CodeGroup>340<CodeGroup>

337 ```python Python theme={null}341 ```python Python theme={null}

340 344 

341 if file_path.startswith("/etc"):345 if file_path.startswith("/etc"):

342 return {346 return {

343 # 최상위 필드: 대화에 지침을 주입합니다347 # 최상위 필드: 사용자에게 표시되는 메시지

344 "systemMessage": "Remember: system directories like /etc are protected.",348 "systemMessage": "Remember: system directories like /etc are protected.",

345 # hookSpecificOutput: 작업을 차단합니다349 # hookSpecificOutput: 작업을 차단합니다

346 "hookSpecificOutput": {350 "hookSpecificOutput": {

360 364 

361 if (filePath?.startsWith("/etc")) {365 if (filePath?.startsWith("/etc")) {

362 return {366 return {

363 // 최상위 필드: 대화에 지침을 주입합니다367 // 최상위 필드: 사용자에게 표시되는 메시지

364 systemMessage: "Remember: system directories like /etc are protected.",368 systemMessage: "Remember: system directories like /etc are protected.",

365 // hookSpecificOutput: 작업을 차단합니다369 // hookSpecificOutput: 작업을 차단합니다

366 hookSpecificOutput: {370 hookSpecificOutput: {

807 811 

808### systemMessage가 출력에 나타나지 않음812### systemMessage가 출력에 나타나지 않음

809 813 

810`systemMessage` 필드는 모델이 보는 대화에 컨텍스트를 추가하지만 모든 SDK 출력 모드에 나타나지 않을 수 있습니다. 훅 결정을 애플리케이션에 표시해야 하면 별도로 기록하거나 전용 출력 채널을 사용합니다.814`systemMessage` 필드는 사용자에게 메시지를 표시합니다. 기본적으로 SDK는 메시지 스트림에서 훅 출력을 표시하지 않으므로 `includeHookEvents`(`Python에서는 include_hook_events`)를 설정하지 않으면 메시지가 나타나지 않을 수 있습니다. 대신 모델에 컨텍스트를 전달하려면 [`additionalContext`](/ko/hooks#add-context-for-claude)를 반환합니다.

815 

816훅 결정을 애플리케이션에 안정적으로 표시해야 하면 별도로 기록하거나 전용 출력 채널을 사용합니다.

811 817 

812## 관련 리소스818## 관련 리소스

813 819 

1860다음을 포함할 수 있는 [`HookJSONOutput`](#hookjsonoutput)을 반환합니다.1860다음을 포함할 수 있는 [`HookJSONOutput`](#hookjsonoutput)을 반환합니다.

1861 1861 

1862* `decision`: 작업을 차단하려면 `"block"`1862* `decision`: 작업을 차단하려면 `"block"`

1863* `systemMessage`: 기록에 추가할 시스템 메시지1863* `systemMessage`: 사용자에게 표시되는 경고 메시지

1864* `hookSpecificOutput`: hook 특정 출력 데이터1864* `hookSpecificOutput`: hook 특정 출력 데이터

1865 1865 

1866### `HookContext`1866### `HookContext`

2645 2645 

2646**도구 이름:** `TodoWrite`2646**도구 이름:** `TodoWrite`

2647 2647 

2648<Note>

2649 `TodoWrite`는 더 이상 사용되지 않으며 향후 릴리스에서 제거될 예정입니다. 대신 `TaskCreate`, `TaskGet`, `TaskUpdate`, `TaskList`를 사용하십시오. `CLAUDE_CODE_ENABLE_TASKS=1`을 설정하여 옵트인하십시오. 모니터링 코드 변경 방법은 [작업 도구로 마이그레이션](/ko/agent-sdk/todo-tracking#migrate-to-task-tools)을 참조하십시오.

2650</Note>

2651 

2648**입력:**2652**입력:**

2649 2653 

2650```python theme={null}2654```python theme={null}

2668}2672}

2669```2673```

2670 2674 

2675### TaskCreate

2676 

2677**도구 이름:** `TaskCreate`

2678 

2679**입력:**

2680 

2681```python theme={null}

2682{

2683 "subject": str, # 짧은 작업 제목

2684 "description": str, # 상세한 작업 본문

2685 "activeForm": str | None, # 진행 중일 때 표시되는 현재형 레이블

2686 "metadata": dict | None, # 임의의 호출자 메타데이터

2687}

2688```

2689 

2690**출력:**

2691 

2692```python theme={null}

2693{

2694 "task": {"id": str, "subject": str}, # 할당된 ID가 있는 생성된 작업

2695}

2696```

2697 

2698### TaskUpdate

2699 

2700**도구 이름:** `TaskUpdate`

2701 

2702**입력:**

2703 

2704```python theme={null}

2705{

2706 "taskId": str, # 패치할 작업의 ID

2707 "status": Literal["pending", "in_progress", "completed", "deleted"] | None,

2708 "subject": str | None,

2709 "description": str | None,

2710 "activeForm": str | None,

2711 "addBlocks": list[str] | None, # 이 작업이 이제 차단하는 작업 ID

2712 "addBlockedBy": list[str] | None, # 이제 이 작업을 차단하는 작업 ID

2713 "owner": str | None,

2714 "metadata": dict | None,

2715}

2716```

2717 

2718**출력:**

2719 

2720```python theme={null}

2721{

2722 "success": bool,

2723 "taskId": str,

2724 "updatedFields": list[str], # 변경된 필드의 이름

2725 "error": str | None,

2726 "statusChange": {"from": str, "to": str} | None,

2727}

2728```

2729 

2730### TaskGet

2731 

2732**도구 이름:** `TaskGet`

2733 

2734**입력:**

2735 

2736```python theme={null}

2737{

2738 "taskId": str, # 읽을 작업의 ID

2739}

2740```

2741 

2742**출력:**

2743 

2744```python theme={null}

2745{

2746 "task": {

2747 "id": str,

2748 "subject": str,

2749 "description": str,

2750 "status": Literal["pending", "in_progress", "completed"],

2751 "blocks": list[str],

2752 "blockedBy": list[str],

2753 } | None, # ID를 찾을 수 없을 때 None

2754}

2755```

2756 

2757### TaskList

2758 

2759**도구 이름:** `TaskList`

2760 

2761**입력:**

2762 

2763```python theme={null}

2764{}

2765```

2766 

2767**출력:**

2768 

2769```python theme={null}

2770{

2771 "tasks": [

2772 {

2773 "id": str,

2774 "subject": str,

2775 "status": Literal["pending", "in_progress", "completed"],

2776 "owner": str | None,

2777 "blockedBy": list[str],

2778 }

2779 ],

2780}

2781```

2782 

2671### BashOutput2783### BashOutput

2672 2784 

2673**도구 이름:** `BashOutput`2785**도구 이름:** `BashOutput`

389| `fallbackModel` | `string` | `undefined` | 기본 모델이 실패할 경우 사용할 모델 |389| `fallbackModel` | `string` | `undefined` | 기본 모델이 실패할 경우 사용할 모델 |

390| `forkSession` | `boolean` | `false` | `resume`으로 재개할 때 원본 세션을 계속하는 대신 새 세션 ID로 포크합니다 |390| `forkSession` | `boolean` | `false` | `resume`으로 재개할 때 원본 세션을 계속하는 대신 새 세션 ID로 포크합니다 |

391| `hooks` | `Partial<Record<`[`HookEvent`](#hookevent)`, `[`HookCallbackMatcher`](#hookcallbackmatcher)`[]>>` | `{}` | 이벤트에 대한 훅 콜백 |391| `hooks` | `Partial<Record<`[`HookEvent`](#hookevent)`, `[`HookCallbackMatcher`](#hookcallbackmatcher)`[]>>` | `{}` | 이벤트에 대한 훅 콜백 |

392| `includeHookEvents` | `boolean` | `false` | 훅 라이프사이클 이벤트를 [`SDKHookStartedMessage`](#sdkhookstartedmessage), [`SDKHookProgressMessage`](#sdkhookprogressmessage) 및 [`SDKHookResponseMessage`](#sdkhookresponsemessage)로 메시지 스트림에 포함합니다 |

392| `includePartialMessages` | `boolean` | `false` | 부분 메시지 이벤트 포함 |393| `includePartialMessages` | `boolean` | `false` | 부분 메시지 이벤트 포함 |

393| `maxBudgetUsd` | `number` | `undefined` | 클라이언트 측 비용 추정이 이 USD 값에 도달하면 쿼리를 중지합니다. `total_cost_usd`와 동일한 추정과 비교됩니다. [비용 및 사용량 추적](/ko/agent-sdk/cost-tracking) 참조 |394| `maxBudgetUsd` | `number` | `undefined` | 클라이언트 측 비용 추정이 이 USD 값에 도달하면 쿼리를 중지합니다. `total_cost_usd`와 동일한 추정과 비교됩니다. [비용 및 사용량 추적](/ko/agent-sdk/cost-tracking) 참조 |

394| `maxThinkingTokens` | `number` | `undefined` | *더 이상 사용되지 않음:* 대신 `thinking`을 사용합니다. 사고 프로세스의 최대 토큰 |395| `maxThinkingTokens` | `number` | `undefined` | *더 이상 사용되지 않음:* 대신 `thinking`을 사용합니다. 사고 프로세스의 최대 토큰 |

1596 | ReadMcpResourceInput1597 | ReadMcpResourceInput

1597 | SubscribeMcpResourceInput1598 | SubscribeMcpResourceInput

1598 | SubscribePollingInput1599 | SubscribePollingInput

1600 | TaskCreateInput

1601 | TaskGetInput

1602 | TaskListInput

1599 | TaskStopInput1603 | TaskStopInput

1604 | TaskUpdateInput

1600 | TodoWriteInput1605 | TodoWriteInput

1601 | UnsubscribeMcpResourceInput1606 | UnsubscribeMcpResourceInput

1602 | UnsubscribePollingInput1607 | UnsubscribePollingInput

1850**도구 이름:** `TaskCreate`1855**도구 이름:** `TaskCreate`

1851 1856 

1852```typescript theme={null}1857```typescript theme={null}

1853// SDK에서 아직 내보내지지 않음; 로컬로 정의합니다.

1854type TaskCreateInput = {1858type TaskCreateInput = {

1855 subject: string;1859 subject: string;

1856 description: string;1860 description: string;

1866**도구 이름:** `TaskUpdate`1870**도구 이름:** `TaskUpdate`

1867 1871 

1868```typescript theme={null}1872```typescript theme={null}

1869// SDK에서 아직 내보내지지 않음; 로컬로 정의합니다.

1870type TaskUpdateInput = {1873type TaskUpdateInput = {

1871 taskId: string;1874 taskId: string;

1872 status?: "pending" | "in_progress" | "completed" | "deleted";1875 status?: "pending" | "in_progress" | "completed" | "deleted";

1887**도구 이름:** `TaskGet`1890**도구 이름:** `TaskGet`

1888 1891 

1889```typescript theme={null}1892```typescript theme={null}

1890// SDK에서 아직 내보내지지 않음; 로컬로 정의합니다.

1891type TaskGetInput = {1893type TaskGetInput = {

1892 taskId: string;1894 taskId: string;

1893};1895};

1900**도구 이름:** `TaskList`1902**도구 이름:** `TaskList`

1901 1903 

1902```typescript theme={null}1904```typescript theme={null}

1903// SDK에서 아직 내보내지지 않음; 로컬로 정의합니다.

1904type TaskListInput = {};1905type TaskListInput = {};

1905```1906```

1906 1907 

1983 | MonitorOutput1984 | MonitorOutput

1984 | NotebookEditOutput1985 | NotebookEditOutput

1985 | ReadMcpResourceOutput1986 | ReadMcpResourceOutput

1987 | TaskCreateOutput

1988 | TaskGetOutput

1989 | TaskListOutput

1986 | TaskStopOutput1990 | TaskStopOutput

1991 | TaskUpdateOutput

1987 | TodoWriteOutput1992 | TodoWriteOutput

1988 | WebFetchOutput1993 | WebFetchOutput

1989 | WebSearchOutput;1994 | WebSearchOutput;

2347**도구 이름:** `TaskCreate`2352**도구 이름:** `TaskCreate`

2348 2353 

2349```typescript theme={null}2354```typescript theme={null}

2350// Not yet exported from the SDK; define locally.

2351type TaskCreateOutput = {2355type TaskCreateOutput = {

2352 task: {2356 task: {

2353 id: string;2357 id: string;

2363**도구 이름:** `TaskUpdate`2367**도구 이름:** `TaskUpdate`

2364 2368 

2365```typescript theme={null}2369```typescript theme={null}

2366// Not yet exported from the SDK; define locally.

2367type TaskUpdateOutput = {2370type TaskUpdateOutput = {

2368 success: boolean;2371 success: boolean;

2369 taskId: string;2372 taskId: string;

2383**도구 이름:** `TaskGet`2386**도구 이름:** `TaskGet`

2384 2387 

2385```typescript theme={null}2388```typescript theme={null}

2386// Not yet exported from the SDK; define locally.

2387type TaskGetOutput = {2389type TaskGetOutput = {

2388 task: {2390 task: {

2389 id: string;2391 id: string;

2403**도구 이름:** `TaskList`2405**도구 이름:** `TaskList`

2404 2406 

2405```typescript theme={null}2407```typescript theme={null}

2406// Not yet exported from the SDK; define locally.

2407type TaskListOutput = {2408type TaskListOutput = {

2408 tasks: Array<{2409 tasks: Array<{

2409 id: string;2410 id: string;

46 </Step>46 </Step>

47 47 

48 <Step title="세션 디스패치">48 <Step title="세션 디스패치">

49 작업을 설명하는 프롬프트를 입력하고 `Enter`를 누릅니다. 새로운 백그라운드 세션이 해당 작업에서 시작되고 작업 중인지, 입력을 기다리는지, 완료되었는지를 보여주는 행으로 나타납니다. 새로운 세션은 에이전트 뷰 헤더에 표시된 모델과 해당 디렉토리에서 `claude`를 실행할 때 얻을 수 있는 동일한 [권한 모드](#permission-mode-and-settings)를 사용합니다.49 작업을 설명하는 프롬프트를 입력하고 `Enter`를 누릅니다. 새로운 백그라운드 세션이 해당 작업에서 시작되고 작업 중인지, 입력을 기다리는지, 완료되었는지를 보여주는 행으로 나타납니다. 새로운 세션은 에이전트 뷰 헤더에 표시된 모델과 해당 디렉토리에서 `claude`를 실행할 때 얻을 수 있는 동일한 [권한 모드](#permission-mode-model-and-effort)를 사용합니다.

50 50 

51 여기에 입력하는 모든 프롬프트는 자신의 새로운 세션을 시작합니다. 다른 프롬프트를 입력하고 `Enter`를 누르면 첫 번째 세션에 후속 메시지를 보내는 대신 첫 번째 세션과 함께 두 번째 세션을 시작합니다. 이렇게 여러 세션을 병렬로 실행할 수 있습니다.51 여기에 입력하는 모든 프롬프트는 자신의 새로운 세션을 시작합니다. 다른 프롬프트를 입력하고 `Enter`를 누르면 첫 번째 세션에 후속 메시지를 보내는 대신 첫 번째 세션과 함께 두 번째 세션을 시작합니다. 이렇게 여러 세션을 병렬로 실행할 수 있습니다.

52 52 

74 74 

75목록은 시작한 모든 백그라운드 세션을 표시하며, 모든 프로젝트에 걸쳐 있습니다. 한 저장소에서 작업하는 세션과 다른 worktree에서 작업하는 세션은 모두 여기에 나타나며, 에이전트 뷰를 연 디렉토리와 관계없이 표시됩니다. 다른 터미널에서 열려 있는 대화형 세션은 [백그라운드로 보낼](#from-inside-a-session) 때까지 나타나지 않습니다. [서브에이전트](/ko/sub-agents)와 [팀원](/ko/agent-teams)은 세션이 생성하는 별도의 행으로 나열되지 않습니다.75목록은 시작한 모든 백그라운드 세션을 표시하며, 모든 프로젝트에 걸쳐 있습니다. 한 저장소에서 작업하는 세션과 다른 worktree에서 작업하는 세션은 모두 여기에 나타나며, 에이전트 뷰를 연 디렉토리와 관계없이 표시됩니다. 다른 터미널에서 열려 있는 대화형 세션은 [백그라운드로 보낼](#from-inside-a-session) 때까지 나타나지 않습니다. [서브에이전트](/ko/sub-agents)와 [팀원](/ko/agent-teams)은 세션이 생성하는 별도의 행으로 나열되지 않습니다.

76 76 

77뷰를 한 프로젝트로 범위를 지정하려면 `claude agents --cwd <path>`로 시작합니다. 해당 디렉토리 아래에서 시작된 세션만 나타나며, [worktree](/ko/worktrees)에서 실행 중인 모든 세션을 포함합니다.

78 

77```text theme={null}79```text theme={null}

78고정됨80고정됨

79 ✽ clawd walk cycle Write assets/sprites/clawd-walk.png 3m81 ✽ clawd walk cycle Write assets/sprites/clawd-walk.png 3m

221프롬프트의 일부를 접두사로 붙이거나 언급하여 세션이 시작되는 방식을 제어합니다:223프롬프트의 일부를 접두사로 붙이거나 언급하여 세션이 시작되는 방식을 제어합니다:

222 224 

223| 입력 | 효과 |225| 입력 | 효과 |

224| :------------------------ | :--------------------------------------------------------------------------------------- |226| :------------------------ | :----------------------------------------------------------------------------------------- |

225| `<agent-name> <prompt>` | 첫 번째 단어가 사용자 정의 [서브에이전트](/ko/sub-agents) 이름과 일치하면 해당 서브에이전트가 프론트매터의 구성으로 세션의 주 에이전트로 실행됨 |227| `<agent-name> <prompt>` | 첫 번째 단어가 사용자 정의 [서브에이전트](/ko/sub-agents) 이름과 일치하면 해당 서브에이전트가 프론트매터의 구성으로 세션의 주 에이전트로 실행됩니다 |

226| `@<agent-name>` | 프롬프트의 어디든지 사용자 정의 서브에이전트를 언급하여 주 에이전트로 실행 |228| `@<agent-name>` | 프롬프트의 어디든지 사용자 정의 서브에이전트를 언급하여 주 에이전트로 실행합니다 |

227| `@<repo>` | 에이전트 뷰를 연 디렉토리 아래의 저장소를 언급하여 세션을 거기서 실행 |229| `@<repo>` | 에이전트 뷰를 연 디렉토리 아래의 저장소를 언급하여 세션을 거기서 실행합니다 |

228| `/<skill>` | [스킬](/ko/skills)을 프롬프트로 디스패치하도록 제안 |230| `/<skill>` | [스킬](/ko/skills)을 프롬프트로 디스패치하도록 제안합니다 |

229| `#<number>` 또는 풀 리퀘스트 URL | 세션이 이미 해당 PR에서 작업 중이면 디스패치 대신 선택 |231| `#<number>` 또는 풀 리퀘스트 URL | 세션이 이미 해당 PR에서 작업 중이면 디스패치 대신 선택합니다 |

230| `Shift+Enter` | 디스패치하고 즉시 새 세션에 연결 |232| `Shift+Enter` | 디스패치하고 즉시 새 세션에 연결합니다 |

231 233 

232반복되는 작업을 [스킬](/ko/skills)로 패키징하면 프롬프트를 다시 입력하지 않고 에이전트 뷰에서 동일한 워크플로우를 여러 번 시작할 수 있습니다.234반복되는 작업을 [스킬](/ko/skills)로 패키징하면 프롬프트를 다시 입력하지 않고 에이전트 뷰에서 동일한 워크플로우를 여러 번 시작할 수 있습니다.

233 235 

285 287 

286### 모델 설정288### 모델 설정

287 289 

288에이전트 뷰 헤더에 표시된 모델 이름은 디스패치 기본값입니다. 입력에서 시작하는 새로운 세션은 이 모델을 사용하며, 이는 모든 세션에서 [`/model`](/ko/model-config)이 제어하는 것과 동일한 설정입니다.290에이전트 뷰 헤더에 표시된 모델 이름은 디스패치 기본값입니다. 입력에서 시작하는 새로운 세션은 이 모델을 사용하며, 이는 모든 세션에서 [`/model`](/ko/model-config)이 제어하는 것과 동일한 설정입니다. 에이전트 뷰를 열 때 `--model`을 전달하여 전체 에이전트 뷰 세션에 대해 이를 재정의합니다. [권한 모드, 모델 및 노력](#permission-mode-model-and-effort)을 참조하십시오.

289 291 

290각 백그라운드 세션은 다른 모델에서 실행될 수 있습니다. 한 세션에 대해 이를 재정의하려면:292각 백그라운드 세션은 다른 모델에서 실행될 수 있습니다. 한 세션에 대해 이를 재정의하려면:

291 293 

293* 실행 중인 세션에 연결하고 거기서 `/model`을 실행합니다. 세션이 다시 생성되면 변경 사항이 유지됩니다.295* 실행 중인 세션에 연결하고 거기서 `/model`을 실행합니다. 세션이 다시 생성되면 변경 사항이 유지됩니다.

294* 프론트매터가 `model` 필드를 설정하는 [서브에이전트](/ko/sub-agents)를 디스패치합니다.296* 프론트매터가 `model` 필드를 설정하는 [서브에이전트](/ko/sub-agents)를 디스패치합니다.

295 297 

296### 권한 모드 및 설정298### 권한 모드, 모델 및 노력

299 

300백그라운드 세션은 실행되는 디렉토리에서 [설정](/ko/settings)을 읽으며, 마치 거기서 `claude`를 시작한 것처럼 동일합니다.

301 

302[권한 모드](/ko/permissions)는 세션을 시작한 방식에 따라 달라집니다. `/bg` 또는 `←`로 기존 세션을 백그라운드로 이동하면 현재 권한 모드가 유지되므로 `acceptEdits` 또는 `auto`로 전환한 세션은 분리 후에도 해당 모드에 유지됩니다. 에이전트 뷰 입력에서 디스패치하거나 셸에서 `claude --bg`를 실행하면 해당 디렉토리의 설정에서 `defaultMode`를 사용하거나 디스패치된 [서브에이전트의 프론트매터](/ko/sub-agents#supported-frontmatter-fields)에서 `permissionMode`를 사용합니다.

303 

304에이전트 뷰를 열 때 `--permission-mode`, `--model` 또는 `--effort` 중 하나를 전달하여 에이전트 뷰에서 디스패치하는 모든 세션에 대한 기본값을 설정합니다:

305 

306```bash theme={null}

307claude agents --permission-mode plan --model opus --effort high

308```

309 

310<Note>

311 `claude agents`에 `--permission-mode`, `--model` 또는 `--effort`를 전달하려면 Claude Code v2.1.142 이상이 필요합니다. 이전 버전은 이러한 플래그를 unknown-option 오류로 거부합니다.

312</Note>

297 313 

298디스패치된 세션은 실행되는 디렉토리에서 [설정](/ko/settings) 및 [권한 모드](/ko/permissions)를 읽으며, 마치 거기서 `claude`를 시작한 것처럼 동일합니다. 에이전트 뷰 입력에서 디스패치하면 권한 모드를 전달하지 않으므로 세션은 해당 디렉토리의 설정에서 `defaultMode`를 사용하거나 디스패치된 [서브에이전트의 프론트매터](/ko/sub-agents#supported-frontmatter-fields)에서 `permissionMode`를 사용합니다.314활성 기본값은 디스패치 입력 아래의 바닥글에 나타납니다.

299 315 

300셸에서 모드를 설정하려면 `claude --bg`와 함께 `--permission-mode`를 전달합니다. 이러한 방식으로 `bypassPermissions` 또는 `auto`를 사용하는 것은 대화형으로 한 번 실행하여 해당 모드를 수락할 때까지 거부됩니다. 이러한 모드는 감시하지 않는 세션이 승인 없이 작동하도록 허용하기 때문입니다.316이러한 플래그가 없으면 세션은 해당 디렉토리의 설정에서 `defaultMode`를 사용하거나 디스패치된 [서브에이전트의 프론트매터](/ko/sub-agents#supported-frontmatter-fields)에서 `permissionMode`를 사용하며, 에이전트 뷰 헤더에 표시된 모델을 사용합니다.

317 

318`bypassPermissions` 또는 `auto`를 사용하는 것은 대화형으로 한 번 실행하여 해당 모드를 수락할 때까지 거부됩니다. 이러한 모드는 감시하지 않는 세션이 승인 없이 작동하도록 허용하기 때문입니다. 이는 `claude agents`에 모드를 전달하든 `claude --bg --permission-mode`에 전달하든 동일하게 적용됩니다.

319 

320### 설정, 플러그인 및 MCP 서버

321 

322에이전트 뷰는 설정, 플러그인, MCP 서버 및 추가 디렉토리를 로드하기 위해 `claude`와 동일한 구성 플래그를 허용합니다. 각 플래그는 에이전트 뷰 자체에 적용되며 디스패치하는 모든 세션에 전달되므로 이러한 방식으로 로드하는 플러그인 또는 MCP 서버는 해당 세션에서도 사용 가능합니다.

323 

324| 플래그 | 효과 |

325| :----------------------------------------------------------------------------------------------- | :------------------------------------------ |

326| [`--settings <file-or-json>`](/ko/settings) | 에이전트 뷰 및 디스패치된 세션에 대한 설정 재정의 |

327| [`--add-dir <path>`](/ko/permissions#additional-directories-grant-file-access-not-configuration) | 추가 디렉토리에 파일 액세스 권한 부여 |

328| [`--plugin-dir <path>`](/ko/plugins) | 로컬 디렉토리에서 플러그인 로드 |

329| [`--mcp-config <file-or-json>`](/ko/mcp) | 구성 파일 또는 JSON 문자열에서 MCP 서버 로드 |

330| `--strict-mcp-config` | `--mcp-config`에서만 MCP 서버를 사용하고 다른 MCP 구성 무시 |

331 

332`--add-dir`, `--plugin-dir` 또는 `--mcp-config`를 값당 한 번씩 반복합니다. `--add-dir a b c`와 같은 공백으로 구분된 형식은 `claude agents`에서 지원되지 않습니다.

333 

334다음 예제는 설정 재정의 및 하나의 추가 디렉토리로 에이전트 뷰를 엽니다:

335 

336```bash theme={null}

337claude agents --settings ./ci-settings.json --add-dir ../shared-lib

338```

301 339 

302## 셸에서 세션 관리340## 셸에서 세션 관리

303 341 

304모든 백그라운드 세션에는 셸에서 사용할 수 있는 짧은 ID가 있습니다. ID는 `claude --bg`로 세션을 시작할 때 출력되며, 각 세션의 ID는 `~/.claude/jobs/` 아래의 디렉터리 이름입니다. 이 명령은 스크립팅이나 에이전트 뷰를 열고 싶지 않을 때 유용합니다.342모든 백그라운드 세션에는 셸에서 사용할 수 있는 짧은 ID가 있습니다. ID는 `claude --bg`로 세션을 시작할 때 출력되며, 각 세션의 ID는 `~/.claude/jobs/` 아래의 디렉터리 이름입니다. 이 명령은 스크립팅이나 에이전트 뷰를 열고 싶지 않을 때 유용합니다.

305 343 

306| 명령 | 목적 |344| 명령 | 목적 |

307| :--------------------- | :----------------------------------------- |345| :--------------------- | :------------------------------------------------------ |

308| `claude agents` | 에이전트 뷰 열기 |346| `claude agents` | 에이전트 뷰 열기. `--cwd <path>`를 전달하여 해당 디렉터리 아래에서 시작된 세션만 나열 |

309| `claude attach <id>` | 이 터미널에서 세션에 연결 |347| `claude attach <id>` | 이 터미널에서 세션에 연결 |

310| `claude logs <id>` | 세션의 최근 출력 인쇄 |348| `claude logs <id>` | 세션의 최근 출력 인쇄 |

311| `claude stop <id>` | 세션 중지. `claude kill`도 허용 |349| `claude stop <id>` | 세션 중지. `claude kill`도 허용 |

170 170 

171Claude Code는 AWS SSO 및 회사 ID 공급자에 대한 자동 자격 증명 새로 고침을 지원합니다. Claude Code 설정 파일에 이러한 설정을 추가하십시오([설정](/ko/settings)에서 파일 위치 참조).171Claude Code는 AWS SSO 및 회사 ID 공급자에 대한 자동 자격 증명 새로 고침을 지원합니다. Claude Code 설정 파일에 이러한 설정을 추가하십시오([설정](/ko/settings)에서 파일 위치 참조).

172 172 

173Claude Code가 AWS 자격 증명이 만료되었음을 감지하면(타임스탬프를 기반으로 로컬에서 또는 Bedrock이 자격 증명 오류를 반환할 때), 요청을 다시 시도하기 전에 새 자격 증명을 얻기 위해 구성된 `awsAuthRefresh` 및/또는 `awsCredentialExport` 명령을 자동으로 실행합니다.173이 두 설정은 서로 다른 트리거 조건을 가집니다:

174 

175* **`awsAuthRefresh`**: Claude Code가 AWS 자격 증명이 만료되었음을 감지할 때만 실행됩니다. 타임스탬프를 기반으로 로컬에서 또는 Bedrock이 자격 증명 오류를 반환할 때 감지되며, 새로 고쳐진 자격 증명으로 요청을 다시 시도합니다.

176* **`awsCredentialExport`**: 세션 시작 시 및 각 자격 증명 다시 로드 시 실행되며, AWS 기본 자격 증명 공급자 체인의 자격 증명이 여전히 유효한 경우에도 실행됩니다. Bedrock 계정이 기본 공급자 체인이 확인할 자격 증명과 다른 교차 계정 자격 증명을 필요로 할 때 사용하십시오.

174 177 

175##### 예제 구성178##### 예제 구성

176 179 

187 190 

188**`awsAuthRefresh`**: `.aws` 디렉토리를 수정하는 명령(예: 자격 증명, SSO 캐시 또는 구성 파일 업데이트)에 사용하십시오. 명령의 출력이 사용자에게 표시되지만 대화형 입력은 지원되지 않습니다. 이는 CLI가 URL 또는 코드를 표시하고 브라우저에서 인증을 완료하는 브라우저 기반 SSO 흐름에 적합합니다.191**`awsAuthRefresh`**: `.aws` 디렉토리를 수정하는 명령(예: 자격 증명, SSO 캐시 또는 구성 파일 업데이트)에 사용하십시오. 명령의 출력이 사용자에게 표시되지만 대화형 입력은 지원되지 않습니다. 이는 CLI가 URL 또는 코드를 표시하고 브라우저에서 인증을 완료하는 브라우저 기반 SSO 흐름에 적합합니다.

189 192 

190**`awsCredentialExport`**: `.aws`를 수정할 수 없고 자격 증명을 직접 반환해야 하는 경우에만 사용하십시오. 출력은 자동으로 캡처되며 사용자에게 표시되지 않습니다. 명령은 다음 형식으로 JSON을 출력해야 합니다:193**`awsCredentialExport`**: `.aws`를 수정할 수 없고 자격 증명을 직접 반환해야 하는 경우에만 사용하십시오. 이 명령은 자격 증명이 만료되었을 때뿐만 아니라 자격 증명을 새로 고쳐야 할 때마다 실행됩니다. 출력은 자동으로 캡처되며 사용자에게 표시되지 않습니다. 명령은 다음 형식으로 JSON을 출력해야 합니다:

191 194 

192```json theme={null}195```json theme={null}

193{196{

52 연구 및 계획을 구현과 분리하여 잘못된 문제를 해결하는 것을 피하십시오.52 연구 및 계획을 구현과 분리하여 잘못된 문제를 해결하는 것을 피하십시오.

53</Tip>53</Tip>

54 54 

55Claude가 바로 코딩으로 뛰어들도록 하면 잘못된 문제를 해결하는 코드가 생성될 수 있습니다. [Plan Mode](/ko/common-workflows#use-plan-mode-for-safe-code-analysis)를 사용하여 탐색을 실행과 분리하십시오.55Claude가 바로 코딩으로 뛰어들도록 하면 잘못된 문제를 해결하는 코드가 생성될 수 있습니다. [Plan Mode](/ko/permission-modes#analyze-before-you-edit-with-plan-mode)를 사용하여 탐색을 실행과 분리하십시오.

56 56 

57권장 워크플로우에는 4가지 단계가 있습니다:57권장 워크플로우에는 4가지 단계가 있습니다:

58 58 

60 <Step title="탐색">60 <Step title="탐색">

61 Plan Mode를 입력하십시오. Claude는 파일을 읽고 변경을 수행하지 않고 질문에 답합니다.61 Plan Mode를 입력하십시오. Claude는 파일을 읽고 변경을 수행하지 않고 질문에 답합니다.

62 62 

63 ```txt claude (Plan Mode) theme={null}63 ```txt claude (plan mode) theme={null}

64 /src/auth를 읽고 세션 및 로그인을 어떻게 처리하는지 이해하세요.64 read /src/auth and understand how we handle sessions and login.

65 또한 비밀에 대한 환경 변수를 어떻게 관리하는지 살펴보세요.65 also look at how we manage environment variables for secrets.

66 ```66 ```

67 </Step>67 </Step>

68 68 

69 <Step title="계획">69 <Step title="계획">

70 Claude에게 상세한 구현 계획을 작성하도록 요청하십시오.70 Claude에게 상세한 구현 계획을 작성하도록 요청하십시오.

71 71 

72 ```txt claude (Plan Mode) theme={null}72 ```txt claude (plan mode) theme={null}

73 Google OAuth를 추가하고 싶습니다. 어떤 파일을 변경해야 합니까?73 I want to add Google OAuth. What files need to change?

74 세션 흐름은 무엇입니까? 계획을 작성하세요.74 What's the session flow? Create a plan.

75 ```75 ```

76 76 

77 `Ctrl+G`를 눌러 Claude가 진행하기 전에 텍스트 편집기에서 계획을 열어 직접 편집하십시오.77 `Ctrl+G`를 눌러 Claude가 진행하기 전에 텍스트 편집기에서 계획을 열어 직접 편집하십시오.

78 </Step>78 </Step>

79 79 

80 <Step title="구현">80 <Step title="구현">

81 Normal Mode로 전환하고 Claude가 코드를 작성하도록 하여 계획에 대해 검증하십시오.81 Plan Mode를 종료하고 Claude가 코드를 작성하도록 하여 계획에 대해 검증하십시오.

82 82 

83 ```txt claude (Normal Mode) theme={null}83 ```txt claude (default mode) theme={null}

84 계획에서 OAuth 흐름을 구현하세요. 콜백 핸들러에 대한 테스트를 작성하고,84 implement the OAuth flow from your plan. write tests for the

85 테스트 스위트를 실행하고 실패를 수정하세요.85 callback handler, run the test suite and fix any failures.

86 ```86 ```

87 </Step>87 </Step>

88 88 

89 <Step title="커밋">89 <Step title="커밋">

90 Claude에게 설명적인 메시지로 커밋하고 PR을 생성하도록 요청하십시오.90 Claude에게 설명적인 메시지로 커밋하고 PR을 생성하도록 요청하십시오.

91 91 

92 ```txt claude (Normal Mode) theme={null}92 ```txt claude (default mode) theme={null}

93 설명적인 메시지로 커밋하고 PR을 열기93 commit with a descriptive message and open a PR

94 ```94 ```

95 </Step>95 </Step>

96</Steps>96</Steps>

396* 작업 간에 자주 `/clear`를 사용하여 context window를 완전히 재설정하십시오396* 작업 간에 자주 `/clear`를 사용하여 context window를 완전히 재설정하십시오

397* 자동 압축이 트리거되면 Claude는 코드 패턴, 파일 상태, 주요 결정을 포함하여 가장 중요한 것을 요약합니다397* 자동 압축이 트리거되면 Claude는 코드 패턴, 파일 상태, 주요 결정을 포함하여 가장 중요한 것을 요약합니다

398* 더 많은 제어를 위해 `/compact <instructions>`를 실행하십시오(예: `/compact Focus on the API changes`)398* 더 많은 제어를 위해 `/compact <instructions>`를 실행하십시오(예: `/compact Focus on the API changes`)

399* 대화의 일부만 압축하려면 `Esc + Esc` 또는 `/rewind`를 사용하고, 메시지 체크포인트를 선택하고, **Summarize from here**를 선택하십시오. 이는 해당 지점부터의 메시지를 압축하면서 이전 context를 유지합니다.399* 대화의 일부만 압축하려면 `Esc + Esc` 또는 `/rewind`를 사용하고, 메시지 체크포인트를 선택하고, **Summarize from here** 또는 **Summarize up to here**를 선택하십시오. 첫 번째는 해당 지점부터의 메시지를 압축하면서 이전 context를 유지하고, 두 번째는 이전 메시지를 압축하면서 최근 메시지를 완전히 유지합니다. [Restore vs. summarize](/ko/checkpointing#restore-vs-summarize)를 참조하십시오.

400* CLAUDE.md에서 `"When compacting, always preserve the full list of modified files and any test commands"`와 같은 지시사항으로 압축 동작을 사용자 정의하여 중요한 context가 요약을 통해 유지되도록 하십시오400* CLAUDE.md에서 `"When compacting, always preserve the full list of modified files and any test commands"`와 같은 지시사항으로 압축 동작을 사용자 정의하여 중요한 context가 요약을 통해 유지되도록 하십시오

401* 빠른 질문의 경우 context에 들어가지 않아야 하므로 [`/btw`](/ko/interactive-mode#side-questions-with-btw)를 사용하십시오. 답변은 해제 가능한 오버레이에 나타나고 대화 기록에 들어가지 않으므로 context를 증가시키지 않고 세부 정보를 확인할 수 있습니다.401* 빠른 질문의 경우 context에 들어가지 않아야 하므로 [`/btw`](/ko/interactive-mode#side-questions-with-%2Fbtw)를 사용하십시오. 답변은 해제 가능한 오버레이에 나타나고 대화 기록에 들어가지 않으므로 context를 증가시키지 않고 세부 정보를 확인할 수 있습니다.

402 402 

403### subagents를 사용하여 조사하기403### subagents를 사용하여 조사하기

404 404 

409context가 기본 제약 조건이므로 subagents는 사용 가능한 가장 강력한 도구 중 하나입니다. Claude가 코드베이스를 연구할 때 많은 파일을 읽으며, 모두 context를 소비합니다. Subagents는 별도의 context window에서 실행되고 요약을 보고합니다:409context가 기본 제약 조건이므로 subagents는 사용 가능한 가장 강력한 도구 중 하나입니다. Claude가 코드베이스를 연구할 때 많은 파일을 읽으며, 모두 context를 소비합니다. Subagents는 별도의 context window에서 실행되고 요약을 보고합니다:

410 410 

411```text theme={null}411```text theme={null}

412subagents를 사용하여 인증 시스템이 토큰 새로 고침을 어떻게 처리하는지,412Use subagents to investigate how our authentication system handles token

413그리고 재사용해야 할 기존 OAuth 유틸리티가 있는지 조사하세요.413refresh, and whether we have any existing OAuth utilities I should reuse.

414```414```

415 415 

416subagent는 코드베이스를 탐색하고, 관련 파일을 읽고, 주요 대화를 복잡하게 하지 않고 발견 사항을 보고합니다.416subagent는 코드베이스를 탐색하고, 관련 파일을 읽고, 주요 대화를 복잡하게 하지 않고 발견 사항을 보고합니다.

418Claude가 구현한 후 검증을 위해 subagents를 사용할 수도 있습니다:418Claude가 구현한 후 검증을 위해 subagents를 사용할 수도 있습니다:

419 419 

420```text theme={null}420```text theme={null}

421subagent를 사용하여 이 코드를 엣지 케이스에 대해 검토하세요421use a subagent to review this code for edge cases

422```422```

423 423 

424### 체크포인트로 rewind하기424### 체크포인트로 rewind하기

425 425 

426<Tip>426<Tip>

427 Claude가 수행하는 모든 작업은 체크포인트를 생성합니다. 이전 체크포인트로 대화, 코드 또는 둘 다를 복원할 수 있습니다.427 Claude가 수행하는 모든 프롬프트는 체크포인트를 생성합니다. 이전 체크포인트로 대화, 코드 또는 둘 다를 복원할 수 있습니다.

428</Tip>428</Tip>

429 429 

430Claude는 변경 전에 자동으로 체크포인트합니다. `Escape`를 두 번 누르거나 `/rewind`를 실행하여 rewind 메뉴를 열기. 대화만 복원하거나, 코드만 복원하거나, 둘 다 복원하거나, 선택한 메시지에서 요약할 수 있습니다. 자세한 내용은 [Checkpointing](/ko/checkpointing)을 참조하십시오.430Claude는 각 변경 전에 자동으로 파일을 스냅샷하므로 체크포인트가 파일을 복원할 수 있습니다. `Escape`를 두 번 누르거나 `/rewind`를 실행하여 rewind 메뉴를 열기. 대화만 복원하거나, 코드만 복원하거나, 둘 다 복원하거나, 선택한 메시지에서 요약할 수 있습니다. 자세한 내용은 [Checkpointing](/ko/checkpointing)을 참조하십시오.

431 431 

432모든 움직임을 신중하게 계획하는 대신 Claude에게 위험한 것을 시도하도록 할 수 있습니다. 작동하지 않으면 rewind하고 다른 접근 방식을 시도하십시오. 체크포인트는 세션 간에 유지되므로 터미널을 닫아도 나중에 rewind할 수 있습니다.432모든 움직임을 신중하게 계획하는 대신 Claude에게 위험한 것을 시도하도록 할 수 있습니다. 작동하지 않으면 rewind하고 다른 접근 방식을 시도하십시오. 체크포인트는 세션 간에 유지되므로 터미널을 닫아도 나중에 rewind할 수 있습니다.

433 433 

438### 대화 재개하기438### 대화 재개하기

439 439 

440<Tip>440<Tip>

441 `claude --continue`를 실행하여 중단한 곳에서 계속하거나, `--resume`을 사용하여 최근 세션에서 선택하십시오.441 `/rename`으로 세션에 이름을 지정하고 분기처럼 취급하십시오: 각 작업 스트림은 자체 지속적인 context를 가집니다.

442</Tip>442</Tip>

443 443 

444Claude Code는 대화를 로컬로 저장합니다. 작업이 여러 세션에 걸쳐 있을 때 context를 다시 설명할 필요가 없습니다:444Claude Code는 대화를 로컬로 저장하므로 작업이 여러 세션에 걸쳐 있을 때 context를 다시 설명할 필요가 없습니다. `claude --continue`를 실행하여 가장 최근 세션을 선택하거나, `claude --resume`을 실행하여 목록에서 선택하십시오. `oauth-migration`과 같은 설명적인 이름으로 세션에 이름을 지정하여 나중에 찾을 수 있도록 하십시오. [Manage sessions](/ko/sessions)에서 전체 resume, branch, naming 제어 집합을 참조하십시오.

445 

446```bash theme={null}

447claude --continue # 가장 최근 대화 재개

448claude --resume # 최근 대화에서 선택

449```

450 

451`/rename`을 사용하여 세션에 `"oauth-migration"` 또는 `"debugging-memory-leak"`과 같은 설명적인 이름을 지정하여 나중에 찾을 수 있도록 하십시오. 세션을 분기처럼 취급하십시오: 다양한 작업 스트림은 별도의 지속적인 context를 가질 수 있습니다.

452 445 

453***446***

454 447 

464 CI, pre-commit hooks 또는 스크립트에서 `claude -p "prompt"`를 사용하십시오. 스트리밍 JSON 출력의 경우 `--output-format stream-json`을 추가하십시오.457 CI, pre-commit hooks 또는 스크립트에서 `claude -p "prompt"`를 사용하십시오. 스트리밍 JSON 출력의 경우 `--output-format stream-json`을 추가하십시오.

465</Tip>458</Tip>

466 459 

467`claude -p "your prompt"`를 사용하면 세션 없이 비대화형으로 Claude를 실행할 수 있습니다. 비대화형 모드는 Claude를 CI 파이프라인, pre-commit hooks 또는 자동화된 워크플로우에 통합하는 방법입니다. 출력 형식을 사용하면 결과를 프로그래밍 방식으로 구문 분석할 수 있습니다: 일반 텍스트, JSON 또는 스트리밍 JSON.460`claude -p "your prompt"`를 사용하면 세션 없이 비대화형으로 Claude를 실행할 수 있습니다. [비대화형 모드](/ko/headless)는 Claude를 CI 파이프라인, pre-commit hooks 또는 자동화된 워크플로우에 통합하는 방법입니다. 출력 형식을 사용하면 결과를 프로그래밍 방식으로 구문 분석할 수 있습니다: 일반 텍스트, JSON 또는 스트리밍 JSON.

468 461 

469```bash theme={null}462```bash theme={null}

470# 일회성 쿼리463# 일회성 쿼리

483 개발 속도를 높이거나, 격리된 실험을 실행하거나, 복잡한 워크플로우를 시작하기 위해 여러 Claude 세션을 병렬로 실행하십시오.476 개발 속도를 높이거나, 격리된 실험을 실행하거나, 복잡한 워크플로우를 시작하기 위해 여러 Claude 세션을 병렬로 실행하십시오.

484</Tip>477</Tip>

485 478 

486병렬 세션을 실행하는 세 가지 주요 방법이 있습니다:479조정하고 싶은 정도에 맞는 병렬 접근 방식을 선택하십시오:

487 480 

488* [Claude Code 데스크톱 앱](/ko/desktop#work-in-parallel-with-sessions): 여러 로컬 세션을 시각적으로 관리하십시오. 각 세션은 자신의 격리된 worktree를 가집니다.481* [Worktrees](/ko/worktrees): 격리된 git 체크아웃에서 별도의 CLI 세션을 실행하여 편집이 충돌하지 않도록 합니다

489* [웹의 Claude Code](/ko/claude-code-on-the-web): Anthropic의 안전한 클라우드 인프라에서 격리된 VM에서 실행하십시오.482* [데스크톱 앱](/ko/desktop#work-in-parallel-with-sessions): 여러 로컬 세션을 시각적으로 관리하십시오. 각 세션은 자신의 worktree에 있습니다

490* [Agent teams](/ko/agent-teams): 공유 작업, 메시징, 팀 리더를 사용한 여러 세션의 자동 조정.483* [웹의 Claude Code](/ko/claude-code-on-the-web): Anthropic이 관리하는 클라우드 인프라의 격리된 VM에서 세션을 실행하십시오

484* [Agent teams](/ko/agent-teams): 공유 작업, 메시징, 팀 리더를 사용한 여러 세션의 자동 조정

491 485 

492작업을 병렬화하는 것 외에도 여러 세션은 품질 중심 워크플로우를 활성화합니다. 새로운 context는 Claude가 방금 작성한 코드에 편향되지 않으므로 코드 검토를 개선합니다.486작업을 병렬화하는 것 외에도 여러 세션은 품질 중심 워크플로우를 활성화합니다. 새로운 context는 Claude가 방금 작성한 코드에 편향되지 않으므로 코드 검토를 개선합니다.

493 487 

28* **대화 복원**: 현재 코드를 유지하면서 해당 메시지로 되돌립니다28* **대화 복원**: 현재 코드를 유지하면서 해당 메시지로 되돌립니다

29* **코드 복원**: 대화를 유지하면서 파일 변경 사항을 되돌립니다29* **코드 복원**: 대화를 유지하면서 파일 변경 사항을 되돌립니다

30* **여기서부터 요약**: 이 지점부터 이후의 대화를 요약으로 압축하여 context window 공간을 확보합니다30* **여기서부터 요약**: 이 지점부터 이후의 대화를 요약으로 압축하여 context window 공간을 확보합니다

31* **여기까지 요약**: 이 지점 이전의 대화를 요약으로 압축하여 이후 메시지를 그대로 유지합니다

31* **취소**: 변경 사항을 적용하지 않고 메시지 목록으로 돌아갑니다32* **취소**: 변경 사항을 적용하지 않고 메시지 목록으로 돌아갑니다

32 33 

33대화를 복원하거나 요약한 후 선택한 메시지의 원본 프롬프트가 입력 필드에 복원되므로 다시 보내거나 편집할 수 있습니다.34대화를 복원하거나 여기서부터 요약을 선택한 후 선택한 메시지의 원본 프롬프트가 입력 필드에 복원되므로 다시 보내거나 편집할 수 있습니다.

35 

36여기까지 요약을 선택하면 대화의 끝에 남겨지며 입력 필드는 비어 있습니다.

34 37 

35#### 복원 vs. 요약38#### 복원 vs. 요약

36 39 

37세 가지 복원 옵션은 상태를 되돌립니다: 코드 변경 사항, 대화 기록 또는 둘 다를 실행 취소합니다. "여기서부터 요약"은 다르게 작동합니다:40복원 옵션은 상태를 되돌립니다: 코드 변경 사항, 대화 기록 또는 둘 다를 실행 취소합니다. 요약 옵션은 디스크의 파일을 변경하지 않으면서 대화의 일부를 AI 생성 요약으로 압축합니다:

38 41 

39* 선택한 메시지 이전의 메시지는 그대로 유지됩니다42* **여기서부터 요약**: 선택한 메시지 이전의 메시지는 그대로 유지됩니다. 선택한 메시지와 그 이후의 모든 메시지는 요약으로 대체됩니다. 초기 context를 완전한 세부 정보로 유지하면서 부수적인 논의를 버리려면 이를 사용합니다.

40* 선택한 메시지와 그 이후의 모든 메시지는 컴팩트한 AI 생성 요약으로 대체됩니다43* **여기까지 요약**: 선택한 메시지 이전의 메시지는 요약으로 대체됩니다. 선택한 메시지와 그 이후의 모든 메시지는 그대로 유지되며 대화의 끝에 남겨집니다. 최근 작업을 완전한 세부 정보로 유지하면서 초기 설정 논의를 압축하려면 이를 사용합니다.

41* 디스크의 파일은 변경되지 않습니다

42* 원본 메시지는 세션 기록에 보존되므로 Claude가 필요한 경우 세부 정보를 참조할 수 있습니다

43 44 

44이는 `/compact`와 유사하지만 대상이 지정됩니다: 전체 대화를 요약하는 대신 초기 context를 완전한 세부 정보로 유지하고 공간을 차지하는 부분만 압축합니다. 요약이 초점을 맞출 내용을 안내하기 위해 선택적 지침을 입력할 수 있습니다.45두 경우 모두 원본 메시지는 세션 기록에 보존되므로 Claude가 필요한 경우 세부 정보를 참조할 수 있습니다. 요약이 초점을 맞출 내용을 안내하기 위해 선택적 지침을 입력할 수 있습니다. 이는 `/compact`와 유사하지만 대상이 지정됩니다: 전체 대화를 요약하는 대신 선택한 메시지의 어느 쪽을 압축할지 선택합니다.

45 46 

46<Note>47<Note>

47 Summarize는 동일한 세션에 유지되고 context를 압축합니다. 원본 세션을 그대로 유지하면서 다른 접근 방식을 시도하고 싶다면 [fork](/ko/how-claude-code-works#resume-or-fork-sessions) 대신 사용하세요(`claude --continue --fork-session`).48 Summarize는 동일한 세션에 유지되고 context를 압축합니다. 원본 세션을 그대로 유지하면서 다른 접근 방식을 시도하고 싶다면 [fork](/ko/sessions#branch-a-session) 대신 사용하세요(`claude --continue --fork-session`).

48</Note>49</Note>

49 50 

50## 일반적인 사용 사례51## 일반적인 사용 사례

85## 참고 항목86## 참고 항목

86 87 

87* [Interactive mode](/ko/interactive-mode) - 키보드 단축키 및 세션 제어88* [Interactive mode](/ko/interactive-mode) - 키보드 단축키 및 세션 제어

88* [Built-in commands](/ko/commands) - `/rewind`를 사용하여 checkpoint에 액세스89* [Commands](/ko/commands) - `/rewind`를 사용하여 checkpoint에 액세스

89* [CLI reference](/ko/cli-reference) - 명령줄 옵션90* [CLI reference](/ko/cli-reference) - 명령줄 옵션

782 782 

783### Remote Control 세션 만료 또는 액세스 거부783### Remote Control 세션 만료 또는 액세스 거부

784 784 

785`--teleport`는 클라우드 세션이 사용하는 동일한 Remote Control 세션 인프라를 통해 연결되므로 인증 및 세션 만료 오류는 Remote Control 용어로 표시됩니다. `Remote Control session has expired` 또는 `Access denied`가 표시될 수 있습니다. 연결 토큰은 단기이며 계정으로 범위가 지정됩니다.785`--teleport`는 클라우드 세션이 사용하는 동일한 Remote Control 세션 인프라를 통해 연결되므로 인증 및 세션 만료 오류는 Remote Control 용어로 표시됩니다. `Remote Control session expired` 또는 `Access denied`가 표시될 수 있습니다. 연결 토큰은 단기이며 계정으로 범위가 지정됩니다.

786 786 

787* 로컬에서 `/login`을 실행하여 자격 증명을 새로 고친 다음 다시 연결하세요787* 로컬에서 `/login`을 실행하여 자격 증명을 새로 고친 다음 다시 연결하세요

788* 세션을 소유한 동일한 계정으로 로그인했는지 확인하세요788* 세션을 소유한 동일한 계정으로 로그인했는지 확인하세요

24| `claude auth login` | Anthropic 계정에 로그인합니다. `--email`을 사용하여 이메일 주소를 미리 입력하고, `--sso`를 사용하여 SSO 인증을 강제하고, `--console`을 사용하여 Claude 구독 대신 API 사용 청구를 위해 Anthropic Console로 로그인할 수 있습니다 | `claude auth login --console` |24| `claude auth login` | Anthropic 계정에 로그인합니다. `--email`을 사용하여 이메일 주소를 미리 입력하고, `--sso`를 사용하여 SSO 인증을 강제하고, `--console`을 사용하여 Claude 구독 대신 API 사용 청구를 위해 Anthropic Console로 로그인할 수 있습니다 | `claude auth login --console` |

25| `claude auth logout` | Anthropic 계정에서 로그아웃합니다 | `claude auth logout` |25| `claude auth logout` | Anthropic 계정에서 로그아웃합니다 | `claude auth logout` |

26| `claude auth status` | 인증 상태를 JSON으로 표시합니다. 사람이 읽을 수 있는 출력을 위해 `--text`를 사용합니다. 로그인된 경우 코드 0으로 종료되고, 로그인되지 않은 경우 1로 종료됩니다 | `claude auth status` |26| `claude auth status` | 인증 상태를 JSON으로 표시합니다. 사람이 읽을 수 있는 출력을 위해 `--text`를 사용합니다. 로그인된 경우 코드 0으로 종료되고, 로그인되지 않은 경우 1로 종료됩니다 | `claude auth status` |

27| `claude agents` | [에이전트 보기](/ko/agent-view)를 열어 병렬 백그라운드 세션을 모니터링하고 디스패치합니다. 출력이 파이프될 때는 구성된 [subagents](/ko/sub-agents)를 대신 나열합니다 | `claude agents` |27| `claude agents` | [에이전트 보기](/ko/agent-view)를 열어 병렬 백그라운드 세션을 모니터링하고 디스패치합니다. `--cwd <path>`를 사용하여 해당 디렉토리 아래에서 시작된 세션만 표시합니다 | `claude agents` |

28| `claude attach <id>` | 이 터미널에서 [백그라운드 세션](/ko/agent-view#manage-sessions-from-the-shell)에 연결합니다 | `claude attach 7c5dcf5d` |28| `claude attach <id>` | 이 터미널에서 [백그라운드 세션](/ko/agent-view#manage-sessions-from-the-shell)에 연결합니다 | `claude attach 7c5dcf5d` |

29| `claude auto-mode defaults` | 기본 제공 [자동 모드](/ko/permission-modes#eliminate-prompts-with-auto-mode) 분류기 규칙을 JSON으로 인쇄합니다. `claude auto-mode config`를 사용하여 설정이 적용된 유효한 구성을 확인합니다 | `claude auto-mode defaults > rules.json` |29| `claude auto-mode defaults` | 기본 제공 [자동 모드](/ko/permission-modes#eliminate-prompts-with-auto-mode) 분류기 규칙을 JSON으로 인쇄합니다. `claude auto-mode config`를 사용하여 설정이 적용된 유효한 구성을 확인합니다 | `claude auto-mode defaults > rules.json` |

30| `claude logs <id>` | [백그라운드 세션](/ko/agent-view#manage-sessions-from-the-shell)의 최근 출력을 인쇄합니다 | `claude logs 7c5dcf5d` |30| `claude logs <id>` | [백그라운드 세션](/ko/agent-view#manage-sessions-from-the-shell)의 최근 출력을 인쇄합니다 | `claude logs 7c5dcf5d` |

26 26 

27**세션 간.** `/clear`는 프로젝트 메모리를 유지하면서 새 작업을 새로 시작합니다. `/resume` 및 `/branch`를 사용하면 이전 대화로 돌아가거나 분기할 수 있습니다. `/teleport`는 웹 세션을 이 터미널로 가져오고, `/remote-control`을 사용하면 다른 기기에서 이 로컬 세션을 계속할 수 있습니다.27**세션 간.** `/clear`는 프로젝트 메모리를 유지하면서 새 작업을 새로 시작합니다. `/resume` 및 `/branch`를 사용하면 이전 대화로 돌아가거나 분기할 수 있습니다. `/teleport`는 웹 세션을 이 터미널로 가져오고, `/remote-control`을 사용하면 다른 기기에서 이 로컬 세션을 계속할 수 있습니다.

28 28 

29**문제가 발생했을 때.** `/rewind`는 코드와 대화를 checkpoint로 되돌립니다. `/doctor` 및 `/debug`는 설치 및 런타임 문제를 진단하고, `/feedback`은 세션 컨텍스트가 첨부된 버그를 보고합니다.29**문제가 발생했을 때.** `/rewind`는 코드와 대화를 checkpoint로 되돌리거나 대화의 일부를 요약합니다. `/doctor` 및 `/debug`는 설치 및 런타임 문제를 진단하고, `/feedback`은 세션 컨텍스트가 첨부된 버그를 보고합니다.

30 30 

31## 모든 명령어31## 모든 명령어

32 32 

148 148 

149### 터미널에서 명령 실행하기149### 터미널에서 명령 실행하기

150 150 

151통합 터미널을 사용하면 다른 앱으로 전환하지 않고 세션과 함께 명령을 실행할 수 있습니다. **Views** 메뉴에서 열거나 macOS 또는 Windows에서 \*\*Ctrl+\`\*\*를 누릅니다. 터미널은 세션의 작업 디렉토리에서 열리고 Claude와 동일한 환경을 공유하므로 `npm test` 또는 `git status`와 같은 명령은 Claude가 편집하는 것과 동일한 파일을 봅니다. 터미널은 로컬 세션에서만 사용 가능합니다.151통합 터미널을 사용하면 다른 앱으로 전환하지 않고 세션과 함께 명령을 실행할 수 있습니다. **Views** 메뉴에서 열거나 macOS 또는 Windows에서 \*\*Ctrl+\`\*\*를 누릅니다. 터미널은 세션의 작업 디렉토리에서 열리고 Claude와 동일한 환경을 공유하므로 `npm test` 또는 `git status`와 같은 명령은 Claude가 편집하는 것과 동일한 파일을 봅니다. 두 번째 터미널 탭을 열려면 터미널 패널 헤더의 \*\*+\*\*를 클릭하거나 채팅의 폴더를 마우스 오른쪽 버튼으로 클릭하여 **Open in terminal**을 선택합니다. 터미널은 로컬 세션에서만 사용 가능합니다.

152 152 

153### 파일 열기 및 편집하기153### 파일 열기 및 편집하기

154 154 

296 296 

297사이드바 상단의 컨트롤을 사용하여 상태, 프로젝트 또는 환경별로 세션을 필터링하고 프로젝트별로 세션을 그룹화합니다. 세션 이름을 바꾸려면 활성 세션 상단의 도구 모음에서 세션 제목을 클릭합니다. 컨텍스트 사용량을 확인하려면 [사용량 확인](#check-usage)을 참조하세요. 컨텍스트가 가득 차면 Claude는 자동으로 대화를 요약하고 계속 작업합니다. `/compact`를 입력하여 요약을 더 일찍 트리거하고 컨텍스트 공간을 확보할 수도 있습니다. [컨텍스트 윈도우](/ko/how-claude-code-works#the-context-window)에서 압축이 작동하는 방식에 대한 자세한 내용을 참조하세요.297사이드바 상단의 컨트롤을 사용하여 상태, 프로젝트 또는 환경별로 세션을 필터링하고 프로젝트별로 세션을 그룹화합니다. 세션 이름을 바꾸려면 활성 세션 상단의 도구 모음에서 세션 제목을 클릭합니다. 컨텍스트 사용량을 확인하려면 [사용량 확인](#check-usage)을 참조하세요. 컨텍스트가 가득 차면 Claude는 자동으로 대화를 요약하고 계속 작업합니다. `/compact`를 입력하여 요약을 더 일찍 트리거하고 컨텍스트 공간을 확보할 수도 있습니다. [컨텍스트 윈도우](/ko/how-claude-code-works#the-context-window)에서 압축이 작동하는 방식에 대한 자세한 내용을 참조하세요.

298 298 

299데스크톱 앱은 Code 세션이 작업을 완료하고 현재 해당 세션을 보고 있지 않을 때 OS 알림을 보냅니다.

300 

299### 세션을 벗어나지 않고 옆 질문 하기301### 세션을 벗어나지 않고 옆 질문 하기

300 302 

301사이드 채팅을 사용하면 세션의 컨텍스트를 사용하지만 메인 대화에 아무것도 추가하지 않고 Claude에게 질문할 수 있습니다. 코드 조각을 이해하거나, 가정을 확인하거나, 세션을 벗어나지 않고 아이디어를 탐색하려고 할 때 사용합니다.303사이드 채팅을 사용하면 세션의 컨텍스트를 사용하지만 메인 대화에 아무것도 추가하지 않고 Claude에게 질문할 수 있습니다. 코드 조각을 이해하거나, 가정을 확인하거나, 세션을 벗어나지 않고 아이디어를 탐색하려고 할 때 사용합니다.

598관리 설정은 프로젝트 및 사용자 설정을 재정의하고 Desktop이 CLI 세션을 생성할 때 적용됩니다. 조직의 [관리 설정](/ko/settings#settings-precedence) 파일에서 이러한 키를 설정하거나 관리 콘솔을 통해 원격으로 푸시할 수 있습니다.600관리 설정은 프로젝트 및 사용자 설정을 재정의하고 Desktop이 CLI 세션을 생성할 때 적용됩니다. 조직의 [관리 설정](/ko/settings#settings-precedence) 파일에서 이러한 키를 설정하거나 관리 콘솔을 통해 원격으로 푸시할 수 있습니다.

599 601 

600| 키 | 설명 |602| 키 | 설명 |

601| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |603| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

602| `permissions.disableBypassPermissionsMode` | 사용자가 권한 무시 모드를 활성화하지 못하도록 하려면 `"disable"`로 설정합니다. |604| `permissions.disableBypassPermissionsMode` | 사용자가 권한 무시 모드를 활성화하지 못하도록 하려면 `"disable"`로 설정합니다. |

603| `disableAutoMode` | 사용자가 [Auto](/ko/permission-modes#eliminate-prompts-with-auto-mode) 모드를 활성화하지 못하도록 하려면 `"disable"`로 설정합니다. 모드 선택기에서 Auto를 제거합니다. `permissions` 아래에서도 허용됩니다. |605| `disableAutoMode` | 사용자가 [Auto](/ko/permission-modes#eliminate-prompts-with-auto-mode) 모드를 활성화하지 못하도록 하려면 `"disable"`로 설정합니다. 모드 선택기에서 Auto를 제거합니다. `permissions` 아래에서도 허용됩니다. |

604| `autoMode` | 조직 전체에서 auto mode 분류기가 신뢰하고 차단하는 것을 사용자 정의합니다. [auto mode 구성](/ko/auto-mode-config)을 참조하세요. |606| `autoMode` | 조직 전체에서 auto mode 분류기가 신뢰하고 차단하는 것을 사용자 정의합니다. [auto mode 구성](/ko/auto-mode-config)을 참조하세요. |

605| `sshConfigs` | 환경 드롭다운에 나타나는 [SSH 연결](#pre-configure-ssh-connections-for-your-team)을 사전 구성합니다. 사용자는 관리 연결을 편집하거나 삭제할 수 없습니다. |607| `sshConfigs` | 환경 드롭다운에 나타나는 [SSH 연결](#pre-configure-ssh-connections-for-your-team)을 사전 구성합니다. 사용자는 관리 연결을 편집하거나 삭제할 수 없습니다. |

606| `sshHostAllowlist` | [SSH 세션](#restrict-which-ssh-hosts-users-can-connect-to)을 확인된 호스트명이 이러한 패턴 중 하나와 일치하는 호스트로 제한합니다. 빈 배열은 SSH 세션을 비활성화합니다. 관리 설정에서만 읽습니다. |608| `sshHostAllowlist` | [SSH 세션](#restrict-which-ssh-hosts-users-can-connect-to)을 확인된 호스트명이 이러한 패턴 중 하나와 일치하는 호스트로 제한합니다. 빈 배열은 SSH 세션을 비활성화합니다. 관리 설정에서만 읽습니다. |

609| `managedMcpServers` | 타사 배포에서 모든 사용자에게 MCP 서버 구성을 푸시합니다. 각 항목은 `"http"`, `"sse"`, 또는 `"stdio"`의 전송, 연결 세부 정보, 그리고 선택적으로 해당 서버의 어떤 도구를 사용자가 호출할 수 있는지 제한하는 `toolPolicy` 맵을 지정합니다. 타사(3P) Desktop 배포에서만 사용 가능합니다. |

607 610 

608각 머신의 디스크에 배포된 관리 설정 파일은 Desktop 세션에 적용됩니다. 관리 콘솔을 통해 원격으로 푸시된 관리 설정은 현재 CLI 및 IDE 세션에만 도달하므로, Desktop 배포의 경우 MDM을 통해 파일을 배포하거나 위의 [관리 콘솔 컨트롤](#admin-console-controls)을 사용합니다.611각 머신의 디스크에 배포된 관리 설정 파일은 Desktop 세션에 적용됩니다. 관리 콘솔을 통해 원격으로 푸시된 관리 설정은 현재 CLI 및 IDE 세션에만 도달하므로, Desktop 배포의 경우 MDM을 통해 파일을 배포하거나 위의 [관리 콘솔 컨트롤](#admin-console-controls)을 사용합니다.

609 612 

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

4 

5# Claude Code Desktop에서 반복 작업 예약하기

6 

7> Claude Code Desktop에서 예약된 작업을 설정하여 일일 코드 리뷰, 종속성 감사 또는 아침 브리핑을 위해 Claude를 자동으로 반복 실행합니다.

8 

9예약된 작업은 선택한 시간과 빈도에 따라 새 세션을 자동으로 시작합니다. 일일 코드 리뷰, 종속성 업데이트 확인 또는 캘린더와 받은편지함에서 정보를 가져오는 아침 브리핑과 같은 반복 작업에 사용합니다.

10 

11Desktop 앱의 **Routines** 페이지를 통해 로컬 예약된 작업과 원격 [routines](/ko/routines)을 모두 만들 수 있습니다. 로컬 작업은 사용자의 머신에서 실행되며 파일과 도구에 직접 접근할 수 있지만, 앱이 열려 있고 컴퓨터가 깨어 있을 때만 실행됩니다. 원격 routine은 컴퓨터가 꺼져 있어도 Anthropic 관리 클라우드 인프라에서 실행되며, API 호출이나 GitHub 이벤트에 대해서도 실행될 수 있습니다. 이 페이지는 로컬 예약된 작업을 다룹니다. 원격 routine과 해당 트리거 옵션에 대해서는 [Routines](/ko/routines)을 참조하세요.

12 

13## 예약 옵션 비교

14 

15Claude Code offers three ways to schedule recurring or one-off work:

16 

17| | [Cloud](/en/routines) | [Desktop](/en/desktop-scheduled-tasks) | [`/loop`](/en/scheduled-tasks) |

18| :------------------------- | :----------------------------- | :------------------------------------- | :---------------------------------- |

19| Runs on | Anthropic cloud | Your machine | Your machine |

20| Requires machine on | No | Yes | Yes |

21| Requires open session | No | No | Yes |

22| Persistent across restarts | Yes | Yes | Restored on `--resume` if unexpired |

23| Access to local files | No (fresh clone) | Yes | Yes |

24| MCP servers | Connectors configured per task | [Config files](/en/mcp) and connectors | Inherits from session |

25| Permission prompts | No (runs autonomously) | Configurable per task | Inherits from session |

26| Customizable schedule | Via `/schedule` in the CLI | Yes | Yes |

27| Minimum interval | 1 hour | 1 minute | 1 minute |

28 

29<Tip>

30 Use **cloud tasks** for work that should run reliably without your machine. Use **Desktop tasks** when you need access to local files and tools. Use **`/loop`** for quick polling during a session.

31</Tip>

32 

33<Note>

34 기본적으로 예약된 작업은 커밋되지 않은 변경 사항을 포함하여 작업 디렉토리의 현재 상태에 대해 실행됩니다. 작업을 만들 때 worktree 토글을 활성화하여 각 실행이 자신의 격리된 Git worktree를 갖도록 하면, [병렬 세션](/ko/desktop#work-in-parallel-with-sessions)과 동일한 방식으로 작동합니다.

35</Note>

36 

37## 예약된 작업 만들기

38 

39사이드바에서 **Routines**을 클릭한 다음 **New routine**을 클릭하고 **Local**을 선택합니다. 다음 필드를 구성합니다:

40 

41| 필드 | 설명 |

42| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

43| Name | 작업의 식별자입니다. 소문자 kebab-case로 변환되며 디스크의 폴더 이름으로 사용됩니다. 작업 전체에서 고유해야 합니다. |

44| Description | 작업 목록에 표시되는 짧은 요약입니다. |

45| Instructions | 작업이 실행될 때 Claude가 수행해야 할 작업입니다. 프롬프트 상자의 다른 메시지를 작성하는 것과 동일한 방식으로 작성합니다. instructions 입력에는 권한 모드 및 모델에 대한 선택기가 포함되어 있으며, 아래에서 작업 폴더를 선택하고 격리된 worktree에서 실행할지 여부를 선택합니다. |

46| Schedule | 작업이 실행되는 빈도입니다. 아래의 [schedule options](#schedule-options)을 참조하세요. |

47 

48작업을 저장하기 전에 폴더가 필요합니다. 아직 해당 폴더를 신뢰하지 않은 경우 Desktop은 저장하기 전에 폴더를 신뢰하도록 요청합니다.

49 

50모든 세션에서 원하는 작업을 설명하여 작업을 만들 수도 있습니다. 예를 들어, "매일 아침 9시에 실행되는 일일 코드 리뷰 설정"은 반복 작업을 만들고, "내일 오후 3시에 배포 확인을 상기시켜 줘"는 실행 후 자신을 비활성화하는 일회성 작업을 만듭니다.

51 

52## 예약 옵션

53 

54Schedule 컨트롤에서 사전 설정을 선택합니다:

55 

56* **Manual**: 일정이 없으며, **Run now**를 클릭할 때만 실행됩니다. 요청 시 트리거하는 프롬프트를 저장하는 데 유용합니다.

57* **Hourly**: 매시간 실행됩니다.

58* **Daily**: 시간 선택기를 표시하며, 기본값은 현지 시간 오전 9:00입니다.

59* **Weekdays**: Daily와 동일하지만 토요일과 일요일을 건너뜁니다.

60* **Weekly**: 시간 선택기와 요일 선택기를 표시합니다.

61 

6215분마다, 매월 1일, 또는 특정 미래 시간의 일회성 실행과 같이 선택기가 제공하지 않는 간격의 경우, Desktop의 모든 세션에서 Claude에게 일정을 설정하도록 요청합니다. 일반 언어를 사용합니다. 예를 들어, "6시간마다 모든 테스트를 실행하는 작업을 예약해 줘"입니다.

63 

64## 예약된 작업이 실행되는 방식

65 

66예약된 작업은 사용자의 머신에서 실행됩니다. Desktop은 앱이 열려 있는 동안 매분 일정을 확인하고 열려 있는 수동 세션과 독립적으로 작업이 만료되면 새 세션을 시작합니다. 각 작업은 API 트래픽을 분산하기 위해 예약된 시간 이후 몇 분의 작은 지연을 받습니다. 지연은 결정론적입니다: 동일한 작업은 항상 동일한 오프셋에서 시작됩니다.

67 

68작업이 실행되면 데스크톱 알림을 받고 새 세션이 사이드바의 **Scheduled** 섹션 아래에 나타납니다. 이를 열어 Claude가 수행한 작업을 확인하고, 변경 사항을 검토하거나, 권한 프롬프트에 응답합니다. 세션은 다른 세션처럼 작동합니다: Claude는 파일을 편집하고, 명령을 실행하고, 커밋을 만들고, 풀 요청을 열 수 있습니다.

69 

70작업은 desktop 앱이 실행 중이고 컴퓨터가 깨어 있을 때만 실행됩니다. 컴퓨터가 예약된 시간을 통해 절전 모드로 전환되면 실행이 건너뜁니다. 유휴 절전을 방지하려면 **Desktop app → General** 아래의 Settings에서 **Keep computer awake**를 활성화합니다. 노트북 뚜껑을 닫으면 여전히 절전 모드로 전환됩니다. 컴퓨터가 꺼져 있어도 실행되어야 하거나 API 호출이나 GitHub 이벤트에 대해 트리거되어야 하는 작업의 경우, 대신 원격 [routine](/ko/routines)을 만듭니다.

71 

72## 놓친 실행

73 

74앱이 시작되거나 컴퓨터가 깨어나면 Desktop은 지난 7일 동안 각 작업이 놓친 실행이 있는지 확인합니다. 있으면 Desktop은 가장 최근에 놓친 시간에 대해 정확히 하나의 catch-up 실행을 시작하고 더 오래된 것은 버립니다. 6일을 놓친 일일 작업은 깨어날 때 한 번 실행됩니다. Desktop은 catch-up 실행이 시작될 때 알림을 표시합니다.

75 

76프롬프트를 작성할 때 이를 염두에 두세요. 오전 9시에 예약된 작업은 컴퓨터가 하루 종일 절전 모드였다면 오후 11시에 실행될 수 있습니다. 타이밍이 중요한 경우 프롬프트 자체에 보호 장치를 추가합니다. 예를 들어, "오늘의 커밋만 검토합니다. 오후 5시 이후이면 검토를 건너뛰고 놓친 내용의 요약만 게시합니다."

77 

78## 예약된 작업에 대한 권한

79 

80각 작업에는 자신의 권한 모드가 있으며, 이는 작업을 만들거나 편집할 때 설정합니다. `~/.claude/settings.json`의 Allow 규칙도 예약된 작업 세션에 적용됩니다. 작업이 Ask 모드에서 실행되고 권한이 없는 도구를 실행해야 하는 경우, 승인할 때까지 실행이 정지됩니다. 세션은 사이드바에 열려 있으므로 나중에 답변할 수 있습니다.

81 

82정지를 방지하려면 작업을 만든 후 **Run now**를 클릭하고 권한 프롬프트를 확인한 다음 각 프롬프트에 대해 "always allow"를 선택합니다. 해당 작업의 향후 실행은 프롬프트 없이 동일한 도구를 자동으로 승인합니다. 작업의 세부 정보 페이지에서 이러한 승인을 검토하고 취소할 수 있습니다.

83 

84## 예약된 작업 관리

85 

86**Routines** 목록에서 작업을 클릭하여 세부 정보 페이지를 엽니다. 여기에서 다음을 수행할 수 있습니다:

87 

88* **Run now**: 다음 예약된 시간을 기다리지 않고 작업을 즉시 시작합니다.

89* **Status**: Active와 Paused 사이를 전환하여 작업을 삭제하지 않고 예약된 실행을 일시 중지하거나 재개합니다.

90* **Edit**: instructions, schedule, folder 또는 기타 설정을 변경합니다.

91* **Review history**: 건너뛴 실행을 포함하여 모든 과거 실행을 확인합니다. 건너뛴 항목 위에 마우스를 올려 이유를 확인합니다: 컴퓨터가 절전 모드였거나, 이전 실행이 여전히 진행 중이거나, 다른 예약된 작업이 이미 실행 중입니다. **Show more**를 클릭하여 더 오래된 항목을 로드합니다.

92* **Review allowed permissions**: **Always allowed** 패널에서 이 작업에 대해 저장된 도구 승인을 확인하고 취소합니다.

93* **Delete**: 작업을 제거하고 생성한 모든 세션을 보관합니다. 확인 대화 상자에 **Also delete files on disk** 확인란이 나타납니다. 이를 확인하여 작업의 `SKILL.md` 파일과 `~/.claude/scheduled-tasks/`의 관련 데이터도 제거합니다.

94 

95Desktop의 모든 세션에서 Claude에게 요청하여 작업을 나열, 만들, 편집 및 일시 중지할 수도 있습니다. 예를 들어, "내 dependency-audit 작업을 일시 중지해 줘" 또는 "내 예약된 작업을 보여 줘"입니다. 작업을 삭제하려면 세부 정보 페이지의 **Delete** 버튼을 사용합니다.

96 

97예약된 작업은 실행 중인 세션 내에서 `update_scheduled_task` MCP 도구를 사용하여 자신의 일정이나 프롬프트를 수정할 수도 있습니다. 이를 통해 작업은 발견한 내용에 따라 자신을 재예약할 수 있습니다. 예를 들어, 릴리스 브랜치가 생성되었음을 감지할 때 코드 리뷰를 더 일찍 실행하도록 재예약합니다.

98 

99디스크에서 작업의 프롬프트를 편집하려면 `~/.claude/scheduled-tasks/<task-name>/SKILL.md`를 엽니다 (설정된 경우 [`CLAUDE_CONFIG_DIR`](/ko/env-vars) 아래). 파일은 `name` 및 `description`에 대해 YAML frontmatter를 사용하며, 프롬프트는 본문입니다. 변경 사항은 다음 실행에 적용됩니다. Schedule, folder, model 및 enabled state는 이 파일에 없습니다: Edit 양식을 통해 변경하거나 Claude에게 요청합니다.

100 

101## 관련 리소스

102 

103* [Routines](/ko/routines): Anthropic 관리 인프라에서 일정에 따라, API 호출을 통해 또는 GitHub 이벤트에 대응하여 작업을 실행합니다. 컴퓨터가 꺼져 있어도 실행됩니다.

104* [Run prompts on a schedule](/ko/scheduled-tasks): CLI에서 `/loop`를 사용한 세션 범위 예약

105* [Claude Code GitHub Actions](/ko/github-actions): 머신에서가 아닌 CI에서 일정에 따라 Claude를 실행합니다.

106* [Use Claude Code Desktop](/ko/desktop): 전체 Desktop 앱 가이드

45| `ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION` | Bedrock 또는 Bedrock Mantle 사용 시 Haiku 클래스 모델의 AWS 리전 재정의 |45| `ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION` | Bedrock 또는 Bedrock Mantle 사용 시 Haiku 클래스 모델의 AWS 리전 재정의 |

46| `ANTHROPIC_VERTEX_BASE_URL` | Vertex AI 엔드포인트 URL을 재정의합니다. 사용자 정의 Vertex 엔드포인트 또는 [LLM 게이트웨이](/ko/llm-gateway)를 통해 라우팅할 때 사용합니다. [Google Vertex AI](/ko/google-vertex-ai) 참조 |46| `ANTHROPIC_VERTEX_BASE_URL` | Vertex AI 엔드포인트 URL을 재정의합니다. 사용자 정의 Vertex 엔드포인트 또는 [LLM 게이트웨이](/ko/llm-gateway)를 통해 라우팅할 때 사용합니다. [Google Vertex AI](/ko/google-vertex-ai) 참조 |

47| `ANTHROPIC_VERTEX_PROJECT_ID` | Vertex AI 요청용 GCP 프로젝트 ID입니다. `GCLOUD_PROJECT`, `GOOGLE_CLOUD_PROJECT` 또는 `GOOGLE_APPLICATION_CREDENTIALS` 자격 증명 파일의 프로젝트로 재정의됩니다. [Google Vertex AI](/ko/google-vertex-ai) 참조 |47| `ANTHROPIC_VERTEX_PROJECT_ID` | Vertex AI 요청용 GCP 프로젝트 ID입니다. `GCLOUD_PROJECT`, `GOOGLE_CLOUD_PROJECT` 또는 `GOOGLE_APPLICATION_CREDENTIALS` 자격 증명 파일의 프로젝트로 재정의됩니다. [Google Vertex AI](/ko/google-vertex-ai) 참조 |

48| `ANTHROPIC_WORKSPACE_ID` | [워크로드 ID 페더레이션](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation)용 워크스페이스 ID입니다. 페더레이션 규칙이 둘 이상의 워크스페이스로 범위가 지정되어 있을 때 토큰 교환이 어느 워크스페이스를 대상으로 할지 알 수 있도록 이를 설정합니다. |

48| `API_TIMEOUT_MS` | API 요청의 타임아웃(밀리초)(기본값: 600000, 또는 10분; 최대: 2147483647). 느린 네트워크에서 요청이 시간 초과되거나 프록시를 통해 라우팅할 때 이를 증가시킵니다. 최대값을 초과하는 값은 기본 타이머를 오버플로우하여 요청이 즉시 실패하게 합니다. |49| `API_TIMEOUT_MS` | API 요청의 타임아웃(밀리초)(기본값: 600000, 또는 10분; 최대: 2147483647). 느린 네트워크에서 요청이 시간 초과되거나 프록시를 통해 라우팅할 때 이를 증가시킵니다. 최대값을 초과하는 값은 기본 타이머를 오버플로우하여 요청이 즉시 실패하게 합니다. |

49| `AWS_BEARER_TOKEN_BEDROCK` | 인증용 Bedrock API 키([Bedrock API 키](https://aws.amazon.com/blogs/machine-learning/accelerate-ai-development-with-amazon-bedrock-api-keys/) 참조) |50| `AWS_BEARER_TOKEN_BEDROCK` | 인증용 Bedrock API 키([Bedrock API 키](https://aws.amazon.com/blogs/machine-learning/accelerate-ai-development-with-amazon-bedrock-api-keys/) 참조) |

50| `BASH_DEFAULT_TIMEOUT_MS` | 장시간 실행되는 bash 명령의 기본 타임아웃(기본값: 120000, 또는 2분) |51| `BASH_DEFAULT_TIMEOUT_MS` | 장시간 실행되는 bash 명령의 기본 타임아웃(기본값: 120000, 또는 2분) |

138| `CLAUDE_CODE_PLUGIN_CACHE_DIR` | 플러그인 루트 디렉토리를 재정의합니다. 이름과 달리 이는 캐시 자체가 아닌 부모 디렉토리를 설정합니다: 마켓플레이스 및 플러그인 캐시는 이 경로 아래의 하위 디렉토리에 있습니다. 기본값은 `~/.claude/plugins`입니다. |139| `CLAUDE_CODE_PLUGIN_CACHE_DIR` | 플러그인 루트 디렉토리를 재정의합니다. 이름과 달리 이는 캐시 자체가 아닌 부모 디렉토리를 설정합니다: 마켓플레이스 및 플러그인 캐시는 이 경로 아래의 하위 디렉토리에 있습니다. 기본값은 `~/.claude/plugins`입니다. |

139| `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS` | 플러그인을 설치하거나 업데이트할 때 git 작업의 타임아웃(밀리초)(기본값: 120000). 큰 리포지토리 또는 느린 네트워크 연결의 경우 이 값을 증가시킵니다. [Git 작업 시간 초과](/ko/plugin-marketplaces#git-operations-time-out) 참조 |140| `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS` | 플러그인을 설치하거나 업데이트할 때 git 작업의 타임아웃(밀리초)(기본값: 120000). 큰 리포지토리 또는 느린 네트워크 연결의 경우 이 값을 증가시킵니다. [Git 작업 시간 초과](/ko/plugin-marketplaces#git-operations-time-out) 참조 |

140| `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE` | `git pull`이 실패할 때 기존 마켓플레이스 캐시를 유지하려면 `1`로 설정합니다. 다시 복제하면 같은 방식으로 실패할 오프라인 또는 에어갭 환경에서 유용합니다. [오프라인 환경에서 마켓플레이스 업데이트 실패](/ko/plugin-marketplaces#marketplace-updates-fail-in-offline-environments) 참조 |141| `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE` | `git pull`이 실패할 때 기존 마켓플레이스 캐시를 유지하려면 `1`로 설정합니다. 다시 복제하면 같은 방식으로 실패할 오프라인 또는 에어갭 환경에서 유용합니다. [오프라인 환경에서 마켓플레이스 업데이트 실패](/ko/plugin-marketplaces#marketplace-updates-fail-in-offline-environments) 참조 |

142| `CLAUDE_CODE_PLUGIN_PREFER_HTTPS` | GitHub `owner/repo` 플러그인 소스를 SSH 대신 HTTPS를 통해 복제하려면 `1`로 설정합니다. CI 러너, 컨테이너 또는 `github.com`에 대해 구성된 SSH 키가 없는 모든 환경에서 유용합니다. |

141| `CLAUDE_CODE_PLUGIN_SEED_DIR` | 하나 이상의 읽기 전용 플러그인 시드 디렉토리의 경로이며, Unix에서는 `:`로, Windows에서는 `;`로 구분됩니다. 이를 사용하여 사전 채워진 플러그인 디렉토리를 컨테이너 이미지에 번들로 제공합니다. Claude Code는 시작 시 이러한 디렉토리에서 마켓플레이스를 등록하고 다시 복제하지 않고 사전 캐시된 플러그인을 사용합니다. [컨테이너용 플러그인 사전 채우기](/ko/plugin-marketplaces#pre-populate-plugins-for-containers) 참조 |143| `CLAUDE_CODE_PLUGIN_SEED_DIR` | 하나 이상의 읽기 전용 플러그인 시드 디렉토리의 경로이며, Unix에서는 `:`로, Windows에서는 `;`로 구분됩니다. 이를 사용하여 사전 채워진 플러그인 디렉토리를 컨테이너 이미지에 번들로 제공합니다. Claude Code는 시작 시 이러한 디렉토리에서 마켓플레이스를 등록하고 다시 복제하지 않고 사전 캐시된 플러그인을 사용합니다. [컨테이너용 플러그인 사전 채우기](/ko/plugin-marketplaces#pre-populate-plugins-for-containers) 참조 |

142| `CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST` | Claude Code를 포함하고 대신 모델 공급자 라우팅을 관리하는 호스트 플랫폼에서 설정합니다. 설정하면 설정 파일의 `CLAUDE_CODE_USE_BEDROCK`, `ANTHROPIC_BASE_URL`, `ANTHROPIC_API_KEY`와 같은 공급자 선택, 엔드포인트, 인증 변수가 무시되므로 사용자 설정이 호스트의 라우팅을 재정의할 수 없습니다. Bedrock, Vertex, Foundry에 대한 자동 원격 분석 옵트아웃도 건너뛰므로 원격 분석은 표준 `DISABLE_TELEMETRY` 옵트아웃을 따릅니다. [API 공급자별 기본 동작](/ko/data-usage#default-behaviors-by-api-provider) 참조 |144| `CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST` | Claude Code를 포함하고 대신 모델 공급자 라우팅을 관리하는 호스트 플랫폼에서 설정합니다. 설정하면 설정 파일의 `CLAUDE_CODE_USE_BEDROCK`, `ANTHROPIC_BASE_URL`, `ANTHROPIC_API_KEY`와 같은 공급자 선택, 엔드포인트, 인증 변수가 무시되므로 사용자 설정이 호스트의 라우팅을 재정의할 수 없습니다. Bedrock, Vertex, Foundry에 대한 자동 원격 분석 옵트아웃도 건너뛰므로 원격 분석은 표준 `DISABLE_TELEMETRY` 옵트아웃을 따릅니다. [API 공급자별 기본 동작](/ko/data-usage#default-behaviors-by-api-provider) 참조 |

143| `CLAUDE_CODE_PROXY_RESOLVES_HOSTS` | 호출자 대신 프록시가 DNS 해석을 수행하도록 허용하려면 `1`로 설정합니다. 프록시가 호스트명 해석을 처리해야 하는 환경에 대해 옵트인합니다. |145| `CLAUDE_CODE_PROXY_RESOLVES_HOSTS` | 호출자 대신 프록시가 DNS 해석을 수행하도록 허용하려면 `1`로 설정합니다. 프록시가 호스트명 해석을 처리해야 하는 환경에 대해 옵트인합니다. |

152| `CLAUDE_CODE_SHELL` | 자동 셸 감지를 재정의합니다. 로그인 셸이 선호하는 작업 셸과 다를 때 유용합니다(예: `bash` vs `zsh`). |154| `CLAUDE_CODE_SHELL` | 자동 셸 감지를 재정의합니다. 로그인 셸이 선호하는 작업 셸과 다를 때 유용합니다(예: `bash` vs `zsh`). |

153| `CLAUDE_CODE_SHELL_PREFIX` | Claude Code가 생성하는 모든 셸 명령을 래핑할 명령 접두사: Bash 도구 호출, [훅](/ko/hooks) 명령, stdio [MCP 서버](/ko/mcp) 시작 명령. 로깅 또는 감사에 유용합니다. 예: `/path/to/logger.sh`를 설정하면 각 명령을 `/path/to/logger.sh <command>`로 실행합니다. |155| `CLAUDE_CODE_SHELL_PREFIX` | Claude Code가 생성하는 모든 셸 명령을 래핑할 명령 접두사: Bash 도구 호출, [훅](/ko/hooks) 명령, stdio [MCP 서버](/ko/mcp) 시작 명령. 로깅 또는 감사에 유용합니다. 예: `/path/to/logger.sh`를 설정하면 각 명령을 `/path/to/logger.sh <command>`로 실행합니다. |

154| `CLAUDE_CODE_SIMPLE` | 최소 시스템 프롬프트 및 Bash, 파일 읽기, 파일 편집 도구만으로 실행하려면 `1`로 설정합니다. `--mcp-config`의 MCP 도구는 계속 사용 가능합니다. 훅, skill, 플러그인, MCP 서버, 자동 메모리, CLAUDE.md의 자동 검색을 비활성화합니다. [`--bare`](/ko/headless#start-faster-with-bare-mode) CLI 플래그가 이를 설정합니다. |156| `CLAUDE_CODE_SIMPLE` | 최소 시스템 프롬프트 및 Bash, 파일 읽기, 파일 편집 도구만으로 실행하려면 `1`로 설정합니다. `--mcp-config`의 MCP 도구는 계속 사용 가능합니다. 훅, skill, 플러그인, MCP 서버, 자동 메모리, CLAUDE.md의 자동 검색을 비활성화합니다. [`--bare`](/ko/headless#start-faster-with-bare-mode) CLI 플래그가 이를 설정합니다. |

155| `CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT` | Opus 4.7에서 최소 시스템 프롬프트 및 축소된 도구 설명을 사용하려면 `1`로 설정합니다. 다른 모델에는 효과가 없습니다. 전체 도구 세트, 훅, MCP 서버, CLAUDE.md 검색은 계속 활성화됩니다. |157| `CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT` | 모든 모델에서 더 짧은 시스템 프롬프트 및 축소된 도구 설명을 사용하려면 `1`로 설정합니다. `0`, `false`, `no`, 또는 `off`로 설정하여 실험 또는 서버 구성이 그렇지 않으면 활성화할 때에도 옵트아웃합니다. 전체 도구 세트, 훅, MCP 서버, CLAUDE.md 검색은 계속 활성화됩니다. |

156| `CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH` | [Claude Platform on AWS](/ko/claude-platform-on-aws)에 대한 클라이언트 측 인증을 건너뜁니다. 게이트웨이가 요청에 자체 서명하는 경우 |158| `CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH` | [Claude Platform on AWS](/ko/claude-platform-on-aws)에 대한 클라이언트 측 인증을 건너뜁니다. 게이트웨이가 요청에 자체 서명하는 경우 |

157| `CLAUDE_CODE_SKIP_BEDROCK_AUTH` | Bedrock에 대한 AWS 인증을 건너뜁니다(예: LLM 게이트웨이를 사용할 때). |159| `CLAUDE_CODE_SKIP_BEDROCK_AUTH` | Bedrock에 대한 AWS 인증을 건너뜁니다(예: LLM 게이트웨이를 사용할 때). |

158| `CLAUDE_CODE_SKIP_FOUNDRY_AUTH` | Microsoft Foundry에 대한 Azure 인증을 건너뜁니다(예: LLM 게이트웨이를 사용할 때). |160| `CLAUDE_CODE_SKIP_FOUNDRY_AUTH` | Microsoft Foundry에 대한 Azure 인증을 건너뜁니다(예: LLM 게이트웨이를 사용할 때). |

200| `DISABLE_PROMPT_CACHING_HAIKU` | Haiku 모델에 대해 프롬프트 캐싱을 비활성화하려면 `1`로 설정합니다. |202| `DISABLE_PROMPT_CACHING_HAIKU` | Haiku 모델에 대해 프롬프트 캐싱을 비활성화하려면 `1`로 설정합니다. |

201| `DISABLE_PROMPT_CACHING_OPUS` | Opus 모델에 대해 프롬프트 캐싱을 비활성화하려면 `1`로 설정합니다. |203| `DISABLE_PROMPT_CACHING_OPUS` | Opus 모델에 대해 프롬프트 캐싱을 비활성화하려면 `1`로 설정합니다. |

202| `DISABLE_PROMPT_CACHING_SONNET` | Sonnet 모델에 대해 프롬프트 캐싱을 비활성화하려면 `1`로 설정합니다. |204| `DISABLE_PROMPT_CACHING_SONNET` | Sonnet 모델에 대해 프롬프트 캐싱을 비활성화하려면 `1`로 설정합니다. |

203| `DISABLE_TELEMETRY` | 원격 분석을 거부하려면 `1`로 설정합니다. 원격 분석 이벤트에는 코드, 파일 경로 또는 bash 명령과 같은 사용자 데이터가 포함되지 않습니다. |205| `DISABLE_TELEMETRY` | 원격 분석을 거부하려면 `1`로 설정합니다. 원격 분석 이벤트에는 코드, 파일 경로 또는 bash 명령과 같은 사용자 데이터가 포함되지 않습니다. 기능 플래그도 비활성화하므로 아직 롤아웃 중인 일부 기능을 사용하지 못할 수 있습니다. |

204| `DISABLE_UPDATES` | 수동 `claude update` 및 `claude install`을 포함한 모든 업데이트를 차단하려면 `1`로 설정합니다. `DISABLE_AUTOUPDATER`보다 더 엄격합니다. 자신의 채널을 통해 Claude Code를 배포하고 사용자가 자체 업데이트하지 않아야 할 때 사용합니다. |206| `DISABLE_UPDATES` | 수동 `claude update` 및 `claude install`을 포함한 모든 업데이트를 차단하려면 `1`로 설정합니다. `DISABLE_AUTOUPDATER`보다 더 엄격합니다. 자신의 채널을 통해 Claude Code를 배포하고 사용자가 자체 업데이트하지 않아야 할 때 사용합니다. |

205| `DISABLE_UPGRADE_COMMAND` | `/upgrade` 명령을 숨기려면 `1`로 설정합니다. |207| `DISABLE_UPGRADE_COMMAND` | `/upgrade` 명령을 숨기려면 `1`로 설정합니다. |

206| `DO_NOT_TRACK` | 원격 분석을 거부하려면 `1`로 설정합니다. `DISABLE_TELEMETRY` 설정과 동일합니다. [표준 교차 도구 규칙](https://consoledonottrack.com/)로 인정됩니다. |208| `DO_NOT_TRACK` | 원격 분석을 거부하려면 `1`로 설정합니다. `DISABLE_TELEMETRY` 설정과 동일합니다. [표준 교차 도구 규칙](https://consoledonottrack.com/)로 인정됩니다. |

156 156 

157### skills 사용157### skills 사용

158 158 

159`prompt` 입력은 [skill](/ko/skills) 호출뿐만 아니라 일반 텍스트도 허용합니다:

160 

161* 저장소의 `.claude/skills/` 디렉토리에 있는 skill의 경우, 작업 단계 전에 `actions/checkout`을 실행하고 `/skill-name`을 전달합니다.

162* 플러그인에 패키징된 skill의 경우, `plugin_marketplaces` 및 `plugins` 입력으로 플러그인을 설치하고 네임스페이스가 지정된 `/plugin-name:skill-name`을 전달합니다.

163 

164다음 워크플로우는 `code-review` 플러그인을 설치하고 각 새로운 또는 업데이트된 pull request에서 해당 skill을 실행합니다:

165 

159```yaml theme={null}166```yaml theme={null}

160name: Code Review167name: Code Review

161on:168on:

168 - uses: anthropics/claude-code-action@v1175 - uses: anthropics/claude-code-action@v1

169 with:176 with:

170 anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}177 anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

171 prompt: "Review this pull request for code quality, correctness, and security. Analyze the diff, then post your findings as review comments."178 plugin_marketplaces: "https://github.com/anthropics/claude-code.git"

172 claude_args: "--max-turns 5"179 plugins: "code-review@claude-code-plugins"

180 prompt: "/code-review:code-review ${{ github.repository }}/pull/${{ github.event.pull_request.number }}"

173```181```

174 182 

175### 프롬프트를 사용한 사용자 정의 자동화183### 프롬프트를 사용한 사용자 정의 자동화

622Claude Code Action v1은 단순화된 구성을 사용합니다:630Claude Code Action v1은 단순화된 구성을 사용합니다:

623 631 

624| 파라미터 | 설명 | 필수 |632| 파라미터 | 설명 | 필수 |

625| ------------------- | ------------------------------------------------ | ----- |633| --------------------- | ------------------------------------------------ | ----- |

626| `prompt` | Claude에 대한 지침 (일반 텍스트 또는 [skill](/ko/skills) 이름) | 아니오\* |634| `prompt` | Claude에 대한 지침 (일반 텍스트 또는 [skill](/ko/skills) 이름) | 아니오\* |

627| `claude_args` | Claude Code에 전달된 CLI 인수 | 아니오 |635| `claude_args` | Claude Code에 전달된 CLI 인수 | 아니오 |

636| `plugin_marketplaces` | 플러그인 마켓플레이스 Git URL의 줄 바꿈으로 구분된 목록 | 아니오 |

637| `plugins` | 실행 전에 설치할 플러그인 이름의 줄 바꿈으로 구분된 목록 | 아니오 |

628| `anthropic_api_key` | Claude API 키 | 예\*\* |638| `anthropic_api_key` | Claude API 키 | 예\*\* |

629| `github_token` | API 액세스용 GitHub 토큰 | 아니오 |639| `github_token` | API 액세스용 GitHub 토큰 | 아니오 |

630| `trigger_phrase` | 사용자 정의 트리거 구문 (기본값: "@claude") | 아니오 |640| `trigger_phrase` | 사용자 정의 트리거 구문 (기본값: "@claude") | 아니오 |

70 70 

71### Checkpoint71### Checkpoint

72 72 

73Claude가 각 편집을 수행하기 전에 캡처된 코드의 자동 스냅샷입니다. `Esc`를 두 번 누르거나 `/rewind`를 실행하여 코드, 대화 또는 둘 다를 이전 지점으로 복원합니다. 체크포인트는 세션에 로컬이며, git과 별개이고, Bash 도구를 통해 수행된 변경 사항을 추적하지 않습니다.73각 프롬프트를 전송할 때마다 생성되는 복원 지점입니다. Claude Code는 모든 편집 전에 파일을 스냅샷하므로 체크포인트가 파일을 되돌릴 수 있습니다. `Esc`를 두 번 누르거나 `/rewind`를 실행하여 코드, 대화 또는 둘 다를 이전 지점으로 복원하거나, 선택한 메시지에서 대화의 일부를 요약합니다. 체크포인트는 세션에 로컬이며, git과 별개이고, Bash 도구를 통해 수행된 변경 사항을 추적하지 않습니다.

74 74 

75자세히 알아보기: [체크포인팅](/ko/checkpointing)75자세히 알아보기: [체크포인팅](/ko/checkpointing)

76 76 

67많은 턴에 걸쳐 유지되는 조건은 일반적으로 다음을 포함합니다:67많은 턴에 걸쳐 유지되는 조건은 일반적으로 다음을 포함합니다:

68 68 

69* **하나의 측정 가능한 최종 상태**: 테스트 결과, 빌드 종료 코드, 파일 수, 빈 큐69* **하나의 측정 가능한 최종 상태**: 테스트 결과, 빌드 종료 코드, 파일 수, 빈 큐

70* **명시된 확인**: Claude가 이를 증명하는 방법(예: "`npm test` 종료 0" 또는 "`git status`가 깨끗함")70* **명시된 확인**: Claude가 이를 입증하는 방법(예: "`npm test` 종료 0" 또는 "`git status`가 깨끗함")

71* **중요한 제약 조건**: 그 과정에서 변경되지 않아야 하는 모든 것(예: "다른 테스트 파일은 수정되지 않음")71* **중요한 제약 조건**: 그 과정에서 변경되지 않아야 하는 모든 것(예: "다른 테스트 파일은 수정되지 않음")

72 72 

73조건은 최대 4,000자까지 가능합니다.73조건은 최대 4,000자까지 가능합니다.

108 108 

109### 비대화형으로 실행109### 비대화형으로 실행

110 110 

111`/goal`은 [비대화형 모드](/ko/headless)와 [원격 제어](/ko/remote-control)에서 작동합니다. `-p`로 목표를 설정하면 단일 호출에서 루프를 완료까지 실행합니다:111`/goal`은 [비대화형 모드](/ko/headless), [데스크톱 앱](/ko/desktop), [원격 제어](/ko/remote-control)에서 작동합니다. `-p`로 목표를 설정하면 단일 호출에서 루프를 완료까지 실행합니다:

112 112 

113```bash theme={null}113```bash theme={null}

114claude -p "/goal CHANGELOG.md has an entry for every PR merged this week"114claude -p "/goal CHANGELOG.md has an entry for every PR merged this week"

297| :-------------- | :-- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |297| :-------------- | :-- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

298| `type` | 예 | `"command"`, `"http"`, `"mcp_tool"`, `"prompt"` 또는 `"agent"` |298| `type` | 예 | `"command"`, `"http"`, `"mcp_tool"`, `"prompt"` 또는 `"agent"` |

299| `if` | 아니오 | `"Bash(git *)"` 또는 `"Edit(*.ts)"`와 같은 권한 규칙 구문을 사용하여 이 hook이 실행될 때를 필터링합니다. hook은 도구 호출이 패턴과 일치할 때만 생성되거나 Bash 명령이 너무 복잡하여 구문 분석할 수 없을 때 생성됩니다. 도구 이벤트에서만 평가됩니다: `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, `PermissionDenied`. 다른 이벤트에서는 `if`가 설정된 hook이 절대 실행되지 않습니다. [권한 규칙](/ko/permissions)과 동일한 구문을 사용합니다 |299| `if` | 아니오 | `"Bash(git *)"` 또는 `"Edit(*.ts)"`와 같은 권한 규칙 구문을 사용하여 이 hook이 실행될 때를 필터링합니다. hook은 도구 호출이 패턴과 일치할 때만 생성되거나 Bash 명령이 너무 복잡하여 구문 분석할 수 없을 때 생성됩니다. 도구 이벤트에서만 평가됩니다: `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, `PermissionDenied`. 다른 이벤트에서는 `if`가 설정된 hook이 절대 실행되지 않습니다. [권한 규칙](/ko/permissions)과 동일한 구문을 사용합니다 |

300| `timeout` | 아니오 | 취소하기 전 초 단위. 기본값: 명령의 경우 600, 프롬프트의 경우 30, 에이전트의 경우 60 |300| `timeout` | 아니오 | 취소하기 전 초 단위. 기본값: `command`, `http`, `mcp_tool`의 경우 600; `prompt`의 경우 30; `agent`의 경우 60. [`UserPromptSubmit`](#userpromptsubmit)은 `command`, `http`, `mcp_tool`의 기본값을 30으로 낮춥니다 |

301| `statusMessage` | 아니오 | hook이 실행되는 동안 표시되는 사용자 정의 스피너 메시지 |301| `statusMessage` | 아니오 | hook이 실행되는 동안 표시되는 사용자 정의 스피너 메시지 |

302| `once` | 아니오 | `true`인 경우 세션당 한 번만 실행된 후 제거됩니다. [Skill 및 에이전트의 Hook](#hooks-in-skills-and-agents)에서 선언된 hook에만 적용됨; 설정 파일 및 에이전트 frontmatter에서는 무시됨 |302| `once` | 아니오 | `true`인 경우 세션당 한 번만 실행된 후 제거됩니다. [Skill 및 에이전트의 Hook](#hooks-in-skills-and-agents)에서 선언된 hook에만 적용됨; 설정 파일 및 에이전트 frontmatter에서는 무시됨 |

303 303 

558 558 

559명령 hook은 stdin을 통해 JSON 데이터를 받고 종료 코드, stdout, stderr를 통해 결과를 전달합니다. HTTP hook은 POST 요청 본문으로 동일한 JSON을 받고 HTTP 응답 본문을 통해 결과를 전달합니다. 이 섹션에서는 모든 이벤트에 공통적인 필드와 동작을 다룹니다. [Hook 이벤트](#hook-events) 아래의 각 이벤트 섹션에는 특정 입력 스키마와 결정 제어 옵션이 포함됩니다.559명령 hook은 stdin을 통해 JSON 데이터를 받고 종료 코드, stdout, stderr를 통해 결과를 전달합니다. HTTP hook은 POST 요청 본문으로 동일한 JSON을 받고 HTTP 응답 본문을 통해 결과를 전달합니다. 이 섹션에서는 모든 이벤트에 공통적인 필드와 동작을 다룹니다. [Hook 이벤트](#hook-events) 아래의 각 이벤트 섹션에는 특정 입력 스키마와 결정 제어 옵션이 포함됩니다.

560 560 

561macOS 및 Linux에서 명령 hook은 v2.1.139부터 제어 터미널 없이 자신의 세션에서 실행됩니다. hook 프로세스 및 모든 자식 프로세스는 `/dev/tty`를 열거나 Claude Code 인터페이스에 직접 이스케이프 시퀀스를 보낼 수 없습니다. Windows에는 `/dev/tty`가 없습니다. 모든 플랫폼에서 사용자에게 메시지를 표시하려면 JSON 출력에서 [`systemMessage`](#json-output)를 반환합니다. 데스크톱 알림을 트리거하거나 창 제목을 설정하거나 벨을 울리려면 대신 [`terminalSequence`](#emit-terminal-notifications)를 반환합니다.

562 

561### 공통 입력 필드563### 공통 입력 필드

562 564 

563Hook 이벤트는 각 [hook 이벤트](#hook-events) 섹션에서 문서화된 이벤트 특정 필드 외에 이러한 필드를 JSON으로 받습니다. 명령 hook의 경우 이 JSON은 stdin을 통해 도착합니다. HTTP hook의 경우 POST 요청 본문으로 도착합니다.565Hook 이벤트는 각 [hook 이벤트](#hook-events) 섹션에서 문서화된 이벤트 특정 필드 외에 이러한 필드를 JSON으로 받습니다. 명령 hook의 경우 이 JSON은 stdin을 통해 도착합니다. HTTP hook의 경우 POST 요청 본문으로 도착합니다.

685 687 

686hook의 stdout은 JSON 객체만 포함해야 합니다. 셸 프로필이 시작 시 텍스트를 인쇄하면 JSON 구문 분석을 방해할 수 있습니다. 문제 해결 가이드의 [JSON 검증 실패](/ko/hooks-guide#json-validation-failed)를 참조하세요.688hook의 stdout은 JSON 객체만 포함해야 합니다. 셸 프로필이 시작 시 텍스트를 인쇄하면 JSON 구문 분석을 방해할 수 있습니다. 문제 해결 가이드의 [JSON 검증 실패](/ko/hooks-guide#json-validation-failed)를 참조하세요.

687 689 

688컨텍스트에 주입된 hook 출력 (`additionalContext`, `systemMessage` 또는 일반 stdout)은 10,000자로 제한됩니다. 이 제한을 초과하는 출력은 파일에 저장되고 미리보기 및 파일 경로로 바뀌며, 큰 도구 결과가 처리되는 방식과 동일합니다.690hook 출력 문자열 (`additionalContext`, `systemMessage`, 및 일반 stdout)은 10,000자로 제한됩니다. 이 제한을 초과하는 출력은 파일에 저장되고 미리보기 및 파일 경로로 바뀌며, 큰 도구 결과가 처리되는 방식과 동일합니다.

689 691 

690JSON 객체는 세 가지 종류의 필드를 지원합니다:692JSON 객체는 세 가지 종류의 필드를 지원합니다:

691 693 

694* \*\*`hookSpecificOutput`\*\*은 더 풍부한 제어가 필요한 이벤트를 위한 중첩 객체입니다. 이벤트 이름으로 설정된 `hookEventName` 필드가 필요합니다.696* \*\*`hookSpecificOutput`\*\*은 더 풍부한 제어가 필요한 이벤트를 위한 중첩 객체입니다. 이벤트 이름으로 설정된 `hookEventName` 필드가 필요합니다.

695 697 

696| 필드 | 기본값 | 설명 |698| 필드 | 기본값 | 설명 |

697| :--------------- | :------ | :----------------------------------------------------------------- |699| :----------------- | :------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

698| `continue` | `true` | `false`인 경우 hook이 실행된 후 Claude가 완전히 중지됩니다. 모든 이벤트 특정 결정 필드보다 우선합니다 |700| `continue` | `true` | `false`인 경우 hook이 실행된 후 Claude가 완전히 중지됩니다. 모든 이벤트 특정 결정 필드보다 우선합니다 |

699| `stopReason` | 없음 | `continue`가 `false`일 때 사용자에게 표시되는 메시지. Claude에는 표시되지 않음 |701| `stopReason` | 없음 | `continue`가 `false`일 때 사용자에게 표시되는 메시지. Claude에는 표시되지 않음 |

700| `suppressOutput` | `false` | `true`인 경우 디버그 로그에서 stdout을 숨깁니다 |702| `suppressOutput` | `false` | `true`인 경우 디버그 로그에서 stdout을 숨깁니다 |

701| `systemMessage` | 없음 | 사용자에게 표시되는 경고 메시지 |703| `systemMessage` | 없음 | 사용자에게 표시되는 경고 메시지 |

704| `terminalSequence` | 없음 | Claude Code가 사용자를 대신하여 내보낼 터미널 이스케이프 시퀀스 (예: 데스크톱 알림, 창 제목 또는 벨). OSC `0`/`1`/`2`/`9`/`99`/`777` 및 BEL로 제한됩니다. 값에 허용 목록 외의 항목이 포함되면 필드는 무시됩니다. `/dev/tty`를 사용할 수 없는 hook 대신 이를 사용합니다 |

702 705 

703Claude를 이벤트 유형과 관계없이 완전히 중지하려면:706Claude를 이벤트 유형과 관계없이 완전히 중지하려면:

704 707 

706{ "continue": false, "stopReason": "Build failed, fix errors before continuing" }709{ "continue": false, "stopReason": "Build failed, fix errors before continuing" }

707```710```

708 711 

712#### 터미널 알림 내보내기

713 

714`terminalSequence` 필드는 Claude Code v2.1.141 이상이 필요합니다.

715 

716Hook은 제어 터미널 없이 실행되므로 이스케이프 시퀀스를 `/dev/tty`에 직접 쓰는 것이 실패합니다. 대신 `terminalSequence` 필드에 이스케이프 시퀀스를 반환하면 Claude Code가 자신의 터미널 쓰기 경로를 통해 이를 내보냅니다. 이는 race-free이고 tmux 및 GNU screen 내에서 작동하며 `/dev/tty`가 없는 Windows에서도 작동합니다.

717 

718필드는 하나 이상의 허용 목록에 있는 이스케이프 시퀀스 문자열을 허용합니다:

719 

720* OSC `0`, `1`, `2`: 창 및 아이콘 제목

721* OSC `9`: iTerm2, ConEmu, Windows Terminal, 및 WezTerm 알림 (`9;4` 작업 표시줄 진행률 포함)

722* OSC `99`: Kitty 알림

723* OSC `777`: urxvt, Ghostty, 및 Warp 알림

724* 맨 BEL

725 

726시퀀스는 BEL 또는 ST로 종료될 수 있습니다. 허용 목록 외의 항목 (CSI 커서 및 색상 시퀀스, OSC 팔레트 시퀀스, OSC 8 하이퍼링크, OSC 52 클립보드 쓰기, 및 OSC 1337 포함)은 거부되고 필드는 무시됩니다.

727 

728아래 예제는 `Notification` hook에서 데스크톱 알림을 발생시킵니다. 이스케이프 시퀀스는 `printf` 8진수 이스케이프로 빌드되므로 제어 바이트가 셸 명령줄에 나타나지 않으며, `jq -n --arg`는 JSON 출력을 빌드하므로 알림 메시지의 따옴표, 백슬래시, 및 줄바꿈이 올바르게 이스케이프됩니다:

729 

730```bash theme={null}

731#!/bin/bash

732# Notification hook: Claude Code가 주의가 필요할 때 데스크톱을 ping합니다.

733input=$(cat)

734title="Claude Code'

735body=$(jq -r '.message // "Needs your attention"' <<<"$input")

736seq=$(printf '\033]777;notify;%s;%s\007' "$title" "$body")

737jq -nc --arg seq "$seq" '{terminalSequence: $seq}'

738```

739 

740`{ "terminalSequence": "..." }` 형태는 모든 셸 또는 언어에서 동일합니다. Windows에서는 PowerShell 또는 스크립트에서 이스케이프 문자열을 빌드하고 동일한 JSON 객체를 내보냅니다.

741 

742<Note>

743 `terminalSequence`는 이전에 `/dev/tty`에 직접 이스케이프 시퀀스를 작성한 hook의 지원되는 대체입니다. 허용 목록은 커서를 이동하거나 색상을 변경할 수 없는 시퀀스로 제한되므로 hook은 화면상의 프롬프트를 손상시킬 수 없습니다.

744</Note>

745 

709#### Claude를 위한 컨텍스트 추가746#### Claude를 위한 컨텍스트 추가

710 747 

711`additionalContext` 필드는 hook에서 Claude의 컨텍스트 윈도우로 문자열을 전달합니다. Claude Code는 문자열을 시스템 미리 알림으로 래핑하고 hook이 발생한 지점에서 대화에 삽입합니다. Claude는 다음 모델 요청에서 미리 알림을 읽지만 인터페이스에 채팅 메시지로 나타나지 않습니다.748`additionalContext` 필드는 hook에서 Claude의 컨텍스트 윈도우로 문자열을 전달합니다. Claude Code는 문자열을 시스템 미리 알림으로 래핑하고 hook이 발생한 지점에서 대화에 삽입합니다. Claude는 다음 모델 요청에서 미리 알림을 읽지만 인터페이스에 채팅 메시지로 나타나지 않습니다.

989 1026 

990사용자가 프롬프트를 제출할 때, Claude가 처리하기 전에 실행됩니다. 이를 통해 프롬프트/대화를 기반으로 추가 컨텍스트를 추가하거나, 프롬프트를 검증하거나, 특정 유형의 프롬프트를 차단할 수 있습니다.1027사용자가 프롬프트를 제출할 때, Claude가 처리하기 전에 실행됩니다. 이를 통해 프롬프트/대화를 기반으로 추가 컨텍스트를 추가하거나, 프롬프트를 검증하거나, 특정 유형의 프롬프트를 차단할 수 있습니다.

991 1028 

1029`UserPromptSubmit` hook은 `command`, `http`, `mcp_tool` 유형에 대해 기본 30초 시간 초과를 가지며, 이는 다른 이벤트에서 이러한 유형의 기본 600초보다 짧습니다. 이 hook은 모든 프롬프트 전에 실행되고 모델 처리가 완료될 때까지 차단하므로 stuck hook은 세션을 정지시킵니다. hook에 더 많은 시간이 필요하면 hook 항목에서 `timeout` 필드를 설정합니다.

1030 

992#### UserPromptSubmit 입력1031#### UserPromptSubmit 입력

993 1032 

994[공통 입력 필드](#common-input-fields) 외에도 UserPromptSubmit hook은 사용자가 제출한 텍스트를 포함하는 `prompt` 필드를 받습니다.1033[공통 입력 필드](#common-input-fields) 외에도 UserPromptSubmit hook은 사용자가 제출한 텍스트를 포함하는 `prompt` 필드를 받습니다.

2596 2635 

2597비동기 hook이 발생하면 Claude Code는 hook 프로세스를 시작하고 완료를 기다리지 않고 즉시 계속합니다. hook은 동기 hook과 동일한 JSON 입력을 stdin을 통해 받습니다.2636비동기 hook이 발생하면 Claude Code는 hook 프로세스를 시작하고 완료를 기다리지 않고 즉시 계속합니다. hook은 동기 hook과 동일한 JSON 입력을 stdin을 통해 받습니다.

2598 2637 

2599백그라운드 프로세스가 종료된 후 hook이 `systemMessage` 또는 `additionalContext` 필드가 있는 JSON 응답을 생성한 경우 해당 콘텐츠는 다음 대화 턴에서 Claude에 컨텍스트로 전달됩니다.2638백그라운드 프로세스가 종료된 후 hook이 `additionalContext` 필드가 있는 JSON 응답을 생성한 경우 해당 콘텐츠는 다음 대화 턴에서 Claude에 컨텍스트로 전달됩니다. `systemMessage` 필드는 Claude가 아닌 사용자에게 표시됩니다.

2600 2639 

2601비동기 hook 완료 알림은 기본적으로 억제됩니다. 보려면 `Ctrl+O`로 자세한 모드를 활성화하거나 `--verbose`로 Claude Code를 시작합니다.2640비동기 hook 완료 알림은 기본적으로 억제됩니다. 보려면 `Ctrl+O`로 자세한 모드를 활성화하거나 `--verbose`로 Claude Code를 시작합니다.

2602 2641 

2617 exit 02656 exit 0

2618fi2657fi

2619 2658 

2620# 테스트를 실행하고 systemMessage를 통해 결과를 보고합니다2659# 테스트를 실행하고 additionalContext를 통해 결과를 Claude에 보고합니다

2621RESULT=$(npm test 2>&1)2660RESULT=$(npm test 2>&1)

2622EXIT_CODE=$?2661EXIT_CODE=$?

2623 2662 

2624if [ $EXIT_CODE -eq 0 ]; then2663if [ $EXIT_CODE -eq 0 ]; then

2625 echo "{\"systemMessage\": \"Tests passed after editing $FILE_PATH\"}"2664 MSG="Tests passed after editing $FILE_PATH"

2626else2665else

2627 echo "{\"systemMessage\": \"Tests failed after editing $FILE_PATH: $RESULT\"}"2666 MSG="Tests failed after editing $FILE_PATH: $RESULT"

2628fi2667fi

2668jq -nc --arg msg "$MSG" '{hookSpecificOutput: {hookEventName: "PostToolUse", additionalContext: $msg}}'

2629```2669```

2630 2670 

2631그런 다음 프로젝트 루트의 `.claude/settings.json`에 이 구성을 추가합니다. `async: true` 플래그를 사용하면 Claude가 테스트 실행 중에 계속 작업할 수 있습니다:2671그런 다음 프로젝트 루트의 `.claude/settings.json`에 이 구성을 추가합니다. `async: true` 플래그를 사용하면 Claude가 테스트 실행 중에 계속 작업할 수 있습니다:

861 861 

862### 제한 사항862### 제한 사항

863 863 

864* 명령 hooks는 stdout, stderr 및 종료 코드를 통해서만 통신합니다. 직접 `/` 명령이나 도구 호출을 트리거할 수 없습니다. `additionalContext`를 통해 반환된 텍스트는 Claude가 일반 텍스트로 읽는 시스템 알림으로 주입됩니다. HTTP hooks는 응답 본문을 통해 통신합니다.864* 명령 hooks는 stdout, stderr 및 종료 코드를 통해서만 통신합니다. `/` 명령이나 도구 호출을 직접 트리거할 수 없습니다. `additionalContext`를 통해 반환된 텍스트는 Claude가 일반 텍스트로 읽는 시스템 알림으로 주입됩니다. HTTP hooks는 응답 본문을 통해 통신합니다.

865* Hook 타임아웃은 기본적으로 10분이며 `timeout` 필드(초 단위)로 hook당 구성 가능합니다.865* Hook 타임아웃은 유형에 따라 다릅니다. `timeout` 필드(초 단위)로 hook당 재정의할 수 있습니다.

866 * `command`, `http`, `mcp_tool`: 10분. `UserPromptSubmit`은 이를 30초로 낮춥니다.

867 * `prompt`: 30초.

868 * `agent`: 60초.

866* `PostToolUse` hooks는 도구가 이미 실행되었으므로 작업을 취소할 수 없습니다.869* `PostToolUse` hooks는 도구가 이미 실행되었으므로 작업을 취소할 수 없습니다.

867* `PermissionRequest` hooks는 [비대화형 모드](/ko/headless)(`-p`)에서 발생하지 않습니다. 자동화된 권한 결정을 위해 `PreToolUse` hooks를 사용합니다.870* `PermissionRequest` hooks는 [비대화형 모드](/ko/headless)(`-p`)에서 발생하지 않습니다. 자동화된 권한 결정을 위해 `PreToolUse` hooks를 사용합니다.

868* `Stop` hooks는 작업 완료 시에만이 아니라 Claude가 응답을 완료할 때마다 발생합니다. 사용자 중단 시에는 발생하지 않습니다. API 오류는 대신 [StopFailure](/ko/hooks#stopfailure)를 발생시킵니다.871* `Stop` hooks는 작업 완료 시에만이 아니라 Claude가 응답을 완료할 때마다 발생합니다. 사용자 중단 시에는 발생하지 않습니다. API 오류는 대신 [StopFailure](/ko/hooks#stopfailure)를 발생시킵니다.

458 458 

459많은 클라우드 기반 MCP 서버는 인증이 필요합니다. Claude Code는 보안 연결을 위해 OAuth 2.0을 지원합니다.459많은 클라우드 기반 MCP 서버는 인증이 필요합니다. Claude Code는 보안 연결을 위해 OAuth 2.0을 지원합니다.

460 460 

461Claude Code는 서버가 `401 Unauthorized`로 응답하고 인증 서버를 가리키는 `WWW-Authenticate` 헤더를 포함할 때 원격 서버를 인증이 필요한 것으로 표시합니다. 해당 응답을 반환하는 모든 사용자 정의 서버는 다른 원격 서버와 동일한 `/mcp` 인증 흐름을 받습니다.461Claude Code는 서버가 `401 Unauthorized` 또는 `403 Forbidden`으로 응답할 때 원격 서버를 인증이 필요한 것으로 표시합니다. 두 상태 코드 모두 서버를 `/mcp`에 플래그하여 OAuth 흐름을 완료할 수 있습니다. 인증 서버를 가리키는 `WWW-Authenticate` 헤더를 반환하는 사용자 정의 서버는 다른 원격 서버와 동일한 자동 검색을 받습니다.

462 462 

463<Steps>463<Steps>

464 <Step title="인증이 필요한 서버 추가">464 <Step title="인증이 필요한 서버 추가">

576 576 

577### OAuth 메타데이터 검색 재정의577### OAuth 메타데이터 검색 재정의

578 578 

579특정 OAuth 인증 서버 메타데이터 URL을 가리켜 기본 검색 체인을 우회하도록 Claude Code를 설정합니다. MCP 서버의 표준 엔드포인트가 오류를 반환하거나 내부 프록시를 통해 검색을 라우팅하려는 경우에 설정합니다. 기본적으로 Claude Code는 먼저 `/.well-known/oauth-protected-resource`에서 RFC 9728 보호된 리소스 메타데이터를 확인한 다음 `/.well-known/oauth-authorization-server`에서 RFC 8414 인증 서버 메타데이터로 돌아갑니다.579특정 OAuth 인증 서버 메타데이터 URL을 가리켜 기본 검색 체인을 우회하도록 Claude Code를 설정합니다. MCP 서버의 표준 엔드포인트가 오류를 반환하거나 내부 프록시를 통해 검색을 라우팅하려는 경우에 `authServerMetadataUrl`을 설정합니다. 기본적으로 Claude Code는 먼저 `/.well-known/oauth-protected-resource`에서 RFC 9728 보호된 리소스 메타데이터를 확인한 다음 `/.well-known/oauth-authorization-server`에서 RFC 8414 인증 서버 메타데이터로 돌아갑니다.

580 580 

581`.mcp.json`의 서버 구성의 `oauth` 객체에 `authServerMetadataUrl`을 설정합니다:581`.mcp.json`의 서버 구성의 `oauth` 객체에 `authServerMetadataUrl`을 설정합니다:

582 582 

51 사용 가능한 플래그:51 사용 가능한 플래그:

52 52 

53 | 플래그 | 설명 |53 | 플래그 | 설명 |

54 | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |54 | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

55 | `--name "My Project"` | claude.ai/code의 세션 목록에 표시되는 사용자 정의 세션 제목을 설정합니다. |55 | `--name "My Project"` | claude.ai/code의 세션 목록에 표시되는 사용자 정의 세션 제목을 설정합니다. |

56 | `--remote-control-session-name-prefix <prefix>` | 명시적 이름이 설정되지 않았을 때 자동 생성된 세션 이름의 접두사입니다. 기본값은 컴퓨터의 호스트 이름이며, `myhost-graceful-unicorn`과 같은 이름을 생성합니다. 동일한 효과를 위해 `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX`를 설정하세요. |56 | `--remote-control-session-name-prefix <prefix>` | 명시적 이름이 설정되지 않았을 때 자동 생성된 세션 이름의 접두사입니다. 기본값은 컴퓨터의 호스트 이름이며, `myhost-graceful-unicorn`과 같은 이름을 생성합니다. 동일한 효과를 위해 `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX`를 설정하세요. |

57 | `--spawn <mode>` | 서버가 세션을 생성하는 방식입니다.<br />• `same-dir` (기본값): 모든 세션이 현재 작업 디렉토리를 공유하므로 동일한 파일을 편집할 때 충돌할 수 있습니다.<br />• `worktree`: 각 온디맨드 세션은 자체 [git worktree](/ko/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees)를 가져옵니다. git 저장소가 필요합니다.<br />• `session`: 단일 세션 모드입니다. 정확히 하나의 세션을 제공하고 추가 연결을 거부합니다. 시작 시에만 설정합니다.<br />런타임에 `w`를 눌러 `same-dir`과 `worktree` 사이를 전환하세요. |57 | `--spawn <mode>` | 서버가 세션을 생성하는 방식입니다.<br />• `same-dir` (기본값): 모든 세션이 현재 작업 디렉토리를 공유하므로 동일한 파일을 편집할 때 충돌할 수 있습니다.<br />• `worktree`: 각 온디맨드 세션은 자체 [git worktree](/ko/worktrees)를 가져옵니다. git 저장소가 필요합니다.<br />• `session`: 단일 세션 모드입니다. 정확히 하나의 세션을 제공하고 추가 연결을 거부합니다. 시작 시에만 설정합니다.<br />런타임에 `w`를 눌러 `same-dir`과 `worktree` 사이를 전환하세요. |

58 | `--capacity <N>` | 최대 동시 세션 수입니다. 기본값은 32입니다. `--spawn=session`과 함께 사용할 수 없습니다. |58 | `--capacity <N>` | 최대 동시 세션 수입니다. 기본값은 32입니다. `--spawn=session`과 함께 사용할 수 없습니다. |

59 | `--verbose` | 자세한 연결 및 세션 로그를 표시합니다. |59 | `--verbose` | 자세한 연결 및 세션 로그를 표시합니다. |

60 | `--sandbox` / `--no-sandbox` | 파일 시스템 및 네트워크 격리를 위해 [샌드박싱](/ko/sandboxing)을 활성화하거나 비활성화합니다. 기본적으로 꺼져 있습니다. |60 | `--sandbox` / `--no-sandbox` | 파일 시스템 및 네트워크 격리를 위해 [샌드박싱](/ko/sandboxing)을 활성화하거나 비활성화합니다. 기본적으로 꺼져 있습니다. |

113 113 

114* **세션 URL 열기**: 모든 브라우저에서 URL을 열어 [claude.ai/code](https://claude.ai/code)의 세션으로 직접 이동합니다.114* **세션 URL 열기**: 모든 브라우저에서 URL을 열어 [claude.ai/code](https://claude.ai/code)의 세션으로 직접 이동합니다.

115* **QR 코드 스캔**: 세션 URL 옆에 표시된 QR 코드를 스캔하여 Claude 앱에서 직접 열 수 있습니다. `claude remote-control`을 사용하면 스페이스바를 눌러 QR 코드 표시를 전환할 수 있습니다.115* **QR 코드 스캔**: 세션 URL 옆에 표시된 QR 코드를 스캔하여 Claude 앱에서 직접 열 수 있습니다. `claude remote-control`을 사용하면 스페이스바를 눌러 QR 코드 표시를 전환할 수 있습니다.

116* **[claude.ai/code](https://claude.ai/code) 또는 Claude 앱 열기**: 세션 목록에서 이름으로 세션을 찾습니다. Remote Control 세션은 온라인 상태일 때 녹색 상태 점이 있는 컴퓨터 아이콘을 표시합니다.116* **[claude.ai/code](https://claude.ai/code) 또는 Claude 앱 열기**: 세션 목록에서 이름으로 세션을 찾습니다. Claude 모바일 앱에서 네비게이션의 **코드**를 탭하여 세션 목록에 도달하세요. Remote Control 세션은 온라인 상태일 때 녹색 상태 점이 있는 컴퓨터 아이콘을 표시합니다.

117 117 

118원격 세션 제목은 다음 순서로 선택됩니다:118원격 세션 제목은 다음 순서로 선택됩니다:

119 119 

130 130 

131### 모든 세션에 대해 Remote Control 활성화131### 모든 세션에 대해 Remote Control 활성화

132 132 

133기본적으로 Remote Control은 `claude remote-control`, `claude --remote-control` 또는 `/remote-control`을 명시적으로 실행할 때만 활성화됩니다. 모든 대화형 세션에 대해 자동으로 활성화하려면 Claude Code 내에서 `/config`를 실행하고 **모든 세션에 대해 Remote Control 활성화**를 `true`로 설정하세요. 비활성화하려면 `false`로 다시 설정하세요.133기본적으로 Remote Control은 `claude remote-control`, `claude --remote-control` 또는 `/remote-control`을 명시적으로 실행할 때만 활성화됩니다. 모든 대화형 세션에 대해 자동으로 활성화하려면 Claude Code 내에서 `/config`를 실행하고 **모든 세션에 대해 Remote Control 활성화**를 `true`로 설정하세요. 비활성화하려면 `false`로 다시 설정하세요. Desktop 앱에서는 **설정 → Claude Code → 기본적으로 원격 제어 활성화**에서도 전환할 수 있습니다.

134 134 

135이 설정이 켜져 있으면 각 대화형 Claude Code 프로세스는 하나의 원격 세션을 등록합니다. 여러 인스턴스를 실행하면 각각 자체 환경 및 세션을 가져옵니다. 단일 프로세스에서 여러 동시 세션을 실행하려면 [서버 모드](#remote-control-세션-시작)를 대신 사용하세요.135이 설정이 켜져 있으면 각 대화형 Claude Code 프로세스는 하나의 원격 세션을 등록합니다. 여러 인스턴스를 실행하면 각각 자체 환경 및 세션을 가져옵니다. 단일 프로세스에서 여러 동시 세션을 실행하려면 [서버 모드](#remote-control-세션-시작)를 대신 사용하세요.

136 136 

215 215 

216### "Remote Control이 조직의 정책에 의해 비활성화되었습니다"216### "Remote Control이 조직의 정책에 의해 비활성화되었습니다"

217 217 

218이 오류에는 세 가지 서로 다른 원인이 있습니다. 먼저 `/status`를 실행하여 사용 중인 로그인 방법과 구독을 확인하세요.218이 오류에는 네 가지 서로 다른 원인이 있습니다. 먼저 `/status`를 실행하여 사용 중인 로그인 방법과 구독을 확인하세요.

219 219 

220* **API 키 또는 Console 계정으로 인증됨**: Remote Control은 claude.ai OAuth가 필요합니다. `/login`을 실행하고 claude.ai 옵션을 선택하세요. `ANTHROPIC_API_KEY`가 환경에 설정되어 있으면 설정을 해제하세요.220* **API 키 또는 Console 계정으로 인증됨**: Remote Control은 claude.ai OAuth가 필요합니다. `/login`을 실행하고 claude.ai 옵션을 선택하세요. `ANTHROPIC_API_KEY`가 환경에 설정되어 있으면 설정을 해제하세요.

221* **Team 또는 Enterprise 관리자가 활성화하지 않음**: Remote Control은 이러한 요금제에서 기본적으로 꺼져 있습니다. 관리자는 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code)에서 **Remote Control** 토글을 켜서 활성화할 수 있습니다. 이는 서버 측 조직 설정이며 [관리 전용 설정](/ko/permissions#managed-only-settings) 키가 아닙니다.221* **Team 또는 Enterprise 관리자가 활성화하지 않음**: Remote Control은 이러한 요금제에서 기본적으로 꺼져 있습니다. 관리자는 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code)에서 **Remote Control** 토글을 켜서 활성화할 수 있습니다. 이 토글은 서버 측 조직 설정입니다.

222* **관리자 토글이 회색으로 표시됨**: 조직에 Remote Control과 호환되지 않는 데이터 보존 또는 규정 준수 구성이 있습니다. 이는 관리자 패널에서 변경할 수 없습니다. Anthropic 지원팀에 문의하여 옵션을 논의하세요.222* **관리자 토글이 회색으로 표시됨**: 조직에 Remote Control과 호환되지 않는 데이터 보존 또는 규정 준수 구성이 있습니다. 이는 관리자 패널에서 변경할 수 없습니다. Anthropic 지원팀에 문의하여 옵션을 논의하세요.

223* **오류에 `disableRemoteControl`이 언급됨**: IT 관리자가 조직 전체 토글과 무관하게 [관리 설정](/ko/settings#settings-files)을 통해 이 장치에서 Remote Control을 비활성화했습니다.

223 224 

224### "원격 자격 증명 가져오기 실패"225### "원격 자격 증명 가져오기 실패"

225 226 

158 158 

159이것이 subagent를 만들고 관리하는 권장 방법입니다. 수동 생성 또는 자동화의 경우 subagent 파일을 직접 추가할 수도 있습니다.159이것이 subagent를 만들고 관리하는 권장 방법입니다. 수동 생성 또는 자동화의 경우 subagent 파일을 직접 추가할 수도 있습니다.

160 160 

161명령줄에서 [agent view](/ko/agent-view)를 열지 않고 구성된 모든 subagent를 나열하려면 `claude agents`의 출력을 파이프합니다. 예를 들어 `claude agents | cat`은 소스별로 그룹화된 에이전트를 인쇄하고 더 높은 우선순위 정의로 재정의되는 에이전트를 나타냅니다.

162 

163### Subagent 범위 선택161### Subagent 범위 선택

164 162 

165Subagent는 YAML frontmatter가 있는 Markdown 파일입니다. 범위에 따라 다른 위치에 저장합니다. 여러 subagent가 같은 이름을 공유할 때 더 높은 우선순위 위치가 우선합니다.163Subagent는 YAML frontmatter가 있는 Markdown 파일입니다. 범위에 따라 다른 위치에 저장합니다. 여러 subagent가 같은 이름을 공유할 때 더 높은 우선순위 위치가 우선합니다.

178 176 

179**사용자 subagent** (`~/.claude/agents/`)는 모든 프로젝트에서 사용 가능한 개인 subagent입니다.177**사용자 subagent** (`~/.claude/agents/`)는 모든 프로젝트에서 사용 가능한 개인 subagent입니다.

180 178 

179Claude Code는 `.claude/agents/` 및 `~/.claude/agents/`를 재귀적으로 스캔하므로 `agents/review/` 또는 `agents/research/`와 같은 하위 폴더로 정의를 구성할 수 있습니다. 하위 디렉토리 경로는 subagent가 식별되거나 호출되는 방식에 영향을 주지 않습니다. 왜냐하면 ID는 `name` frontmatter 필드에서만 나오기 때문입니다. 전체 트리에서 `name` 값을 고유하게 유지합니다: 한 범위 내의 두 파일이 같은 이름을 선언하면 Claude Code는 경고 없이 하나를 유지하고 다른 하나를 버립니다.

180 

181플러그인 `agents/` 디렉토리도 재귀적으로 스캔됩니다. 프로젝트 및 사용자 범위와 달리 플러그인의 `agents/` 디렉토리 내의 하위 폴더는 [범위가 지정된 식별자](#invoke-subagents-explicitly)의 일부가 됩니다: 플러그인 `my-plugin`의 `agents/review/security.md`에 있는 파일은 `my-plugin:review:security`로 등록됩니다.

182 

181**CLI 정의 subagent**는 Claude Code를 시작할 때 JSON으로 전달됩니다. 해당 세션에만 존재하며 디스크에 저장되지 않으므로 빠른 테스트 또는 자동화 스크립트에 유용합니다. 단일 `--agents` 호출에서 여러 subagent를 정의할 수 있습니다:183**CLI 정의 subagent**는 Claude Code를 시작할 때 JSON으로 전달됩니다. 해당 세션에만 존재하며 디스크에 저장되지 않으므로 빠른 테스트 또는 자동화 스크립트에 유용합니다. 단일 `--agents` 호출에서 여러 subagent를 정의할 수 있습니다:

182 184 

183<Tabs>185<Tabs>

638 640 

639전체 메시지는 여전히 Claude로 이동하며, Claude는 요청한 내용을 기반으로 subagent의 작업 프롬프트를 작성합니다. @-mention은 Claude가 호출하는 subagent를 제어하며, 받는 프롬프트는 제어하지 않습니다.641전체 메시지는 여전히 Claude로 이동하며, Claude는 요청한 내용을 기반으로 subagent의 작업 프롬프트를 작성합니다. @-mention은 Claude가 호출하는 subagent를 제어하며, 받는 프롬프트는 제어하지 않습니다.

640 642 

641활성화된 [플러그인](/ko/plugins)에서 제공하는 Subagent는 typeahead에 `<plugin-name>:<agent-name>`으로 나타납니다. 세션에서 현재 실행 중인 명명된 background subagent도 typeahead에 나타나며 이름 옆에 상태를 표시합니다. 선택기를 사용하지 않고 수동으로 mention을 입력할 수도 있습니다: 로컬 subagent의 경우 `@agent-<name>`, 플러그인 subagent의 경우 `@agent-<plugin-name>:<agent-name>`.643활성화된 [플러그인](/ko/plugins)에서 제공하는 Subagent는 typeahead에 `my-plugin:code-reviewer` 또는 플러그인이 [agents를 하위 폴더로 구성](#choose-the-subagent-scope)할 때 `my-plugin:review:security`와 같은 범위가 지정된 이름으로 나타납니다. 세션에서 현재 실행 중인 명명된 background subagent도 typeahead에 나타나며 이름 옆에 상태를 표시합니다. 선택기를 사용하지 않고 수동으로 mention을 입력할 수도 있습니다: 로컬 subagent의 경우 `@agent-<name>`, 플러그인 subagent의 경우 범위가 지정된 이름 뒤에 `@agent-`를 입력합니다. 예를 들어 `@agent-my-plugin:code-reviewer`입니다.

642 644 

643**전체 세션을 subagent로 실행합니다.** [`--agent <name>`](/ko/cli-reference)을 전달하여 주 스레드 자체가 해당 subagent의 시스템 프롬프트, 도구 제한 및 모델을 취하는 세션을 시작합니다:645**전체 세션을 subagent로 실행합니다.** [`--agent <name>`](/ko/cli-reference)을 전달하여 주 스레드 자체가 해당 subagent의 시스템 프롬프트, 도구 제한 및 모델을 취하는 세션을 시작합니다:

644 646 

650 652 

651이것은 내장 및 사용자 정의 subagent에서 작동하며, 세션을 재개할 때 선택이 유지됩니다.653이것은 내장 및 사용자 정의 subagent에서 작동하며, 세션을 재개할 때 선택이 유지됩니다.

652 654 

653플러그인 제공 subagent의 경우 범위가 지정된 이름을 전달합니다: `claude --agent <plugin-name>:<agent-name>`.655플러그인 제공 subagent의 경우 범위가 지정된 이름을 전달합니다: `claude --agent <plugin-name>:<agent-name>`. 플러그인이 에이전트를 `agents/` 디렉토리의 하위 폴더에 배치하면 범위가 지정된 이름에 하위 폴더를 포함합니다. 예를 들어 `claude --agent my-plugin:review:security`입니다.

654 656 

655프로젝트의 모든 세션에 대한 기본값으로 만들려면 `.claude/settings.json`에서 `agent`를 설정합니다:657프로젝트의 모든 세션에 대한 기본값으로 만들려면 `.claude/settings.json`에서 `agent`를 설정합니다:

656 658 

16 16 

17음성 받아쓰기는 기록된 오디오를 Anthropic의 서버로 스트리밍하여 전사합니다. 오디오는 로컬에서 처리되지 않습니다. 음성 텍스트 변환 서비스는 Claude.ai 계정으로 인증할 때만 사용 가능하며, Claude Code가 Anthropic API 키, Amazon Bedrock, Google Vertex AI 또는 Microsoft Foundry를 직접 사용하도록 구성된 경우에는 사용할 수 없습니다. 전사는 Claude 메시지나 토큰을 소비하지 않으며 `/usage`에 표시된 한도에 포함되지 않습니다. Anthropic이 데이터를 처리하는 방법은 [데이터 사용](/ko/data-usage)을 참조하세요.17음성 받아쓰기는 기록된 오디오를 Anthropic의 서버로 스트리밍하여 전사합니다. 오디오는 로컬에서 처리되지 않습니다. 음성 텍스트 변환 서비스는 Claude.ai 계정으로 인증할 때만 사용 가능하며, Claude Code가 Anthropic API 키, Amazon Bedrock, Google Vertex AI 또는 Microsoft Foundry를 직접 사용하도록 구성된 경우에는 사용할 수 없습니다. 전사는 Claude 메시지나 토큰을 소비하지 않으며 `/usage`에 표시된 한도에 포함되지 않습니다. Anthropic이 데이터를 처리하는 방법은 [데이터 사용](/ko/data-usage)을 참조하세요.

18 18 

19음성 받아쓰기는 또한 로컬 마이크 접근이 필요하므로 [웹의 Claude Code](/ko/claude-code-on-the-web) 또는 SSH 세션과 같은 원격 환경에서는 작동하지 않습니다. WSL에서 음성 받아쓰기는 오디오 접근을 위해 WSLg가 필요하며, 이는 Windows 11의 WSL2에 포함되어 있습니다. Windows 10 또는 WSL1에서는 대신 기본 Windows에서 Claude Code를 실행하세요.19음성 받아쓰기는 또한 로컬 마이크 접근이 필요하므로 [웹의 Claude Code](/ko/claude-code-on-the-web) 또는 SSH 세션과 같은 원격 환경에서는 작동하지 않습니다. WSL에서 음성 받아쓰기는 오디오 접근을 위해 WSLg가 필요하며, 이는 Windows 10 또는 11의 Microsoft Store에서 설치된 WSL2에 포함되어 있습니다. WSLg를 사용할 수 없는 경우(예: WSL1), 대신 기본 Windows에서 Claude Code를 실행하세요.

20 20 

21오디오 녹음은 macOS, Linux 및 Windows의 기본 제공 네이티브 모듈을 사용합니다. Linux에서 네이티브 모듈을 로드할 수 없으면 Claude Code는 ALSA utils의 `arecord` 또는 SoX의 `rec`으로 폴백합니다. 둘 다 사용할 수 없으면 `/voice`는 패키지 관리자에 대한 설치 명령을 출력합니다.21오디오 녹음은 macOS, Linux 및 Windows의 기본 제공 네이티브 모듈을 사용합니다. Linux에서 네이티브 모듈을 로드할 수 없으면 Claude Code는 ALSA utils의 `arecord` 또는 SoX의 `rec`으로 폴백합니다. 둘 다 사용할 수 없으면 `/voice`는 패키지 관리자에 대한 설치 명령을 출력합니다.

22 22 

51}51}

52```52```

53 53 

54음성 받아쓰기가 활성화되어 있는 동안 입력 바닥글은 프롬프트가 비어 있을 때 `hold Space to speak` 힌트를 표시합니다. 힌트 텍스트는 두 모드 모두에서 동일하며, [사용자 정의 상태 줄](/ko/statusline)이 구성된 경우 나타나지 않습니다.54음성 받아쓰기가 활성화되어 있는 동안 입력 바닥글은 프롬프트가 비어 있을 때 `hold Space to speak` 힌트를 표시합니다. 힌트는 현재 `voice:pushToTalk` 바인딩을 반영하며, [받아쓰기 키를 다시 바인딩](#rebind-the-dictation-key)하면 업데이트됩니다. 힌트 텍스트는 두 모드 모두에서 동일하며, [사용자 정의 상태 줄](/ko/statusline)이 구성된 경우 나타나지 않습니다.

55 55 

56전사는 두 모드 모두에서 코딩 어휘에 맞게 조정됩니다. `regex`, `OAuth`, `JSON` 및 `localhost`와 같은 일반적인 개발 용어가 올바르게 인식되며, 현재 프로젝트 이름과 git 분기 이름이 자동으로 인식 힌트로 추가됩니다.56전사는 두 모드 모두에서 코딩 어휘에 맞게 조정됩니다. `regex`, `OAuth`, `JSON` 및 `localhost`와 같은 일반적인 개발 용어가 올바르게 인식되며, 현재 프로젝트 이름과 git 분기 이름이 자동으로 인식 힌트로 추가됩니다.

57 57 

155* **`Voice mode requires a Claude.ai account`**: API 키 또는 타사 공급자로 인증되었습니다. `/login`을 실행하여 Claude.ai 계정으로 로그인하세요.155* **`Voice mode requires a Claude.ai account`**: API 키 또는 타사 공급자로 인증되었습니다. `/login`을 실행하여 Claude.ai 계정으로 로그인하세요.

156* **`Microphone access is denied`**: 시스템 설정에서 터미널에 마이크 권한을 부여하세요. macOS에서는 시스템 설정 → 개인정보 보호 및 보안 → 마이크로 이동하여 터미널 앱을 활성화한 다음 `/voice`를 다시 실행하세요. Windows에서는 설정 → 개인정보 보호 및 보안 → 마이크로 이동하여 데스크톱 앱에 대한 마이크 접근을 켜세요. 그런 다음 `/voice`를 다시 실행하세요. 터미널이 macOS 설정에 나열되지 않으면 [macOS 마이크 설정에 나열되지 않은 터미널](#terminal-not-listed-in-macos-microphone-settings)을 참조하세요.156* **`Microphone access is denied`**: 시스템 설정에서 터미널에 마이크 권한을 부여하세요. macOS에서는 시스템 설정 → 개인정보 보호 및 보안 → 마이크로 이동하여 터미널 앱을 활성화한 다음 `/voice`를 다시 실행하세요. Windows에서는 설정 → 개인정보 보호 및 보안 → 마이크로 이동하여 데스크톱 앱에 대한 마이크 접근을 켜세요. 그런 다음 `/voice`를 다시 실행하세요. 터미널이 macOS 설정에 나열되지 않으면 [macOS 마이크 설정에 나열되지 않은 터미널](#terminal-not-listed-in-macos-microphone-settings)을 참조하세요.

157* **Linux에서 `No audio recording tool found`**: 네이티브 오디오 모듈을 로드할 수 없고 폴백이 설치되지 않았습니다. 오류 메시지에 표시된 명령으로 SoX를 설치하세요. 예: `sudo apt-get install sox`.157* **Linux에서 `No audio recording tool found`**: 네이티브 오디오 모듈을 로드할 수 없고 폴백이 설치되지 않았습니다. 오류 메시지에 표시된 명령으로 SoX를 설치하세요. 예: `sudo apt-get install sox`.

158* **`Voice mode could not find a working audio recorder in WSL`**: WSLg는 ALSA 장치가 아닌 PulseAudio를 통해 오디오를 라우팅하므로 SoX는 PulseAudio 백엔드가 명시적으로 설치되어야 합니다. `sudo apt install sox libsox-fmt-pulse`를 실행하세요. `sox`만 설치하면 ALSA 백엔드가 함께 설치되는데, WSL에서는 `/dev/snd` 장치가 없기 때문에 녹음할 수 없습니다.

159* **`Voice input is failing repeatedly and has been paused`**: 음성 받아쓰기가 여러 번 시작 실패를 겪었고 하나가 성공할 때까지 새 세션 시도를 중단했습니다. 이는 일반적으로 이 호스트의 마이크 또는 오디오 스택이 오디오를 캡처할 수 없음을 의미합니다. 예를 들어 헤드리스 서버, 오디오 패스스루가 없는 원격 셸 또는 거부된 마이크 권한이 있습니다. 작동하는 입력 장치를 확인하고 위의 항목에서 근본 원인을 해결한 다음 음성을 다시 트리거하세요.

158* **누르고 있기 모드에서 `Space`를 누르고 있어도 아무것도 일어나지 않음**: 누르고 있는 동안 프롬프트 입력을 봅니다. 공백이 계속 누적되면 음성 받아쓰기가 꺼져 있을 가능성이 높습니다. `/voice hold`를 실행하여 활성화하세요. 1\~2개의 공백만 나타나고 그 다음 아무것도 없으면 음성 받아쓰기는 켜져 있지만 누르고 있기 감지가 트리거되지 않습니다. 누르고 있기 감지는 터미널이 키 반복 이벤트를 보내야 하므로 OS 수준에서 키 반복이 비활성화되면 누르고 있는 키를 감지할 수 없습니다. 키 반복 요구 사항을 피하려면 `/voice tap`으로 탭 모드로 전환하세요.160* **누르고 있기 모드에서 `Space`를 누르고 있어도 아무것도 일어나지 않음**: 누르고 있는 동안 프롬프트 입력을 봅니다. 공백이 계속 누적되면 음성 받아쓰기가 꺼져 있을 가능성이 높습니다. `/voice hold`를 실행하여 활성화하세요. 1\~2개의 공백만 나타나고 그 다음 아무것도 없으면 음성 받아쓰기는 켜져 있지만 누르고 있기 감지가 트리거되지 않습니다. 누르고 있기 감지는 터미널이 키 반복 이벤트를 보내야 하므로 OS 수준에서 키 반복이 비활성화되면 누르고 있는 키를 감지할 수 없습니다. 키 반복 요구 사항을 피하려면 `/voice tap`으로 탭 모드로 전환하세요.

159* **탭 모드에서 `Space`를 탭하면 녹음 대신 공백을 입력함**: 첫 번째 탭은 프롬프트 입력이 비어 있을 때만 녹음을 시작합니다. 먼저 입력을 지우거나 `/voice tap`을 실행하여 탭 모드에 있는지 확인하세요.161* **탭 모드에서 `Space`를 탭하면 녹음 대신 공백을 입력함**: 첫 번째 탭은 프롬프트 입력이 비어 있을 때만 녹음을 시작합니다. 먼저 입력을 지우거나 `/voice tap`을 실행하여 탭 모드에 있는지 확인하세요.

160* **`No audio detected from microphone`**: 녹음이 시작되었지만 침묵을 캡처했습니다. 올바른 입력 장치가 시스템 기본값으로 설정되어 있고 입력 수준이 음소거되거나 0에 가깝지 않은지 확인하세요. Windows에서는 설정 → 시스템 → 사운드 → 입력을 열고 마이크를 선택하세요. macOS에서는 시스템 설정 → 사운드 → 입력을 열어보세요.162* **`No audio detected from microphone`**: 녹음이 시작되었지만 침묵을 캡처했습니다. 올바른 입력 장치가 시스템 기본값으로 설정되어 있고 입력 수준이 음소거되거나 0에 가깝지 않은지 확인하세요. Windows에서는 설정 → 시스템 → 사운드 → 입력을 열고 마이크를 선택하세요. macOS에서는 시스템 설정 → 사운드 → 입력을 열어보세요.