Documentation 2026-10-09 23:02 UTC to 2026-10-10 17:02 UTC

124 124 

125부분 메시지가 활성화되지 않은 경우, `StreamEvent`를 제외한 모든 메시지 유형을 수신합니다. 일반적인 유형으로는 `SystemMessage` (세션 초기화), `AssistantMessage` (완전한 콘텐츠 블록), `ResultMessage` (최종 결과), 그리고 대화 기록이 압축되었을 때를 나타내는 컴팩트 경계 메시지 (TypeScript의 `SDKCompactBoundaryMessage`; Python의 `SystemMessage`와 서브타입 `"compact_boundary"`)가 있습니다.125부분 메시지가 활성화되지 않은 경우, `StreamEvent`를 제외한 모든 메시지 유형을 수신합니다. 일반적인 유형으로는 `SystemMessage` (세션 초기화), `AssistantMessage` (완전한 콘텐츠 블록), `ResultMessage` (최종 결과), 그리고 대화 기록이 압축되었을 때를 나타내는 컴팩트 경계 메시지 (TypeScript의 `SDKCompactBoundaryMessage`; Python의 `SystemMessage`와 서브타입 `"compact_boundary"`)가 있습니다.

126 126 

127<h3 id="handle-a-stream-that’s-cut-off">

128 중단된 스트림 처리하기

129</h3>

130 

131턴을 중단하거나 연결이 끊기는 경우처럼 스트림이 메시지 도중에 중단되더라도, 턴이 끝나기 전에 해당 메시지의 `message_stop`을 수신합니다. 중단된 텍스트 블록이나 thinking 블록도 `content_block_stop`을 받습니다. 중단된 도구 호출은 이를 받지 않으므로, 도구 호출의 블록이 아직 열려 있는 상태에서 `message_stop`이 도착하면 해당 호출의 입력을 불완전한 것으로 처리해야 합니다.

132 

133Claude Code v2.1.290 이전에는 중단된 스트림이 `message_stop` 없이 턴을 종료할 수 있었기 때문에, 스트림 이벤트로 렌더링한 응답이 계속 진행 중으로 표시될 수 있었습니다. TypeScript Agent SDK는 v0.3.290부터, Python Agent SDK는 v0.2.164부터 Claude Code v2.1.290 이상을 번들로 포함합니다. 턴이 끝난 후에도 응답이 계속 진행 중으로 표시된다면 SDK를 업데이트하십시오.

134 

127<h2 id="stream-tool-calls">135<h2 id="stream-tool-calls">

128 도구 호출 스트리밍136 도구 호출 스트리밍

129</h2>137</h2>

1588 1588 

1589서브에이전트의 메시지를 작업 이벤트와 매칭할 때는 메시지의 `parent_tool_use_id`를 작업 이벤트의 `tool_use_id`와 짝짓지 말고 `agent_id`를 기준으로 매칭하세요. 도구 호출이 서브에이전트를 재개하면 작업 이벤트는 해당 호출의 `tool_use_id`를 가지지만, 메시지는 서브에이전트를 처음 시작한 도구 호출의 `parent_tool_use_id`를 유지하므로 두 값이 더 이상 일치하지 않습니다.1589서브에이전트의 메시지를 작업 이벤트와 매칭할 때는 메시지의 `parent_tool_use_id`를 작업 이벤트의 `tool_use_id`와 짝짓지 말고 `agent_id`를 기준으로 매칭하세요. 도구 호출이 서브에이전트를 재개하면 작업 이벤트는 해당 호출의 `tool_use_id`를 가지지만, 메시지는 서브에이전트를 처음 시작한 도구 호출의 `parent_tool_use_id`를 유지하므로 두 값이 더 이상 일치하지 않습니다.

1590 1590 

1591Claude Code는 [`user_message_uuid`](#user_message_uuid)에 설명된 조건에 따라 턴의 첫 번째 어시스턴트 메시지에 `user_message_uuid`와 `user_message_uuids`를 설정합니다. 재시작으로 중단된 턴을 Claude Code가 다시 실행할 때, 해당 필드를 가진 재실행의 어시스턴트 메시지에는 [`resume_reason`](#resume_reason)도 포함됩니다.1591Claude Code는 [`user_message_uuid`](#user_message_uuid)에 설명된 조건에 따라 턴의 첫 번째 어시스턴트 메시지에 `user_message_uuid`와 `user_message_uuids`를 설정합니다. 재시작으로 중단된 턴을 이어가는 턴인 경우, 해당 필드를 포함하는 어시스턴트 메시지에는 [`resume_reason`](#resume_reason)도 포함됩니다.

1592 1592 

1593`timestamp`는 메시지를 생성한 프로세스에서 메시지 콘텐츠 생성이 완료된 ISO 8601 시각입니다. 이 값은 해당 머신의 시계에서 가져오므로 표시 용도로만 사용하고 메시지 정렬에는 사용하지 마세요. 하나의 API 턴이 같은 `message.id`를 공유하는 여러 어시스턴트 메시지를 생성할 수 있으며, 각 메시지는 고유한 `timestamp`를 가집니다. 이 필드가 없으면 메시지를 수신한 시각을 대신 사용하세요.1593`timestamp`는 메시지를 생성한 프로세스에서 메시지 콘텐츠 생성이 완료된 ISO 8601 시각입니다. 이 값은 해당 머신의 시계에서 가져오므로 표시 용도로만 사용하고 메시지 정렬에는 사용하지 마세요. 하나의 API 턴이 같은 `message.id`를 공유하는 여러 어시스턴트 메시지를 생성할 수 있으며, 각 메시지는 고유한 `timestamp`를 가집니다. 이 필드가 없으면 메시지를 수신한 시각을 대신 사용하세요.

1594 1594 

1631 1631 

1632`message.content` 중 사용자가 입력하지 않고 붙여 넣은 부분을 Claude Code에 알리려면 `inline_pastes`를 설정합니다. 붙여 넣기 한 번당 하나의 문자열입니다. 프롬프트 텍스트는 사용자가 넣은 위치에 그대로 유지됩니다. Claude Code는 나열된 각 붙여 넣기를 해당 위치에서 `<pasted_content>` 태그로 감쌀 수 있으므로, Claude는 붙여 넣은 자료와 사용자가 직접 쓴 말을 구별할 수 있습니다. 프롬프트의 마지막 텍스트 블록에 있는 붙여 넣기만 감싸집니다. TypeScript Agent SDK v0.3.280 이상이 필요합니다.1632`message.content` 중 사용자가 입력하지 않고 붙여 넣은 부분을 Claude Code에 알리려면 `inline_pastes`를 설정합니다. 붙여 넣기 한 번당 하나의 문자열입니다. 프롬프트 텍스트는 사용자가 넣은 위치에 그대로 유지됩니다. Claude Code는 나열된 각 붙여 넣기를 해당 위치에서 `<pasted_content>` 태그로 감쌀 수 있으므로, Claude는 붙여 넣은 자료와 사용자가 직접 쓴 말을 구별할 수 있습니다. 프롬프트의 마지막 텍스트 블록에 있는 붙여 넣기만 감싸집니다. TypeScript Agent SDK v0.3.280 이상이 필요합니다.

1633 1633 

1634각 붙여넣기 필드에는 크기 제한이 있습니다.

1635 

1636* `pasted_content`: 항목과 그 안의 콘텐츠 블록을 합한 수가 1,000개를 넘으면 Claude Code는 필드 전체를 무시합니다.

1637* `inline_pastes`: Claude Code는 비어 있지 않은 처음 100개 항목을 사용하고 나머지는 무시합니다.

1638 

1634보내는 메시지를 Claude Code가 처리하는 방식을 바꾸려면 `shouldQuery`, `client_composed`, 또는 `priority`를 설정합니다.1639보내는 메시지를 Claude Code가 처리하는 방식을 바꾸려면 `shouldQuery`, `client_composed`, 또는 `priority`를 설정합니다.

1635 1640 

1636* `shouldQuery`: `false`로 설정하면 어시스턴트 턴을 트리거하지 않고 메시지를 트랜스크립트에 추가합니다. 메시지는 보류되었다가 턴을 트리거하는 다음 사용자 메시지에 병합됩니다. 별도로 실행한 명령의 출력처럼 모델 호출을 소비하지 않고 컨텍스트를 주입할 때 사용합니다.1641* `shouldQuery`: `false`로 설정하면 어시스턴트 턴을 트리거하지 않고 메시지를 트랜스크립트에 추가합니다. 메시지는 보류되었다가 턴을 트리거하는 다음 사용자 메시지에 병합됩니다. 별도로 실행한 명령의 출력처럼 모델 호출을 소비하지 않고 컨텍스트를 주입할 때 사용합니다.

1775* `ttft_stream_ms`: 응답 스트림이 열리는 첫 번째 `message_start` 스트림 이벤트까지의 시간(밀리초)입니다. `ttft_ms`보다 작으며, 둘 사이의 차이는 첫 번째 메시지를 스트리밍하는 데 걸린 시간입니다. success 분기에만 있습니다.1780* `ttft_stream_ms`: 응답 스트림이 열리는 첫 번째 `message_start` 스트림 이벤트까지의 시간(밀리초)입니다. `ttft_ms`보다 작으며, 둘 사이의 차이는 첫 번째 메시지를 스트리밍하는 데 걸린 시간입니다. success 분기에만 있습니다.

1776* `user_message_uuid`: 이 턴이 응답한, 사용자가 보낸 메시지의 `uuid`입니다. 어떤 결과에 포함되는지는 [`user_message_uuid`](#user_message_uuid)를 참조하세요.1781* `user_message_uuid`: 이 턴이 응답한, 사용자가 보낸 메시지의 `uuid`입니다. 어떤 결과에 포함되는지는 [`user_message_uuid`](#user_message_uuid)를 참조하세요.

1777* `user_message_uuids`: 이 턴에서 Claude Code가 응답한, 사용자가 보낸 모든 메시지의 `uuid`입니다. [`user_message_uuids`](#user_message_uuids)를 참조하세요.1782* `user_message_uuids`: 이 턴에서 Claude Code가 응답한, 사용자가 보낸 모든 메시지의 `uuid`입니다. [`user_message_uuids`](#user_message_uuids)를 참조하세요.

1778* `resume_reason`: 재시작으로 중단된 이 턴을 Claude Code가 다시 실행한 이유입니다. 두 분기 모두에 있습니다. [`resume_reason`](#resume_reason)을 참조하십시오.1783* `resume_reason`: 이 턴이 재시작으로 중단된 턴을 이어가는 이유입니다. 두 분기 모두에 있습니다. [`resume_reason`](#resume_reason)을 참조하세요.

1779* `local_command`: 턴이 디스패치한 명령의 이름으로, `/compact`처럼 에이전트 루프에 진입하지 않고 명령이 완료한 턴의 success 결과에 있습니다. 이름은 소문자와 밑줄로 변환되므로 `/reload-plugins`는 `reload_plugins`로 보고됩니다. MCP 서버가 제공하는 명령과 기본 제공 `/mcp`는 `mcp`로 보고됩니다. 사용자가 직접 정의한 명령은 `custom`으로 보고됩니다. 인수는 절대 포함되지 않습니다. 에이전트 루프에 진입한 모든 턴과 명령을 실행하지 않은 전송에는 없습니다. Agent SDK v0.3.268 이상이 필요합니다.1784* `local_command`: 턴이 디스패치한 명령의 이름으로, `/compact`처럼 에이전트 루프에 진입하지 않고 명령이 완료한 턴의 success 결과에 있습니다. 이름은 소문자와 밑줄로 변환되므로 `/reload-plugins`는 `reload_plugins`로 보고됩니다. MCP 서버가 제공하는 명령과 기본 제공 `/mcp`는 `mcp`로 보고됩니다. 사용자가 직접 정의한 명령은 `custom`으로 보고됩니다. 인수는 절대 포함되지 않습니다. 에이전트 루프에 진입한 모든 턴과 명령을 실행하지 않은 전송에는 없습니다. Agent SDK v0.3.268 이상이 필요합니다.

1780* `request_sent_wall_ms`: 서버 측 타임스탬프와 조인하기 위한, Claude Code가 API 요청을 디스패치한 시점의 epoch 밀리초입니다. API 요청을 보낸 턴의 `is_error`가 false인 success 결과에서 [`user_message_uuid`](#user_message_uuid)와 함께일 때만 있습니다.1785* `request_sent_wall_ms`: 서버 측 타임스탬프와 조인하기 위한, Claude Code가 API 요청을 디스패치한 시점의 epoch 밀리초입니다. API 요청을 보낸 턴의 `is_error`가 false인 success 결과에서 [`user_message_uuid`](#user_message_uuid)와 함께일 때만 있습니다.

1781* `first_content_frame_ms`: 첫 번째 `content_block_start` 또는 `content_block_delta` 스트림 이벤트까지의 시간(밀리초)이며, thinking 블록도 콘텐츠로 계산합니다. success 분기에서 `is_error`가 false일 때만 있습니다. Agent SDK v0.3.260 이상이 필요합니다.1786* `first_content_frame_ms`: 첫 번째 `content_block_start` 또는 `content_block_delta` 스트림 이벤트까지의 시간(밀리초)이며, thinking 블록도 콘텐츠로 계산합니다. success 분기에서 `is_error`가 false일 때만 있습니다. Agent SDK v0.3.260 이상이 필요합니다.

1825 1830 

1826* **사용자가 보낸 일반 메시지**, 즉 `isSynthetic: true`가 없는 메시지: 턴은 실행 내내 해당 메시지에 응답합니다. 여러 메시지를 짧은 간격으로 보내면 Claude Code가 이를 하나의 턴으로 병합할 수 있으며, 이때 이 필드에는 마지막 메시지의 `uuid`만 담깁니다. 병합된 메시지 중 어느 것과든 응답을 매칭하려면 [`user_message_uuids`](#user_message_uuids)를 사용하세요.1831* **사용자가 보낸 일반 메시지**, 즉 `isSynthetic: true`가 없는 메시지: 턴은 실행 내내 해당 메시지에 응답합니다. 여러 메시지를 짧은 간격으로 보내면 Claude Code가 이를 하나의 턴으로 병합할 수 있으며, 이때 이 필드에는 마지막 메시지의 `uuid`만 담깁니다. 병합된 메시지 중 어느 것과든 응답을 매칭하려면 [`user_message_uuids`](#user_message_uuids)를 사용하세요.

1827* **사용자가 `isSynthetic: true`로 보낸 메시지**: 턴은 처음에 해당 메시지에 응답합니다. Claude Code가 도구 호출 사이에 사용자의 일반 메시지를 받아들이면, 그때부터 턴은 받아들인 메시지에 응답합니다. 합성 메시지의 `uuid`를 반환하려면 Agent SDK v0.3.265 이상이 필요하며, 이전 버전은 합성 턴에서 아무것도 반환하지 않습니다.1832* **사용자가 `isSynthetic: true`로 보낸 메시지**: 턴은 처음에 해당 메시지에 응답합니다. Claude Code가 도구 호출 사이에 사용자의 일반 메시지를 받아들이면, 그때부터 턴은 받아들인 메시지에 응답합니다. 합성 메시지의 `uuid`를 반환하려면 Agent SDK v0.3.265 이상이 필요하며, 이전 버전은 합성 턴에서 아무것도 반환하지 않습니다.

1828* **[`CLAUDE_CODE_RESUME_INTERRUPTED_TURN`](/docs/ko/env-vars)에 따라 중단된 턴을 다시 실행하기 위해 Claude Code가 생성한 프롬프트**: 중단된 턴의 마지막 프롬프트가 사용자가 보낸 일반 메시지인 경우, 그것이 턴을 시작했든 Claude Code가 턴 중에 받아들였든 재실행은 처음에 해당 메시지에 응답합니다. [`resume_reason`](#resume_reason)으로 재실행의 프레임과 중단된 시도의 프레임을 구별할 수 있습니다. 마지막 프롬프트가 사용자의 일반 메시지가 아니면, 재실행은 처음에 사용자의 어떤 메시지에도 응답하지 않습니다. Claude Code가 도구 호출 사이에 사용자의 일반 메시지를 받아들이면, 그때부터 턴은 받아들인 메시지에 응답합니다. 중단된 턴의 프롬프트를 반환하려면 Agent SDK v0.3.268 이상이 필요합니다.1833* **[`CLAUDE_CODE_RESUME_INTERRUPTED_TURN`](/docs/ko/env-vars)에 따라 중단된 턴을 이어가기 위해 Claude Code가 생성하는 프롬프트**: 중단된 턴의 마지막 프롬프트가 사용자가 보낸 일반 메시지인 경우(턴을 시작한 메시지이든 턴 중에 Claude Code가 가져온 메시지이든), 이어가는 턴은 처음에 해당 메시지에 응답합니다. [`resume_reason`](#resume_reason)으로 이어가는 턴의 프레임과 중단된 시도의 프레임을 구분할 수 있습니다. 마지막 프롬프트가 사용자의 일반 메시지가 아니면, 이어가는 턴은 처음에 사용자의 어떤 메시지에도 응답하지 않습니다. Claude Code가 도구 호출 사이에 사용자의 일반 메시지를 가져오면, 그때부터 턴은 가져온 메시지에 응답합니다. 중단된 턴의 프롬프트를 되돌려 보내려면 Agent SDK v0.3.268 이상이 필요합니다.

1829* **Claude Code가 자체적으로 생성한 기타 프롬프트**: 턴은 처음에 사용자의 어떤 메시지에도 응답하지 않으며 프레임에 반환 값이 없습니다. Claude Code가 도구 호출 사이에 사용자의 일반 메시지를 받아들이면, 그때부터 턴은 해당 메시지에 응답합니다. 받아들인 메시지의 반환에는 Agent SDK v0.3.265 이상이 필요하며, 이전 버전은 이러한 턴에서 아무것도 반환하지 않습니다.1834* **Claude Code가 자체적으로 생성한 기타 프롬프트**: 턴은 처음에 사용자의 어떤 메시지에도 응답하지 않으며 프레임에 반환 값이 없습니다. Claude Code가 도구 호출 사이에 사용자의 일반 메시지를 받아들이면, 그때부터 턴은 해당 메시지에 응답합니다. 받아들인 메시지의 반환에는 Agent SDK v0.3.265 이상이 필요하며, 이전 버전은 이러한 턴에서 아무것도 반환하지 않습니다.

1830 1835 

1831Claude Code는 응답한 메시지의 `uuid`를 세 종류의 프레임에 반환합니다.1836Claude Code는 응답한 메시지의 `uuid`를 세 종류의 프레임에 반환합니다.

1857 `resume_reason`1862 `resume_reason`

1858</h4>1863</h4>

1859 1864 

1860재시작 후 Claude Code가 이 턴을 다시 실행한 이유입니다. Claude Code는 [`CLAUDE_CODE_RESUME_INTERRUPTED_TURN`](/docs/ko/env-vars)에 따라 다시 실행한 턴에 이 필드를 설정하므로, 재실행의 응답과 결과를 중단된 시도의 것과 구별할 수 있습니다. Agent SDK v0.3.268 이상이 필요합니다.1865이 턴이 재시작으로 중단된 턴을 이어가는 이유입니다. Claude Code는 [`CLAUDE_CODE_RESUME_INTERRUPTED_TURN`](/docs/ko/env-vars)에 따라 중단된 턴을 이어가는 턴에 이 필드를 설정하므로, 이어가는 턴의 응답 및 결과를 중단된 시도의 것과 구분할 수 있습니다. Agent SDK v0.3.268 이상이 필요합니다.

1861 1866 

1862Claude Code는 두 종류의 프레임에 이 필드를 설정합니다.1867Claude Code는 두 종류의 프레임에 이 필드를 설정합니다.

1863 1868 

1864* **재실행의 결과**: 결과에 `user_message_uuid`가 있든 없든 success와 error 분기 모두에 설정합니다.1869* **이어가는 턴의 결과**: 성공 분기와 오류 분기 모두에, 결과에 `user_message_uuid`가 포함되는지 여부와 관계없이 설정합니다.

1865* **재실행의 응답 프레임**: [`user_message_uuid`](#user_message_uuid)를 가진 프레임입니다.1870* **이어가는 턴의 응답 프레임**: [`user_message_uuid`](#user_message_uuid)를 포함하는 프레임입니다.

1866 1871 

1867값은 `interrupted_turn`처럼 턴이 다시 실행된 이유를 나타내는 짧은 소문자 토큰입니다.1872값은 `interrupted_turn` 같은 짧은 소문자 토큰입니다.

1868 1873 

1869<h4 id="queued_turn_count">1874<h4 id="queued_turn_count">

1870 `queued_turn_count`1875 `queued_turn_count`

2029};2034};

2030```2035```

2031 2036 

2032Claude Code는 [`user_message_uuid`](#user_message_uuid)에 설명된 조건에 따라 턴의 ping이 아닌 첫 번째 스트림 이벤트에, 그리고 턴이 응답하는 메시지가 바뀔 때 다시 `user_message_uuid`와 `user_message_uuids`를 설정합니다. 재시작으로 중단된 턴을 Claude Code가 다시 실행할 때, 해당 필드를 가진 재실행의 스트림 이벤트에는 [`resume_reason`](#resume_reason)도 포함됩니다.2037Claude Code는 [`user_message_uuid`](#user_message_uuid)에 설명된 조건에 따라 턴의 ping이 아닌 첫 번째 스트림 이벤트에 `user_message_uuid`와 `user_message_uuids`를 설정하고, 턴이 응답하는 메시지가 바뀔 때 다시 설정합니다. 재시작으로 중단된 턴을 이어가는 턴인 경우, 해당 필드를 포함하는 스트림 이벤트에는 [`resume_reason`](#resume_reason)도 포함됩니다.

2033 2038 

2034<h3 id="sdkcompactboundarymessage">2039<h3 id="sdkcompactboundarymessage">

2035 `SDKCompactBoundaryMessage`2040 `SDKCompactBoundaryMessage`

3556| - | - | - |3561| - | - | - |

3557| `script` | `string` | 인라인 워크플로 스크립트입니다. `export const meta = { name, description }`을 리터럴로 시작해야 하며, 그 뒤에 `agent()`, `parallel()`, `pipeline()` 및 `phase()`를 사용하는 스크립트 본문이 따릅니다. `meta`의 선택적 `phases` 배열은 진행 상황 보기에서 에이전트를 명명된 단계 아래에 그룹화합니다 |3562| `script` | `string` | 인라인 워크플로 스크립트입니다. `export const meta = { name, description }`을 리터럴로 시작해야 하며, 그 뒤에 `agent()`, `parallel()`, `pipeline()` 및 `phase()`를 사용하는 스크립트 본문이 따릅니다. `meta`의 선택적 `phases` 배열은 진행 상황 보기에서 에이전트를 명명된 단계 아래에 그룹화합니다 |

3558| `name` | `string` | 기본 제공 워크플로의 이름 또는 `.claude/workflows/`에 저장된 워크플로입니다. 스크립트로 확인됩니다 |3563| `name` | `string` | 기본 제공 워크플로의 이름 또는 `.claude/workflows/`에 저장된 워크플로입니다. 스크립트로 확인됩니다 |

3559| `scriptPath` | `string` | 디스크의 워크플로 스크립트 파일 경로입니다. `script` 및 `name`보다 우선합니다. Claude Code는 모든 호출의 스크립트를 유지하고 결과에서 경로를 반환하므로, 해당 파일을 편집하고 동일한 `scriptPath`로 다시 호출하여 반복할 수 있습니다 |3564| `scriptPath` | `string` | 디스크의 워크플로 스크립트 파일 경로입니다(예: 이전 실행이 반환한 `scriptPath`). `script` 및 `name`보다 우선합니다. 세션의 도구에 `Read`가 포함되어 있지 않으면 Claude Code는 오류와 함께 `scriptPath`를 거부합니다 |

3560| `args` | `unknown` | 스크립트에 전역 `args`로 노출되는 입력 값으로, 연구 질문이나 파일 경로 목록과 같은 매개변수화된 명명된 워크플로용입니다. 배열과 객체를 JSON 인코딩된 문자열이 아닌 실제 JSON 값으로 전달합니다 |3565| `args` | `unknown` | 스크립트에 전역 `args`로 노출되는 입력 값으로, 연구 질문이나 파일 경로 목록과 같은 매개변수화된 명명된 워크플로용입니다. 배열과 객체를 JSON 인코딩된 문자열이 아닌 실제 JSON 값으로 전달합니다 |

3561| `resumeFromRunId` | `string` | 재개할 이전 `Workflow` 호출의 실행 ID입니다. 입력이 변경되지 않은 완료된 `agent()` 호출은 일반적으로 캐시된 결과를 반환합니다. 나머지는 실시간으로 실행됩니다. [일시 중지 후 재개](/docs/ko/workflows#resume-after-a-pause)는 어느 완료된 호출이 다시 실행되는지 다룹니다. 동일한 세션만 해당됩니다 |3566| `resumeFromRunId` | `string` | 재개할 이전 `Workflow` 호출의 실행 ID입니다. 입력이 변경되지 않은 완료된 `agent()` 호출은 일반적으로 캐시된 결과를 반환합니다. 나머지는 실시간으로 실행됩니다. [일시 중지 후 재개](/docs/ko/workflows#resume-after-a-pause)는 어느 완료된 호출이 다시 실행되는지 다룹니다. 동일한 세션만 해당됩니다 |

3562| `title` | `string` | 무시됨; 스크립트의 `meta` 블록이 제목을 설정합니다 |3567| `title` | `string` | 무시됨; 스크립트의 `meta` 블록이 제목을 설정합니다 |

129 VS Code 세션의 권한 프롬프트129 VS Code 세션의 권한 프롬프트

130</h3>130</h3>

131 131 

132VS Code 세션에서 Claude Code가 브라우저 작업 전에 확인을 요청하는지는 세션이 브라우저에 연결된 방식에 따라 달라집니다:132VS Code 세션에서 Claude Code가 브라우저 작업 전에 확인을 요청하면 프롬프트가 채팅 패널에 카드로 표시됩니다. 작업 대상이 허용하지 않은 사이트인 경우 카드에서 해당 사이트를 허용하는 옵션도 제공합니다.

133 133 

134* **`@browser`를 입력한 경우**: Claude Code가 원래 확인을 요청했을 각 브라우저 작업을 확장 프로그램이 승인합니다.134[기본적으로 활성화](#enable-chrome-by-default)가 켜져 있어 시작 시 브라우저에 연결된 세션에서는 Claude Code가 Manual, Edit automatically, Auto, Bypass permissions 모드에서 허용하지 않은 사이트에 대한 브라우저 작업 전에 확인을 요청합니다. Auto 및 Bypass permissions 모드에서는 해당 세션에서 `@browser`를 입력하기 전까지 이 동작이 적용됩니다.

135* **[기본적으로 활성화](#enable-chrome-by-default) 설정으로 시작 시 연결된 경우**: 해당 세션에서 `@browser`를 입력하기 전까지 Claude Code는 Manual, Edit automatically, Auto, Bypass permissions 모드에서 허용하지 않은 사이트에 대한 브라우저 작업 전에 확인을 요청합니다.

136 135 

137<h3 id="browser-tools-in-plan-mode">136<h3 id="browser-tools-in-plan-mode">

138 플랜 모드의 브라우저 도구137 플랜 모드의 브라우저 도구

139</h3>138</h3>

140 139 

141[플랜 모드](/docs/ko/permission-modes#analyze-before-you-edit-with-plan-mode)에서는 Claude가 GIF를 녹화하거나, 새 탭을 열거나, 단축키를 실행하기 전에 권한 프롬프트가 표시됩니다. 단, [`@browser`](#permission-prompts-in-vs-code-sessions)를 입력한 VS Code 세션은 예외입니다. 대화형 CLI 세션에서 [권한 우회 모드를 사용할 수 있고](/docs/ko/permission-modes#skip-all-checks-with-bypasspermissions-mode) [기능 플래그 가져오기](/docs/ko/env-vars#features-that-need-feature-flag-fetching)가 꺼져 있으면 이러한 호출은 프롬프트 없이 실행됩니다.140[플랜 모드](/docs/ko/permission-modes#analyze-before-you-edit-with-plan-mode)에서는 Claude가 GIF를 녹화하거나, 새 탭을 열거나, 단축키를 실행하기 전에 권한 프롬프트가 표시됩니다. 대화형 CLI 세션에서 [권한 우회 모드를 사용할 수 있고](/docs/ko/permission-modes#skip-all-checks-with-bypasspermissions-mode) [기능 플래그 가져오기](/docs/ko/env-vars#features-that-need-feature-flag-fetching)가 꺼져 있으면 이러한 호출은 프롬프트 없이 실행됩니다.

142 141 

143`createIfEmpty`를 설정하는 `tabs_context_mcp` 호출도 확인을 요청하며, 이러한 작업 중 하나라도 포함하는 `browser_batch` 호출도 마찬가지입니다.142`createIfEmpty`를 설정하는 `tabs_context_mcp` 호출도 확인을 요청하며, 이러한 작업 중 하나라도 포함하는 `browser_batch` 호출도 마찬가지입니다.

144 143 

263 개발자 연결263 개발자 연결

264</h2>264</h2>

265 265 

266개발자는 자신의 노트북에서 한 번의 브라우저 로그인으로 회사 업무 계정을 사용하여 연결합니다. 모델에 대한 요청이 조직의 업스트림 자격 증명을 사용하여 게이트웨이를 거치기 때문에 claude.ai 계정, API 키 또는 구독이 필요하지 않습니다. 연결은 MDM을 통해 푸시하는 [클라이언트 측 관리형 설정](/docs/ko/claude-apps-gateway-config#client-side-managed-settings)에 의해 구동되므로 개발자 측에서 수동으로 설정할 것이 없습니다. 이 섹션에서는 관리자가 구성하는 내용을 다룹니다.266개발자는 자신의 노트북에서 한 번의 브라우저 로그인으로 회사 업무 계정을 사용하여 연결합니다. 모델에 대한 요청이 조직의 업스트림 자격 증명을 사용하여 게이트웨이를 거치기 때문에 claude.ai 계정, API 키 또는 구독이 필요하지 않습니다. 연결은 MDM을 통해 푸시하는 [클라이언트 측 관리형 설정](/docs/ko/claude-apps-gateway-config#client-side-managed-settings)에 의해 구동되며, 이 섹션에서는 관리자가 구성하는 내용을 다룹니다.

267 267 

268CLI는 첫 연결 시 게이트웨이의 TLS 리프 인증서 지문을 생성하고 호스트명별로 고정합니다. 로그인 중, 자동 세션 새로 고침 중, 관리형 설정 가져오기 중에 해당 핀을 다시 확인하며, 추론 요청은 핀 없이 표준 TLS 검증을 사용합니다. HTTPS 프록시를 통해 라우팅된 요청은 핀 검사를 건너뛰므로, 게이트웨이 호스트를 `NO_PROXY`에 추가하여 직접 연결을 유지하세요.268CLI는 첫 연결 시 게이트웨이의 TLS 리프 인증서 지문을 생성하고 호스트명별로 고정합니다. 로그인 중, 자동 세션 새로 고침 중, 관리형 설정 가져오기 중에 해당 핀을 다시 확인하며, 추론 요청은 핀 없이 표준 TLS 검증을 사용합니다. HTTPS 프록시를 통해 라우팅된 요청은 핀 검사를 건너뛰므로, 게이트웨이 호스트를 `NO_PROXY`에 추가하여 직접 연결을 유지하세요.

269 269 

287 게이트웨이 URL 설정287 게이트웨이 URL 설정

288</h3>288</h3>

289 289 

290MDM을 통해 또는 디스크에 직접 배포하는 OS별 [관리형 설정 파일](/docs/ko/managed-settings#delivery-mechanisms)에 세 개의 키가 들어갑니다. `forceLoginMethod`와 `forceLoginGatewayUrl`은 URL이 채워진 **Cloud gateway** 화면에서 `/login`을 바로 열고, `parentSettingsBehavior: "merge"`는 Claude Desktop이 게이트웨이의 송신 허용 목록을 자신이 시작하는 Claude Code 세션에 전달할 수 있게 합니다. 이는 [Claude Desktop 세션에 정책 전달](#deliver-policy-to-claude-desktop-sessions)에서 설명합니다.290MDM을 통해 또는 디스크에 직접 배포하는 OS별 [관리형 설정 파일](/docs/ko/managed-settings#delivery-mechanisms)에 세 개의 키가 들어갑니다. 관리형 설정이 없는 머신의 경우에는 [사용자 설정에서 게이트웨이 URL 설정](#set-the-gateway-url-in-user-settings)을 참조하세요. `forceLoginMethod`와 `forceLoginGatewayUrl`은 URL이 채워진 **Cloud gateway** 화면에서 `/login`을 바로 열고, `parentSettingsBehavior: "merge"`는 Claude Desktop이 게이트웨이의 송신 허용 목록을 자신이 시작하는 Claude Code 세션에 전달할 수 있게 합니다. 이는 [Claude Desktop 세션에 정책 전달](#deliver-policy-to-claude-desktop-sessions)에서 설명합니다.

291 291 

292```json theme={null}292```json theme={null}

293{293{

299 299 

300개발자는 Enter를 눌러 연결합니다. [첫 연결 TLS 지문 프롬프트](#connect-developers)는 여전히 나타납니다. 파일이 머신에 배포되면, 게이트웨이 로그인을 완료하지 않은 개발자는 [Administrator policy requires a Cloud gateway sign-in](/docs/ko/errors#administrator-policy-requires-a-cloud-gateway-sign-in)에 설명된 메시지 중 하나를 보게 됩니다. `CLAUDE_CODE_USE_BEDROCK` 같은 환경 변수를 통해 클라우드 제공자를 선택하는 개발자는 게이트웨이 로그인이 필요하지 않습니다.300개발자는 Enter를 눌러 연결합니다. [첫 연결 TLS 지문 프롬프트](#connect-developers)는 여전히 나타납니다. 파일이 머신에 배포되면, 게이트웨이 로그인을 완료하지 않은 개발자는 [Administrator policy requires a Cloud gateway sign-in](/docs/ko/errors#administrator-policy-requires-a-cloud-gateway-sign-in)에 설명된 메시지 중 하나를 보게 됩니다. `CLAUDE_CODE_USE_BEDROCK` 같은 환경 변수를 통해 클라우드 제공자를 선택하는 개발자는 게이트웨이 로그인이 필요하지 않습니다.

301 301 

302개발자는 이를 수동으로 설정할 수 없습니다. 로그인 선택기에는 게이트웨이 옵션이 없으며, `forceLoginGatewayUrl`은 개발자 자신의 설정 파일에서는 무시됩니다. URL 없이 `forceLoginMethod`만 설정하면 개발자에게 "IT 관리자에게 문의하세요" 메시지만 표시됩니다. 로그인 키는 머신에 푸시하는 파일에 넣어야 하며, 이미 연결된 클라이언트에만 도달하는 게이트웨이의 `managed.policies[].cli` 블록에 넣으면 안 됩니다.302로그인 선택기에는 게이트웨이 옵션이 없으며, 관리형 설정에서 URL 없이 `forceLoginMethod`만 설정하면 개발자에게 "IT 관리자에게 문의하세요" 메시지만 표시됩니다. 로그인 키는 머신에 푸시하는 파일에 넣어야 하며, 이미 연결된 클라이언트에만 도달하는 게이트웨이의 `managed.policies[].cli` 블록에 넣으면 안 됩니다.

303 

304<h4 id="set-the-gateway-url-in-user-settings">

305 사용자 설정에서 게이트웨이 URL 설정

306</h4>

307 

308관리형 설정이 없는 머신에서는 각 개발자가 자신의 사용자 설정 파일인 `~/.claude/settings.json`에 `forceLoginMethod`와 `forceLoginGatewayUrl`을 추가하도록 하세요. 이를 위해서는 개발자 머신에 Claude Code v2.1.295 이상이 필요합니다. 이 예제는 `claude-gateway.internal.example.com`의 게이트웨이를 지정합니다.

309 

310```json theme={null}

311{

312 "forceLoginMethod": "gateway",

313 "forceLoginGatewayUrl": "https://claude-gateway.internal.example.com"

314}

315```

316 

317개발자가 Claude Code 프롬프트에서 `/login`을 실행하면 해당 주소로 **Cloud gateway** 화면이 열리고, 개발자는 Enter를 눌러 연결합니다. [첫 연결 TLS 지문 프롬프트](#connect-developers)는 여전히 나타납니다. 이 방식으로 설정한 키에는 다음 제한이 적용됩니다.

318 

319* **사용자 설정에서만 유효**: Claude Code는 프로젝트의 `.claude/settings.json` 또는 `.claude/settings.local.json`이 아니라 `~/.claude/settings.json`에서 두 키를 읽습니다.

320* **관리형 설정이 있으면 무시됨**: 관리형 설정 파일, macOS plist 또는 Windows HKLM 정책, 또는 [정책 헬퍼](/docs/ko/settings-reference#policyhelper)를 통해 관리자의 설정이 머신에 도달하면, Claude Code는 사용자 설정에 지정된 게이트웨이를 무시합니다.

303 321 

304<h3 id="allow-a-gateway-on-public-address-space-you-own">322<h3 id="allow-a-gateway-on-public-address-space-you-own">

305 소유한 공인 주소 공간의 게이트웨이 허용323 소유한 공인 주소 공간의 게이트웨이 허용

981 * **혼합된 키**: `code`와 `cli`(또는 이전 표기인 `settings`)가 모두 있는 파일은 부팅 시 게이트웨이를 중지시킵니다. 모든 블록을 한 번의 편집으로 하나의 키 아래에 두십시오.981 * **혼합된 키**: `code`와 `cli`(또는 이전 표기인 `settings`)가 모두 있는 파일은 부팅 시 게이트웨이를 중지시킵니다. 모든 블록을 한 번의 편집으로 하나의 키 아래에 두십시오.

982</Warning>982</Warning>

983 983 

984`.env` 파일 읽기를 거부하는 규칙 같은 정책의 Claude Code 설정은 `cli` 또는 `code` 키 아래 블록에 들어갑니다. 두 키는 같은 내용을 받습니다. 키에 따라 설정이 적용되는 위치가 결정됩니다.984`.env` 파일 읽기를 거부하는 규칙과 같은 정책의 Claude Code 설정은 `cli` 또는 `code` 키 아래의 블록에 들어갑니다. `code`가 권장 키이며, `cli`는 레거시 키입니다. 두 키 모두 동일한 내용을 받습니다. 키는 설정이 적용되는 위치를 결정합니다.

985 985 

986* **`cli`**: 터미널, VS Code 및 JetBrains 확장 프로그램, Agent SDK. `cli` 아래에서 Claude Desktop의 Code 탭은 [파생 설정](#claude-desktop-overlay)을 받으므로, `Read(./.env)` 같은 범위 지정 규칙은 그곳의 사용자를 막지 않습니다.986* **`cli`**: 터미널, VS Code 및 JetBrains 확장 프로그램, Agent SDK. `cli` 아래에서 Claude Desktop의 Code 탭은 [파생 설정](#claude-desktop-overlay)을 받으므로, `Read(./.env)` 같은 범위 지정 규칙은 그곳의 사용자를 막지 않습니다.

987* **`code`**: 같은 위치이며, Claude Desktop의 Code 탭도 포함할 수 있습니다.987* **`code`**: 같은 위치이며, Claude Desktop의 Code 탭도 포함할 수 있습니다.

988 988 

989선택의 기준은 이 설정이 Code 탭에도 적용되어야 하는지 여부입니다. 그렇지 않다면 아무것도 바꾸지 마십시오. `cli`를 사용하는 파일은 기존대로 동작하며, [`desktop`](#claude-desktop-overlay) 키가 있는 정책에서 `cli`를 발견한 게이트웨이는 부팅 시 경고를 표시하지만 그대로 시작됩니다. Code 탭도 포함하려면 권장 키인 `code`로 전환하십시오.989`cli`를 사용하는 파일은 이전과 같이 동작하며, [`desktop`](#claude-desktop-overlay) 키가 있는 정책에서 `cli`를 발견한 게이트웨이는 부팅 시 경고하지만 시작은 합니다. 설정이 Code 탭에도 적용될 수 있도록 `code`로 전환하십시오.

990 990 

991전환하기 전에 [Code 탭에서 `code` 설정 적용하기](#apply-code-settings-in-the-code-tab)를 읽으십시오. 설정이 Code 탭에 적용되려면 정책에 `desktop` 키가 있어야 하고 사용자 머신에 설정 작업이 필요하며, Claude Desktop에서 웹 검색이 꺼집니다.991전환하기 전에 [Code 탭에서 `code` 설정 적용하기](#apply-code-settings-in-the-code-tab)를 읽으십시오. 설정이 Code 탭에 적용되려면 정책에 `desktop` 키가 있어야 하고 사용자 머신에 설정 작업이 필요하며, Claude Desktop에서 웹 검색이 꺼집니다.

992 992 

1713 1713 

1714Claude Desktop의 경우 Claude Desktop의 자체 [관리형 구성](https://claude.com/docs/third-party/claude-desktop/configuration)에서 `bootstrapUrl` 키를 `<listen.public_url>/user/bootstrap`으로 설정합니다. 로그인 흐름 및 그룹별 정책은 정책이 `desktop` 키로 서버 측에서 옵트인되면 CLI의 정책과 일치합니다. 옵트인이 없으면 `/user/bootstrap`은 404를 반환합니다. 서버 측 절반은 [Claude Desktop 오버레이](#claude-desktop-overlay)를 참조하십시오.1714Claude Desktop의 경우 Claude Desktop의 자체 [관리형 구성](https://claude.com/docs/third-party/claude-desktop/configuration)에서 `bootstrapUrl` 키를 `<listen.public_url>/user/bootstrap`으로 설정합니다. 로그인 흐름 및 그룹별 정책은 정책이 `desktop` 키로 서버 측에서 옵트인되면 CLI의 정책과 일치합니다. 옵트인이 없으면 `/user/bootstrap`은 404를 반환합니다. 서버 측 절반은 [Claude Desktop 오버레이](#claude-desktop-overlay)를 참조하십시오.

1715 1715 

1716Claude Code는 [`forceLoginGatewayUrl`](/docs/ko/settings-reference#forcelogingatewayurl), [`gatewayInternalNetworks`](/docs/ko/settings-reference#gatewayinternalnetworks), 및 [`forceLoginMethod`](/docs/ko/settings-reference#forceloginmethod)의 `"gateway"` 값을 머신의 관리형 소스에서만 인정합니다: `managed-settings.json`, macOS plist 또는 Windows HKLM 레지스트리, 또는 정책 헬퍼. 개발자가 자신의 `~/.claude/settings.json`에서 이들을 설정하는 것은 게이트웨이 로그인을 구성하지 않으며, 게이트웨이 페이로드에서 설정하는 것도 마찬가지입니다.1716Claude Code는 [`forceLoginGatewayUrl`](/docs/ko/settings-reference#forcelogingatewayurl), [`gatewayInternalNetworks`](/docs/ko/settings-reference#gatewayinternalnetworks), 및 [`forceLoginMethod`](/docs/ko/settings-reference#forceloginmethod)의 `"gateway"` 값을 머신의 관리형 소스에서 인정합니다: `managed-settings.json`, macOS plist 또는 Windows HKLM 레지스트리, 또는 정책 헬퍼. 게이트웨이 페이로드에서 이들을 설정해도 게이트웨이 로그인은 구성되지 않습니다. 개발자 자신의 `~/.claude/settings.json`에 대해서는 [사용자 설정에서 게이트웨이 URL 설정](/docs/ko/claude-apps-gateway#set-the-gateway-url-in-user-settings)을 참조하십시오.

1717 1717 

1718페이로드에서 `forceLoginMethod` 및 `forceLoginOrgUUID`를 제외합니다. Claude Code는 여전히 시작 자격 증명 확인을 위해 페이로드에서 두 키를 모두 읽으므로, 머신에 Anthropic 발급 자격 증명을 유지하는 개발자는 로그인 후에도 [관리자 정책이 Cloud 게이트웨이 로그인을 요구합니다](/docs/ko/errors#administrator-policy-requires-a-cloud-gateway-sign-in)에서 설명한 시작 종료를 받게 됩니다.1718페이로드에서 `forceLoginMethod` 및 `forceLoginOrgUUID`를 제외합니다. Claude Code는 여전히 시작 자격 증명 확인을 위해 페이로드에서 두 키를 모두 읽으므로, 머신에 Anthropic 발급 자격 증명을 유지하는 개발자는 로그인 후에도 [관리자 정책이 Cloud 게이트웨이 로그인을 요구합니다](/docs/ko/errors#administrator-policy-requires-a-cloud-gateway-sign-in)에서 설명한 시작 종료를 받게 됩니다.

1719 1719 

135 게이트웨이 URL을 개발자 머신으로 푸시135 게이트웨이 URL을 개발자 머신으로 푸시

136</h3>136</h3>

137 137 

138게이트웨이가 제공되면, MDM을 통해 또는 OS별 `managed-settings.json`을 직접 작성하여 관리형 설정을 통해 각 개발자의 머신으로 `forceLoginMethod`, `forceLoginGatewayUrl` 및 `parentSettingsBehavior: "merge"`를 푸시하세요. 이 없이는 `/login`이 게이트웨이 옵션이 없는 표준 계정 선택기를 표시합니다.138게이트웨이가 제공되면, MDM을 통해 또는 OS별 `managed-settings.json`을 직접 작성하여 관리형 설정을 통해 각 개발자의 머신으로 `forceLoginMethod`, `forceLoginGatewayUrl` 및 `parentSettingsBehavior: "merge"`를 푸시하세요.

139 139 

140키를 배포하면 Claude Code는 머신의 남은 API 키 또는 claude.ai 로그인을 사용하지 않으므로, 로그인 지침과 함께 푸시를 계획하세요. [관리자 정책에서 Cloud 게이트웨이 로그인 필요](/docs/ko/errors#administrator-policy-requires-a-cloud-gateway-sign-in)는 개발자가 보는 메시지를 설명합니다.140키를 배포하면 Claude Code는 머신의 남은 API 키 또는 claude.ai 로그인을 사용하지 않으므로, 로그인 지침과 함께 푸시를 계획하세요. [관리자 정책에서 Cloud 게이트웨이 로그인 필요](/docs/ko/errors#administrator-policy-requires-a-cloud-gateway-sign-in)는 개발자가 보는 메시지를 설명합니다.

141 141 

277 277 

278스레드는 스레드의 모델이 지원할 때 [자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode)에서 실행되므로, 대부분의 도구 호출은 사용자에게 묻지 않고 실행됩니다. 스레드가 사용자의 승인이 필요할 때, 프롬프트는 해당 스레드 내부에 있고 스레드는 거기서 답변할 때까지 기다립니다. 프로젝트 대화에서 Claude에 진행하라고 말하는 것은 도달하지 않습니다.278스레드는 스레드의 모델이 지원할 때 [자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode)에서 실행되므로, 대부분의 도구 호출은 사용자에게 묻지 않고 실행됩니다. 스레드가 사용자의 승인이 필요할 때, 프롬프트는 해당 스레드 내부에 있고 스레드는 거기서 답변할 때까지 기다립니다. 프로젝트 대화에서 Claude에 진행하라고 말하는 것은 도달하지 않습니다.

279 279 

280각 승인은 해당 프롬프트 또는 더 광범위한 옵션을 선택하면 해당 스레드의 나머지를 포함합니다. 모든 스레드가 특정 명령을 묻지 않고 실행하도록 하거나 일부를 차단하려면, 저장소의 `.claude/settings.json`에 [권한 규칙](/docs/ko/permissions)을 추가합니다. 클라우드 스레드는 한 저장소가 있는 프로젝트에서만 적용합니다. [스레드가 저장소에서 선택하는 것](#what-threads-pick-up-from-your-repositories)을 참조합니다. 여러 저장소가 있는 프로젝트에서는 저장소의 권한 규칙이 클라우드 스레드에 도달하지 않으므로, 자동 모드와 각 스레드 내에서 주는 승인에 의존합니다.280각 승인은 해당 프롬프트에 적용되며, 더 광범위한 옵션을 선택하면 해당 스레드의 나머지에 적용됩니다.

281 

282모든 스레드가 특정 명령을 묻지 않고 실행하도록 하거나 일부를 차단하려면, 저장소의 `.claude/settings.json`에 [권한 규칙](/docs/ko/permissions)을 추가합니다. 프로젝트의 클라우드 스레드가 이 규칙을 적용하는지 확인합니다.

283 

284* **저장소 하나**: 클라우드 스레드가 규칙을 적용합니다. [스레드가 저장소에서 선택하는 것](#what-threads-pick-up-from-your-repositories)을 참조합니다.

285* **여러 저장소, Anthropic 호스팅 환경**: 어떤 저장소의 권한 규칙도 클라우드 스레드에 도달하지 않으므로, 자동 모드와 각 스레드 내에서 주는 승인에 의존합니다.

286* **여러 저장소, 자체 호스팅 환경**: [어떤 저장소의 설정이 적용되는지](/docs/ko/self-hosted-environments-configuration#repository-settings-in-sessions-with-several-repositories)를 참조합니다.

281 287 

282<h3 id="run-a-thread-on-your-own-computer">288<h3 id="run-a-thread-on-your-own-computer">

283 자신의 컴퓨터에서 스레드 실행289 자신의 컴퓨터에서 스레드 실행

381 저장소에서 스레드가 가져오는 것387 저장소에서 스레드가 가져오는 것

382</h3>388</h3>

383 389 

384각 클라우드 스레드는 프로젝트의 모든 저장소를 복제하고 모든 저장소에서 `CLAUDE.md`와 스킬을 로드합니다. 권한 규칙, 훅, `env`는 스레드가 시작하는 디렉토리의 `.claude/settings.json`에서만 옵니다: 프로젝트에 저장소가 하나일 때는 저장소 내부이고, 여러 개일 때는 복제본 위이며, 이 경우 이들 항목을 위해 어떤 저장소의 파일도 읽히지 않습니다.390각 클라우드 스레드는 프로젝트의 모든 저장소를 복제하고 모든 저장소에서 `CLAUDE.md`와 스킬을 로드합니다. 권한 규칙, 훅, `env`는 스레드가 시작하는 디렉토리의 `.claude/settings.json`에서만 옵니다.

385 391 

386| 각 저장소에서 | 한 저장소 | 여러 저장소 |392| 각 저장소에서 | 한 저장소 | 여러 저장소 |

387| :- | :- | :- |393| :- | :- | :- |

388| `CLAUDE.md` | 스레드가 시작할 때 로드됨 | 스레드가 시작할 때 모든 저장소에서 로드됨 |394| `CLAUDE.md` | 스레드가 시작할 때 로드됨 | 스레드가 시작할 때 모든 저장소에서 로드됨 |

389| `.claude/` 아래의 스킬, 에이전트, 명령 | 로드됨 | 모든 저장소에서 로드됨 |395| `.claude/` 아래의 스킬, 에이전트, 명령 | 로드됨 | 모든 저장소에서 로드됨 |

390| `.claude/settings.json`에서 활성화된 플러그인 | 로드되지 않음. 대신 **프로젝트 설정 > 플러그인**에서 플러그인을 추가하세요 | 로드되지 않음. 대신 **프로젝트 설정 > 플러그인**에서 플러그인을 추가하세요 |396| `.claude/settings.json`에서 활성화된 플러그인 | 로드되지 않음. 대신 **프로젝트 설정 > 플러그인**에서 플러그인을 추가하세요 | 로드되지 않음. 대신 **프로젝트 설정 > 플러그인**에서 플러그인을 추가하세요 |

391| `.claude/settings.json`에서 정의된 권한 규칙, 훅, `env` | 스레드에 적용됩니다. 단, [클라우드 세션이 인정하지 않는](/docs/ko/cloud-environments#what-carries-over-from-your-setup) `env` 키는 제외됩니다 | 적용되지 않음 |397| `.claude/settings.json`에서 정의된 권한 규칙, 훅, `env` | 스레드에 적용됩니다. 단, [클라우드 세션이 인정하지 않는](/docs/ko/cloud-environments#what-carries-over-from-your-setup) `env` 키는 제외됩니다 | Anthropic 호스팅 환경에서는 적용되지 않습니다. 자체 호스팅 환경의 경우 [어떤 저장소의 설정이 적용되는지](/docs/ko/self-hosted-environments-configuration#repository-settings-in-sessions-with-several-repositories)를 참조하세요 |

392 398 

393여러 저장소가 있는 프로젝트에서, 각 복제본은 스레드에 [추가 디렉토리](/docs/ko/memory#load-from-additional-directories)로 첨부되며 `CLAUDE.md` 로드가 켜져 있습니다. 이것이 스레드가 위에서 시작하더라도 모든 저장소의 `CLAUDE.md`와 스킬이 시작할 때 로드되는 이유입니다. 이러한 프로젝트에서는 프로젝트 지침에 상시 규칙을 넣고 [클라우드 환경](#choose-an-environment-for-threads)을 통해 스레드에 환경 변수를 제공하세요.399여러 저장소가 있는 프로젝트에서는 프로젝트 지침에 상시 규칙을 넣고 [클라우드 환경](#choose-an-environment-for-threads)을 통해 스레드에 환경 변수를 제공하세요.

394 400 

395<h3 id="choose-an-environment-for-threads">401<h3 id="choose-an-environment-for-threads">

396 스레드의 환경 선택하기402 스레드의 환경 선택하기

406 412 

407클라우드 스레드는 머신에만 설치된 스킬, MCP 서버, 플러그인, 도구가 없습니다. [Remote Control](/docs/ko/remote-control)을 통해 Claude가 머신에서 실행하는 스레드는 거기에 설치된 것을 사용합니다. 이들 각각을 클라우드 스레드에서 사용 가능하게 하려면:413클라우드 스레드는 머신에만 설치된 스킬, MCP 서버, 플러그인, 도구가 없습니다. [Remote Control](/docs/ko/remote-control)을 통해 Claude가 머신에서 실행하는 스레드는 거기에 설치된 것을 사용합니다. 이들 각각을 클라우드 스레드에서 사용 가능하게 하려면:

408 414 

409* 스킬, 서브에이전트, 명령: 프로젝트에 추가한 저장소에 커밋합니다. 예를 들어 `.claude/skills/<skill-name>/SKILL.md`의 스킬입니다. 각 클라우드 스레드는 프로젝트의 모든 저장소를 복제하고 각 저장소에서 `.claude/skills/`, `.claude/agents/`, `.claude/commands/`를 로드하므로, 한 저장소에 커밋된 스킬은 모든 클라우드 스레드에서 사용 가능합니다. 클라우드 스레드는 또한 claude.ai 계정에 대해 활성화한 스킬을 로드합니다.415* 스킬, 서브에이전트, 명령: 프로젝트에 추가한 저장소에 커밋합니다. 예를 들어 `.claude/skills/<skill-name>/SKILL.md`의 스킬입니다. 각 클라우드 스레드는 프로젝트의 모든 저장소를 복제하고 각 저장소에서 `.claude/skills/`, `.claude/agents/`, `.claude/commands/`를 로드하므로, 한 저장소에 커밋된 스킬은 모든 클라우드 스레드에서 사용 가능합니다. 클라우드 스레드는 또한 [claude.ai 계정에 대해 활성화한 스킬](/docs/ko/skills#skills-in-cowork-and-cloud-sessions)을 로드합니다.

410* 플러그인: **프로젝트 설정 > 플러그인**에서 추가합니다; 각 새로운 클라우드 스레드에 로드됩니다. 저장소가 `.claude/settings.json`에서 선언하는 플러그인은 [클라우드 스레드에 로드되지 않습니다](/docs/ko/cloud-environments#what-carries-over-from-your-setup).416* 플러그인: **프로젝트 설정 > 플러그인**에서 추가합니다; 각 새로운 클라우드 스레드에 로드됩니다. 저장소가 `.claude/settings.json`에서 선언하는 플러그인은 [클라우드 스레드에 로드되지 않습니다](/docs/ko/cloud-environments#what-carries-over-from-your-setup).

411* MCP 서버: 클라우드 스레드는 claude.ai 계정의 커넥터에서 MCP 도구를 가져옵니다. 커넥터는 [claude.ai/customize/connectors](https://claude.ai/customize/connectors)에서 한 번 연결하거나 **프로젝트 설정 > 환경**의 **커넥터 관리** 링크를 통해 연결하는 MCP 서버입니다. 모든 클라우드 스레드는 프로젝트별 설정 없이 모두 사용할 수 있습니다. 프로젝트 대화 자체는 커넥터가 없으므로 커넥터가 필요한 작업을 클라우드 스레드의 작업으로 보냅니다. 한 저장소가 있는 프로젝트에서, 클라우드 스레드는 또한 해당 저장소의 [`.mcp.json`](/docs/ko/cloud-environments#what-carries-over-from-your-setup)에서 MCP 서버를 로드합니다. [커넥터가 Claude Code에 도달하는 방법](/docs/ko/mcp#how-connectors-reach-claude-code)은 클라우드 세션의 규칙과 커넥터를 끄는 설정을 나열합니다.417* MCP 서버: 클라우드 스레드는 claude.ai 계정의 커넥터에서 MCP 도구를 가져옵니다. 커넥터는 [claude.ai/customize/connectors](https://claude.ai/customize/connectors)에서 한 번 연결하거나 **프로젝트 설정 > 환경**의 **커넥터 관리** 링크를 통해 연결하는 MCP 서버입니다. 모든 클라우드 스레드는 프로젝트별 설정 없이 모두 사용할 수 있습니다. 프로젝트 대화 자체는 커넥터가 없으므로 커넥터가 필요한 작업을 클라우드 스레드의 작업으로 보냅니다. 한 저장소가 있는 프로젝트에서, 클라우드 스레드는 또한 해당 저장소의 [`.mcp.json`](/docs/ko/cloud-environments#what-carries-over-from-your-setup)에서 MCP 서버를 로드합니다. [커넥터가 Claude Code에 도달하는 방법](/docs/ko/mcp#how-connectors-reach-claude-code)은 클라우드 세션의 규칙과 커넥터를 끄는 설정을 나열합니다.

412* 명령줄 도구 및 패키지: 환경의 [설정 스크립트](/docs/ko/cloud-environments#setup-scripts)에 설치합니다.418* 명령줄 도구 및 패키지: 환경의 [설정 스크립트](/docs/ko/cloud-environments#setup-scripts)에 설치합니다.

108| `--maintenance` | `maintenance` 매처를 사용하여 세션 전에 [Setup 훅](/docs/ko/hooks#setup)을 실행합니다(인쇄 모드만 해당) | `claude -p --maintenance "query"` |108| `--maintenance` | `maintenance` 매처를 사용하여 세션 전에 [Setup 훅](/docs/ko/hooks#setup)을 실행합니다(인쇄 모드만 해당) | `claude -p --maintenance "query"` |

109| `--max-budget-usd` | API 호출에 대한 예상 지출이 이 금액에 도달하면 실행을 중지합니다(인쇄 모드만 해당). Claude Code는 [클라이언트 측 비용 추정치](/docs/ko/agent-sdk/cost-tracking#estimates-not-billing)를 기준으로 한도를 확인하며, 이는 실제 청구 금액과 다를 수 있습니다. [서브에이전트](/docs/ko/sub-agents)의 지출이 한도에 포함됩니다. 지출이 한도를 초과할 수 있으므로 [여유를 두세요](/docs/ko/agent-sdk/agent-loop#budget-headroom). `--continue` 또는 `--resume`으로 대화로 돌아올 때 [이전 실행에서 복원된](/docs/ko/agent-sdk/cost-tracking#accumulate-costs-across-multiple-calls) 합계는 이에 포함되지 않습니다. 지출이 한도에 도달하면 다른 서브에이전트를 생성하면 `Budget limit reached`로 실패하고 Claude Code는 여전히 실행 중인 백그라운드 서브에이전트를 중지합니다. 한도 적용 동작에는 Claude Code v2.1.217 이상이 필요합니다 | `claude -p --max-budget-usd 5.00 "query"` |109| `--max-budget-usd` | API 호출에 대한 예상 지출이 이 금액에 도달하면 실행을 중지합니다(인쇄 모드만 해당). Claude Code는 [클라이언트 측 비용 추정치](/docs/ko/agent-sdk/cost-tracking#estimates-not-billing)를 기준으로 한도를 확인하며, 이는 실제 청구 금액과 다를 수 있습니다. [서브에이전트](/docs/ko/sub-agents)의 지출이 한도에 포함됩니다. 지출이 한도를 초과할 수 있으므로 [여유를 두세요](/docs/ko/agent-sdk/agent-loop#budget-headroom). `--continue` 또는 `--resume`으로 대화로 돌아올 때 [이전 실행에서 복원된](/docs/ko/agent-sdk/cost-tracking#accumulate-costs-across-multiple-calls) 합계는 이에 포함되지 않습니다. 지출이 한도에 도달하면 다른 서브에이전트를 생성하면 `Budget limit reached`로 실패하고 Claude Code는 여전히 실행 중인 백그라운드 서브에이전트를 중지합니다. 한도 적용 동작에는 Claude Code v2.1.217 이상이 필요합니다 | `claude -p --max-budget-usd 5.00 "query"` |

110| `--max-turns` | 에이전트 턴의 수를 제한합니다(인쇄 모드만 해당). 한도에 도달하면 오류로 종료됩니다. 기본적으로 제한이 없습니다. `--input-format stream-json`을 사용하면 한도가 턴을 끝낼 때 여전히 대기열에 있는 메시지는 대기열에 남아 있고 자체 한도로 새 턴을 시작합니다 | `claude -p --max-turns 3 "query"` |110| `--max-turns` | 에이전트 턴의 수를 제한합니다(인쇄 모드만 해당). 한도에 도달하면 오류로 종료됩니다. 기본적으로 제한이 없습니다. `--input-format stream-json`을 사용하면 한도가 턴을 끝낼 때 여전히 대기열에 있는 메시지는 대기열에 남아 있고 자체 한도로 새 턴을 시작합니다 | `claude -p --max-turns 3 "query"` |

111| `--mcp-config` | JSON 파일 또는 문자열에서 MCP 서버를 로드합니다(공백으로 구분). 이 플래그를 `-p`와 함께 전달하면 Claude Code는 첫 번째 턴을 실행하기 전에 여전히 보류 중인 서버가 연결될 때까지 기다립니다. [`MCP_TIMEOUT`](/docs/ko/env-vars) 시작 시간 초과(기본값 30초)까지입니다. [캐시된 도구 목록](/docs/ko/mcp#managing-your-servers)이 있는 서버는 대기를 건너뛰고 처음 사용할 때 연결됩니다. 대기에는 Claude Code v2.1.221 이상이 필요합니다 | `claude --mcp-config ./mcp.json` |111| `--mcp-config` | JSON 파일 또는 문자열에서 MCP 서버를 로드합니다(공백으로 구분). 이 플래그를 `-p`와 함께 전달하면 Claude Code는 첫 번째 턴을 실행하기 전에 여전히 보류 중인 서버가 연결될 때까지 기다립니다. [`MCP_TIMEOUT`](/docs/ko/env-vars) 시작 타임아웃(기본값 30초)까지입니다. [캐시된 도구 목록](/docs/ko/mcp#managing-your-servers)이 있는 서버는 대기를 건너뛰고 처음 사용할 때 연결됩니다. [자체 호스팅 환경](/docs/ko/self-hosted-environments-configuration#connection-timing)에서는 대신 더 짧은 대기가 적용됩니다. 대기에는 Claude Code v2.1.221 이상이 필요합니다 | `claude --mcp-config ./mcp.json` |

112| `--model` | `sonnet`, `opus`, `haiku` 또는 `fable`과 같은 [모델 별칭](/docs/ko/model-config#model-aliases) 또는 모델의 전체 이름으로 현재 세션에 대한 모델을 설정합니다. [`model`](/docs/ko/settings-reference#model) 설정 및 [`ANTHROPIC_MODEL`](/docs/ko/model-config#environment-variables)을 재정의합니다 | `claude --model claude-sonnet-5` |112| `--model` | `sonnet`, `opus`, `haiku` 또는 `fable`과 같은 [모델 별칭](/docs/ko/model-config#model-aliases) 또는 모델의 전체 이름으로 현재 세션에 대한 모델을 설정합니다. [`model`](/docs/ko/settings-reference#model) 설정 및 [`ANTHROPIC_MODEL`](/docs/ko/model-config#environment-variables)을 재정의합니다 | `claude --model claude-sonnet-5` |

113| `--name`, `-n` | 세션의 표시 이름을 설정합니다. `/resume` 및 터미널 제목에 표시됩니다. `claude --resume <name>`으로 명명된 세션을 재개할 수 있습니다. 대화형 세션에서 이 머신의 다른 라이브 세션이 이미 이름을 사용하는 경우 Claude Code는 [그 변형을 적용합니다](/docs/ko/sessions#name-your-sessions). <br /><br />[`/rename`](/docs/ko/commands)은 세션 중에 이름을 변경하고 프롬프트 표시줄에도 표시합니다 | `claude -n "my-feature-work"` |113| `--name`, `-n` | 세션의 표시 이름을 설정합니다. `/resume` 및 터미널 제목에 표시됩니다. `claude --resume <name>`으로 명명된 세션을 재개할 수 있습니다. 대화형 세션에서 이 머신의 다른 라이브 세션이 이미 이름을 사용하는 경우 Claude Code는 [그 변형을 적용합니다](/docs/ko/sessions#name-your-sessions). <br /><br />[`/rename`](/docs/ko/commands)은 세션 중에 이름을 변경하고 프롬프트 표시줄에도 표시합니다 | `claude -n "my-feature-work"` |

114| `--no-chrome` | 이 세션에 대해 [Chrome 브라우저 통합](/docs/ko/chrome)을 비활성화합니다 | `claude --no-chrome` |114| `--no-chrome` | 이 세션에 대해 [Chrome 브라우저 통합](/docs/ko/chrome)을 비활성화합니다 | `claude --no-chrome` |

314| 저장소의 `.claude/settings.json`에 선언된 플러그인 및 마켓플레이스 | 아니오 | 클라우드 세션은 저장소가 [`enabledPlugins`](/docs/ko/settings-reference#enabledplugins) 아래에서 켜는 플러그인을 설치하지 않으며, [`extraKnownMarketplaces`](/docs/ko/settings-reference#extraknownmarketplaces) 아래에 나열하는 마켓플레이스의 플러그인도 포함됩니다 |314| 저장소의 `.claude/settings.json`에 선언된 플러그인 및 마켓플레이스 | 아니오 | 클라우드 세션은 저장소가 [`enabledPlugins`](/docs/ko/settings-reference#enabledplugins) 아래에서 켜는 플러그인을 설치하지 않으며, [`extraKnownMarketplaces`](/docs/ko/settings-reference#extraknownmarketplaces) 아래에 나열하는 마켓플레이스의 플러그인도 포함됩니다 |

315| 조직의 [서버 관리형 설정](/docs/ko/server-managed-settings) | 예, [Claude Tag](https://claude.com/docs/claude-tag/overview) 세션 제외 | 세션이 시작될 때 Anthropic의 서버에서 가져옵니다. 클라우드 세션에서 `availableModels`이 적용되는 방식은 [사용 환경 범위](/docs/ko/model-config#surface-coverage)를 참조하세요. MDM 또는 관리형 설정 파일을 통해 장치에 배포된 설정은 세션이 Anthropic 관리 VM에서 실행되기 때문에 적용되지 않습니다. [자체 호스팅 환경](/docs/ko/self-hosted-environments)에서 세션은 [Claude Code가 관리형 소스를 결합하는 방식](/docs/ko/managed-settings#how-claude-code-combines-managed-sources)에 따라 러너 이미지의 관리형 설정 파일도 읽습니다 |315| 조직의 [서버 관리형 설정](/docs/ko/server-managed-settings) | 예, [Claude Tag](https://claude.com/docs/claude-tag/overview) 세션 제외 | 세션이 시작될 때 Anthropic의 서버에서 가져옵니다. 클라우드 세션에서 `availableModels`이 적용되는 방식은 [사용 환경 범위](/docs/ko/model-config#surface-coverage)를 참조하세요. MDM 또는 관리형 설정 파일을 통해 장치에 배포된 설정은 세션이 Anthropic 관리 VM에서 실행되기 때문에 적용되지 않습니다. [자체 호스팅 환경](/docs/ko/self-hosted-environments)에서 세션은 [Claude Code가 관리형 소스를 결합하는 방식](/docs/ko/managed-settings#how-claude-code-combines-managed-sources)에 따라 러너 이미지의 관리형 설정 파일도 읽습니다 |

316| 사용자 `~/.claude/CLAUDE.md` | 아니오 | 저장소가 아닌 머신에 있습니다. [저장소에 커밋하지 않고 개인 기본 설정 추가](#add-personal-preferences-without-committing-to-the-repo)를 참조하세요 |316| 사용자 `~/.claude/CLAUDE.md` | 아니오 | 저장소가 아닌 머신에 있습니다. [저장소에 커밋하지 않고 개인 기본 설정 추가](#add-personal-preferences-without-committing-to-the-repo)를 참조하세요 |

317| 사용자 `~/.claude/skills/`, `~/.claude/agents/`, `~/.claude/commands/` | 아니오 | 저장소가 아닌 머신에 있습니다. 대신 저장소의 `.claude/` 디렉터리에 커밋합니다. 클라우드 세션은 claude.ai에서 활성화한 스킬을 자동으로 로드합니다 |317| 사용자 `~/.claude/skills/`, `~/.claude/agents/`, `~/.claude/commands/` | 아니오 | 저장소가 아닌 머신에 있습니다. 대신 저장소의 `.claude/` 디렉터리에 커밋합니다. 클라우드 세션은 [claude.ai에서 활성화한 스킬](/docs/ko/skills#skills-in-cowork-and-cloud-sessions)을 자동으로 로드합니다 |

318| 사용자 설정에서만 활성화된 플러그인 | 아니오 | 사용자 범위 `enabledPlugins`은 머신의 `~/.claude/settings.json`에 있습니다 |318| 사용자 설정에서만 활성화된 플러그인 | 아니오 | 사용자 범위 `enabledPlugins`은 머신의 `~/.claude/settings.json`에 있습니다 |

319| `claude mcp add`로 기본 로컬 범위 또는 사용자 범위에서 추가한 MCP 서버 | 아니오 | 이는 저장소가 아닌 머신의 `~/.claude.json`에 씁니다. 저장소의 [`.mcp.json`](/docs/ko/mcp#project-scope)에 쓰는 `claude mcp add --scope project`로 서버를 추가하고 해당 파일을 커밋합니다. 하나의 저장소가 있는 세션이 이를 로드합니다 |319| `claude mcp add`로 기본 로컬 범위 또는 사용자 범위에서 추가한 MCP 서버 | 아니오 | 이는 저장소가 아닌 머신의 `~/.claude.json`에 씁니다. 저장소의 [`.mcp.json`](/docs/ko/mcp#project-scope)에 쓰는 `claude mcp add --scope project`로 서버를 추가하고 해당 파일을 커밋합니다. 하나의 저장소가 있는 세션이 이를 로드합니다 |

320| 저장소의 `.claude/settings.json` `env` 블록의 전송 변수(예: `NODE_EXTRA_CA_CERTS` 및 [mTLS 클라이언트 인증서 변수](/docs/ko/network-config#mtls-authentication)) | 아니오 | 호스팅 환경이 세션의 API 연결을 관리하므로 Claude Code는 이러한 키를 무시하고 각 무시된 키를 세션의 디버그 로그에 기록합니다 |320| 저장소의 `.claude/settings.json` `env` 블록의 전송 변수(예: `NODE_EXTRA_CA_CERTS` 및 [mTLS 클라이언트 인증서 변수](/docs/ko/network-config#mtls-authentication)) | 아니오 | 호스팅 환경이 세션의 API 연결을 관리하므로 Claude Code는 이러한 키를 무시하고 각 무시된 키를 세션의 디버그 로그에 기록합니다 |

340| `CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION` | [WebSearch](/docs/ko/tools-reference#session-search-limit) 호출의 상한입니다(기본값: 200). Claude가 상한에 도달하면 이후의 WebSearch 호출은 이미 수집한 정보로 계속 진행하라는 알림을 반환합니다. 상한이 없는 양의 정수를 허용합니다. 그 밖의 값은 무시되고 기본값이 적용되므로 상한을 올릴 수는 있지만 끌 수는 없습니다. Claude Code v2.1.212 이상이 필요합니다 |340| `CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION` | [WebSearch](/docs/ko/tools-reference#session-search-limit) 호출의 상한입니다(기본값: 200). Claude가 상한에 도달하면 이후의 WebSearch 호출은 이미 수집한 정보로 계속 진행하라는 알림을 반환합니다. 상한이 없는 양의 정수를 허용합니다. 그 밖의 값은 무시되고 기본값이 적용되므로 상한을 올릴 수는 있지만 끌 수는 없습니다. Claude Code v2.1.212 이상이 필요합니다 |

341| `CLAUDE_CODE_MCP_ALLOWLIST_ENV` | 셸 환경을 상속하는 대신, 안전한 기본 환경과 서버에 구성된 `env`만으로 stdio MCP 서버를 생성하려면 `1`로 설정합니다 |341| `CLAUDE_CODE_MCP_ALLOWLIST_ENV` | 셸 환경을 상속하는 대신, 안전한 기본 환경과 서버에 구성된 `env`만으로 stdio MCP 서버를 생성하려면 `1`로 설정합니다 |

342| `CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS` | 아직 실행 중인 MCP 도구 호출이 [백그라운드 작업으로 이동](/docs/ko/mcp#automatic-backgrounding-of-long-tool-calls)하기까지의 경과 시간(밀리초)입니다(기본값: 120000, 즉 2분). 자동 백그라운드 전환을 끄려면 `0`으로 설정합니다. Claude Code v2.1.212 이상이 필요합니다 |342| `CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS` | 아직 실행 중인 MCP 도구 호출이 [백그라운드 작업으로 이동](/docs/ko/mcp#automatic-backgrounding-of-long-tool-calls)하기까지의 경과 시간(밀리초)입니다(기본값: 120000, 즉 2분). 자동 백그라운드 전환을 끄려면 `0`으로 설정합니다. Claude Code v2.1.212 이상이 필요합니다 |

343| `CLAUDE_CODE_MCP_STARTUP_WAIT_MS` | [비대화형](/docs/ko/headless) 세션의 첫 번째 턴이 아직 연결 중인 MCP 서버를 기다리는 시간(밀리초)으로, 기본 [첫 번째 턴 대기](/docs/ko/agent-sdk/mcp#connection-timing)를 대체합니다. 설정하면 대기가 보류 중인 모든 서버에 적용됩니다. 대기를 건너뛰려면 `0`으로 설정합니다. [`--permission-prompt-tool`](/docs/ko/cli-reference#cli-flags) 서버는 값과 관계없이 자체 `MCP_TIMEOUT` 대기를 유지합니다. Claude Code v2.1.274 이상이 필요합니다 |343| `CLAUDE_CODE_MCP_STARTUP_WAIT_MS` | [비대화형](/docs/ko/headless) 세션의 첫 번째 턴이 아직 연결 중인 MCP 서버를 기다리는 시간(밀리초)으로, 기본 [첫 번째 턴 대기](/docs/ko/agent-sdk/mcp#connection-timing)를 대체합니다. 설정하면 대기는 보류 중인 모든 서버를 대상으로 하며, [자체 호스팅 환경](/docs/ko/self-hosted-environments-configuration#connection-timing)에서는 대기 시간만 변경합니다. `0`으로 설정하면 대기를 건너뜁니다. [`--permission-prompt-tool`](/docs/ko/cli-reference#cli-flags) 서버는 값과 관계없이 자체 `MCP_TIMEOUT` 대기를 유지합니다. Claude Code v2.1.274 이상이 필요합니다 |

344| `CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT` | MCP 도구 호출의 유휴 타임아웃(밀리초)입니다. stdio, HTTP, SSE, WebSocket 또는 [claude.ai 커넥터](/docs/ko/mcp#use-mcp-servers-from-claude-ai) MCP 서버가 이 시간 동안 응답이나 진행 알림을 보내지 않으면, 전체 `MCP_TOOL_TIMEOUT`을 기다리는 대신 도구 호출이 오류와 함께 중단됩니다. 네트워크 서버의 300000(5분), stdio 서버의 1800000(30분)이라는 전송 방식별 기본값을 재정의합니다. 유휴 검사를 비활성화하려면 `0`으로 설정합니다. 1000 미만의 값은 1초로 올라가며, 값은 유효 `MCP_TOOL_TIMEOUT`으로 제한됩니다. `.mcp.json`에서 서버별 `timeout`이 1000 이상이면 해당 서버의 유휴 시간이 최소 `timeout` 값으로 올라갑니다. IDE 서버나 SDK 인프로세스 서버에는 적용되지 않습니다. Claude Code v2.1.187 이상이 필요합니다. v2.1.203 이전에는 stdio 서버가 유휴 타임아웃에서 제외되었습니다 |344| `CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT` | MCP 도구 호출의 유휴 타임아웃(밀리초)입니다. stdio, HTTP, SSE, WebSocket 또는 [claude.ai 커넥터](/docs/ko/mcp#use-mcp-servers-from-claude-ai) MCP 서버가 이 시간 동안 응답이나 진행 알림을 보내지 않으면, 전체 `MCP_TOOL_TIMEOUT`을 기다리는 대신 도구 호출이 오류와 함께 중단됩니다. 네트워크 서버의 300000(5분), stdio 서버의 1800000(30분)이라는 전송 방식별 기본값을 재정의합니다. 유휴 검사를 비활성화하려면 `0`으로 설정합니다. 1000 미만의 값은 1초로 올라가며, 값은 유효 `MCP_TOOL_TIMEOUT`으로 제한됩니다. `.mcp.json`에서 서버별 `timeout`이 1000 이상이면 해당 서버의 유휴 시간이 최소 `timeout` 값으로 올라갑니다. IDE 서버나 SDK 인프로세스 서버에는 적용되지 않습니다. Claude Code v2.1.187 이상이 필요합니다. v2.1.203 이전에는 stdio 서버가 유휴 타임아웃에서 제외되었습니다 |

345| `CLAUDE_CODE_MESSAGING_SOCKET` | 사용자가 아닌 Claude Code가 설정합니다. [inbox 소켓](/docs/ko/cross-session-messaging#the-sessions-inbox-socket)을 바인딩하는 세션에서 Claude Code는 소켓을 바인딩할 때 해당 소켓의 경로를 훅과 Bash 명령에 export합니다. 메시징이 켜진 상태로 시작하는 세션에서는 Claude Code가 훅이 실행되기 전에 소켓을 바인딩합니다. 머신의 다른 세션은 이 경로로 메시지를 전달합니다. 각 세션은 부모로부터 상속된 소켓이 아닌 자체 소켓을 export하며, 이 소켓으로 도착하는 메시지는 세션의 [인바운드 제어](/docs/ko/cross-session-messaging#control-inbound-messages)를 거칩니다. 설정의 `env` 블록으로는 설정할 수 없습니다. Claude Code v2.1.224 이상이 필요합니다 |345| `CLAUDE_CODE_MESSAGING_SOCKET` | 사용자가 아닌 Claude Code가 설정합니다. [inbox 소켓](/docs/ko/cross-session-messaging#the-sessions-inbox-socket)을 바인딩하는 세션에서 Claude Code는 소켓을 바인딩할 때 해당 소켓의 경로를 훅과 Bash 명령에 export합니다. 메시징이 켜진 상태로 시작하는 세션에서는 Claude Code가 훅이 실행되기 전에 소켓을 바인딩합니다. 머신의 다른 세션은 이 경로로 메시지를 전달합니다. 각 세션은 부모로부터 상속된 소켓이 아닌 자체 소켓을 export하며, 이 소켓으로 도착하는 메시지는 세션의 [인바운드 제어](/docs/ko/cross-session-messaging#control-inbound-messages)를 거칩니다. 설정의 `env` 블록으로는 설정할 수 없습니다. Claude Code v2.1.224 이상이 필요합니다 |

346| `CLAUDE_CODE_MESSAGING_TOKEN` | 사용자가 아닌 Claude Code가 설정합니다. [inbox 소켓](/docs/ko/cross-session-messaging#the-sessions-inbox-socket)을 바인딩하는 세션에서 Claude Code는 `CLAUDE_CODE_MESSAGING_SOCKET`과 함께 이 세션별 토큰을 훅과 Bash 명령에 export합니다. 소켓에 게시하는 스크립트는 첫 줄로 `{"type":"auth","token":"<token>"}`를 보내 해당 세션에 속함을 증명할 수 있습니다. 네이티브 Windows에서는 Claude Code가 이 줄을 요구하며, 유효한 줄로 시작하지 않는 연결은 모두 닫습니다. Claude Code가 토큰을 확인하는 시점은 [자체 자식 규칙](/docs/ko/cross-session-messaging#the-sessions-inbox-socket)에 설명되어 있습니다. 각 세션은 부모 세션에서 상속된 토큰이 아닌 자체 토큰을 export합니다. 설정의 `env` 블록으로는 설정할 수 없습니다. Claude Code v2.1.228 이상이 필요합니다 |346| `CLAUDE_CODE_MESSAGING_TOKEN` | 사용자가 아닌 Claude Code가 설정합니다. [inbox 소켓](/docs/ko/cross-session-messaging#the-sessions-inbox-socket)을 바인딩하는 세션에서 Claude Code는 `CLAUDE_CODE_MESSAGING_SOCKET`과 함께 이 세션별 토큰을 훅과 Bash 명령에 export합니다. 소켓에 게시하는 스크립트는 첫 줄로 `{"type":"auth","token":"<token>"}`를 보내 해당 세션에 속함을 증명할 수 있습니다. 네이티브 Windows에서는 Claude Code가 이 줄을 요구하며, 유효한 줄로 시작하지 않는 연결은 모두 닫습니다. Claude Code가 토큰을 확인하는 시점은 [자체 자식 규칙](/docs/ko/cross-session-messaging#the-sessions-inbox-socket)에 설명되어 있습니다. 각 세션은 부모 세션에서 상속된 토큰이 아닌 자체 토큰을 export합니다. 설정의 `env` 블록으로는 설정할 수 없습니다. Claude Code v2.1.228 이상이 필요합니다 |

247| `Windows reported an error (EBADF) when Claude Code read this session's transcript file` | [명령줄 오류](#windows-reported-an-error-ebadf) |247| `Windows reported an error (EBADF) when Claude Code read this session's transcript file` | [명령줄 오류](#windows-reported-an-error-ebadf) |

248| `Cannot switch renderers in this session` | [명령줄 오류](#cannot-switch-renderers-in-this-session) |248| `Cannot switch renderers in this session` | [명령줄 오류](#cannot-switch-renderers-in-this-session) |

249| `Cannot switch renderers while work is running in the background` | [명령줄 오류](#cannot-switch-renderers-in-this-session) |249| `Cannot switch renderers while work is running in the background` | [명령줄 오류](#cannot-switch-renderers-in-this-session) |

250| `Claude Code couldn't restart` | [명령줄 오류](#claude-code-couldnt-restart) |

250| `Couldn't open Claude Desktop` | [명령줄 오류](#couldnt-open-claude-desktop) |251| `Couldn't open Claude Desktop` | [명령줄 오류](#couldnt-open-claude-desktop) |

251| `Failed to open Claude Desktop. Please try opening it manually.` | [명령줄 오류](#couldnt-open-claude-desktop) |252| `Failed to open Claude Desktop. Please try opening it manually.` | [명령줄 오류](#couldnt-open-claude-desktop) |

252| `Couldn't read your Zed keymap` / `Couldn't back up your Zed keymap` / `Couldn't update your Zed keymap` | [명령줄 오류](#terminal-setup-left-your-zed-keymap-unchanged) |253| `Couldn't read your Zed keymap` / `Couldn't back up your Zed keymap` / `Couldn't update your Zed keymap` | [명령줄 오류](#terminal-setup-left-your-zed-keymap-unchanged) |

334| `Session isn't responding` / `Press enter again to restart this session — it isn't responding` | [백그라운드 세션 오류](#session-isnt-responding) |335| `Session isn't responding` / `Press enter again to restart this session — it isn't responding` | [백그라운드 세션 오류](#session-isnt-responding) |

335| `Session <id> was stopped while the respawn was in flight` | [백그라운드 세션 오류](#session-was-stopped-while-the-respawn-was-in-flight) |336| `Session <id> was stopped while the respawn was in flight` | [백그라운드 세션 오류](#session-was-stopped-while-the-respawn-was-in-flight) |

336| `This session was running agent '<name>', which is no longer available` | [백그라운드 세션 오류](#session-agent-no-longer-available) |337| `This session was running agent '<name>', which is no longer available` | [백그라운드 세션 오류](#session-agent-no-longer-available) |

338| `This session restarted <time> after its next /loop wakeup was due, so that wakeup will not fire` | [백그라운드 세션 오류](#restarted-after-its-next-loop-wakeup-was-due) |

337| `CLAUDE_CODE_PROCESS_WRAPPER: launcher ...` | [백그라운드 세션 오류](#claude_code_process_wrapper-launcher-errors) |339| `CLAUDE_CODE_PROCESS_WRAPPER: launcher ...` | [백그라운드 세션 오류](#claude_code_process_wrapper-launcher-errors) |

338| `EUNKNOWN: unknown error, uv_spawn` | [백그라운드 세션 오류](#eunknown-when-starting-a-background-session) |340| `EUNKNOWN: unknown error, uv_spawn` | [백그라운드 세션 오류](#eunknown-when-starting-a-background-session) |

339| `EACCES: permission denied, posix_spawn` | [백그라운드 세션 오류](#eacces-when-starting-a-background-session) |341| `EACCES: permission denied, posix_spawn` | [백그라운드 세션 오류](#eacces-when-starting-a-background-session) |

439| :- | :- | :- |441| :- | :- | :- |

440| [`CLAUDE_CODE_MAX_RETRIES`](/docs/ko/env-vars) | 10 | 재시도 횟수입니다. v2.1.186부터 최대 15로 제한됩니다. v2.1.199부터는 `CLAUDE_CODE_RETRY_WATCHDOG`이 기본값을 높이고 상한을 제거합니다. 스크립트에서 실패를 더 빨리 확인하려면 값을 낮추세요. |442| [`CLAUDE_CODE_MAX_RETRIES`](/docs/ko/env-vars) | 10 | 재시도 횟수입니다. v2.1.186부터 최대 15로 제한됩니다. v2.1.199부터는 `CLAUDE_CODE_RETRY_WATCHDOG`이 기본값을 높이고 상한을 제거합니다. 스크립트에서 실패를 더 빨리 확인하려면 값을 낮추세요. |

441| [`CLAUDE_CODE_RETRY_WATCHDOG`](/docs/ko/env-vars) | 설정 안 됨 | CI 작업과 같은 무인 세션에서 `1`로 설정하면 `CLAUDE_CODE_MAX_RETRIES`회 시도 후 실패하는 대신 `429` 및 `529` 용량 오류를 무기한 재시도합니다. 표준 속도 요청이 지출 한도나 소진된 사용량 크레딧을 보고하는 `429`를 받으면, 일정에 따라 재설정되는 [게이트웨이 지출 한도](#spend-limit-reached)에서 온 것이라도 Claude Code는 즉시 실패합니다. v2.1.239 이전에는 워치독이 이를 무기한 재시도했습니다. 빠른 모드 요청에 대해서는 [속도 제한 처리](/docs/ko/fast-mode#handle-rate-limits)를 참조하세요. v2.1.199 이상에서는 서버 오류, 시간 초과, 끊어진 연결 등 다른 일시적인 오류의 기본 재시도 횟수도 약 3시간의 백오프에 해당하는 300으로 높이고, `CLAUDE_CODE_MAX_RETRIES`를 명시적으로 설정한 경우 15의 상한을 제거합니다. |443| [`CLAUDE_CODE_RETRY_WATCHDOG`](/docs/ko/env-vars) | 설정 안 됨 | CI 작업과 같은 무인 세션에서 `1`로 설정하면 `CLAUDE_CODE_MAX_RETRIES`회 시도 후 실패하는 대신 `429` 및 `529` 용량 오류를 무기한 재시도합니다. 표준 속도 요청이 지출 한도나 소진된 사용량 크레딧을 보고하는 `429`를 받으면, 일정에 따라 재설정되는 [게이트웨이 지출 한도](#spend-limit-reached)에서 온 것이라도 Claude Code는 즉시 실패합니다. v2.1.239 이전에는 워치독이 이를 무기한 재시도했습니다. 빠른 모드 요청에 대해서는 [속도 제한 처리](/docs/ko/fast-mode#handle-rate-limits)를 참조하세요. v2.1.199 이상에서는 서버 오류, 시간 초과, 끊어진 연결 등 다른 일시적인 오류의 기본 재시도 횟수도 약 3시간의 백오프에 해당하는 300으로 높이고, `CLAUDE_CODE_MAX_RETRIES`를 명시적으로 설정한 경우 15의 상한을 제거합니다. |

444| [`CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS`](/docs/ko/env-vars) | 설정 안 됨 | `CLAUDE_CODE_RETRY_WATCHDOG`이 설정된 경우 각 API 요청이 `429` 및 `529` 오류가 해소되기를 기다리는 최대 시간(밀리초)입니다. 설정하지 않으면 대기 시간에 제한이 없습니다. Claude Code v2.1.295 이상이 필요합니다. |

442| [`CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS`](/docs/ko/env-vars) | 500 | API가 `529` 과부하 오류로 거부한 요청의 재시도 간 백오프 시작 지연 시간(밀리초)입니다. API가 용량 한계에 도달했을 때 재시도를 더 긴 기간에 걸쳐 분산하려면 최대 32000까지 값을 높이세요. `CLAUDE_CODE_RETRY_WATCHDOG`이 `1`로 설정되어 있거나 거부된 요청이 [빠른 모드](/docs/ko/fast-mode#handle-rate-limits)로 전송된 경우에는 효과가 없습니다. Claude Code v2.1.292 이상이 필요합니다. |445| [`CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS`](/docs/ko/env-vars) | 500 | API가 `529` 과부하 오류로 거부한 요청의 재시도 간 백오프 시작 지연 시간(밀리초)입니다. API가 용량 한계에 도달했을 때 재시도를 더 긴 기간에 걸쳐 분산하려면 최대 32000까지 값을 높이세요. `CLAUDE_CODE_RETRY_WATCHDOG`이 `1`로 설정되어 있거나 거부된 요청이 [빠른 모드](/docs/ko/fast-mode#handle-rate-limits)로 전송된 경우에는 효과가 없습니다. Claude Code v2.1.292 이상이 필요합니다. |

443| [`API_TIMEOUT_MS`](/docs/ko/env-vars) | 600000 | 요청당 타임아웃(밀리초)입니다. 느린 네트워크나 프록시의 경우 값을 높이세요. [No response from API](#no-response-from-api)에 설명된 대로, Claude Code가 응답 헤더를 기다리는 시간의 상한으로도 사용됩니다. |446| [`API_TIMEOUT_MS`](/docs/ko/env-vars) | 600000 | 요청당 타임아웃(밀리초)입니다. 느린 네트워크나 프록시의 경우 값을 높이세요. [No response from API](#no-response-from-api)에 설명된 대로, Claude Code가 응답 헤더를 기다리는 시간의 상한으로도 사용됩니다. |

444| [`CLAUDE_CODE_NONSTREAMING_TIMEOUT_RETRIES`](/docs/ko/env-vars) | 설정 안 됨 | 시간 초과된 [비스트리밍 요청](#streaming-response-ended-before-any-complete-data-was-received)을 다시 보내는 횟수의 한도입니다. 한도에 도달하면 요청이 실패합니다. 생성하는 데 타임아웃보다 오래 걸리는 Claude의 응답은 다시 보낼 때마다 다시 시간 초과되므로, 더 빨리 실패하려면 `0`과 같은 낮은 값으로 설정하세요. 각 비스트리밍 시도는 로컬 세션에서 300초 후, 또는 `API_TIMEOUT_MS`를 양수 값으로 설정한 경우 해당 시간 후에 시간 초과됩니다. Claude Code v2.1.285 이상이 필요합니다. |447| [`CLAUDE_CODE_NONSTREAMING_TIMEOUT_RETRIES`](/docs/ko/env-vars) | 설정 안 됨 | 시간 초과된 [비스트리밍 요청](#streaming-response-ended-before-any-complete-data-was-received)을 다시 보내는 횟수의 한도입니다. 한도에 도달하면 요청이 실패합니다. 생성하는 데 타임아웃보다 오래 걸리는 Claude의 응답은 다시 보낼 때마다 다시 시간 초과되므로, 더 빨리 실패하려면 `0`과 같은 낮은 값으로 설정하세요. 각 비스트리밍 시도는 로컬 세션에서 300초 후, 또는 `API_TIMEOUT_MS`를 양수 값으로 설정한 경우 해당 시간 후에 시간 초과됩니다. Claude Code v2.1.285 이상이 필요합니다. |

1900 1903 

1901Claude Code는 [관리형 설정 파일, MDM 정책 또는 정책 도우미](/docs/ko/managed-settings)가 [`forceLoginMethod`](/docs/ko/settings-reference#forceloginmethod)를 `"gateway"`로 설정하거나 `forceLoginMethod` 없이 [`forceLoginGatewayUrl`](/docs/ko/settings-reference#forcelogingatewayurl)을 설정할 때 이 확인을 건너뜁니다. 두 구성 중 하나를 사용하면 Claude Code는 Anthropic 로그인 방법이 아닌 **클라우드 게이트웨이** 화면에서 로그인 단계를 엽니다. Claude Code는 또한 머신에 관리형 설정 소스가 존재하지만 읽을 수 없을 때 확인을 건너뜁니다. 해당 소스가 게이트웨이 구성을 보유할 수 있기 때문입니다. v2.1.247 이전에는 Claude Code가 이 구성에서도 확인을 실행했고, Anthropic의 엔드포인트에 도달할 수 없을 때 이 오류로 종료했습니다.1904Claude Code는 [관리형 설정 파일, MDM 정책 또는 정책 도우미](/docs/ko/managed-settings)가 [`forceLoginMethod`](/docs/ko/settings-reference#forceloginmethod)를 `"gateway"`로 설정하거나 `forceLoginMethod` 없이 [`forceLoginGatewayUrl`](/docs/ko/settings-reference#forcelogingatewayurl)을 설정할 때 이 확인을 건너뜁니다. 두 구성 중 하나를 사용하면 Claude Code는 Anthropic 로그인 방법이 아닌 **클라우드 게이트웨이** 화면에서 로그인 단계를 엽니다. Claude Code는 또한 머신에 관리형 설정 소스가 존재하지만 읽을 수 없을 때 확인을 건너뜁니다. 해당 소스가 게이트웨이 구성을 보유할 수 있기 때문입니다. v2.1.247 이전에는 Claude Code가 이 구성에서도 확인을 실행했고, Anthropic의 엔드포인트에 도달할 수 없을 때 이 오류로 종료했습니다.

1902 1905 

1906Claude Code는 관리형 설정이 없는 머신에서 사용자 자신의 `~/.claude/settings.json`이 `forceLoginMethod` 및 `forceLoginGatewayUrl`로 [게이트웨이를 지정](/docs/ko/claude-apps-gateway#set-the-gateway-url-in-user-settings)하는 경우에도 확인을 건너뜁니다. v2.1.295 이전에는 Claude Code가 이 경우에도 확인을 실행했습니다.

1907 

1903**수행할 작업:**1908**수행할 작업:**

1904 1909 

1905* 메시지가 프록시 변수의 이름을 지정하는 경우, 해당 값이 올바른 프록시를 가리키는지 확인하고 네트워크 팀에 메시지의 호스트에 대한 HTTPS 연결을 허용하도록 요청합니다. [네트워크 구성](/docs/ko/network-config)을 참조합니다.1910* 메시지가 프록시 변수의 이름을 지정하는 경우, 해당 값이 올바른 프록시를 가리키는지 확인하고 네트워크 팀에 메시지의 호스트에 대한 HTTPS 연결을 허용하도록 요청합니다. [네트워크 구성](/docs/ko/network-config)을 참조합니다.

3412 3417 

3413Claude Code는 [동적 컨텍스트를 주입하는](/docs/ko/skills#when-an-injected-command-fails) 모든 스킬에 대해 같은 오류를 표시하며, 주입된 명령이 실패하면 해당 스킬 호출이 중단됩니다. 명령이 실행되기도 전에 발생하는 두 가지 유사한 문자열이 있습니다:3418Claude Code는 [동적 컨텍스트를 주입하는](/docs/ko/skills#when-an-injected-command-fails) 모든 스킬에 대해 같은 오류를 표시하며, 주입된 명령이 실패하면 해당 스킬 호출이 중단됩니다. 명령이 실행되기도 전에 발생하는 두 가지 유사한 문자열이 있습니다:

3414 3419 

3415* `Shell command permission check failed for pattern "..."`: 명령의 권한 검사에서 허용되지 않았습니다. [주입된 명령에 대한 권한 검사](/docs/ko/skills#permission-checks-on-injected-commands)에서 각 권한 모드에서 어떤 결과가 중단을 일으키는지, 그리고 `allowed-tools`로 명령을 사전 승인하는 방법을 다룹니다3420* `Shell command permission check failed for pattern "..."`: 명령의 권한 검사에서 허용되지 않았습니다. [주입된 명령의 권한 검사](/docs/ko/skills#permission-checks-on-injected-commands)에서 각 권한 모드에서 어떤 결과가 중단을 일으키는지, 그리고 `allowed-tools`로 명령을 미리 승인하는 방법을 설명합니다

3416* ``Skill <name> requires bash (`shell: bash` in frontmatter) but Git Bash was not found``: 스킬의 frontmatter가 bash가 없는 시스템에서 bash를 요구합니다. Git for Windows를 설치하거나 frontmatter를 `shell: powershell`로 변경합니다. [주입된 명령이 실행되는 방식](/docs/ko/skills#how-injected-commands-run)을 참조하십시오3421* ``Skill <name> requires bash (`shell: bash` in frontmatter) but Git Bash was not found``: 스킬의 frontmatter가 bash가 없는 머신에서 bash를 요구합니다. Git for Windows를 설치하거나 frontmatter를 `shell: powershell`로 변경합니다. [주입된 명령이 실행되는 방식](/docs/ko/skills#how-injected-commands-run)을 참조하세요

3417 3422 

3418**해결 방법:**3423**해결 방법:**

3419 3424 

3562 3567 

3563* **기본 브랜치를 전달하지 않은 경우**: Claude Code는 저장소의 기본 브랜치와 비교했으며, 위 예시처럼 기본 브랜치를 명시적으로 전달하도록 제안합니다3568* **기본 브랜치를 전달하지 않은 경우**: Claude Code는 저장소의 기본 브랜치와 비교했으며, 위 예시처럼 기본 브랜치를 명시적으로 전달하도록 제안합니다

3564* **클론에 이미 있는 기본 브랜치를 전달한 경우**: 힌트는 ``Make sure <branch> exists locally or on origin (try `git fetch origin <branch>`)``입니다3569* **클론에 이미 있는 기본 브랜치를 전달한 경우**: 힌트는 ``Make sure <branch> exists locally or on origin (try `git fetch origin <branch>`)``입니다

3565* **클론에 없는 기본 브랜치를 전달한 경우**: Claude Code는 비교하기 전에 origin에서 해당 브랜치를 fetch했습니다. 힌트는 ``<branch> was fetched from origin but shares no history with HEAD. If another branch is your real base, pass it explicitly (`/code-review ultra <branch>`)``입니다. Claude Code가 클론이 shallow인지 판단할 수 없는 경우에는 대신 `git fetch --unshallow origin`을 제안합니다. v2.1.221 이전에는 fetch한 모든 기본 브랜치에 대해 힌트가 `git fetch --unshallow origin`을 제안했으며, 완전한 클론에서 이 명령은 `fatal: --unshallow on a complete repository does not make sense`로 실패합니다.3570* **클론에 없던 기본 브랜치를 전달한 경우**: Claude Code는 비교하기 전에 origin에서 해당 브랜치를 가져왔습니다. 힌트는 ``<branch> was fetched from origin but shares no history with HEAD. If another branch is your real base, pass it explicitly (`/code-review ultra <branch>`)``로 표시되며, Claude Code가 클론이 얕은 클론인지 판단할 수 없으면 대신 `git fetch --unshallow origin`을 제안합니다. v2.1.221 이전에는 가져온 모든 기본 브랜치에 대해 힌트가 `git fetch --unshallow origin`을 제안했으며, 완전한 클론에서는 이 명령이 `fatal: --unshallow on a complete repository does not make sense`로 실패합니다.

3566 3571 

3567**해결 방법:**3572**해결 방법:**

3568 3573 

3816 3821 

3817* 해당 제한 없이 시작된 세션에서 `/tui fullscreen`을 실행하거나, 다시 전환하려면 `/tui default`를 실행합니다. Claude Code는 그곳에서 [`tui` 설정](/docs/ko/settings-reference#tui)을 저장합니다3822* 해당 제한 없이 시작된 세션에서 `/tui fullscreen`을 실행하거나, 다시 전환하려면 `/tui default`를 실행합니다. Claude Code는 그곳에서 [`tui` 설정](/docs/ko/settings-reference#tui)을 저장합니다

3818 3823 

3824<h3 id="claude-code-couldnt-restart">

3825 Claude Code couldn't restart

3826</h3>

3827 

3828Claude Code가 다시 시작하는 중이었습니다. 예를 들어 [`/tui`](/docs/ko/fullscreen#enable-fullscreen-rendering)를 실행한 후 전체 화면 렌더링으로 전환하거나 전체 화면 렌더링에서 전환하는 경우입니다. 세션은 닫았지만 새 프로세스를 시작할 수 없었으므로 이 메시지를 출력하고 상태 1로 종료했습니다.

3829 

3830```text theme={null}

3831Claude Code couldn't restart. Your conversation is saved. Start Claude Code again and run /resume to pick it up.

3832```

3833 

3834다시 시작할 때 다시 열 대화가 없었던 경우(예: 새 세션에서 `/tui`가 첫 입력이었던 경우) 메시지는 `Claude Code couldn't restart. Start Claude Code again.`입니다.

3835 

3836**해결 방법:**

3837 

3838* 같은 디렉터리에서 셸로 `claude`를 다시 실행합니다. 메시지에 대화가 저장되었다고 표시되었다면 새 세션에서 [`/resume`](/docs/ko/sessions#resume-a-session)을 실행하고 해당 대화를 선택합니다

3839* 다시 시작이 계속 실패하면 셸에서 [`claude --debug-file claude-debug.log`](/docs/ko/cli-reference#cli-flags)로 Claude Code를 시작합니다. 해당 세션에서 다시 시작이 실패하면, 시작한 디렉터리의 `claude-debug.log`에 운영 체제의 오류와 함께 `Failed to relaunch:` 줄이 기록됩니다. [문제를 보고](#report-an-error)할 때 해당 줄을 포함하십시오

3840 

3819<h3 id="couldnt-open-claude-desktop">3841<h3 id="couldnt-open-claude-desktop">

3820 Claude Desktop을 열 수 없음3842 Claude Desktop을 열 수 없음

3821</h3>3843</h3>

4752 Worktree 격리 확인으로 인해 명령이 차단됨4774 Worktree 격리 확인으로 인해 명령이 차단됨

4753</h3>4775</h3>

4754 4776 

4755Claude가 [worktree에 격리된 세션](/docs/ko/worktrees#how-claude-code-enforces-isolation)에서 Bash 또는 Monitor 명령을 실행했으며, Claude Code가 다음 두 가지 이유 중 하나로 거부했습니다:4777Claude가 [worktree에 격리된 세션](/docs/ko/worktrees#how-claude-code-enforces-isolation)에서 Bash, [PowerShell](/docs/ko/tools-reference#powershell-tool) 또는 [Monitor](/docs/ko/tools-reference#monitor-tool) 명령을 실행했으며, Claude Code가 다음 이유 중 하나로 거부했습니다:

4756 4778 

4757* 명령이 git을 주 체크아웃으로 지정합니다.4779* 명령이 주 체크아웃 또는 다른 worktree에서 실행됩니다. 메시지는 작업 디렉터리가 `resolved to the shared checkout` 또는 `is in a different worktree`라고 표시합니다.

4758* Claude Code는 명령 텍스트에서 명령이 실행하는 모든 git이 worktree 내에 머물러 있는지 확인할 수 없습니다. git을 명시하지 않는 명령도 이 이유로 거부될 수 있습니다. `${!name}`과 같은 변수 간접 참조를 확장하거나 `${ command; }`와 같은 Bash 함수 치환을 실행하면 자체가 명령일 수 있는 런타임 값이 생성되기 때문입니다.4780* Bash 또는 Monitor 명령이 git을 주 체크아웃으로 지정합니다.

4781* Claude Code는 Bash 또는 Monitor 명령의 텍스트에서 명령이 실행하는 모든 git이 worktree 내에 머물러 있는지 확인할 수 없습니다. git을 명시하지 않는 명령도 이 이유로 거부될 수 있습니다. `${!name}`과 같은 변수 간접 참조를 확장하거나 `${ command; }`와 같은 Bash 함수 치환을 실행하면 자체가 명령일 수 있는 런타임 값이 생성되기 때문입니다.

4759 4782 

4760메시지의 중간은 확인할 수 없는 것을 명시합니다:4783메시지는 `is isolated in the worktree <path>, but this command` 뒤에 이유를 표시합니다. 예를 들어 Claude Code가 텍스트를 확인할 수 없는 명령의 경우 다음과 같습니다:

4761 4784 

4762```text wrap theme={null}4785```text wrap theme={null}

4763This session is isolated in the worktree /path/to/worktree, but this command evaluates ${!x@P} arithmetically inside a construct too complex to verify, which can run a command hidden in a variable's value. Refusing to run it — a worktree-isolated session's git operations must target its own worktree. Split it into plain, separate commands and run them from /path/to/worktree.4786This session is isolated in the worktree /path/to/worktree, but this command evaluates ${!x@P} arithmetically inside a construct too complex to verify, which can run a command hidden in a variable's value. Refusing to run it — a worktree-isolated session's git operations must target its own worktree. Split it into plain, separate commands and run them from /path/to/worktree.

4765 4788 

4766**할 일:**4789**할 일:**

4767 4790 

4768* 일반적으로 아무것도 하지 않습니다: Claude는 메시지를 읽고 최종 문장이 요청하는 방식으로 명령을 다시 작성합니다.4791* **git이 주 체크아웃을 가리키거나 명령 텍스트를 확인할 수 없는 경우**: 아무것도 하지 않습니다. Claude는 메시지를 읽고 최종 문장이 요청하는 방식으로 명령을 다시 작성합니다. 요청한 명령이 텍스트의 확장 때문에 계속 거부되면 플래그된 값을 문자 그대로 작성하고 worktree 내에서 git을 자체 일반 명령으로 실행합니다.

4769* 요청한 명령이 계속 거부되면 플래그된 값을 문자 그대로 철자합니다: 간접 참조 또는 치환을 해당 값으로 바꾸고 worktree 내에서 git을 자체 일반 명령으로 실행합니다.

4770* 의도적으로 주 체크아웃에 작용하려면 세션 외부의 터미널에서 명령을 직접 실행합니다.4792* 의도적으로 주 체크아웃에 작용하려면 세션 외부의 터미널에서 명령을 직접 실행합니다.

4771 4793 

4772<h3 id="this-session-has-no-saved-transcript">4794<h3 id="this-session-has-no-saved-transcript">

4946* 또는 존재하는 에이전트를 명시하는 `--agent <name>`으로 재개하여 대신 해당 에이전트로 세션을 실행합니다.4968* 또는 존재하는 에이전트를 명시하는 `--agent <name>`으로 재개하여 대신 해당 에이전트로 세션을 실행합니다.

4947* 에이전트가 프로젝트 범위이고 세션의 원래 디렉터리를 신뢰하지 않았으면 거기서 Claude Code를 한 번 실행하고 신뢰 대화 상자를 수락한 다음 다시 재개합니다.4969* 에이전트가 프로젝트 범위이고 세션의 원래 디렉터리를 신뢰하지 않았으면 거기서 Claude Code를 한 번 실행하고 신뢰 대화 상자를 수락한 다음 다시 재개합니다.

4948 4970 

4971<h3 id="restarted-after-its-next-loop-wakeup-was-due">

4972 다음 /loop 깨우기 예정 시간이 지난 후 이 세션이 다시 시작됨

4973</h3>

4974 

4975[백그라운드 세션](/docs/ko/agent-view)의 [자체 페이스 `/loop`](/docs/ko/scheduled-tasks#let-claude-choose-the-interval)가 중지되었습니다. 루프가 다음 깨우기를 기다리는 동안 세션의 프로세스가 종료되었고, 세션의 [다음 프로세스](/docs/ko/agent-view#the-supervisor-process)가 시작되기 전에 해당 깨우기 예정 시간이 지났습니다. 놓친 깨우기는 늦게 실행되지 않습니다. 알림은 세션이 다시 시작되었을 때 깨우기가 얼마나 지연되었는지 표시합니다:

4976 

4977```text theme={null}

4978This session restarted 12m after its next /loop wakeup was due, so that wakeup will not fire. The loop stays stopped until Claude schedules it again: reply to continue it.

4979```

4980 

4981v2.1.295 이전에는 이 상황에서 알림 없이 루프가 중지되었습니다.

4982 

4983**할 일:**

4984 

4985* 루프를 계속하려면 [세션에 답장](/docs/ko/agent-view#peek-and-reply)하여 `keep the loop running`과 같이 그렇게 말합니다. Claude는 답장과 함께 알림을 읽고 다음 깨우기를 예약할 수 있습니다.

4986* 루프를 더 이상 사용하지 않으려면 아무것도 하지 않습니다. 루프는 이미 중지되었습니다.

4987 

4949<h3 id="claude_code_process_wrapper-launcher-errors">4988<h3 id="claude_code_process_wrapper-launcher-errors">

4950 CLAUDE\_CODE\_PROCESS\_WRAPPER 런처 오류4989 CLAUDE\_CODE\_PROCESS\_WRAPPER 런처 오류

4951</h3>4990</h3>

89* **[Monitor](/docs/ko/tools-reference#monitor-tool) 감시**: 실행은 감시가 시간 초과되거나 10분 상한이 대기를 종료할 때까지, 둘 중 먼저 발생하는 시점까지 기다립니다. 대기하는 동안 Claude는 감시가 보고하는 항목에 계속 응답합니다. 기본적으로 감시는 Claude가 시작한 후 5분 후에 시간 초과됩니다.89* **[Monitor](/docs/ko/tools-reference#monitor-tool) 감시**: 실행은 감시가 시간 초과되거나 10분 상한이 대기를 종료할 때까지, 둘 중 먼저 발생하는 시점까지 기다립니다. 대기하는 동안 Claude는 감시가 보고하는 항목에 계속 응답합니다. 기본적으로 감시는 Claude가 시작한 후 5분 후에 시간 초과됩니다.

90* **대기 중인 웨이크업**: 프롬프트를 `--input-format stream-json`이 아닌 텍스트로 전달한 실행에서 Claude가 [자체 속도 조절 `/loop` 웨이크업](/docs/ko/scheduled-tasks#let-claude-choose-the-interval)을 예약한 경우, 실행은 10분 상한을 넘더라도 각 웨이크업이 실행되기를 기다리고 [루프가 끝날](/docs/ko/scheduled-tasks#stop-a-loop) 때까지 해당 반복을 실행합니다.90* **대기 중인 웨이크업**: 프롬프트를 `--input-format stream-json`이 아닌 텍스트로 전달한 실행에서 Claude가 [자체 속도 조절 `/loop` 웨이크업](/docs/ko/scheduled-tasks#let-claude-choose-the-interval)을 예약한 경우, 실행은 10분 상한을 넘더라도 각 웨이크업이 실행되기를 기다리고 [루프가 끝날](/docs/ko/scheduled-tasks#stop-a-loop) 때까지 해당 반복을 실행합니다.

91 91 

92stderr가 터미널이고 실행이 5초 동안 대기한 경우, Claude Code는 `Waiting for background work to finish`로 시작하고 해당 작업을 명시하는 줄을 stderr에 출력합니다. [`json` 또는 `stream-json` 출력](#get-structured-output)에서는 stdout이 터미널이 아닐 때만 이 줄이 출력되므로, 스크립트가 읽는 JSON에는 이 줄이 포함되지 않습니다.

93 

92실행이 [`--max-budget-usd`](/docs/ko/cli-reference#cli-flags) 상한에 도달하면 Claude Code는 기다리는 대신 남은 백그라운드 작업을 중지합니다.94실행이 [`--max-budget-usd`](/docs/ko/cli-reference#cli-flags) 상한에 도달하면 Claude Code는 기다리는 대신 남은 백그라운드 작업을 중지합니다.

93 95 

94백그라운드 작업이 다른 턴을 시작하면, 실행은 기본 `text` 출력에서는 각 턴의 결과를 출력하고 `json` 출력에서는 마지막 턴의 결과를 출력합니다. v2.1.295 이전에는 `text` 출력에서도 마지막 턴의 결과만 출력했습니다.96백그라운드 작업이 다른 턴을 시작하면, 실행은 기본 `text` 출력에서는 각 턴의 결과를 출력하고 `json` 출력에서는 마지막 턴의 결과를 출력합니다. v2.1.295 이전에는 `text` 출력에서도 마지막 턴의 결과만 출력했습니다.

296 298 

297`--plugin-dir` 디렉터리 또는 아카이브 자체가 로드되지 않으면 해당 `plugin_errors` 항목은 해결된 절대 경로를 `path`로 포함합니다. 이를 사용하여 여러 `--plugin-dir` 값 중 어느 것이 실패했는지 확인할 수 있습니다. `path` 필드는 Claude Code v2.1.283 이상이 필요합니다.299`--plugin-dir` 디렉터리 또는 아카이브 자체가 로드되지 않으면 해당 `plugin_errors` 항목은 해결된 절대 경로를 `path`로 포함합니다. 이를 사용하여 여러 `--plugin-dir` 값 중 어느 것이 실패했는지 확인할 수 있습니다. `path` 필드는 Claude Code v2.1.283 이상이 필요합니다.

298 300 

299MCP 서버 필드도 동일한 방식으로 사용합니다. `-p`와 함께 [`--mcp-config`](/docs/ko/cli-reference#cli-flags)를 전달하면 Claude Code는 첫 번째 턴을 실행하기 전에 여전히 대기 중인 서버를 기다리며, [`MCP_TIMEOUT`](/docs/ko/env-vars) 시작 타임아웃(기본값 30초)까지 기다립니다. [캐시된 도구 목록](/docs/ko/agent-sdk/mcp#connection-timing)이 있는 원격 서버는 대기를 건너뛰고 `system/init`에서 `pending`을 표시하며 첫 번째 도구 호출에서 연결합니다. 대기는 Claude Code v2.1.221 이상이 필요합니다.301MCP 서버 필드도 동일한 방식으로 사용합니다. `-p`와 함께 [`--mcp-config`](/docs/ko/cli-reference#cli-flags)를 전달하면 Claude Code는 첫 번째 턴을 실행하기 전에 여전히 대기 중인 서버를 기다리며, [`MCP_TIMEOUT`](/docs/ko/env-vars) 시작 타임아웃(기본값 30초)까지 기다립니다. [캐시된 도구 목록](/docs/ko/agent-sdk/mcp#connection-timing)이 있는 원격 서버는 대기를 건너뛰고 `system/init`에서 `pending`을 표시하며 첫 번째 도구 호출에서 연결합니다. [자체 호스팅 환경](/docs/ko/self-hosted-environments-configuration#connection-timing)에서는 대신 더 짧은 대기가 적용됩니다. 대기는 Claude Code v2.1.221 이상이 필요합니다.

300 302 

301Claude Code는 시작 시 각 `--mcp-config` 항목을 검증하고 검증에 실패한 항목을 건너뜁니다(예: `type`이 없는 `url` 항목). 실행이 계속되고 깔끔하게 종료되므로 이러한 필드를 확인하여 로드되지 않은 서버를 포착합니다:303Claude Code는 시작 시 각 `--mcp-config` 항목을 검증하고 검증에 실패한 항목을 건너뜁니다(예: `type`이 없는 `url` 항목). 실행이 계속되고 깔끔하게 종료되므로 이러한 필드를 확인하여 로드되지 않은 서버를 포착합니다:

302 304 

336 338 

337전체 세션에 대한 기준선을 설정하려면 개별 도구를 나열하는 대신 [권한 모드](/docs/ko/permission-modes)를 전달합니다. 권한 모드를 설정하지 않는 실행은 [기본 제공 시작 권한 모드](/docs/ko/permission-modes#which-mode-a-session-starts-in)를 사용하며, 이는 `auto`일 수 있으므로 원하는 권한 모드를 전달합니다:339전체 세션에 대한 기준선을 설정하려면 개별 도구를 나열하는 대신 [권한 모드](/docs/ko/permission-modes)를 전달합니다. 권한 모드를 설정하지 않는 실행은 [기본 제공 시작 권한 모드](/docs/ko/permission-modes#which-mode-a-session-starts-in)를 사용하며, 이는 `auto`일 수 있으므로 원하는 권한 모드를 전달합니다:

338 340 

339* **`auto`**: `--permission-mode auto`를 전달하여 분류기가 대부분의 작업을 검토하도록 합니다341* **`auto`**: `--permission-mode auto`를 전달하여 사용자 대신 분류기가 대부분의 작업을 검토하도록 합니다

340* **`dontAsk`**: Claude Code는 그렇지 않으면 프롬프트할 모든 호출을 거부하며, 이는 잠긴 CI 실행에 유용합니다. Manual 모드에서 승인이 필요하지 않은 작업(예: 작업 디렉터리의 파일 읽기 및 [읽기 전용 명령 집합](/docs/ko/permissions#read-only-commands))과 `--allowedTools` 항목 또는 `permissions.allow` 규칙이 적용되는 작업은 여전히 실행됩니다. `AskUserQuestion`, [조직이 `ask`로 설정한](/docs/ko/mcp#organization-controls-on-connector-tools) 커넥터 도구 및 [`requiresUserInteraction`](/docs/ko/mcp#require-approval-for-a-specific-tool)으로 표시된 MCP 도구는 허용 규칙이 일치해도 거부됩니다342* **`dontAsk`**: Claude Code는 그렇지 않으면 프롬프트할 모든 호출을 거부하며, 이는 잠긴 CI 실행에 유용합니다. Manual 모드에서 승인이 필요하지 않은 작업(예: 작업 디렉터리의 파일 읽기 및 [읽기 전용 명령 집합](/docs/ko/permissions#read-only-commands))과 `--allowedTools` 항목 또는 `permissions.allow` 규칙이 적용되는 작업은 여전히 실행됩니다. `AskUserQuestion`, [조직이 `ask`로 설정한](/docs/ko/mcp#organization-controls-on-connector-tools) 커넥터 도구 및 [`requiresUserInteraction`](/docs/ko/mcp#require-approval-for-a-specific-tool)으로 표시된 MCP 도구는 허용 규칙이 일치해도 거부됩니다

341* **`acceptEdits`**: Claude는 프롬프트 없이 파일을 작성하고 Claude Code는 `mkdir`, `touch`, `mv` 및 `cp`와 같은 일반적인 파일 시스템 명령을 자동 승인합니다. [모드가 자동 승인하지 않는 작업](/docs/ko/permission-modes#actions-no-mode-auto-approves)은 여전히 적용됩니다. 읽기 전용 명령 집합을 제외하고 다른 셸 명령 및 네트워크 요청은 여전히 `--allowedTools` 항목 또는 `permissions.allow` 규칙이 필요합니다. [`acceptEdits`가 자동 승인하는 것](/docs/ko/permission-modes#auto-approve-file-edits-with-acceptedits-mode)의 전체 목록을 참조하십시오343* **`acceptEdits`**: Claude는 프롬프트 없이 파일을 작성하고 Claude Code는 `mkdir`, `touch`, `mv` 및 `cp`와 같은 일반적인 파일 시스템 명령을 자동 승인합니다. [모드가 자동 승인하지 않는 작업](/docs/ko/permission-modes#actions-no-mode-auto-approves)은 여전히 적용됩니다. 읽기 전용 명령 집합을 제외하고 다른 셸 명령 및 네트워크 요청은 여전히 `--allowedTools` 항목 또는 `permissions.allow` 규칙이 필요합니다. [`acceptEdits`가 자동 승인하는 것](/docs/ko/permission-modes#auto-approve-file-edits-with-acceptedits-mode)의 전체 목록을 참조하십시오

342 344 

132러너와 세션은 여러 종류의 아웃바운드 연결을 만들며, Anthropic의 인바운드 연결은 필요하지 않습니다:132러너와 세션은 여러 종류의 아웃바운드 연결을 만들며, Anthropic의 인바운드 연결은 필요하지 않습니다:

133 133 

134* **제어 평면**: 러너는 `api.anthropic.com`을 폴링하여 작업을 수행하고 설정 진행 상황 및 실패 이벤트를 게시하며, 모두 아웃바운드 HTTPS입니다. 폴링은 러너의 하트비트로도 작동합니다.134* **제어 평면**: 러너는 `api.anthropic.com`을 폴링하여 작업을 수행하고 설정 진행 상황 및 실패 이벤트를 게시하며, 모두 아웃바운드 HTTPS입니다. 폴링은 러너의 하트비트로도 작동합니다.

135* **SCM 커넥터**: 선택적 오케스트레이터 [SCM 커넥터](/docs/ko/self-hosted-environments-reference#scm-connector-flags) 터널은 유일한 WebSocket 연결입니다.135* **Git**: 러너는 배포가 제공하는 자격 증명으로 인증하여 HTTPS 또는 SSH를 통해 git 호스트에서 복제하고 푸시합니다. 세션별 발급 자격 증명을 포함한 옵션은 [git 구성](/docs/ko/self-hosted-environments-deploy#configure-git)을 참조하세요. [Anthropic git 프록시](/docs/ko/self-hosted-environments-deploy#use-the-anthropic-git-proxy)를 사용하면 github.com에 있는 저장소의 git 트래픽이 대신 `api.anthropic.com`을 거칩니다.

136* **Git**: 러너는 배포가 제공하는 자격 증명으로 인증하여 HTTPS 또는 SSH를 통해 git 호스트에서 복제하고 푸시합니다. [git 구성](/docs/ko/self-hosted-environments-deploy#configure-git)에서 옵션을 다루며, 세션별 발급 자격 증명 및 [Anthropic git 프록시](/docs/ko/self-hosted-environments-deploy#use-the-anthropic-git-proxy)를 포함하며, 이는 git을 `api.anthropic.com` 대신을 통해 라우팅합니다.136* **세션 자식**: 자식 Claude Code 프로세스는 `api.anthropic.com`에 대한 세션의 이벤트 스트림을 유지하며, 모델 추론 및 세션 중에 실행되는 git 명령에 대한 자신의 아웃바운드 호출을 만듭니다. [Anthropic 관리 git](/docs/ko/self-hosted-environments-deploy#use-the-anthropic-git-proxy)을 사용하는 세션에서는 자식이 github.com에 대한 `git` 및 `gh` 트래픽을 `api.anthropic.com`으로 여는 WebSocket 연결을 통해 보냅니다.

137* **세션 자식**: 자식 Claude Code 프로세스는 `api.anthropic.com`에 대한 세션의 이벤트 스트림을 유지하며, 모델 추론 및 세션 중에 실행되는 git 명령에 대한 자신의 아웃바운드 호출을 만듭니다. 전체 이그레스 목록은 [네트워크 요구 사항](/docs/ko/self-hosted-environments-deploy#network-requirements)을 참조하세요. [위의 다이어그램](#how-self-hosted-environments-work)은 선택적 SCM 커넥터를 제외한 이러한 경로를 보여줍니다.137* **SCM 커넥터**: 선택적 오케스트레이터 [SCM 커넥터](/docs/ko/self-hosted-environments-reference#scm-connector-flags)는 사용할 수 없으므로 해당 터널이 열리지 않습니다. 이 터널은 `api.anthropic.com`에 대한 WebSocket 연결입니다.

138 

139전체 이그레스 목록은 [네트워크 요구 사항](/docs/ko/self-hosted-environments-deploy#network-requirements)을 참조하세요. [위의 다이어그램](#how-self-hosted-environments-work)은 선택적 SCM 커넥터와 Anthropic 관리 git 연결을 제외한 이러한 경로를 보여줍니다.

138 140 

139기본적으로 모델 추론은 Anthropic API를 사용합니다. 제어 평면은 각 세션에 API 엔드포인트를 전달하고, 세션은 Anthropic 발급 세션 범위 OAuth 토큰으로 인증합니다. 대신 자체 클라우드 계정으로 모델 요청을 보내려면 [Bedrock 또는 Agent Platform으로 모델 요청 보내기](/docs/ko/self-hosted-environments-configuration#send-model-requests-to-bedrock-or-agent-platform)를 참조하세요.141기본적으로 모델 추론은 Anthropic API를 사용합니다. 제어 평면은 각 세션에 API 엔드포인트를 전달하고, 세션은 Anthropic 발급 세션 범위 OAuth 토큰으로 인증합니다. 대신 자체 클라우드 계정으로 모델 요청을 보내려면 [Bedrock 또는 Agent Platform으로 모델 요청 보내기](/docs/ko/self-hosted-environments-configuration#send-model-requests-to-bedrock-or-agent-platform)를 참조하세요.

140 142 

31| 변수 | 설명 |31| 변수 | 설명 |

32| :- | :- |32| :- | :- |

33| `CLAUDE_CODE_SESSION_ACCESS_TOKEN` | 세션 JWT이며, `sk-ant-cc-` 접두사가 붙습니다. `act` 클레임은 세션 작성자를 식별하며, 작성 사용 환경이 기록한 경우 작성자의 이메일을 포함합니다. 값은 생성 시점의 토큰입니다. 새로고침은 자식의 stdin을 통해 도착하므로 래퍼는 초기 값만 봅니다. [세션 ID 확인](/docs/ko/self-hosted-environments-identity)을 참조하세요. |33| `CLAUDE_CODE_SESSION_ACCESS_TOKEN` | 세션 JWT이며, `sk-ant-cc-` 접두사가 붙습니다. `act` 클레임은 세션 작성자를 식별하며, 작성 사용 환경이 기록한 경우 작성자의 이메일을 포함합니다. 값은 생성 시점의 토큰입니다. 새로고침은 자식의 stdin을 통해 도착하므로 래퍼는 초기 값만 봅니다. [세션 ID 확인](/docs/ko/self-hosted-environments-identity)을 참조하세요. |

34| `CCR_SESSION_ACCOUNT_EMAIL` | 세션 작성자의 이메일이며, 서명 검증 없이 러너에 의해 토큰의 `act.email` 클레임에서 미리 추출됩니다. 커밋 트레일러와 같은 레이블 지정에 적합합니다. 이메일이 자격 증명 발급을 제어할 때는 토큰을 확인하고 [세션 작성자로 범위가 지정된 자격 증명 프로비저닝](#provision-credentials-scoped-to-the-session-creator)에 설명된 대로 클레임을 읽으세요. 토큰이 작성자 이메일을 전달하지 않으면 설정되지 않습니다. 개인 식별 정보로 취급하세요. |34| `CCR_SESSION_ACCOUNT_EMAIL` | 세션 작성자의 이메일이며, 서명 검증 없이 러너에 의해 토큰의 `act.email` 클레임에서 미리 추출됩니다. 커밋 트레일러와 같은 레이블 지정에 적합합니다. 이메일이 자격 증명 발급을 제어할 때는 대신 토큰을 확인하고 토큰에서 클레임을 읽으세요. [세션 작성자로 범위가 지정된 자격 증명 프로비저닝](#provision-credentials-scoped-to-the-session-creator)을 참조하세요. 토큰이 작성자 이메일을 전달하지 않으면(예: 조직의 서비스 ID가 생성한 세션) 설정되지 않습니다. 개인 식별 정보로 취급하세요. |

35| `CLAUDE_RUNNER_CLIENT_PLATFORM` | 세션을 생성한 클라이언트 사용 환경(예: `web_claude_ai`, `desktop_app`, `ios`, `claude_code_cli`, `scheduled_trigger`)입니다. Anthropic은 세션 생성 시 값을 한 번 기록하므로 래퍼와 모든 라이프사이클 훅이 동일한 값을 봅니다. 채택 분석 및 레이블 지정에만 사용하고 인증 신호로는 사용하지 마세요. 세션에 기록되거나 인식된 사용 환경이 없으면 설정되지 않으므로 `set -u` 아래에서 `${CLAUDE_RUNNER_CLIENT_PLATFORM:-}`로 참조하세요. Claude Code v2.1.229 이상이 필요합니다. |35| `CLAUDE_RUNNER_CLIENT_PLATFORM` | 세션을 생성한 클라이언트 사용 환경(예: `web_claude_ai`, `desktop_app`, `ios`, `claude_code_cli`, `scheduled_trigger`)입니다. Anthropic은 세션 생성 시 값을 한 번 기록하므로 래퍼와 모든 라이프사이클 훅이 동일한 값을 봅니다. 채택 분석 및 레이블 지정에만 사용하고 인증 신호로는 사용하지 마세요. 세션에 기록되거나 인식된 사용 환경이 없으면 설정되지 않습니다. Claude Code v2.1.229 이상이 필요합니다. |

36| `CLAUDE_RUNNER_CLAUDE_BIN` | 러너 자체의 Claude Code 바이너리에 대한 절대 경로입니다. 설치 경로를 하드코딩하지 않고 고정된 바이너리로 제어를 전달하려면 `exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@"`로 래퍼를 종료하세요. |36| `CLAUDE_RUNNER_CLAUDE_BIN` | 러너 자체의 Claude Code 바이너리에 대한 절대 경로입니다. 설치 경로를 하드코딩하지 않고 고정된 바이너리로 제어를 전달하려면 `exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@"`로 래퍼를 종료하세요. |

37| `CLAUDE_CODE_REMOTE_SESSION_ID` | 태그가 지정된 `cse_...` 형식의 세션 ID입니다. 이는 [라이프사이클 훅](#lifecycle-hooks)이 `session_...` 형식의 `CLAUDE_RUNNER_SESSION_ID`로 보는 동일한 세션입니다. UUID 변수는 두 형식 모두에서 일치하며, `cse_` 접두사를 `session_`으로 대체하면 세션 URL에 표시되는 ID가 됩니다. |37| `CLAUDE_CODE_REMOTE_SESSION_ID` | 태그가 지정된 `cse_...` 형식의 세션 ID입니다. 이는 [라이프사이클 훅](#lifecycle-hooks)이 `session_...` 형식의 `CLAUDE_RUNNER_SESSION_ID`로 보는 동일한 세션입니다. UUID 변수는 두 형식 모두에서 일치하며, `cse_` 접두사를 `session_`으로 대체하면 세션 URL에 표시되는 ID가 됩니다. |

38| `CLAUDE_CODE_REMOTE_SESSION_UUID` | 정규 UUID 형식의 동일한 세션 ID이며, UUID를 키로 사용하는 시스템용입니다. |38| `CLAUDE_CODE_REMOTE_SESSION_UUID` | 정규 UUID 형식의 동일한 세션 ID이며, UUID를 키로 사용하는 시스템용입니다. |

39| `CLAUDE_CODE_REMOTE_SLACK_THREAD_URL` | 하나의 Slack 스레드에 속한 [Claude Tag](https://claude.com/docs/claude-tag/overview) 세션의 경우 해당 스레드의 링크입니다. 다른 세션에서는 설정되지 않으며, 스레드 세션에서도 설정되지 않을 수 있습니다. |

40| `CLAUDE_CODE_REMOTE_SLACK_THREAD_TS` | 하나의 Slack 스레드에 속한 Claude Tag 세션의 경우 해당 스레드의 Slack 타임스탬프(예: `1700000000.000100`)입니다. 설정되지 않을 수 있으며, `CLAUDE_CODE_REMOTE_SLACK_THREAD_URL`이 설정되지 않은 경우에도 설정될 수 있으므로 각 변수를 개별적으로 확인하세요. |

39| `CLAUDE_SESSION_INGRESS_TOKEN_FILE` | 현재 세션 JWT를 보유하는 세션별 파일의 절대 경로이며, 토큰 새로고침 전체에서 최신 상태로 유지됩니다. 셸 서브프로세스는 사용자가 세션에 추가한 첨부 파일을 다운로드할 때 `Authorization` 헤더에 대해 이를 읽습니다. `exec`는 변수를 자동으로 보존합니다. 자식의 환경을 다시 빌드하는 래퍼는 변수를 전달해야 하거나 첨부 파일 다운로드가 자동으로 중지됩니다. |41| `CLAUDE_SESSION_INGRESS_TOKEN_FILE` | 현재 세션 JWT를 보유하는 세션별 파일의 절대 경로이며, 토큰 새로고침 전체에서 최신 상태로 유지됩니다. 셸 서브프로세스는 사용자가 세션에 추가한 첨부 파일을 다운로드할 때 `Authorization` 헤더에 대해 이를 읽습니다. `exec`는 변수를 자동으로 보존합니다. 자식의 환경을 다시 빌드하는 래퍼는 변수를 전달해야 하거나 첨부 파일 다운로드가 자동으로 중지됩니다. |

40| `CLAUDE_CONFIG_DIR` | 세션별 Claude 구성 디렉토리이며, 러너가 시작 시 캡처한 러너 호스트 구성의 스냅샷에서 세션 시작 시 작성됩니다. [권한 및 도구 승인](#permissions-and-tool-approval)을 참조하세요. 여기에 대한 쓰기는 이 세션으로 격리됩니다. 디렉토리는 [`--remove-session-state`](/docs/ko/self-hosted-environments-reference#runner-cli-flags)로 러너를 시작하지 않는 한 세션이 끝난 후 `<base-dir>/_sessions/` 아래에 유지됩니다. [사전 준비된 체크아웃 재사용](/docs/ko/self-hosted-environments-deploy#reuse-a-pre-warmed-checkout)을 참조하세요. |42| `CLAUDE_CONFIG_DIR` | 세션별 Claude 구성 디렉토리이며, 러너가 시작 시 캡처한 러너 호스트 구성의 스냅샷에서 세션 시작 시 작성됩니다. [권한 및 도구 승인](#permissions-and-tool-approval)을 참조하세요. 여기에 대한 쓰기는 이 세션으로 격리됩니다. 디렉토리는 [`--remove-session-state`](/docs/ko/self-hosted-environments-reference#runner-cli-flags)로 러너를 시작하지 않는 한 세션이 끝난 후 `<base-dir>/_sessions/` 아래에 유지됩니다. [사전 준비된 체크아웃 재사용](/docs/ko/self-hosted-environments-deploy#reuse-a-pre-warmed-checkout)을 참조하세요. |

41| `ANTHROPIC_BASE_URL` | 자식이 사용할 API 기본 URL이며, 제어 평면에서 세션별로 전달되고 일반적으로 `https://api.anthropic.com`입니다. 이를 재정의하지 마세요. 세션의 추론 자격 증명은 Anthropic에서 발급한 OAuth 토큰이며 다른 공급자는 이를 수락하지 않습니다. |43| `ANTHROPIC_BASE_URL` | 자식이 사용할 API 기본 URL이며, 제어 평면에서 세션별로 전달되고 일반적으로 `https://api.anthropic.com`입니다. 이를 재정의하지 마세요. 세션의 추론 자격 증명은 Anthropic에서 발급한 OAuth 토큰이며 다른 공급자는 이를 수락하지 않습니다. |

43 45 

44래퍼는 또한 서버 제공 환경 변수를 포함한 자식의 관리되는 환경의 나머지를 상속합니다. `exec`는 모두 자동으로 전파합니다. 래퍼가 자식을 다른 방식으로 생성하면 전체 환경을 전달하세요.46래퍼는 또한 서버 제공 환경 변수를 포함한 자식의 관리되는 환경의 나머지를 상속합니다. `exec`는 모두 자동으로 전파합니다. 래퍼가 자식을 다른 방식으로 생성하면 전체 환경을 전달하세요.

45 47 

48`CLAUDE_CODE_REMOTE_SLACK_THREAD_URL` 및 `CLAUDE_CODE_REMOTE_SLACK_THREAD_TS`는 래퍼 또는 [`command` 훅](#command)에 전달됩니다. 셸 명령, git 훅, Claude Code 훅 등 세션이 실행하는 항목에도 전달됩니다. `checkout`, `post-session`, `spawn-runner` 훅은 이를 받지 않습니다.

49 

50<h3 id="give-a-default-to-variables-that-can-be-unset">

51 설정되지 않을 수 있는 변수에 기본값 지정

52</h3>

53 

54`CCR_SESSION_ACCOUNT_EMAIL`, `CLAUDE_RUNNER_CLIENT_PLATFORM`, `CLAUDE_CODE_REMOTE_SLACK_THREAD_URL`, `CLAUDE_CODE_REMOTE_SLACK_THREAD_TS`는 각각 설정되지 않을 수 있습니다. 스크립트가 `set -u`를 사용하는 경우 설정되지 않은 변수를 확장하면 Bash가 `unbound variable`로 중지되므로, `${CCR_SESSION_ACCOUNT_EMAIL:-}`와 같이 기본값을 지정하여 확장하세요.

55 

56셸이 Slack 스레드 링크를 확장하는 모든 곳에서 다음 사항에 주의하세요:

57 

58* **따옴표로 묶기**: 링크에는 `?` 및 `&`와 같이 셸이 해석하는 문자가 포함될 수 있으므로 `"${CLAUDE_CODE_REMOTE_SLACK_THREAD_URL:-}"`와 같이 변수를 따옴표로 묶으세요.

59* **값을 `eval` 및 `sh -c` 문자열에 넣지 않기**: 따옴표 안이라도 `eval` 또는 `sh -c`가 실행하는 문자열에 값을 치환하지 마세요. 대신 해당 문자열이 변수를 참조하도록 하세요.

60 

46<h3 id="keep-stdin-and-file-descriptor-3-attached">61<h3 id="keep-stdin-and-file-descriptor-3-attached">

47 stdin 및 파일 디스크립터 3을 연결된 상태로 유지62 stdin 및 파일 디스크립터 3을 연결된 상태로 유지

48</h3>63</h3>

49 64 

50자식의 stdin은 러너의 제어 채널입니다. 토큰 회전 및 세션 종료 신호가 이를 통해 도착합니다. 러너는 또한 파일 디스크립터 3에서 파이프를 열고 자식의 활동 신호를 읽어 유휴 및 시작 타임아웃을 구동합니다. 일반 `exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@"`는 둘 다 자동으로 보존합니다.65자식의 stdin은 러너의 제어 채널입니다. 토큰 회전 및 세션 종료 신호가 이를 통해 도착합니다. 러너는 또한 파일 디스크립터 3에서 파이프를 열고 자식의 활동 신호를 읽어 유휴 및 시작 타임아웃을 구동합니다. 일반 `exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@"`는 둘 다 자동으로 보존합니다.

51 66 

52래퍼가 맨 `&`로 자식을 백그라운드에 두면 자식의 stdin이 끊깁니다. 세션은 초기 OAuth 토큰의 약 30분 수명이 만료될 때까지 정상으로 보이다가 모든 API 호출이 `401 authentication_error`로 실패합니다. 래퍼가 자식을 백그라운드에 두어야 하는 경우(예: 정리 트랩을 살리기 위해) stdin을 파일 디스크립터 4 이상에 저장하고 명시적으로 다시 연결하세요:67래퍼가 맨 `&`로 자식을 백그라운드에 두면 자식의 stdin이 끊깁니다. 세션은 초기 OAuth 토큰의 약 30분 수명이 만료될 때까지 정상으로 보이다가 해당 토큰을 사용하는 모든 API 호출이 `401 authentication_error`로 실패합니다. 래퍼가 자식을 백그라운드에 두어야 하는 경우(예: 정리 트랩을 살리기 위해) stdin을 파일 디스크립터 4 이상에 저장하고 명시적으로 다시 연결하세요:

53 68 

54```bash theme={null}69```bash theme={null}

55exec 4<&070exec 4<&0

59wait "$CHILD"74wait "$CHILD"

60```75```

61 76 

62래퍼에서 파일 디스크립터 3을 닫거나 재사용하지 마세요. 자식의 stdout 및 stderr 리디렉션은 괜찮습니다.77자식의 stdout은 리디렉션해도 됩니다. 파일 디스크립터 3과 stderr는 러너에 연결된 상태로 유지하세요:

78 

79* **파일 디스크립터 3**: 자식의 활동 신호를 러너에 전달합니다. 래퍼에서 이를 닫거나 재사용하지 마세요.

80* **stderr**: 래퍼 또는 자식이 0이 아닌 값으로 종료되면 러너는 stderr의 마지막 줄을 세션에 게시하고 자체 로그에 출력합니다. 세션 사용자가 해당 줄을 보게 되므로 stderr에 비밀을 출력하지 말고, 래퍼를 배포하기 전에 `set -x`를 제거하세요. stderr를 리디렉션해도 세션은 계속 실행되지만, 러너는 종료 코드만으로 실패를 보고합니다.

63 81 

64<h3 id="pass-the-system-prompt-flags-through">82<h3 id="pass-the-system-prompt-flags-through">

65 시스템 프롬프트 플래그 전달83 시스템 프롬프트 플래그 전달

108 checkout126 checkout

109</h3>127</h3>

110 128 

111저장소당 한 번 실행되며, 러너의 기본 제공 복제 및 페치 대신 실행됩니다. 훅을 사용하여 리드스루 미러에서 복제하거나, 아카이브에서 작업 트리를 시드하거나, 세션별 git 인증을 적용하세요. 러너는 다음 변수를 설정하며, 표에 나열되지 않은 다른 `CLAUDE_RUNNER_` 변수를 설정할 수도 있습니다:129저장소당 한 번 실행되며, 러너의 기본 제공 복제 및 페치 대신 실행됩니다. 훅을 사용하여 HTTPS 또는 SSH로 접근하는 리드스루 미러에서 복제하거나, 아카이브에서 작업 트리를 시드하거나, 세션별 git 인증을 적용하세요. 러너는 다음 변수를 설정하며, 표에 나열되지 않은 다른 `CLAUDE_RUNNER_` 변수를 설정할 수도 있습니다:

112 130 

113| 변수 | 설명 |131| 변수 | 설명 |

114| :- | :- |132| :- | :- |

115| `CLAUDE_RUNNER_REPO_URL` | 복제할 저장소 URL이며, `--git-host-rewrite` 및 `--git-ssh-rewrite`가 적용된 후입니다. |133| `CLAUDE_RUNNER_REPO_URL` | 복제할 저장소 URL이며, `--git-host-rewrite` 및 `--git-ssh-rewrite`가 적용된 후입니다. |

116| `CLAUDE_RUNNER_REPO_REF` | 체크아웃할 리비전: 세션이 요청한 대로 분기, 태그 또는 커밋 SHA입니다. 비어 있으면 저장소의 기본 분기를 의미합니다. |134| `CLAUDE_RUNNER_REPO_REF` | 체크아웃할 리비전으로, 세션이 요청한 그대로입니다: 브랜치, 태그, 커밋 SHA 또는 `refs/pull/<number>/head`와 같은 전체 참조 이름. 비어 있으면 저장소의 기본 브랜치를 의미합니다. |

117| `CLAUDE_RUNNER_CHECKOUT_PATH` | 작업 트리를 남겨야 할 절대 경로 |135| `CLAUDE_RUNNER_CHECKOUT_PATH` | 작업 트리를 남겨야 할 절대 경로 |

118| `CLAUDE_RUNNER_SESSION_ID` | 태그가 지정된 `session_...` 형식의 세션 ID이며, 로깅 및 상관관계 지정용입니다. |136| `CLAUDE_RUNNER_SESSION_ID` | 태그가 지정된 `session_...` 형식의 세션 ID이며, 로깅 및 상관관계 지정용입니다. |

119| `CLAUDE_RUNNER_SESSION_UUID` | 정규 UUID 형식의 동일한 세션 ID |137| `CLAUDE_RUNNER_SESSION_UUID` | 정규 UUID 형식의 동일한 세션 ID |

120| `CLAUDE_RUNNER_API_BASE_URL` | 세션 범위 호출용 Anthropic API 기본 URL |138| `CLAUDE_RUNNER_API_BASE_URL` | 세션 범위 호출용 Anthropic API 기본 URL |

121| `CLAUDE_RUNNER_CLIENT_PLATFORM` | 세션을 생성한 클라이언트 표면(예: `web_claude_ai`, `desktop_app`, `ios`)입니다. 세션에 기록되거나 인식된 표면이 없으면 설정되지 않습니다. |139| `CLAUDE_RUNNER_CLIENT_PLATFORM` | 세션을 생성한 클라이언트 사용 환경(예: `web_claude_ai`, `desktop_app`, `ios`)입니다. 세션에 기록되거나 인식된 사용 환경이 없으면 설정되지 않으므로 `set -u` 아래에서는 `${CLAUDE_RUNNER_CLIENT_PLATFORM:-}`로 참조하세요. Claude Code v2.1.229 이상이 필요합니다. |

122| `CLAUDE_CODE_SESSION_ACCESS_TOKEN` | 세션 범위 API 호출용 세션 액세스 토큰 |140| `CLAUDE_CODE_SESSION_ACCESS_TOKEN` | 세션 범위 API 호출용 세션 액세스 토큰 |

123| `GIT_CONFIG_COUNT`, `GIT_CONFIG_KEY_n`, `GIT_CONFIG_VALUE_n` | 러너가 훅이 실행하는 git에 대해 고정하는 Git 설정입니다. [라이프사이클 훅 내부의 Git 구성](#git-configuration-inside-lifecycle-hooks)에서 설명합니다. Claude Code v2.1.280 이상이 필요합니다. |141| `GIT_CONFIG_COUNT`, `GIT_CONFIG_KEY_n`, `GIT_CONFIG_VALUE_n` | 러너가 훅이 실행하는 git에 대해 고정하는 Git 설정입니다. [라이프사이클 훅 내부의 Git 구성](#git-configuration-inside-lifecycle-hooks)에서 설명합니다. Claude Code v2.1.280 이상이 필요합니다. |

124 142 

125스크립트는 요청된 리비전에서 체크아웃된 `CLAUDE_RUNNER_CHECKOUT_PATH`에 작업 트리를 남겨야 합니다. 분리된 HEAD는 괜찮습니다. 러너는 그 위에 세션의 작업 분기를 생성합니다. 러너는 이후 경로에 `.git`이 포함되어 있는지 확인합니다. 훅이 Perforce 또는 압축 해제된 tarball과 같은 비git 소스를 구체화하면 러너의 환경에서 `CLAUDE_RUNNER_SKIP_GIT_VERIFY=1`을 설정하여 해당 확인을 건너뛰세요. 작업 분기 생성 및 결과 푸시와 같은 git 기반 흐름에는 git 체크아웃이 필요하므로 [`post-session` 훅](#post-session)으로 비git 트리에서 결과를 내보내세요.143스크립트는 요청된 리비전에서 체크아웃된 `CLAUDE_RUNNER_CHECKOUT_PATH`에 작업 트리를 남겨야 합니다. 분리된 HEAD는 괜찮습니다. 러너는 그 위에 세션의 작업 브랜치를 생성합니다.

126 144 

127러너는 훅에 git 자격증명을 전달하지 않습니다. 대신 세션의 ID에서 세션별 복제 자격증명을 발급합니다. [세션 서비스에서 토큰 확인](/docs/ko/self-hosted-environments-identity#verify-the-token-from-your-service)에 설명된 대로 `CLAUDE_RUNNER_API_BASE_URL` 아래의 JWKS 엔드포인트에 대해 표준 JWT 라이브러리로 `CLAUDE_CODE_SESSION_ACCESS_TOKEN`을 확인한 다음 자격증명 서비스가 토큰의 `act` 클레임의 ID에 대한 단기 복제 자격증명을 발급하도록 합니다. `CLAUDE_RUNNER_CLAUDE_BIN`은 체크아웃 훅 환경에서 설정되지 않으므로 `decode-token` 서브명령을 사용할 수 없습니다. SSH 에이전트, 자격증명 도우미 또는 `.netrc`와 같이 호스트가 이미 가지고 있는 git 인증으로 폴백하는 것도 옵션입니다.145훅이 반환된 후 러너는 `CLAUDE_RUNNER_CHECKOUT_PATH`에 `.git`이 포함되어 있는지 확인합니다. 훅이 Perforce 또는 압축 해제된 tarball과 같은 비git 소스를 구체화하면 러너의 환경에서 `CLAUDE_RUNNER_SKIP_GIT_VERIFY=1`을 설정하여 해당 확인을 건너뛰세요. 작업 브랜치 생성 및 결과 푸시와 같은 git 기반 흐름에는 git 체크아웃이 필요하므로 [`post-session` 훅](#post-session)으로 비git 트리에서 결과를 내보내세요.

128 146 

129훅이 0이 아닌 값으로 종료되거나 0으로 종료되지만 사용 가능한 체크아웃을 남기지 않으면 러너가 수행하는 작업은 저장소에 따라 다릅니다:147<h4 id="get-git-credentials-in-the-hook">

148 훅에서 git 자격 증명 얻기

149</h4>

130 150 

131* **세션이 결과를 푸시하는 저장소**: 러너가 세션을 실패하고 0이 아닌 종료 시 스크립트의 stderr 끝을 사용자에게 표시합니다.151러너는 훅에 git 자격 증명을 전달하지 않습니다. `CLAUDE_RUNNER_CLAUDE_BIN`은 체크아웃 훅 환경에서 설정되지 않으므로 `decode-token` 서브명령도 여기서는 사용할 수 없습니다. 대신 세션의 ID에서 세션별 복제 자격 증명을 발급하거나, 호스트 자체의 git 인증으로 폴백하세요:

132* **세션이 읽기만 하는 저장소**(예: 실행 중인 세션에 추가된 저장소): 러너는 `[runner:warn]` 줄을 실패 세부 정보와 함께 로깅하고, `Skipped` 단계를 세션에 게시하고, 훅이 체크아웃 경로에 남긴 것을 제거하고, 나머지 저장소로 계속합니다. 러너가 경로를 즉시 제거할 수 없으면 세션 종료 시 제거를 다시 시도합니다. 건너뛰기로 인해 세션에 저장소가 전혀 없으면 러너는 어쨌든 세션을 실패합니다.

133 152 

134v2.1.228 이전에는 러너가 모든 저장소에 대해 훅 실패 시 세션을 실패했으므로 훅이 제공할 수 없는 읽기 전용 저장소는 세션이 새 러너에서 다시 시작될 때마다 다시 세션을 실패했습니다.153* **세션별 복제 자격 증명**: [세션 서비스에서 토큰 확인](/docs/ko/self-hosted-environments-identity#verify-the-token-from-your-service)에 설명된 대로 `CLAUDE_RUNNER_API_BASE_URL` 아래의 JWKS 엔드포인트에 대해 표준 JWT 라이브러리로 `CLAUDE_CODE_SESSION_ACCESS_TOKEN`을 확인합니다. 그런 다음 자격 증명 서비스가 토큰의 `act` 클레임에 있는 ID에 대한 단기 복제 자격 증명을 발급하도록 합니다. 해당 자격 증명의 키는 `act.sub`로 지정하고, `act.email`을 요구하지 마세요.

154* **호스트 git 인증**: SSH 에이전트, 자격 증명 도우미 또는 `.netrc`와 같이 호스트가 이미 가지고 있는 git 인증을 사용합니다.

135 155 

136러너는 세션이 끝난 후 체크아웃 경로를 제거합니다.156<h4 id="when-the-hook-fails">

157 훅이 실패할 때

158</h4>

159 

160훅이 0이 아닌 값으로 종료되거나, 0으로 종료되지만 사용 가능한 체크아웃을 남기지 않으면 훅이 실패한 것입니다:

161 

162* **세션이 결과를 푸시하는 저장소**: 러너가 세션을 실패하고 0이 아닌 종료 시 스크립트의 stderr 끝을 사용자에게 표시합니다.

163* **세션이 읽기만 하는 저장소**(예: 실행 중인 세션에 추가된 저장소): 러너는 `[runner:warn]` 줄을 실패 세부 정보와 함께 로그에 기록하고, `Skipped` 단계를 세션에 게시하고, 훅이 체크아웃 경로에 남긴 것을 제거하고, 나머지 저장소로 계속합니다. 건너뛰기로 인해 세션에 저장소가 전혀 없으면 러너는 어쨌든 세션을 실패합니다.

164 

165훅이 성공하면 러너는 세션이 끝난 후 체크아웃 경로를 제거합니다.

137 166 

138<h3 id="post-session">167<h3 id="post-session">

139 post-session168 post-session

151| `CLAUDE_RUNNER_WORKSPACE_PATHS` | 세션의 작업 트리의 콜론 구분 절대 경로입니다. 0개 저장소 세션의 경우 비어 있습니다. |180| `CLAUDE_RUNNER_WORKSPACE_PATHS` | 세션의 작업 트리의 콜론 구분 절대 경로입니다. 0개 저장소 세션의 경우 비어 있습니다. |

152| `CLAUDE_RUNNER_DEBUG_LOG_PATH` | 세션의 디버그 로그 경로이며, 훅이 실행되는 동안 여전히 디스크에 있습니다. |181| `CLAUDE_RUNNER_DEBUG_LOG_PATH` | 세션의 디버그 로그 경로이며, 훅이 실행되는 동안 여전히 디스크에 있습니다. |

153| `CLAUDE_RUNNER_API_BASE_URL` | 세션 범위 호출용 Anthropic API 기본 URL |182| `CLAUDE_RUNNER_API_BASE_URL` | 세션 범위 호출용 Anthropic API 기본 URL |

154| `CLAUDE_RUNNER_CLIENT_PLATFORM` | 세션을 생성한 클라이언트 표면(예: `web_claude_ai`, `desktop_app`, `ios`)입니다. 세션에 기록되거나 인식된 표면이 없으면 설정되지 않습니다. Claude Code v2.1.229 이상이 필요합니다. |183| `CLAUDE_RUNNER_CLIENT_PLATFORM` | 세션을 생성한 클라이언트 사용 환경(예: `web_claude_ai`, `desktop_app`, `ios`)입니다. 세션에 기록되거나 인식된 사용 환경이 없으면 설정되지 않으므로 `set -u` 아래에서는 `${CLAUDE_RUNNER_CLIENT_PLATFORM:-}`로 참조하세요. Claude Code v2.1.229 이상이 필요합니다. |

155| `CLAUDE_CODE_SESSION_ACCESS_TOKEN` | 세션 범위 API 호출용 세션 액세스 토큰 |184| `CLAUDE_CODE_SESSION_ACCESS_TOKEN` | 세션 범위 API 호출용 세션 액세스 토큰 |

156| `GIT_CONFIG_COUNT`, `GIT_CONFIG_KEY_n`, `GIT_CONFIG_VALUE_n` | 러너가 훅이 실행하는 git에 대해 고정하는 Git 설정입니다. [라이프사이클 훅 내부의 Git 구성](#git-configuration-inside-lifecycle-hooks)에서 설명합니다. Claude Code v2.1.280 이상이 필요합니다. |185| `GIT_CONFIG_COUNT`, `GIT_CONFIG_KEY_n`, `GIT_CONFIG_VALUE_n` | 러너가 훅이 실행하는 git에 대해 고정하는 Git 설정입니다. [라이프사이클 훅 내부의 Git 구성](#git-configuration-inside-lifecycle-hooks)에서 설명합니다. Claude Code v2.1.280 이상이 필요합니다. |

157 186 

158`CLAUDE_RUNNER_EXIT_REASON`은 네 가지 값 중 하나를 취합니다:187`CLAUDE_RUNNER_EXIT_REASON`은 네 가지 값 중 하나를 취합니다:

159 188 

160* `completed`: 세션이 깔끔하게 종료되었습니다. Claude Code 프로세스가 정상적으로 종료되었거나, 세션이 여전히 실행 중인 동안 아카이브되거나 삭제되었습니다.189* `completed`: 세션이 깔끔하게 종료되었습니다. Claude Code 프로세스가 정상적으로 종료되었거나, 세션이 아카이브되거나 삭제된 후 스스로 종료되었습니다.

161* `failed`: Claude Code 프로세스가 충돌했거나, 시작 후 설정이 실패했습니다.190* `failed`: Claude Code 프로세스가 충돌했거나, 시작 후 설정이 실패했습니다.

162* `interrupted`: 러너가 세션을 중지했습니다. 슬롯을 해제하기 위해 세션을 해제했거나, 시작 시 타임아웃되었거나, 서버가 이 러너에서 세션을 이동했거나, 러너가 드레인 중이었거나, 세션이 [`--kill-session-after-min`](/docs/ko/self-hosted-environments-reference#runner-cli-flags) 제한을 초과했습니다.191* `interrupted`: 러너가 세션을 중지했으며, 다음 경우 중 하나입니다:

192 * 러너가 슬롯을 확보하기 위해 세션을 해제했습니다.

193 * 세션이 시작 시 시간 초과되었습니다.

194 * 서버가 이 러너에서 세션을 이동했습니다.

195 * 프로세스가 종료되기 전에 러너의 폴링이 아카이브 또는 삭제를 감지했습니다.

196 * 러너가 드레인 중이었습니다.

197 * 세션이 [`--kill-session-after-min`](/docs/ko/self-hosted-environments-reference#runner-cli-flags) 제한을 초과했습니다.

163* `abandoned`: 다른 러너가 요청한 세션용으로 예약되어 있습니다. 훅은 현재 이 경우에 실행되지 않습니다.198* `abandoned`: 다른 러너가 요청한 세션용으로 예약되어 있습니다. 훅은 현재 이 경우에 실행되지 않습니다.

164 199 

165[세션 라이프사이클 카운터 의미론](/docs/ko/self-hosted-environments-reference#session-lifecycle-counter-semantics)은 해제, 시작 타임아웃 및 서버 이동을 `interrupted` 대신 `completed`로 계산합니다. 러너가 슬롯을 깔끔하게 반환했기 때문입니다. 훅 수신과 카운터를 비교할 때 이 차이를 예상하세요.200훅 수신을 [세션 라이프사이클 카운터](/docs/ko/self-hosted-environments-reference#session-lifecycle-counter-semantics)와 비교하면 일부 `interrupted` 수신이 카운터에서는 `completed`로 계산된다는 점을 예상하세요. 카운터는 해제, 시작 타임아웃, 서버 이동, 그리고 러너의 폴링이 먼저 감지한 아카이브 또는 삭제를 `completed`로 계산합니다. 러너가 슬롯을 깔끔하게 반환했기 때문입니다.

166 201 

167훅의 종료 상태는 세션 결과에 영향을 주지 않습니다. 실패는 로깅되고 무시됩니다. 러너는 `--post-session-hook-timeout-sec`(기본값 60초)까지 모든 세션 종료(러너 종료 포함)에서 대기합니다. 이 예제는 커밋되지 않은 작업을 구조 분기에 저장합니다:202훅의 종료 상태는 세션 결과에 영향을 주지 않습니다. 실패는 로깅되고 무시됩니다. 러너는 `--post-session-hook-timeout-sec`(기본값 60초)까지 모든 세션 종료(러너 종료 포함)에서 대기합니다. 이 예제는 커밋되지 않은 작업을 구조 분기에 저장합니다:

168 203 

169```bash theme={null}204```bash theme={null}

170#!/usr/bin/env bash205#!/usr/bin/env bash

171set -u206set -u

207export GIT_ALLOW_PROTOCOL=${GIT_ALLOW_PROTOCOL:-https:http:ssh}

172IFS=':'208IFS=':'

173# -c 재정의는 저장소 로컬 설정보다 우선하므로 세션이 작성한 fsmonitor,209# -c 재정의는 저장소 로컬 설정보다 우선하므로 세션이 작성한 fsmonitor,

174# 훅 경로 및 gpg-program 구성이 훅의 권한으로 코드를 실행하는 것을210# 훅 경로 및 gpg-program 구성이 훅의 권한으로 코드를 실행하는 것을

188done224done

189```225```

190 226 

227스크립트의 `GIT_ALLOW_PROTOCOL` 줄은 git을 HTTPS, HTTP 및 SSH 원격으로 제한합니다. 러너의 환경에서 이미 비어 있지 않은 자체 `GIT_ALLOW_PROTOCOL` 목록을 설정한 경우 스크립트는 해당 목록을 유지합니다.

228 

191훅은 러너 호스트의 자체 환경에서 사용 가능한 git 자격 증명으로 푸시합니다. [이미지에 자격 증명 없음 자세](/docs/ko/self-hosted-environments-deploy#configure-git) 아래에서(기본 제공 복제가 Anthropic git 프록시를 통과할 때 포함) 없으므로 푸시하기 전에 훅 내에서 단기 푸시 자격 증명을 발급합니다. 훅이 `CLAUDE_CODE_SESSION_ACCESS_TOKEN`에서 받는 세션 토큰을 자신의 토큰 서비스와 교환하고 [세션 ID 확인](/docs/ko/self-hosted-environments-identity)에서 설명하는 대로 확인합니다. 훅이 세션이 가지지 않은 자격 증명을 보유하면 `origin`을 운영자 제공 URL로 바꾸고 `-c credential.helper=` 및 자신의 도우미를 전달합니다. 세션이 작성한 구성이 여전히 영향을 줄 수 있는 항목은 [라이프사이클 훅 내부의 Git 구성](#git-configuration-inside-lifecycle-hooks)에서 설명합니다.229훅은 러너 호스트의 자체 환경에서 사용 가능한 git 자격 증명으로 푸시합니다. [이미지에 자격 증명 없음 자세](/docs/ko/self-hosted-environments-deploy#configure-git) 아래에서(기본 제공 복제가 Anthropic git 프록시를 통과할 때 포함) 없으므로 푸시하기 전에 훅 내에서 단기 푸시 자격 증명을 발급합니다. 훅이 `CLAUDE_CODE_SESSION_ACCESS_TOKEN`에서 받는 세션 토큰을 자신의 토큰 서비스와 교환하고 [세션 ID 확인](/docs/ko/self-hosted-environments-identity)에서 설명하는 대로 확인합니다. 훅이 세션이 가지지 않은 자격 증명을 보유하면 `origin`을 운영자 제공 URL로 바꾸고 `-c credential.helper=` 및 자신의 도우미를 전달합니다. 세션이 작성한 구성이 여전히 영향을 줄 수 있는 항목은 [라이프사이클 훅 내부의 Git 구성](#git-configuration-inside-lifecycle-hooks)에서 설명합니다.

192 230 

193<h4 id="hook-timing-when-the-runner-releases-a-session">231<h4 id="hook-timing-when-the-runner-releases-a-session">

264| `CLAUDE_RUNNER_ORDER_ID` | 스폰 요청당 고유하고 Kubernetes 리소스 이름에 안전한 불투명 멱등성 키입니다. 프로비저너의 중복 제거 키로 주문 ID만 사용합니다. |302| `CLAUDE_RUNNER_ORDER_ID` | 스폰 요청당 고유하고 Kubernetes 리소스 이름에 안전한 불투명 멱등성 키입니다. 프로비저너의 중복 제거 키로 주문 ID만 사용합니다. |

265| `CLAUDE_RUNNER_SESSION_ID` | 이 요청이 대상으로 하는 세션입니다. 세션의 모든 재요청에서 반복되므로 로깅 및 라우팅에 사용하고 중복 제거 키로는 사용하지 마십시오. [`--min-idle`](/docs/ko/self-hosted-environments-reference#orchestrator-cli-flags)이 설정된 경우 특정 세션 전에 대기 중인 러너를 부팅하는 사전 워밍 요청의 경우 비어 있으므로 변수가 설정되어 있다고 가정하지 마십시오. |303| `CLAUDE_RUNNER_SESSION_ID` | 이 요청이 대상으로 하는 세션입니다. 세션의 모든 재요청에서 반복되므로 로깅 및 라우팅에 사용하고 중복 제거 키로는 사용하지 마십시오. [`--min-idle`](/docs/ko/self-hosted-environments-reference#orchestrator-cli-flags)이 설정된 경우 특정 세션 전에 대기 중인 러너를 부팅하는 사전 워밍 요청의 경우 비어 있으므로 변수가 설정되어 있다고 가정하지 마십시오. |

266| `CLAUDE_RUNNER_SESSION_UUID` | 정규 UUID 형식의 동일한 세션 ID입니다. 사전 워밍 요청의 경우 비어 있습니다. |304| `CLAUDE_RUNNER_SESSION_UUID` | 정규 UUID 형식의 동일한 세션 ID입니다. 사전 워밍 요청의 경우 비어 있습니다. |

267| `CLAUDE_RUNNER_ATTEMPT` | 이 세션이 가진 스폰 요청의 수입니다. 사전 워밍 요청의 경우 `0`입니다. |305| `CLAUDE_RUNNER_ATTEMPT` | 로깅에 사용하는 세션별 카운터입니다. 재시도 횟수나 요청 수가 아닙니다. 사전 워밍 요청의 경우 `0`이지만, 세션에 대한 요청도 `0`을 가질 수 있습니다. |

268| `CLAUDE_RUNNER_ORDER_SERVER_TIME` | 폴 응답의 HTTP `Date` 헤더에서 서버 시간입니다. 훅이 작업 지시서 JWT의 `exp`를 확인할 때 로컬 클록 대신 이 값과 비교하여 시간 차이를 허용합니다. 게이트웨이가 헤더를 생략한 경우 비어 있습니다. |306| `CLAUDE_RUNNER_ORDER_SERVER_TIME` | 폴 응답의 HTTP `Date` 헤더에서 서버 시간입니다. 훅이 작업 지시서 JWT의 `exp`를 확인할 때 로컬 클록 대신 이 값과 비교하여 시간 차이를 허용합니다. 게이트웨이가 헤더를 생략한 경우 비어 있습니다. |

269| `CLAUDE_RUNNER_POOL_ID` | 새 러너가 조인해야 하는 환경의 ID이며, `ccpool_...` 형식입니다. |307| `CLAUDE_RUNNER_POOL_ID` | 새 러너가 조인해야 하는 환경의 ID이며, `ccpool_...` 형식입니다. |

270| `CLAUDE_RUNNER_ACCOUNT_ID` | 세션을 대기열에 넣은 계정의 태그된 ID이며, 계정별 라우팅, 할당량 또는 차지백용입니다. 사용할 수 없을 때 비어 있으며, Claude Tag 채널 세션의 경우 항상 비어 있습니다. 이러한 세션은 계정이 대기열에 넣지 않습니다. |308| `CLAUDE_RUNNER_ACCOUNT_ID` | 세션을 대기열에 넣은 계정의 태그된 ID이며, 계정별 라우팅, 할당량 또는 차지백용입니다. 사용할 수 없을 때 비어 있으며, Claude Tag 채널 세션의 경우 항상 비어 있습니다. 이러한 세션은 계정이 대기열에 넣지 않습니다. |

271| `CLAUDE_RUNNER_ACCOUNT_EMAIL` | 세션을 대기열에 넣은 계정의 이메일입니다. 사용할 수 없을 때 비어 있습니다. 이메일을 개인 식별 정보로 취급하고 로깅하지 마십시오. |309| `CLAUDE_RUNNER_ACCOUNT_EMAIL` | 세션을 대기열에 넣은 계정의 이메일입니다. 사용할 수 없을 때 비어 있습니다. 이메일을 개인 식별 정보로 취급하고 로깅하지 마십시오. |

272| `CLAUDE_RUNNER_PRIMARY_REPO_URL` | 세션의 첫 번째 git 소스의 URL이며, 해당 리포지토리가 사전 워밍된 러너로 라우팅하기 위한 것입니다. 세션에 git 소스가 없을 때 비어 있습니다. |310| `CLAUDE_RUNNER_PRIMARY_REPO_URL` | 세션의 첫 번째 git 소스의 URL이며, 해당 리포지토리가 사전 워밍된 러너로 라우팅하기 위한 것입니다. 세션에 git 소스가 없을 때 비어 있습니다. |

273| `CLAUDE_RUNNER_PRIMARY_REPO_REVISION` | 세션의 첫 번째 git 소스의 리비전입니다: 브랜치, SHA 또는 태그입니다. 지정되지 않은 경우 비어 있습니다. |311| `CLAUDE_RUNNER_PRIMARY_REPO_REVISION` | 세션의 첫 번째 git 소스의 리비전입니다: 브랜치, SHA, 태그 또는 전체 참조 이름입니다. 지정되지 않은 경우 비어 있습니다. |

274| `CLAUDE_RUNNER_REPO_SOURCES` | 세션의 모든 git 소스에 대한 `{url, revision}`의 JSON 배열이며, 보조 리포지토리에서 라우팅하는 훅용입니다. 소스가 없을 때 비어 있습니다. |312| `CLAUDE_RUNNER_REPO_SOURCES` | 세션의 모든 git 소스에 대한 `{url, revision}`의 JSON 배열이며, 보조 리포지토리에서 라우팅하는 훅용입니다. 소스가 없을 때 비어 있습니다. |

275| `CLAUDE_RUNNER_CORRELATION_ID` | 세션 생성 시 제공된 상관 ID이며, 훅이 이 작업 지시서를 세션을 생성한 요청에 매핑할 수 있도록 에코백됩니다. 세션에 없을 때 비어 있습니다. |313| `CLAUDE_RUNNER_CORRELATION_ID` | 세션 생성 시 제공된 상관 ID이며, 훅이 이 작업 지시서를 세션을 생성한 요청에 매핑할 수 있도록 에코백됩니다. 세션에 없을 때 비어 있습니다. |

276| `CLAUDE_RUNNER_CLIENT_PLATFORM` | 세션을 생성한 클라이언트 표면입니다. 예: `web_claude_ai`, `desktop_app`, `ios` 또는 `scheduled_trigger`이며, 채택 분석용입니다. 세션에 기록되거나 인식된 표면이 없을 때 설정되지 않으며, 사전 워밍 요청의 경우도 마찬가지입니다. `[ -n "${CLAUDE_RUNNER_CLIENT_PLATFORM:-}" ]`로 확인하면 `set -u` 하에서 안전하게 유지됩니다. |314| `CLAUDE_RUNNER_CLIENT_PLATFORM` | 세션을 생성한 클라이언트 표면입니다. 예: `web_claude_ai`, `desktop_app`, `ios` 또는 `scheduled_trigger`이며, 채택 분석용입니다. 세션에 기록되거나 인식된 표면이 없을 때 설정되지 않으며, 사전 워밍 요청의 경우도 마찬가지입니다. `[ -n "${CLAUDE_RUNNER_CLIENT_PLATFORM:-}" ]`로 확인하면 `set -u` 하에서 안전하게 유지됩니다. |

286 324 

2871. **`CLAUDE_RUNNER_ORDER_ID`에서 멱등성을 유지합니다.** 동일한 요청의 재전달은 최대 하나의 러너를 스폰해야 합니다. 주문 ID에서 결정론적 리소스 이름을 파생시키고 플랫폼이 중복을 거부하도록 합니다. 대신 `CLAUDE_RUNNER_SESSION_ID`를 키로 사용하지 마십시오. 세션의 모든 재요청은 새 주문 ID와 함께 동일한 세션 ID를 전달하므로, 세션 ID로 명명되거나 중복 제거된 워크로드는 한 번 생성되고 해당 세션에 대해 다시는 생성되지 않습니다.3251. **`CLAUDE_RUNNER_ORDER_ID`에서 멱등성을 유지합니다.** 동일한 요청의 재전달은 최대 하나의 러너를 스폰해야 합니다. 주문 ID에서 결정론적 리소스 이름을 파생시키고 플랫폼이 중복을 거부하도록 합니다. 대신 `CLAUDE_RUNNER_SESSION_ID`를 키로 사용하지 마십시오. 세션의 모든 재요청은 새 주문 ID와 함께 동일한 세션 ID를 전달하므로, 세션 ID로 명명되거나 중복 제거된 워크로드는 한 번 생성되고 해당 세션에 대해 다시는 생성되지 않습니다.

2882. **워크로드를 재시도하지 마십시오.** 하나의 주문 ID는 최대 하나의 생성된 워크로드를 의미합니다. 러너가 등록되지 않으면 Anthropic은 `--expected-spawn-seconds` 후 새 주문 ID로 재요청합니다.3262. **워크로드를 재시도하지 마십시오.** 하나의 주문 ID는 최대 하나의 생성된 워크로드를 의미합니다. 러너가 등록되지 않으면 Anthropic은 `--expected-spawn-seconds` 후 새 주문 ID로 재요청합니다.

2893. **종료 코드 계약을 사용합니다.** 종료 0은 제출됨을 의미합니다. 종료 1은 재시도 가능한 실패를 의미합니다. 세션은 백오프되고 다시 제공됩니다. 종료 2 이상은 재시도 불가능을 의미합니다. 세션은 [Owner](/docs/ko/cloud-environments#organization-shared-environments)가 환경의 **Activity** 탭에서 **Retry**를 선택할 때까지 다시 스폰되지 않습니다. 0이 아닌 종료 시 훅의 stderr 끝이 실패 이유로 표시되므로 실행 가능한 오류를 stderr에 작성하고 시크릿은 절대 작성하지 마십시오. 사전 워밍 요청의 경우 실패할 세션이 없습니다: 오케스트레이터는 0이 아닌 종료를 로컬에만 로깅하고, 서버는 리스 후 스폰을 재요청합니다.3273. **종료 코드 계약을 사용합니다.** 결과에 맞는 상태로 종료합니다:

2904. **`--expected-spawn-seconds`를 최소한 p99 부팅 시간으로 설정합니다.** 이는 서버 측 리스입니다. 모든 오케스트레이터 복제본은 동일한 값을 사용해야 합니다.328 

329 * **종료 0**: 제출됨.

330 * **종료 1**: 재시도 가능한 실패. 세션은 백오프되고 다시 제공됩니다.

331 * **종료 2 이상**: 재시도 불가능한 실패. 사용자가 세션에 새 메시지를 보내거나 [Owner](/docs/ko/cloud-environments#organization-shared-environments)가 환경의 **Activity** 탭에서 해당 세션의 **Retry**를 선택할 때까지 세션은 다시 스폰되지 않습니다.

332 

333 0이 아닌 종료 시 훅의 stderr 끝이 **Activity** 탭에 실패 이유로 표시되므로 실행 가능한 오류를 stderr에 작성하고 시크릿은 절대 작성하지 마십시오. 셸 훅에서는 [일시적인 실패를 재시도 가능한 상태로 유지하십시오](#keep-transient-failures-retryable-in-a-shell-hook).

334 

335 사전 워밍 요청의 경우 실패할 세션이 없습니다: 오케스트레이터는 0이 아닌 종료를 로컬에만 로깅하고, 서버는 `--expected-spawn-seconds` 리스가 만료된 후 스폰을 재요청합니다.

3364. **`--expected-spawn-seconds`를 최소한 스폰 요청부터 러너 등록까지의 p99 시간으로 설정합니다.** 오케스트레이터가 스폰 요청을 받은 시점부터 측정하고, 부팅 시간뿐 아니라 플랫폼에서 용량을 기다리는 시간도 포함하십시오. 이 값은 서버 측 리스이며 작업 지시서도 함께 만료되므로, 워크로드가 이보다 오래 걸리는 러너는 등록할 수 없습니다. 모든 오케스트레이터 복제본은 동일한 값을 사용해야 합니다.

291 337 

292훅이 stdout 또는 stderr에 작성하는 모든 것은 자격증명이 자동으로 삭제된 오케스트레이터의 로그에 나타납니다. 세션이 대기 중인 상태로 유지되면 오케스트레이터의 `/healthz` 본문에서 대기열 수를 확인한 후 [**Cloud environments** 관리 페이지](https://claude.ai/admin-settings/cloud-environments)에서 환경의 **Activity** 탭을 엽니다: 실패한 세션을 확장하여 스폰 오류를 확인하고 **Retry**를 선택하여 재요청합니다.338훅이 stdout 또는 stderr에 작성하는 모든 것은 자격증명이 자동으로 삭제된 오케스트레이터의 로그에 나타납니다. 세션이 대기 중인 상태로 유지되면 오케스트레이터의 `/healthz` 본문에서 대기열 수를 확인한 후 [**Cloud environments** 관리 페이지](https://claude.ai/admin-settings/cloud-environments)에서 환경의 **Activity** 탭을 엽니다: 실패한 세션을 확장하여 스폰 오류를 확인하고 **Retry**를 선택하여 재요청합니다.

293 339 

294**Activity** 탭에 스폰 오류가 없는 상태로 대기 중인 세션은 훅이 세션 ID를 키로 사용하고 있음을 의미할 수 있습니다. 확인하려면 플랫폼에 해당 세션의 첫 번째 스폰 요청에 대한 워크로드가 있는지, 재요청에 대한 워크로드가 없는지 확인합니다. 그렇다면 대신 `CLAUDE_RUNNER_ORDER_ID`를 키로 사용합니다.340**Activity** 탭에 스폰 오류가 없는 상태로 대기 중인 세션은 훅이 세션 ID를 키로 사용하고 있음을 의미할 수 있습니다. 확인하려면 플랫폼에 해당 세션의 첫 번째 스폰 요청에 대한 워크로드가 있는지, 재요청에 대한 워크로드가 없는지 확인합니다. 그렇다면 대신 `CLAUDE_RUNNER_ORDER_ID`를 키로 사용합니다.

295 341 

342<h4 id="keep-transient-failures-retryable-in-a-shell-hook">

343 셸 훅에서 일시적인 실패를 재시도 가능한 상태로 유지하기

344</h4>

345 

346`set -e`를 사용하는 셸 훅에서는 재시도로 해결될 수 있었던 실패가 세션을 차단할 수 있습니다. 훅은 실패한 명령에서 멈추고 해당 명령 자체의 상태로 종료하며, 오케스트레이터는 그 상태에 종료 코드 계약을 적용합니다. 명령이 설치되지 않았을 때의 `127`이나 HTTP 오류 시 `curl --fail`이 반환하는 `22`처럼 많은 실패가 2 이상의 상태를 반환하므로, 첫 번째 실패에서 세션이 차단됩니다.

347 

348훅이 이미 차단한 세션은 사용자가 새 메시지를 보내거나 [Owner](/docs/ko/cloud-environments#organization-shared-environments)가 환경의 **Activity** 탭에서 해당 세션의 **Retry**를 선택할 때까지 차단된 상태로 유지됩니다.

349 

350이러한 실패를 대신 종료 1로 바꾸려면 훅의 `#!` 줄 바로 아래, 실패할 수 있는 어떤 코드보다도 위에 다음 줄을 넣으십시오:

351 

352```bash theme={null}

353set -e

354PERMANENT=; permanent() { printf '%s\n' "$*" >&2; PERMANENT=1; exit 2; }

355trap 'rc=$?; [ "$rc" -eq 0 ] || [ -n "${PERMANENT:-}" ] || exit 1' EXIT

356```

357 

358이 줄들은 훅의 나머지 부분이 동작하는 방식을 바꾸므로, 추가한 후 다음 각 패턴이 있는지 훅을 확인하십시오:

359 

360* **단독 `exit 2` 이상**: trap이 설정되면 종료 1이 됩니다. 어떤 재시도로도 해결할 수 없는 오류의 경우 대신 `permanent "namespace claude-runners does not exist"`처럼 이유와 함께 `permanent`를 호출하십시오. `$( )`, `( )` 또는 파이프 내부가 아닌 메인 셸에서 호출하십시오.

361* **`exec`**: `exec`는 셸을 대체하여 trap이 실행되지 않으므로, 훅의 마지막 명령을 `exec`로 시작하지 마십시오.

362* **두 번째 `EXIT` trap**: 두 번째 `trap ... EXIT`는 첫 번째를 대체하므로 두 trap을 하나로 병합하십시오. 정리 명령을 `rc=$?;` 바로 뒤에 넣고 각각을 `|| true;`로 끝내십시오. 그러면 정리 작업이 성공 시뿐 아니라 실패 시에도 실행되며, 정리 명령이 실패해도 훅의 종료 상태가 설정되지 않습니다. 다음 병합된 trap은 그 형태를 보여 주며, `your-cleanup-command`는 사용자 자신의 명령을 나타냅니다:

363 

364 ```bash theme={null}

365 trap 'rc=$?; your-cleanup-command || true; [ "$rc" -eq 0 ] || [ -n "${PERMANENT:-}" ] || exit 1' EXIT

366 ```

367* **실패해도 되는 명령**: 훅이 이전에 `set -e`를 사용하지 않았다면, 이제 아무것도 찾지 못한 조회나 플랫폼이 거부하는 중복 제출처럼 0이 아닌 값을 반환하는 첫 번째 명령에서 멈춥니다. 훅이 결과에 따라 동작한다면 해당 명령을 `if`의 조건으로 만드십시오. 결과를 무시한다면 명령 뒤에 `|| true`를 붙이십시오.

368 

369trap이 작동하는지 확인하려면 `trap` 줄 바로 아래에 `no-such-command`처럼 존재하지 않는 명령을 호출하는 줄을 추가하십시오. 셸에서 훅 파일을 실행하고 `echo $?`가 `1`을 출력하는지 확인한 다음 해당 줄을 제거하십시오.

370 

296<h2 id="send-model-requests-to-bedrock-or-agent-platform">371<h2 id="send-model-requests-to-bedrock-or-agent-platform">

297 Bedrock 또는 Agent Platform으로 모델 요청 보내기372 Bedrock 또는 Agent Platform으로 모델 요청 보내기

298</h2>373</h2>

381Amazon Bedrock 또는 Google Cloud의 Agent Platform으로 모델 요청을 보내는 세션은 Anthropic API의 세션과 다음과 같은 점에서 다릅니다.456Amazon Bedrock 또는 Google Cloud의 Agent Platform으로 모델 요청을 보내는 세션은 Anthropic API의 세션과 다음과 같은 점에서 다릅니다.

382 457 

383* **claude.ai의 정책**: [서버 관리형 설정](/docs/ko/server-managed-settings)은 이러한 세션에 도달하지 않습니다. Owner가 Claude Code 관리자 설정에서 지정하는 조직 정책도 도달하지 않으므로, Claude Code는 세션 내에서 이를 적용하지 않습니다. 의존하는 규칙은 러너 이미지의 [관리형 설정 파일](/docs/ko/managed-settings#delivery-mechanisms)에 넣으십시오.458* **claude.ai의 정책**: [서버 관리형 설정](/docs/ko/server-managed-settings)은 이러한 세션에 도달하지 않습니다. Owner가 Claude Code 관리자 설정에서 지정하는 조직 정책도 도달하지 않으므로, Claude Code는 세션 내에서 이를 적용하지 않습니다. 의존하는 규칙은 러너 이미지의 [관리형 설정 파일](/docs/ko/managed-settings#delivery-mechanisms)에 넣으십시오.

459* **계정 스킬**: 이러한 세션은 개인의 claude.ai 계정에서 활성화된 스킬을 다운로드하지 않습니다. [각 세션의 구성이 조합되는 방식](#how-each-session’s-config-is-assembled)을 참조하십시오.

384* **파일**: claude.ai나 모바일 또는 데스크톱 앱에서 세션에 첨부한 파일은 세션에 도달하지 않으며, Claude는 [`SendUserFile` 도구](/docs/ko/tools-reference)로 파일을 다시 보낼 수 없습니다. 대신 입력 파일을 저장소나 러너에 두십시오.460* **파일**: claude.ai나 모바일 또는 데스크톱 앱에서 세션에 첨부한 파일은 세션에 도달하지 않으며, Claude는 [`SendUserFile` 도구](/docs/ko/tools-reference)로 파일을 다시 보낼 수 없습니다. 대신 입력 파일을 저장소나 러너에 두십시오.

385* **모델 선택**: Anthropic의 컨트롤 플레인이 각 세션의 모델을 전송하며, 모델 없이 세션이 시작되면 Claude Code는 해당 제공업체의 기본값을 사용합니다. 러너는 세션에 전달하는 환경에서 `ANTHROPIC_MODEL`과 `ANTHROPIC_DEFAULT_MODEL`을 제거합니다. 제공업체 페이지의 예시에서는 `ANTHROPIC_MODEL`을 설정하지만, 러너 환경에서는 두 변수 모두 아무런 효과가 없습니다. [Amazon Bedrock](/docs/ko/amazon-bedrock#4-pin-model-versions) 및 [Agent Platform](/docs/ko/google-vertex-ai#5-pin-model-versions)의 모델 버전 고정에 나오는 모델 계열별 변수는 세션에 도달합니다. 이 변수는 `opus` 같은 별칭이 무엇으로 해석되는지를 결정하며, 전체 모델 ID가 무엇으로 해석되는지는 결정하지 않습니다.461* **모델 선택**: Anthropic의 컨트롤 플레인이 각 세션의 모델을 전송하며, 모델 없이 세션이 시작되면 Claude Code는 해당 제공업체의 기본값을 사용합니다. 러너 환경의 `ANTHROPIC_MODEL`이나 `ANTHROPIC_DEFAULT_MODEL`로는 모델을 선택할 수 없지만, 별칭이 무엇으로 해석되는지는 고정할 수 있습니다.

462 * **`ANTHROPIC_MODEL` 및 `ANTHROPIC_DEFAULT_MODEL`**: 제공업체 페이지의 예시에서는 `ANTHROPIC_MODEL`을 설정하지만, 러너는 세션에 전달하는 환경에서 이 두 변수를 제거합니다.

463 * **모델 계열별 고정 변수**: [Amazon Bedrock](/docs/ko/amazon-bedrock#4-pin-model-versions) 및 [Agent Platform](/docs/ko/google-vertex-ai#5-pin-model-versions)의 모델 버전 고정에 나오는 변수는 세션에 도달합니다. 이 변수는 `opus` 같은 별칭이 무엇으로 해석되는지를 결정하며, 전체 모델 ID가 무엇으로 해석되는지는 결정하지 않습니다.

386* **계정에서 제공하지 않는 모델**: 세션이 모델 이름이 포함된 오류와 함께 메시지에서 실패할 수 있습니다. 개발자가 선택할 수 있는 모델, 모델 버전 고정에 설명된 백그라운드 모델, [자동 모드](/docs/ko/permission-modes#enable-auto-mode-on-bedrock-agent-platform-or-foundry)가 사용하는 분류기 모델을 활성화하십시오. Amazon Bedrock에서는 정책에서 각 모델을 허용하십시오.464* **계정에서 제공하지 않는 모델**: 세션이 모델 이름이 포함된 오류와 함께 메시지에서 실패할 수 있습니다. 개발자가 선택할 수 있는 모델, 모델 버전 고정에 설명된 백그라운드 모델, [자동 모드](/docs/ko/permission-modes#enable-auto-mode-on-bedrock-agent-platform-or-foundry)가 사용하는 분류기 모델을 활성화하십시오. Amazon Bedrock에서는 정책에서 각 모델을 허용하십시오.

387* **웹 검색 및 빠른 모드**: [웹 검색](/docs/ko/tools-reference#websearch-tool-behavior)은 Amazon Bedrock에서 사용할 수 없으며, [빠른 모드](/docs/ko/fast-mode)는 두 제공업체 모두에서 사용할 수 없습니다. 제공업체에 따라 달라지는 기타 기능은 [제공업체별로 달라지는 CLI 기능](/docs/ko/feature-availability#cli-capabilities-that-vary-by-provider)을 참조하십시오.465* **웹 검색 및 빠른 모드**: [웹 검색](/docs/ko/tools-reference#websearch-tool-behavior)은 Amazon Bedrock에서 사용할 수 없으며, [빠른 모드](/docs/ko/fast-mode)는 두 제공업체 모두에서 사용할 수 없습니다. 제공업체에 따라 달라지는 기타 기능은 [제공업체별로 달라지는 CLI 기능](/docs/ko/feature-availability#cli-capabilities-that-vary-by-provider)을 참조하십시오.

388 466 

411 489 

412세션은 러너의 환경을 상속하므로, 러너에서 [`ENABLE_TOOL_SEARCH`](/docs/ko/mcp#scale-with-mcp-tool-search)를 설정하면 러너가 생성하는 모든 세션의 MCP 도구 검색을 제어할 수 있습니다. 값에 대해서는 MCP 페이지에서 다룹니다.490세션은 러너의 환경을 상속하므로, 러너에서 [`ENABLE_TOOL_SEARCH`](/docs/ko/mcp#scale-with-mcp-tool-search)를 설정하면 러너가 생성하는 모든 세션의 MCP 도구 검색을 제어할 수 있습니다. 값에 대해서는 MCP 페이지에서 다룹니다.

413 491 

492<a id="connection-timing" />

493 

494<h3 id="wait-for-mcp-servers-before-the-first-turn">

495 첫 턴 전에 MCP 서버 대기하기

496</h3>

497 

498자체 호스팅 세션은 아직 연결 중인 MCP 서버를 두 개의 별도 시점에서 잠시 기다립니다. 대기 시간 내에 연결되지 못한 서버는 첫 턴이 시작될 때 해당 도구가 누락되며, 이후 별도의 조치 없이 사용할 수 있게 됩니다. 두 가지 대기는 다음과 같습니다:

499 

500* **세션 시작**: 도구 목록을 처음 가져오기 전에, 세션은 항목에 [`alwaysLoad: true`](/docs/ko/mcp#exempt-a-server-from-deferral)를 설정한 HTTP 또는 SSE 서버를 기본적으로 최대 5초 동안 기다리며, 러너 환경에서 [`MCP_CONNECTION_NONBLOCKING=0`](/docs/ko/env-vars)을 설정한 경우에는 모든 서버를 기다립니다. 그 외의 경우 HTTP 및 SSE 서버는 백그라운드에서 연결됩니다. 세션이 여기서 대기하는 동안에는 초기화가 느려집니다. [`MCP_CONNECT_TIMEOUT_MS`](/docs/ko/env-vars)로 5초 기본값을 변경할 수 있습니다.

501* **첫 턴**: 메시지가 도착한 후, 첫 턴은 아직 연결 중인 stdio 서버를 최대 2초 동안 기다립니다. 세션이 여기서 대기하는 동안에는 첫 응답이 느려집니다. 이 대기 시간을 변경하려면 러너 환경에서 [`CLAUDE_CODE_MCP_STARTUP_WAIT_MS`](/docs/ko/env-vars)를 설정합니다. 이 설정은 대기 대상 서버를 변경하지 않습니다. Claude Code v2.1.274 이상이 필요합니다.

502 

503`claude mcp add`에는 `alwaysLoad` 플래그가 없습니다. 이 키를 설정하려면 대신 `claude mcp add-json`으로 서버를 추가합니다. 이 명령은 서버의 JSON에서 해당 키를 받아 `.claude.json`에 기록합니다. Dockerfile에서는 다음과 같습니다:

504 

505```dockerfile theme={null}

506RUN claude mcp add-json core '{"type":"http","url":"https://mcp.example.com/mcp","alwaysLoad":true}' --scope user

507```

508 

509이후 턴에서도 서버의 도구가 나타나지 않으면, [MCP 서버](#mcp-servers)에서 설명한 대로 서버가 세션에 전달되었는지 확인합니다.

510 

414<h3 id="turn-off-built-in-session-tools">511<h3 id="turn-off-built-in-session-tools">

415 기본 제공 세션 도구 끄기512 기본 제공 세션 도구 끄기

416</h3>513</h3>

569 666 

570`SELF_HOSTED_RUNNER_HOST_CONFIG_DIR`을 설정하여 다른 경로에서 시드하거나 빈 디렉토리를 가리켜 시딩을 비활성화하십시오.667`SELF_HOSTED_RUNNER_HOST_CONFIG_DIR`을 설정하여 다른 경로에서 시드하거나 빈 디렉토리를 가리켜 시딩을 비활성화하십시오.

571 668 

572저장소 커밋된 `.claude/settings.json`은 프로젝트 설정으로 위에 계층화됩니다. 여러 저장소가 있는 세션에서는 [최대 하나의 저장소 파일만 적용됩니다](#repository-settings-in-sessions-with-several-repositories). 세션은 또한 러너 이미지의 표준 시스템 경로에서 [`managed-settings.json`](/docs/ko/settings#where-settings-live)을 읽습니다. 해당 키가 [서버 관리 설정](/docs/ko/server-managed-settings)과 함께 적용되는지 여부는 [Claude Code가 관리형 소스를 결합하는 방식](/docs/ko/managed-settings#how-claude-code-combines-managed-sources)을 따릅니다. 기본적으로 조직이 서버 관리 키를 제공할 때 세션은 [Claude Code가 모든 관리자 소스에서 읽는 키](/docs/ko/managed-settings#keys-read-from-every-admin-source)(예: `env` 블록, 샌드박스 잠금, 샌드박스 바이너리 경로 및 `forceRemoteSettingsRefresh`)를 제외하고 러너 이미지의 파일을 무시합니다. [설정 우선순위](/docs/ko/settings#settings-precedence)를 참조하십시오.669세션은 다음 설정 파일도 읽습니다:

670 

671* **프로젝트 설정**: 저장소에 커밋된 `.claude/settings.json`은 사용자 수준 기준선 위에 계층화됩니다. 여러 저장소가 있는 세션에서는 [최대 하나의 저장소 파일만 적용됩니다](#repository-settings-in-sessions-with-several-repositories).

672* **관리형 설정**: 세션은 러너 이미지의 표준 시스템 경로에서 [`managed-settings.json`](/docs/ko/settings#where-settings-live)을 읽습니다. 해당 키가 [서버 관리 설정](/docs/ko/server-managed-settings)과 함께 적용되는지 여부는 [Claude Code가 관리형 소스를 결합하는 방식](/docs/ko/managed-settings#how-claude-code-combines-managed-sources)을 참조하십시오.

673 

674이러한 소스가 적용되는 순서는 [설정 우선순위](/docs/ko/settings#settings-precedence)를 참조하십시오.

573 675 

574Anthropic의 제어 평면이 세션에 [Claude Code 훅](/docs/ko/hooks)을 제공할 때 러너는 자신의 구성 위에 설치하지 않고 자신의 구성과 함께 설치합니다. Claude Code v2.1.229 이상이 필요합니다.676Anthropic의 제어 평면이 세션에 [Claude Code 훅](/docs/ko/hooks)을 제공할 때 러너는 자신의 구성 위에 설치하지 않고 자신의 구성과 함께 설치합니다. Claude Code v2.1.229 이상이 필요합니다.

575 677 

577* **작성자**: 제어 평면은 세션별 또는 타사 입력이 아닌 자신의 배포의 고정 상수에서 스크립트를 채웁니다.679* **작성자**: 제어 평면은 세션별 또는 타사 입력이 아닌 자신의 배포의 고정 상수에서 스크립트를 채웁니다.

578* **여전히 이를 관리하는 것**: `--settings`를 통해 제공된 훅은 관리되는 계층이 아닌 일반 병합 훅 구성에 들어가므로 관리되는 설정이 여전히 적용됩니다. `disableAllHooks`는 이를 비활성화하며, [`allowManagedHooksOnly`](/docs/ko/settings-reference#allowmanagedhooksonly)가 로드된 상태로 유지하는 범주에 포함되지 않습니다.680* **여전히 이를 관리하는 것**: `--settings`를 통해 제공된 훅은 관리되는 계층이 아닌 일반 병합 훅 구성에 들어가므로 관리되는 설정이 여전히 적용됩니다. `disableAllHooks`는 이를 비활성화하며, [`allowManagedHooksOnly`](/docs/ko/settings-reference#allowmanagedhooksonly)가 로드된 상태로 유지하는 범주에 포함되지 않습니다.

579 681 

682사용자가 직접 세션을 시작하면 Claude Code는 해당 사용자의 [claude.ai 계정에서 활성화된 스킬](/docs/ko/skills#skills-in-cowork-and-cloud-sessions)도 해당 세션의 구성 디렉토리로 다운로드합니다. [루틴](/docs/ko/routines) 실행은 소유자의 스킬을 받지 않으며, [Bedrock 또는 Agent Platform으로 모델 요청을 보내는](#send-model-requests-to-bedrock-or-agent-platform) 세션은 스킬을 전혀 다운로드하지 않습니다. 이러한 세션에 필요한 스킬은 저장소의 `.claude/skills/`에 커밋하거나 러너 이미지에 추가하십시오.

683 

580[Claude Tag](https://claude.com/docs/claude-tag/overview) 세션을 제외하면, 자체 호스팅 환경의 세션은 기본적으로 [자동 메모리](/docs/ko/memory#auto-memory)가 꺼진 상태로 실행됩니다. 여러 세션에 걸쳐 유지되어야 하는 지침에는 러너 이미지 또는 저장소의 `CLAUDE.md`를 사용하십시오.684[Claude Tag](https://claude.com/docs/claude-tag/overview) 세션을 제외하면, 자체 호스팅 환경의 세션은 기본적으로 [자동 메모리](/docs/ko/memory#auto-memory)가 꺼진 상태로 실행됩니다. 여러 세션에 걸쳐 유지되어야 하는 지침에는 러너 이미지 또는 저장소의 `CLAUDE.md`를 사용하십시오.

581 685 

582호스트의 `~/.claude/`에 대한 러너의 스냅샷에는 `projects/` 디렉토리가 포함되지 않습니다. 자동 메모리의 기본 스토리지 위치는 이 디렉토리 아래에 있습니다. 이곳에 메모리 파일을 넣더라도 러너는 이를 세션으로 시드하지 않으며, 해당 파일로 자동 메모리가 켜지지도 않습니다.686호스트의 `~/.claude/`에 대한 러너의 스냅샷에는 `projects/` 디렉토리가 포함되지 않습니다. 자동 메모리의 기본 스토리지 위치는 이 디렉토리 아래에 있습니다. 이곳에 메모리 파일을 넣더라도 러너는 이를 세션으로 시드하지 않으며, 해당 파일로 자동 메모리가 켜지지도 않습니다.

20 20 

21* **임시 세션별 컨테이너**: `--capacity 1`과 기본값 `--drain-grace-sec 0`을 사용하여 각 러너 프로세스를 프로세스가 종료될 때 삭제되는 새로운 컨테이너 또는 VM에서 실행하므로 각 컨테이너는 정확히 하나의 세션을 제공합니다. 더 높은 용량이거나 양수 드레인 유예가 있으면 하나의 컨테이너가 동일한 [잠긴 소유자](/docs/ko/self-hosted-environments#key-concepts)의 여러 세션을 제공합니다. [러너 수명 주기](/docs/ko/self-hosted-environments#runner-lifecycle)를 참조하세요. 러너 재시작 간에 파일 시스템을 재사용하지 마세요. 의도적인 [사전 준비된 체크아웃](#reuse-a-pre-warmed-checkout) 설정을 제외하고, 소유자 간에는 절대 재사용하지 마세요.21* **임시 세션별 컨테이너**: `--capacity 1`과 기본값 `--drain-grace-sec 0`을 사용하여 각 러너 프로세스를 프로세스가 종료될 때 삭제되는 새로운 컨테이너 또는 VM에서 실행하므로 각 컨테이너는 정확히 하나의 세션을 제공합니다. 더 높은 용량이거나 양수 드레인 유예가 있으면 하나의 컨테이너가 동일한 [잠긴 소유자](/docs/ko/self-hosted-environments#key-concepts)의 여러 세션을 제공합니다. [러너 수명 주기](/docs/ko/self-hosted-environments#runner-lifecycle)를 참조하세요. 러너 재시작 간에 파일 시스템을 재사용하지 마세요. 의도적인 [사전 준비된 체크아웃](#reuse-a-pre-warmed-checkout) 설정을 제외하고, 소유자 간에는 절대 재사용하지 마세요.

22 * <span id="processes-a-stopped-session-leaves" />러너가 세션을 중지할 때, 셸 명령이 종료된 후에도 계속 실행 중인 프로세스(예: 데몬화된 서비스)에는 신호를 보내지 않습니다. 컨테이너 또는 VM을 삭제하면 해당 프로세스가 종료됩니다.22 * <span id="processes-a-stopped-session-leaves" />러너가 세션을 중지할 때, 셸 명령이 종료된 후에도 계속 실행 중인 프로세스(예: 데몬화된 서비스)에는 신호를 보내지 않습니다. 컨테이너 또는 VM을 삭제하면 해당 프로세스가 종료됩니다.

23* **이미지에 광범위한 자격증명 없음**: 장기 SSH 키, 클라우드 공급자 자격증명, 또는 세션이 필요한 것보다 더 많은 권한을 부여하는 개인 액세스 토큰을 포함하지 마세요. 세션 중에 사용되는 자격증명(예: 푸시 또는 API 토큰)을 [래퍼 스크립트](/docs/ko/self-hosted-environments-configuration#wrapper-scripts)에서 세션별로 발급하세요. 래퍼가 실행되기 전에 발생하는 초기 클론의 경우 [`checkout` 수명 주기 훅](/docs/ko/self-hosted-environments-configuration#checkout) 또는 [`--use-anthropic-git-proxy`](#use-the-anthropic-git-proxy)를 사용하세요. [git 구성](#configure-git)을 참조하세요.23* **이미지에 광범위한 자격 증명 없음**: 장기 SSH 키, 클라우드 공급자 자격 증명, 또는 세션이 필요한 것보다 더 많은 권한을 부여하는 개인 액세스 토큰을 포함하지 마세요. 세션 중에 사용되는 자격 증명(예: 푸시 또는 API 토큰)을 [래퍼 스크립트](/docs/ko/self-hosted-environments-configuration#wrapper-scripts)에서 세션별로 발급하세요. 초기 클론은 래퍼가 실행되기 전에 발생하므로 [`checkout` 수명 주기 훅](/docs/ko/self-hosted-environments-configuration#checkout)으로 처리하거나, 세션의 모든 저장소가 github.com에 있는 경우 [`--use-anthropic-git-proxy`](#use-the-anthropic-git-proxy)로 처리하세요. 두 가지 모두 [git 구성](#configure-git)을 참조하세요.

24* **호스트의 GitHub 자격 증명을 세션에서 분리**: Claude는 세션이 읽을 수 있는 모든 GitHub 자격 증명을 해당 자격 증명이 부여하는 모든 액세스 권한으로 사용할 수 있습니다. 러너 호스트 자체의 광범위한 범위를 가진 GitHub 자격 증명을 세션이 읽을 수 있는 곳에 두지 마세요. 이러한 자격 증명은 개인 액세스 토큰, `gh auth login`이 계정에 대해 저장하는 토큰, 또는 러너 환경의 `GH_TOKEN`일 수 있습니다.

25 * **[Anthropic 관리형 git](#use-the-anthropic-git-proxy) 사용 시**: 이러한 자격 증명이 있으면 Claude는 Anthropic 관리형 git을 거치지 않고 GitHub에 직접 접근합니다.

26 * **Anthropic 관리형 git 미사용 시**: [이미지에 git 구성 포함](#ship-git-config-in-your-image)에서 설명하는 만큼 범위를 엄격하게 제한하면 클론 자격 증명을 이미지에 유지할 수 있습니다.

24* **세션 실행 호스트에서 환경 시크릿 유지**: 환경 시크릿은 러너를 등록하고 환경에 대기 중인 모든 세션을 선택할 수 있습니다. 고정 플릿에서는 모든 러너 호스트에 있으며, 모든 세션의 코드가 시크릿 파일을 읽을 수 있습니다. [온디맨드 러너](/docs/ko/self-hosted-environments-configuration#on-demand-runners)를 선호하세요. 여기서 시크릿은 사용자 코드를 실행하지 않는 오케스트레이터 호스트에 유지되며, 각 러너는 정확히 하나의 러너를 등록하는 단일 사용 작업 주문을 받습니다. 고정 플릿에서는 환경 시크릿 파일을 모든 세션이 읽을 수 있는 것으로 취급하고 의심되는 세션 손상 후 시크릿을 회전하세요.27* **세션 실행 호스트에서 환경 시크릿 유지**: 환경 시크릿은 러너를 등록하고 환경에 대기 중인 모든 세션을 선택할 수 있습니다. 고정 플릿에서는 모든 러너 호스트에 있으며, 모든 세션의 코드가 시크릿 파일을 읽을 수 있습니다. [온디맨드 러너](/docs/ko/self-hosted-environments-configuration#on-demand-runners)를 선호하세요. 여기서 시크릿은 사용자 코드를 실행하지 않는 오케스트레이터 호스트에 유지되며, 각 러너는 정확히 하나의 러너를 등록하는 단일 사용 작업 주문을 받습니다. 고정 플릿에서는 환경 시크릿 파일을 모든 세션이 읽을 수 있는 것으로 취급하고 의심되는 세션 손상 후 시크릿을 회전하세요.

25* **기본 거부 네트워크 이그레스**: 모든 환경에서 네트워크 경계에서 러너 및 세션 컨테이너 아웃바운드 트래픽을 제한하세요. [기본 거부 이그레스](#default-deny-egress)에서 허용할 항목과 이유를 다룹니다.28* **기본 거부 네트워크 이그레스**: 모든 환경에서 네트워크 경계에서 러너 및 세션 컨테이너 아웃바운드 트래픽을 제한하세요. [기본 거부 이그레스](#default-deny-egress)에서 허용할 항목과 이유를 다룹니다.

26* **최소 권한 호스트 IAM**: 러너 호스트에 연결된 컴퓨팅 ID(예: 인스턴스 프로필 또는 노드 서비스 계정)는 러너 자체가 필요한 것만 부여해야 합니다. 세션은 호스트의 ID를 상속하는 대신 래퍼 스크립트를 통해 자신의 자격증명을 얻어야 합니다.29* **최소 권한 호스트 IAM**: 러너 호스트에 연결된 컴퓨팅 ID(예: 인스턴스 프로필 또는 노드 서비스 계정)는 러너 자체가 필요한 것만 부여해야 합니다. 세션은 호스트의 ID를 상속하는 대신 래퍼 스크립트를 통해 자신의 자격증명을 얻어야 합니다.

42 가드는 [`--trust-workspace`](/docs/ko/self-hosted-environments-reference#runner-cli-flags)와 관계없이 실행되며, 리포지토리 훅, `.mcp.json`, 또는 Bash 규칙을 다루지 않습니다. [권한 및 도구 승인](/docs/ko/self-hosted-environments-configuration#permissions-and-tool-approval)에서 이러한 권한이 어디에 속하는지 참조하세요.45 가드는 [`--trust-workspace`](/docs/ko/self-hosted-environments-reference#runner-cli-flags)와 관계없이 실행되며, 리포지토리 훅, `.mcp.json`, 또는 Bash 규칙을 다루지 않습니다. [권한 및 도구 승인](/docs/ko/self-hosted-environments-configuration#permissions-and-tool-approval)에서 이러한 권한이 어디에 속하는지 참조하세요.

43 46 

44<Note>47<Note>

45 조직의 IP 허용 목록은 기본적으로 자체 호스팅 러너 트래픽을 다루지 않습니다. 러너 또는 세션 트래픽에 대한 네트워크 제어로 의존하지 마세요. 대신 자신의 네트워크 경계에서 기본 거부 이그레스를 적용하고, 조직에 대한 IP 허용 목록 적용을 원하면 Anthropic 계정 팀에 문의하세요.48 조직에 [IP 허용 목록](https://support.claude.com/en/articles/13200993-restrict-access-to-claude-with-ip-allowlisting)이 활성화되어 있으면 러너와 세션 컨테이너를 시작하기 전에 해당 공개 이그레스 주소를 허용 목록에 추가하세요. [온디맨드 러너](/docs/ko/self-hosted-environments-configuration#on-demand-runners)를 실행하는 경우 오케스트레이터 호스트의 주소도 추가하세요. 러너 또는 세션 트래픽에 대한 네트워크 제어로 허용 목록에 의존하지 마세요. 대신 자체 네트워크 경계에서 기본 거부 이그레스를 적용하세요.

46</Note>49</Note>

47 50 

48<h2 id="network-requirements">51<h2 id="network-requirements">

55 58 

56| 호스트 | 포트 | 사용 목적 |59| 호스트 | 포트 | 사용 목적 |

57| :- | :- | :- |60| :- | :- | :- |

58| `api.anthropic.com` | 443, HTTPS; SCM 커넥터만 WSS | 러너 제어 평면 및 세션 스트리밍, 모델 추론, 기능 플래그, 제품 분석, [JWKS](/docs/ko/self-hosted-environments-identity) 키 가져오기, 커밋 서명, `--use-anthropic-git-proxy`가 설정되었을 때 git 프록시, `--scm-connector-host`가 설정되었을 때 오케스트레이터의 [SCM 커넥터](/docs/ko/self-hosted-environments-reference#scm-connector-flags) 터널 |61| `api.anthropic.com` | 443, HTTPS; [Anthropic 관리 git](#use-the-anthropic-git-proxy)의 경우 WSS | 러너 제어 평면 및 세션 스트리밍, 모델 추론, 기능 플래그, 제품 분석, [JWKS](/docs/ko/self-hosted-environments-identity) 키 가져오기, 커밋 서명, `--use-anthropic-git-proxy`가 설정되었을 때 Anthropic 관리 git |

59| `github.com` 또는 GitHub Enterprise 호스트와 같은 git 호스트 | 443 또는 22 | 리포지토리 클론 및 푸시. 러너가 `--use-anthropic-git-proxy`를 사용하는 경우 필요하지 않습니다. 이는 git 트래픽을 `api.anthropic.com`을 통해 라우팅합니다. |62| `github.com` 또는 GitHub Enterprise 호스트와 같은 git 호스트 | 443 또는 22 | 러너의 세션이 사용하는 각 git 호스트에서 저장소 클론 및 푸시. [`--use-anthropic-git-proxy`](#use-the-anthropic-git-proxy)를 사용하는 러너의 경우 [`github.com` 경로가 여전히 필요한 경우](#github-com-egress-with-the-anthropic-git-proxy)를 참조하세요. |

63 

64<span id="github-com-egress-with-the-anthropic-git-proxy" />[`--use-anthropic-git-proxy`](#use-the-anthropic-git-proxy)를 사용하는 러너는 `github.com` git 트래픽을 `api.anthropic.com`을 통해 라우팅하므로 `github.com`에 대한 git 호스트 경로가 필요하지 않습니다. 다만 `--push-outcome-on-release`를 설정하거나 `post-session` 훅에서 푸시하는 경우에는 여전히 해당 경로가 필요합니다.

60 65 

61이러한 호스트가 필요한지 여부는 구성에 따라 다릅니다:66이러한 호스트가 필요한지 여부는 구성에 따라 다릅니다:

62 67 

71| `browser-intake-us5-datadoghq.com` | 443 | Anthropic 오류 보고서 업로드, [오류 보고](/docs/ko/data-usage#telemetry-services)가 세션의 계정에 대해 활성화되었을 때만 전송됩니다. `DISABLE_ERROR_REPORTING=1` 또는 `DISABLE_TELEMETRY=1`로 억제됩니다. |76| `browser-intake-us5-datadoghq.com` | 443 | Anthropic 오류 보고서 업로드, [오류 보고](/docs/ko/data-usage#telemetry-services)가 세션의 계정에 대해 활성화되었을 때만 전송됩니다. `DISABLE_ERROR_REPORTING=1` 또는 `DISABLE_TELEMETRY=1`로 억제됩니다. |

72| `bedrock-runtime.us-east-1.amazonaws.com` 또는 `aiplatform.googleapis.com`과 같이 모델 요청, 모델 조회, 자격 증명 갱신에 사용되는 클라우드 제공업체의 엔드포인트 | 443 | 러너가 [Amazon Bedrock 또는 Google Cloud의 Agent Platform으로 모델 요청을 보내는](/docs/ko/self-hosted-environments-configuration#send-model-requests-to-bedrock-or-agent-platform) 경우에만 |77| `bedrock-runtime.us-east-1.amazonaws.com` 또는 `aiplatform.googleapis.com`과 같이 모델 요청, 모델 조회, 자격 증명 갱신에 사용되는 클라우드 제공업체의 엔드포인트 | 443 | 러너가 [Amazon Bedrock 또는 Google Cloud의 Agent Platform으로 모델 요청을 보내는](/docs/ko/self-hosted-environments-configuration#send-model-requests-to-bedrock-or-agent-platform) 경우에만 |

73 78 

74러너는 `statsig.anthropic.com`, `*.sentry.io`, `claude.ai`, 또는 `platform.claude.com`에 도달하지 않습니다. 이러한 호스트는 일부 이전 엔터프라이즈 네트워크 체크리스트에 나타나지만, 러너 또는 세션 트래픽에 대해 허용 목록에 추가할 필요가 없습니다: 기능 플래그 가져오기는 `api.anthropic.com`으로 이동하고, 러너는 대화형 OAuth가 아닌 환경 시크릿으로 인증합니다. 두 호스트 측 흐름은 `claude.ai`에 도달하므로 세션 컨테이너 이그레스를 넓히는 대신 이그레스를 허용하는 호스트에서 실행하세요: 한 줄 설치 프로그램은 설치 시간에 `claude.ai`에서 `install.sh`를 가져오고, 대화형 `claude auth login`은 [안내 설정](/docs/ko/self-hosted-environments-quickstart#set-up-an-environment-and-runner), `doctor`의 서명된 모드, 및 [CI 전달](/docs/ko/self-hosted-environments-testing#authenticate-from-ci)이 사용하며, `claude.ai`, `claude.com`, 및 `platform.claude.com`을 통해 서명합니다. `mcp-proxy.anthropic.com`도 필요하지 않습니다: 자체 호스팅 세션은 이를 사용하지 않으며, 조직의 claude.ai 커넥터를 세션에 전달하는 것(조직에 대해 활성화된 경우)은 `api.anthropic.com`을 통해 라우팅됩니다. [MCP 서버](/docs/ko/self-hosted-environments-configuration#mcp-servers)를 참조하세요.79다음 호스트는 러너 또는 세션 트래픽에 대해 허용 목록에 추가할 필요가 없습니다:

80 

81* **`statsig.anthropic.com`, `*.sentry.io`, `claude.ai`, `platform.claude.com`**: 이러한 호스트는 일부 이전 엔터프라이즈 네트워크 체크리스트에 나타나지만, 러너는 이에 도달하지 않습니다. 기능 플래그 가져오기는 `api.anthropic.com`으로 이동하고, 러너는 대화형 OAuth가 아닌 환경 시크릿으로 인증합니다.

82* **`mcp-proxy.anthropic.com`**: 자체 호스팅 세션은 이를 사용하지 않습니다. 조직에 커넥터 전달이 활성화된 경우 조직의 claude.ai 커넥터는 `api.anthropic.com`을 통해 세션에 도달합니다. [MCP 서버](/docs/ko/self-hosted-environments-configuration#mcp-servers)를 참조하세요.

83 

84다음 호스트 측 흐름은 `claude.ai`에 도달하므로 세션 컨테이너 이그레스를 넓히는 대신 이그레스를 허용하는 호스트에서 실행하세요:

85 

86* **한 줄 설치 프로그램**: 설치 시간에 `claude.ai`에서 `install.sh`를 가져옵니다.

87* **대화형 `claude auth login`**: `claude.ai`, `claude.com`, `platform.claude.com`을 통해 로그인합니다. [안내 설정](/docs/ko/self-hosted-environments-quickstart#run-the-guided-setup), `doctor`의 로그인 모드, [CI 전달](/docs/ko/self-hosted-environments-testing#authenticate-from-ci)이 이를 사용합니다. 로그인에 사용하는 브라우저는 `hcaptcha.com`, `*.hcaptcha.com`, `challenges.cloudflare.com`에서 claude.ai 로그인 페이지의 브라우저 검사도 로드합니다.

75 88 

76<h3 id="default-deny-egress">89<h3 id="default-deny-egress">

77 기본 거부 이그레스90 기본 거부 이그레스

127* **러너가 git을 구성하도록 허용**: `--configure-git`으로 러너를 시작하여 Anthropic 호스팅 세션이 사용하는 동일한 ID 및 커밋 서명 구성을 작성하도록 합니다.140* **러너가 git을 구성하도록 허용**: `--configure-git`으로 러너를 시작하여 Anthropic 호스팅 세션이 사용하는 동일한 ID 및 커밋 서명 구성을 작성하도록 합니다.

128* **이미지에 git 구성 제공**: ID 및 푸시 자격증명을 직접 설정하세요(예: 자신의 봇 ID로 커밋하기 위해).141* **이미지에 git 구성 제공**: ID 및 푸시 자격증명을 직접 설정하세요(예: 자신의 봇 ID로 커밋하기 위해).

129 142 

143github.com의 저장소라면 [`--use-anthropic-git-proxy`](#use-the-anthropic-git-proxy)로 러너를 시작하거나 `CLAUDE_RUNNER_USE_GIT_PROXY=1`을 설정하여 러너의 세션에 대한 git을 Anthropic이 제공하도록 요청할 수도 있습니다.

144 

130러너 호스트의 Git 버전 하한: [`--configure-git`](#let-the-runner-configure-git) SSH 커밋 서명에는 Git 2.34 이상이 필요하고, [`--use-anthropic-git-proxy`](#use-the-anthropic-git-proxy)에는 2.32 이상이 필요하며, [`--push-outcome-on-release`](/docs/ko/self-hosted-environments-reference#runner-cli-flags)로 푸시된 분기에서 세션을 재개하려면 2.29 이상이 필요합니다. 세 가지를 모두 생략하고 git ID를 직접 관리하면 Git 2.24로 충분합니다.145러너 호스트의 Git 버전 하한: [`--configure-git`](#let-the-runner-configure-git) SSH 커밋 서명에는 Git 2.34 이상이 필요하고, [`--use-anthropic-git-proxy`](#use-the-anthropic-git-proxy)에는 2.32 이상이 필요하며, [`--push-outcome-on-release`](/docs/ko/self-hosted-environments-reference#runner-cli-flags)로 푸시된 분기에서 세션을 재개하려면 2.29 이상이 필요합니다. 세 가지를 모두 생략하고 git ID를 직접 관리하면 Git 2.24로 충분합니다.

131 146 

132<h3 id="let-the-runner-configure-git">147<h3 id="let-the-runner-configure-git">

138* `user.name = Claude` 및 `user.email = noreply@anthropic.com`, Anthropic 호스팅 세션과 일치153* `user.name = Claude` 및 `user.email = noreply@anthropic.com`, Anthropic 호스팅 세션과 일치

139* SSH 형식 커밋 및 태그 서명, 러너 관리 shim을 통해 라우팅되어 세션의 자신의 자격증명을 사용하여 Anthropic의 서명 서비스를 통해 각 커밋에 서명합니다. 서명은 Anthropic의 게시된 SSH 서명 키에 대해 GitHub에서 확인할 수 있습니다.154* SSH 형식 커밋 및 태그 서명, 러너 관리 shim을 통해 라우팅되어 세션의 자신의 자격증명을 사용하여 Anthropic의 서명 서비스를 통해 각 커밋에 서명합니다. 서명은 Anthropic의 게시된 SSH 서명 키에 대해 GitHub에서 확인할 수 있습니다.

140* `push.negotiate = true`, git이 푸시를 패킹하기 전에 git 호스트에 이미 가지고 있는 커밋을 요청하도록 합니다. Claude Code v2.1.257 이상이 필요합니다.155* `push.negotiate = true`, git이 푸시를 패킹하기 전에 git 호스트에 이미 가지고 있는 커밋을 요청하도록 합니다. Claude Code v2.1.257 이상이 필요합니다.

141* `core.hooksPath`는 러너 관리 훅 디렉토리를 가리킵니다. 해당 `commit-msg` 및 `prepare-commit-msg` 훅은 각 커밋에 세션 작성자를 위한 `Co-authored-by:` 트레일러를 추가하며, [`CCR_SESSION_ACCOUNT_EMAIL`](/docs/ko/self-hosted-environments-configuration#wrapper-scripts)의 이메일에서 빌드되고 해당 변수가 설정되지 않으면 생략됩니다. 이미지가 이미 `core.hooksPath`를 설정한 경우 러너는 설정을 그대로 두고 이러한 훅 설치를 건너뛰며 `[runner:git]` 경고를 출력합니다.156* `core.hooksPath`는 러너 관리 훅 디렉토리를 가리킵니다. 해당 `commit-msg` 및 `prepare-commit-msg` 훅은 각 커밋에 세션 작성자를 위한 `Co-authored-by:` 트레일러를 추가합니다. 트레일러는 [`CCR_SESSION_ACCOUNT_EMAIL`](/docs/ko/self-hosted-environments-configuration#wrapper-scripts)의 이메일로 만들어지며 해당 변수가 설정되지 않으면 생략됩니다. 이미지가 이미 `core.hooksPath`를 설정했고 러너가 [Anthropic 관리 git](#use-the-anthropic-git-proxy)을 사용하지 않는 경우, 러너는 설정을 그대로 두고 이러한 훅 설치를 건너뛰며 `[runner:git]` 경고를 출력합니다.

142 157 

143커밋 서명에는 Git 2.34 이상이 필요합니다. 러너는 시작 시 확인하고 git이 더 오래되면 오류로 종료합니다. 이 플래그는 푸시 자격증명을 구성하지 않으므로 여전히 이미지에 제공합니다.158커밋 서명에는 Git 2.34 이상이 필요합니다. 러너는 시작 시 확인하고 git이 더 오래되면 오류로 종료합니다. 이 플래그는 푸시 자격증명을 구성하지 않으므로 여전히 이미지에 제공합니다.

144 159 

145v2.1.280 이상의 러너에서는 `checkout` 또는 `post-session` 수명 주기 훅에서 만드는 커밋도 `Co-authored-by:` 트레일러 없이 세션으로 서명됩니다. [수명 주기 훅 내부의 git 구성](/docs/ko/self-hosted-environments-configuration#git-configuration-inside-lifecycle-hooks)에서 러너가 해당 훅 내부에서 고정하는 git 설정을 설명합니다.160v2.1.280 이상의 러너에서는 `checkout` 또는 `post-session` 수명 주기 훅에서 만드는 커밋도 `Co-authored-by:` 트레일러 없이 세션으로 서명됩니다. [수명 주기 훅 내부의 git 구성](/docs/ko/self-hosted-environments-configuration#git-configuration-inside-lifecycle-hooks)에서 러너가 해당 훅 내부에서 고정하는 git 설정을 설명합니다.

146 161 

162`--configure-git` 사용 여부와 관계없이 Claude Code는 Claude에게 커밋 메시지 끝에 `Claude-Session: <url>` 트레일러를, 풀 리퀘스트 설명 끝에 세션의 URL을 추가하도록 지시합니다. 둘 다 생략하려면 러너 호스트의 [`~/.claude/settings.json`](/docs/ko/self-hosted-environments-configuration#how-each-session’s-config-is-assembled)에서 [`attribution.sessionUrl`](/docs/ko/settings-reference#attribution-sessionurl)을 `false`로 설정한 다음 러너를 다시 시작하세요.

163 

147<h3 id="ship-git-config-in-your-image">164<h3 id="ship-git-config-in-your-image">

148 이미지에 git 구성 제공165 이미지에 git 구성 제공

149</h3>166</h3>

186 Anthropic git 프록시 사용203 Anthropic git 프록시 사용

187</h3>204</h3>

188 205 

189`--use-anthropic-git-proxy`로 러너를 시작하거나 `CLAUDE_RUNNER_USE_GIT_PROXY=1`을 설정하여 Anthropic의 git 프록시를 통해 클론하도록 합니다. 세션의 자신의 단기 토큰으로 인증됩니다. 일반 사용자 세션의 경우 프록시는 세션 작성자를 위해 저장된 GitHub 또는 GitHub Enterprise OAuth 토큰을 사용합니다. 봇 및 에이전트 세션의 경우 조직의 GitHub App 설치 토큰을 사용합니다. 어느 쪽이든 러너 이미지는 git 자격증명이 필요하지 않습니다: SSH 키, 자격증명 헬퍼, `.netrc` 없음. 이는 Anthropic 호스팅 환경이 사용하는 동일한 인증 경로입니다.206Anthropic 관리 git이라고도 하는 Anthropic git 프록시를 사용하면 러너 이미지에는 세션 자체를 위한 SSH 키, 자격 증명 헬퍼, `.netrc` 또는 기타 git 자격 증명이 필요하지 않습니다. 대신 러너는 Anthropic에 세션의 git을 제공하도록 요청합니다. Anthropic이 제공하는 사용자 세션의 경우 러너의 클론과 세션 자체의 페치 및 푸시는 Anthropic을 거치며, Anthropic은 세션 작성자를 위해 저장된 GitHub OAuth 토큰을 사용합니다. 봇 및 에이전트 세션은 [Anthropic이 세션의 git을 제공하는 방식](#how-anthropic-serves-git-for-a-session)에서 다룹니다.

207 

208git 프록시는 [켜지](#turn-the-anthropic-git-proxy-on) 않는 한 꺼져 있습니다. 자체 자격 증명으로 git 호스트에 도달하는 러너에는 필요하지 않으며, 해당 러너의 git은 모든 git 호스트에서 작동합니다.

209 

210그 대가로 git 프록시는 러너가 지원하는 범위를 제한하고 러너에 필요한 사항을 변경합니다:

211 

212* **github.com 전용**: Anthropic은 세션의 모든 저장소가 github.com에 있는 경우에만 세션을 제공하며, git 프록시는 아직 GitHub Enterprise Server를 지원하지 않습니다. git 프록시를 사용하는 러너에서 다른 git 호스트의 저장소가 있는 세션은 [시작에 실패합니다](#when-anthropic-doesnt-serve-a-session).

213* **세션의 저장소에 대한 자격 증명만 제공**: Anthropic은 세션에 포함된 저장소에 대해서만 git 자격 증명을 제공하며, 같은 git 호스트의 다른 저장소에는 제공하지 않습니다. 비공개 서브모듈, 패키지 관리자가 git으로 가져오는 의존성, 또는 다른 저장소에 있는 플러그인 마켓플레이스는 Anthropic으로부터 자격 증명을 받지 못합니다. 세션을 만드는 사람들에게 세션을 만들 때 세션에 필요한 [모든 저장소를 추가](/docs/ko/web-quickstart#start-a-task)하도록 요청하세요.

214* **브랜치 푸시만 가능**: 브랜치를 삭제하는 푸시는 실패하며, 태그와 같은 다른 종류의 ref로의 푸시도 실패합니다. 푸시가 업데이트할 수 있는 브랜치는 [GitHub 프록시](/docs/ko/cloud-environments#github-proxy)를 참조하세요.

215* **연결된 GitHub 계정**: 사용자 세션을 만든 사람은 claude.ai에서 GitHub를 연결해야 하며, 그렇지 않으면 세션이 [시작되지 않습니다](#creator-has-no-github-connection).

216* **`--capacity 1`**: git 프록시는 러너 프로세스당 하나의 세션이 필요하므로 병렬 처리를 위해 더 많은 복제본을 실행하세요. [Anthropic git 프록시 켜기](#turn-the-anthropic-git-proxy-on)에서 요구 사항을 나열합니다.

217* **전역 git 구성 대체**: 러너는 자신이 실행되는 사용자의 [전역 git 구성을 삭제하고 대체합니다](#git-proxy-replaces-global-git-config). 전용 사용자로 또는 컨테이너에서 실행하세요.

218* **호스트 푸시를 위한 호스트 자격 증명**: 러너의 [`--push-outcome-on-release`](/docs/ko/self-hosted-environments-reference#runner-cli-flags) 푸시와 [`post-session` 훅](/docs/ko/self-hosted-environments-configuration#post-session)이 수행하는 모든 푸시는 여전히 러너 호스트 자체의 git 자격 증명과 [`github.com`으로의 네트워크 경로](#github-com-egress-with-the-anthropic-git-proxy)를 사용합니다. 해당 자격 증명은 [이미지에 git 구성 제공](#ship-git-config-in-your-image)을 참조하세요.

219* **세션별 결정**: Anthropic은 러너의 각 세션에 대해 git을 제공할지 결정하며, 제공하지 않는 세션은 시작에 실패합니다. [git 프록시를 사용하는 러너에서 세션이 시작에 실패하는 경우](#when-anthropic-doesnt-serve-a-session)에서 원인을 다룹니다.

220 

221<span id="git-proxy-replaces-global-git-config" />

222 

223<Warning>

224 `--use-anthropic-git-proxy`가 설정되면 러너는 자신이 실행되는 사용자의 전역 git 구성을 삭제하고 대체하며 백업을 보관하지 않습니다. 이 작업은 시작 시와 각 세션 전에 수행됩니다. 그곳에 보관한 로그인 또는 자격 증명 헬퍼는 사라집니다. [`--configure-git`](#let-the-runner-configure-git)이 작성하는 설정은 유지됩니다. 러너는 전용 사용자로 또는 컨테이너에서 실행하고, 절대 자신의 사용자로 실행하지 마세요.

225</Warning>

226 

227ID 및 `safe.directory`와 같이 비밀이 아닌 git 설정은 시스템 git 구성에 보관하세요.

228 

229<h4 id="turn-the-anthropic-git-proxy-on">

230 Anthropic git 프록시 켜기

231</h4>

232 

233`--use-anthropic-git-proxy`로 러너를 시작하기 전에 러너 호스트가 다음 각 요구 사항을 충족하는지 확인하세요. 용량 또는 git 요구 사항이 충족되지 않으면 러너는 시작을 거부합니다:

190 234 

191프록시는 `--capacity 1`이 필요합니다. 프록시 URL은 세션별이고 Git 2.32 이상이 필요합니다. 더 오래된 git은 프록시가 세션을 서로 격리하는 데 사용하는 구성 메커니즘을 무시합니다. 러너는 요구사항이 충족되지 않으면 시작을 거부합니다. 프록시가 Anthropic 측에서 가져오기 때문에 git 호스트는 Anthropic 인프라에서 도달할 수 있어야 합니다. 이는 Anthropic 호스팅 세션이 가진 동일한 요구사항입니다. 네트워크 내부에서만 라우팅 가능한 git 호스트의 경우 대신 [`checkout` 수명 주기 훅](/docs/ko/self-hosted-environments-configuration#checkout)을 사용하세요. 각 러너 프로세스는 한 번에 하나의 세션을 처리하므로 병렬 처리를 위해 더 많은 복제본을 실행하세요. 프록시가 활성화되면 `--git-host-rewrite` 및 `--git-ssh-rewrite`는 효과가 없습니다: 프록시 URL은 git 호스트가 아닌 `api.anthropic.com`을 가리킵니다.235* **Claude Code v2.1.267 이상**: 이전 버전은 플래그를 수락하지만 Anthropic에 git 제공 요청을 보고하거나 `Registering as opted in` 라인을 출력하지 않으므로 Anthropic은 해당 세션을 제공하지 않습니다.

236* **기본값인 `--capacity 1`**: 각 러너 프로세스는 한 번에 하나의 세션을 처리하므로 병렬 처리를 위해 더 많은 복제본을 실행하세요.

237* **Git 2.32 이상**: 더 오래된 git은 러너가 git 프록시를 위해 설정하는 세션별 git 구성을 무시합니다.

192 238 

193<Warning>239<Warning>

194 이 페이지의 [Kubernetes](#kubernetes) 및 [Docker Compose](#docker-compose) 레시피는 `--capacity 4`를 사용합니다. `--use-anthropic-git-proxy` 또는 `CLAUDE_RUNNER_USE_GIT_PROXY=1`을 용량을 `1`로 변경하지 않고 이 중 하나에 추가하면 오케스트레이터가 이를 다시 시작할 때마다 러너가 시작 시 종료됩니다. `--capacity 1`을 설정하고 병렬 처리를 위해 더 많은 복제본을 실행하세요. [러너가 종료될 때](#when-the-runner-exits)는 러너가 출력하는 라인을 보여줍니다.240 이 페이지의 [Kubernetes](#kubernetes) 및 [Docker Compose](#docker-compose) 레시피는 `--capacity 4`를 사용합니다. `--use-anthropic-git-proxy` 또는 `CLAUDE_RUNNER_USE_GIT_PROXY=1`을 용량을 `1`로 변경하지 않고 이 중 하나에 추가하면 오케스트레이터가 이를 다시 시작할 때마다 러너가 시작 시 종료됩니다. `--capacity 1`을 설정하고 병렬 처리를 위해 더 많은 복제본을 실행하세요. [러너가 종료될 때](#when-the-runner-exits)는 러너가 출력하는 라인을 보여줍니다.

195</Warning>241</Warning>

196 242 

197러너는 또한 등록할 때 Anthropic에 옵트인을 보고하며, 시작 시 `Registering as opted in to Anthropic-managed git (--use-anthropic-git-proxy)`를 출력합니다. 옵트인 보고에는 Claude Code v2.1.267 이상이 필요하며, 이전 버전은 플래그를 수락하지만 이를 보고하거나 해당 라인을 출력하지 않습니다. 옵트인된 러너의 각 세션은 Anthropic 관리 git 또는 세션별 프록시 URL을 사용합니다. 세션이 세션별 프록시 URL을 사용할 때 러너는 그렇게 하는 것을 나타내는 `[runner:warn]` 라인 하나를 기록합니다.243git 프록시를 켜려면 러너의 명령에 `--use-anthropic-git-proxy`를 추가하거나 러너의 환경에서 `CLAUDE_RUNNER_USE_GIT_PROXY=1`을 설정하세요. 러너 호스트의 셸에서 실행하는 다음 명령은 git 프록시를 켠 상태로 [빠른 시작](/docs/ko/self-hosted-environments-quickstart#set-up-manually)의 러너를 시작합니다:

244 

245```bash theme={null}

246claude self-hosted-runner --environment-secret-file '/etc/claude/environment-secret' --base-dir '<writable-dir>' --use-anthropic-git-proxy

247```

248 

249시작 시 러너는 `Registering as opted in to Anthropic-managed git (--use-anthropic-git-proxy)`를 출력합니다. 그런 다음 Anthropic은 해당 러너의 각 세션에 대해 git을 제공할지 결정합니다. 제공하는 각 세션에 대해 러너는 `governed git ACTIVE`를 포함하는 `[runner:session]` 라인을 로그에 기록합니다. 대신 세션이 시작에 실패하면 [git 프록시를 사용하는 러너에서 세션이 시작에 실패하는 경우](#when-anthropic-doesnt-serve-a-session)를 참조하세요.

250 

251<h4 id="how-anthropic-serves-git-for-a-session">

252 Anthropic이 세션의 git을 제공하는 방식

253</h4>

254 

255Anthropic이 제공하는 세션의 경우 러너의 클론과 세션 자체의 페치 및 푸시는 Anthropic을 거치며, 세션 자체의 단기 토큰으로 인증됩니다:

256 

257* **사용자 세션**: Anthropic은 세션 작성자를 위해 저장된 GitHub OAuth 토큰을 사용합니다.

258* **봇 및 에이전트 세션**: Anthropic은 조직의 GitHub App 설치 토큰을 사용합니다.

259* **URL 다시 쓰기**: `--git-host-rewrite` 및 `--git-ssh-rewrite`는 git 프록시가 제공하는 저장소에 효과가 없습니다.

260 

261<h4 id="when-anthropic-doesnt-serve-a-session">

262 git 프록시를 사용하는 러너에서 세션이 시작에 실패하는 경우

263</h4>

264 

265`--use-anthropic-git-proxy`로 시작한 러너에서는 Anthropic이 세션의 git을 제공하지 않으면 세션이 시작에 실패합니다. 러너의 로그에서 `/git_proxy/`를 포함하는 `api.anthropic.com` 주소를 언급하는 git 오류를 찾으세요.

266 

267Claude Code v2.1.267 이상의 러너는 각 세션에 대해 Anthropic이 세션의 git을 제공하는 경우 `governed git ACTIVE`를 포함하는 `[runner:session]` 라인을, 제공하지 않는 경우 `the server withheld Anthropic-managed git for this session`을 포함하는 `[runner:warn]` 라인 하나를 로그에 기록합니다. 다음 경우 중에서 보고 있는 라인을 찾으세요:

268 

269* **`governed git ACTIVE`와 `withheld` 라인 모두 없음**: Claude Code v2.1.267 이전의 러너는 두 라인 모두 기록하지 않으며, Anthropic은 해당 세션을 제공하지 않습니다. [버전 고정](#pin-the-version)에 따라 러너를 v2.1.267 이상으로 업데이트하세요.

270* **`withheld` 라인**: Anthropic이 세션을 제공하지 않았습니다. 이전에 git 프록시로 작동하던 러너도 사용자 측의 변경 없이 이런 방식으로 실패할 수 있습니다.

271 * **저장소가 github.com에 없음**: GitHub Enterprise Server와 같은 다른 git 호스트에 저장소가 하나라도 있는 세션은 해당 github.com 저장소를 포함하여 제공되지 않습니다. 해당 환경의 러너에 대해 [Anthropic git 프록시를 끄세요](#turn-the-anthropic-git-proxy-off).

272 * **모든 저장소가 github.com에 있음**: `withheld` 라인의 세션 ID와 함께 [Anthropic 계정 팀](#report-an-issue)에 실패를 보고하세요. Anthropic은 자체 측에서 이유를 기록합니다.

273* **`remote: access denied by the git proxy`를 포함하는 라인**: Anthropic이 제공하는 세션도 거부될 수 있습니다. 예를 들어 조직 정책이 세션의 git 액세스를 거부하거나 세션이 저장소에 대한 권한이 없는 경우입니다. 그러면 러너의 로그에 `remote: access denied by the git proxy`를 포함하는 라인이 표시되며, 해당 라인의 나머지 부분에 이유가 나옵니다.

274* <span id="creator-has-no-github-connection" />**`GitHub authentication required`**: 세션 작성자가 claude.ai에서 작동하는 GitHub 연결이 없을 때 표시됩니다. 세션의 클론이 실패하고 git 오류는 `GitHub authentication required. Please reconnect your GitHub account.`로 표시됩니다. 해당 사용자에게 claude.ai 설정에서 GitHub를 연결하거나 다시 연결하도록 요청하세요.

275 

276원인을 해결한 후 실패한 세션을 다시 시작하세요.

277 

278<h4 id="turn-the-anthropic-git-proxy-off">

279 Anthropic git 프록시 끄기

280</h4>

281 

282환경의 세션이 GitHub Enterprise Server와 같이 github.com이 아닌 git 호스트의 저장소를 사용하는 경우 해당 환경의 러너에 대해 `--use-anthropic-git-proxy`를 끄세요.

283 

284<Steps>

285 <Step title="플래그 제거">

286 러너의 명령에서 `--use-anthropic-git-proxy`를 제거하세요. 파드 사양이나 Compose 파일과 같은 러너의 환경에서 `CLAUDE_RUNNER_USE_GIT_PROXY`를 설정한 경우 그곳에서 제거하세요. 셸에서는 설정을 해제하세요:

287 

288 ```bash theme={null}

289 unset CLAUDE_RUNNER_USE_GIT_PROXY

290 ```

291 </Step>

292 

293 <Step title="러너에 git 자격 증명 제공">

294 github.com을 포함하여 러너의 세션이 사용하는 모든 git 호스트에 대해 프롬프트 없이 작동하는 자격 증명을 제공하세요. `--use-anthropic-git-proxy`가 설정되어 있는 동안 러너가 러너 사용자의 전역 git 구성을 삭제했으므로 그곳에 있던 자격 증명은 사라졌습니다. [이미지에 자격 증명을 제공](#ship-git-config-in-your-image)하거나 [`checkout` 수명 주기 훅](/docs/ko/self-hosted-environments-configuration#checkout)을 사용하세요.

295 </Step>

296 

297 <Step title="네트워크 경로 열기">

298 러너가 러너의 세션이 사용하는 각 git 호스트에 포트 443 또는 22로 도달할 수 있도록 허용하세요. [네트워크 요구 사항](#network-requirements)의 git 호스트 행을 참조하세요.

299 </Step>

300 

301 <Step title="러너 다시 시작">

302 러너가 git 프록시 없이 등록되도록 러너를 다시 시작하세요. 그런 다음 실패한 각 세션을 다시 시작하세요.

303 </Step>

304</Steps>

198 305 

199<h4 id="github-api-access-without-the-github-cli">306<h4 id="github-api-access-without-the-github-cli">

200 GitHub CLI 없이 GitHub API 액세스307 GitHub CLI 없이 GitHub API 액세스

266```dockerfile theme={null}373```dockerfile theme={null}

267FROM debian:bookworm-slim374FROM debian:bookworm-slim

268ARG CLAUDE_CODE_VERSION375ARG CLAUDE_CODE_VERSION

269RUN apt-get update && apt-get install -y --no-install-recommends git curl ca-certificates openssh-client \376RUN apt-get update && apt-get install -y --no-install-recommends git curl ca-certificates openssh-client jq \

270 && rm -rf /var/lib/apt/lists/*377 && rm -rf /var/lib/apt/lists/*

271RUN curl -fsSL "https://downloads.claude.ai/claude-code-releases/${CLAUDE_CODE_VERSION:?set with --build-arg CLAUDE_CODE_VERSION}/linux-x64/claude" \378RUN curl -fsSL "https://downloads.claude.ai/claude-code-releases/${CLAUDE_CODE_VERSION:?set with --build-arg CLAUDE_CODE_VERSION}/linux-x64/claude" \

272 -o /usr/local/bin/claude && chmod +x /usr/local/bin/claude379 -o /usr/local/bin/claude && chmod +x /usr/local/bin/claude

382kubectl create namespace claude-runners489kubectl create namespace claude-runners

383```490```

384 491 

385관리 UI의 [**환경 키 복사** 단계](/docs/ko/self-hosted-environments-quickstart#set-up-an-environment-and-runner)에서 복사한 값을 보유하는 로컬 파일에서 지원 Secret을 생성하세요. 시크릿이 셸 기록에 나타나지 않도록 합니다. `(umask 077 && cat > ./environment-secret)`을 실행하고, 시크릿을 붙여넣고, Enter를 누른 다음 Ctrl-D를 누르세요. 그런 다음 Secret을 생성하고 파일을 삭제하세요:492관리자 UI의 [**환경 키 복사** 단계](/docs/ko/self-hosted-environments-quickstart#set-up-manually)에서 복사한 값을 보유하는 로컬 파일에서 지원 Secret을 생성하세요. 이렇게 하면 시크릿이 셸 기록에 나타나지 않습니다. `(umask 077 && cat > ./environment-secret)`을 실행하고, 시크릿을 붙여넣고, Enter를 누른 다음 Ctrl-D를 누르세요. 그런 다음 Secret을 생성하고 파일을 삭제하세요:

386 493 

387```bash theme={null}494```bash theme={null}

388kubectl create secret generic claude-runner-environment-secret -n claude-runners --from-file=environment-secret=./environment-secret495kubectl create secret generic claude-runner-environment-secret -n claude-runners --from-file=environment-secret=./environment-secret

500 사전 준비된 체크아웃 재사용607 사전 준비된 체크아웃 재사용

501</h2>608</h2>

502 609 

503대규모 리포지토리의 경우 클론이 세션 시작을 지배할 수 있습니다. `--capacity 1`에서 [`checkout` 훅](/docs/ko/self-hosted-environments-configuration#checkout) 없이 러너는 `<base-dir>/<repo-owner>/<repo>`에서 리포지토리당 하나의 정규 클론을 유지하고 세션 간에 재사용합니다: 요청된 ref를 가져오고, `HEAD`를 분리하고, 이에 대해 하드 리셋합니다. 거의 변경되지 않았을 때 거의 즉시입니다. 콜드 클론을 건너뛰려면 다음 두 가지 방법 중 하나로 클론을 제공하세요:610대규모 저장소의 경우 클론이 세션 시작 시간의 대부분을 차지할 수 있습니다. 콜드 클론을 건너뛰려면 러너가 자체 클론을 보관하는 경로에 직접 클론을 제공하세요. [`checkout` 훅](/docs/ko/self-hosted-environments-configuration#checkout)이 없으면 러너는 `<base-dir>/<repo-owner>/<repo>`에 저장소당 하나의 정규 클론을 유지하고 세션 간에 재사용합니다:

611 

612* **`--capacity 1`에서**: 러너는 요청된 ref를 가져오고, `HEAD`를 분리한 다음, 해당 ref로 하드 리셋합니다. 변경 사항이 적을 때는 거의 즉시 완료됩니다.

613* **`--capacity`가 1보다 클 때**: 러너는 해당 클론으로 가져온 다음, 각 세션마다 그 클론에서 별도의 worktree를 체크아웃합니다. 사전 준비된 클론은 다운로드 시간은 절약하지만 체크아웃 시간은 절약하지 않습니다.

614 

615클론은 이미지 또는 영구 볼륨에 제공합니다:

504 616 

505* **이미지에 클론**: 러너 이미지를 해당 경로에 빌드합니다. 모든 새로운 컨테이너는 디스크를 재사용하지 않고 준비된 클론으로 시작합니다.617* **이미지에 클론**: 러너 이미지를 해당 경로에 빌드합니다. 모든 새로운 컨테이너는 디스크를 재사용하지 않고 준비된 클론으로 시작합니다.

506* **지속적인 볼륨에 클론**: [`--lock-to-account`](/docs/ko/self-hosted-environments-reference#runner-cli-flags)로 한 사용자의 계정에 사전 잠긴 러너에서 `--base-dir`을 지속적인 볼륨으로 가리키므로 디스크는 해당 계정만 제공합니다. 사전 잠긴 러너는 Claude Tag 채널 세션을 절대 선택하지 않으므로 이 옵션은 이들을 제공하는 러너에 적용되지 않습니다.618* **지속적인 볼륨에 클론**: [`--lock-to-account`](/docs/ko/self-hosted-environments-reference#runner-cli-flags)로 한 사용자의 계정에 사전 잠긴 러너에서 `--base-dir`을 지속적인 볼륨으로 가리키므로 디스크는 해당 계정만 제공합니다. 사전 잠긴 러너는 Claude Tag 채널 세션을 절대 선택하지 않으므로 이 옵션은 이들을 제공하는 러너에 적용되지 않습니다.

508재사용 경로가 보장하고 보장하지 않는 것:620재사용 경로가 보장하고 보장하지 않는 것:

509 621 

510* **모든 클론 형태가 작동합니다**: 경로의 전체, 얕은, 또는 단일 분기 클론은 그대로 사용됩니다. 러너는 기존 클론으로 가져올 때 `--depth`를 절대 전달하지 않으므로 전체 사전 준비는 전체 기록을 유지하고 얕은 것은 얕게 유지됩니다. `CLAUDE_RUNNER_FETCH_DEPTH`(`full`, `0`, 또는 숫자; 기본값 50)는 클론이 아직 없을 때 러너가 만드는 콜드 클론만 제어합니다.622* **모든 클론 형태가 작동합니다**: 경로의 전체, 얕은, 또는 단일 분기 클론은 그대로 사용됩니다. 러너는 기존 클론으로 가져올 때 `--depth`를 절대 전달하지 않으므로 전체 사전 준비는 전체 기록을 유지하고 얕은 것은 얕게 유지됩니다. `CLAUDE_RUNNER_FETCH_DEPTH`(`full`, `0`, 또는 숫자; 기본값 50)는 클론이 아직 없을 때 러너가 만드는 콜드 클론만 제어합니다.

511* **추적된 변경 사항 리셋, 추적되지 않은 파일 유지**: 각 세션은 이전 세션의 추적된 수정을 지우는 하드 리셋에서 시작하지만 러너는 절대 `git clean`을 실행하지 않으므로 잠긴 소유자의 이전 세션의 추적되지 않은 파일은 트리에 유지됩니다.623* **추적된 변경 사항은 리셋되고, 추적되지 않은 파일은 유지됩니다**: `--capacity 1`에서 각 세션은 이전 세션의 추적된 수정 사항을 지우는 하드 리셋으로 시작하지만, 러너는 `git clean`을 실행하지 않으므로 잠금된 소유자의 이전 세션에서 생긴 추적되지 않은 파일은 트리에 남아 있습니다.

512* **세션별 디렉토리도 유지됩니다**: 체크아웃 옆에 러너는 실행하는 모든 세션에 대해 `<base-dir>/_sessions/` 아래에 세션별 항목을 생성합니다. 세션의 Claude 설정 디렉토리는 대화 기록의 로컬 복사본을 보유합니다. 그 옆에는 세션이 있을 때 세션의 업로드된 파일이 있습니다. 세션 디렉토리도 거기에 있습니다: 세션이 실행되는 동안 세션별 worktrees 및 `checkout` 훅 체크아웃을 보유하며, Claude가 그 안에 작성한 다른 모든 것을 유지합니다.624* **세션별 디렉토리도 유지됩니다**: 체크아웃 옆에 러너는 실행하는 모든 세션에 대해 `<base-dir>/_sessions/` 아래에 세션별 항목을 생성합니다. 세션의 Claude 설정 디렉토리는 대화 기록의 로컬 복사본을 보유합니다. 그 옆에는 세션이 있을 때 세션의 업로드된 파일이 있습니다. 세션 디렉토리도 거기에 있습니다: 세션이 실행되는 동안 세션별 worktrees 및 `checkout` 훅 체크아웃을 보유하며, Claude가 그 안에 작성한 다른 모든 것을 유지합니다.

513 625 

514 기본적으로 러너는 세션이 끝날 때 이들을 제자리에 두므로 러너 프로세스보다 오래 지속되는 디스크에서 누적됩니다. 모든 세션은 러너 자신의 사용자로 실행되므로 해당 디스크가 제공하는 나중의 모든 세션이 이들을 읽을 수 있습니다. 지속적인 `--base-dir`을 유지하면 해당 성장에 대해 볼륨의 크기를 조정하세요. 동일한 파일 시스템에서 러너를 다시 시작하는 모든 설정(예: [Docker Compose 레시피](#docker-compose))에도 동일하게 적용됩니다.626 기본적으로 러너는 세션이 끝날 때 이들을 제자리에 두므로 러너 프로세스보다 오래 지속되는 디스크에서 누적됩니다. 모든 세션은 러너 자신의 사용자로 실행되므로 해당 디스크가 제공하는 나중의 모든 세션이 이들을 읽을 수 있습니다. 지속적인 `--base-dir`을 유지하면 해당 성장에 대해 볼륨의 크기를 조정하세요. 동일한 파일 시스템에서 러너를 다시 시작하는 모든 설정(예: [Docker Compose 레시피](#docker-compose))에도 동일하게 적용됩니다.

522 634 

523각 세션의 자식 Claude Code 프로세스는 러너의 자신의 바이너리를 실행하고, 러너는 생성하는 세션 내에서 자동 업데이트를 끕니다. 따라서 모든 세션은 호스트에 설치하거나 이미지에 빌드한 버전을 실행합니다. 호스트 수준 업데이트는 러너가 다음 번에 시작할 때 적용됩니다.635각 세션의 자식 Claude Code 프로세스는 러너의 자신의 바이너리를 실행하고, 러너는 생성하는 세션 내에서 자동 업데이트를 끕니다. 따라서 모든 세션은 호스트에 설치하거나 이미지에 빌드한 버전을 실행합니다. 호스트 수준 업데이트는 러너가 다음 번에 시작할 때 적용됩니다.

524 636 

525세션이 사용하는 모델은 실행 중인 Claude Code 버전보다 최신 Claude Code 버전이 필요할 수 있습니다. 그러면 서버는 해당 모델에 대한 요청을 [Claude Code does not support this model](/docs/ko/errors#claude-code-does-not-support-this-model)로 거부합니다. 버전을 고정하기 전에 세션이 사용하는 모든 모델에 대해 [모델이 필요로 하는 Claude Code 버전](/docs/ko/model-config#available-models)을 확인하세요.637세션이 실행할 버전과 버전이 변경되는 시점을 선택합니다.

526 638 

639* **버전을 고정하기 전에**: 세션이 사용하는 모든 모델에 대해 [모델이 필요로 하는 Claude Code 버전](/docs/ko/model-config#available-models)을 확인하세요. 모델이 세션에서 실행 중인 버전보다 최신 버전을 필요로 하는 경우, 서버는 해당 모델에 대한 요청을 [Claude Code does not support this model](/docs/ko/errors#claude-code-does-not-support-this-model)로 거부합니다.

527* **플릿을 한 버전으로 유지하려면**: 이미지를 고정된 버전으로 빌드하거나 베어 호스트에 특정 버전을 설치하고 [자동 업데이트를 비활성화](/docs/ko/setup#disable-auto-updates)하세요.640* **플릿을 한 버전으로 유지하려면**: 이미지를 고정된 버전으로 빌드하거나 베어 호스트에 특정 버전을 설치하고 [자동 업데이트를 비활성화](/docs/ko/setup#disable-auto-updates)하세요.

528* **업그레이드하려면**: 새로운 버전을 설치하거나 이미지를 다시 빌드한 다음 러너를 재시작하세요.641* **고정 플릿을 업그레이드하려면**: 현재 버전과 설치할 버전 사이의 [변경 로그](/docs/en/changelog) 항목을 읽은 다음, 새로운 버전을 설치하거나 이미지를 다시 빌드하고 러너를 재시작하세요.

642* **온디맨드 러너를 업그레이드하려면**: 현재 버전과 설치할 버전 사이의 [변경 로그](/docs/en/changelog) 항목을 읽은 다음, [`spawn-runner` 훅](/docs/ko/self-hosted-environments-configuration#the-spawn-runner-hook)이 시작하는 이미지를 변경하세요. 새로 생성되는 각 러너는 새 버전을 받습니다. [`--min-idle`](/docs/ko/self-hosted-environments-reference#orchestrator-cli-flags)이 시작한 대기 러너를 포함하여 이미 실행 중인 러너는 종료될 때까지 기존 버전을 유지합니다. 해당 러너의 작업 지시는 일회용이므로 재시작하지 마세요.

529* **플러그인**: 플러그인 마켓플레이스도 자동 업데이트되지 않습니다. 바이너리가 고정된 상태로 유지되는 동안 플러그인이 자동 업데이트되도록 하려면 러너의 환경에서 `FORCE_AUTOUPDATE_PLUGINS=1`을 설정하세요.643* **플러그인**: 플러그인 마켓플레이스도 자동 업데이트되지 않습니다. 바이너리가 고정된 상태로 유지되는 동안 플러그인이 자동 업데이트되도록 하려면 러너의 환경에서 `FORCE_AUTOUPDATE_PLUGINS=1`을 설정하세요.

530 644 

531<h2 id="scale-the-fleet">645<h2 id="scale-the-fleet">

580</h3>694</h3>

581 695 

582* **재개된 세션이 푸시되지 않은 작업을 손실함**: 새로운 러너는 저장소를 시작 브랜치에서 다시 클론하므로, 세션이 푸시하지 않은 작업은 손실됩니다.696* **재개된 세션이 푸시되지 않은 작업을 손실함**: 새로운 러너는 저장소를 시작 브랜치에서 다시 클론하므로, 세션이 푸시하지 않은 작업은 손실됩니다.

583 * **커밋된 작업을 보존하려면**: [`--push-outcome-on-release`](/docs/ko/self-hosted-environments-reference#runner-cli-flags)를 설정합니다. 그러면 러너는 해제하기 전에 세션의 결과 브랜치를 최선의 노력으로 푸시하며, 재개된 세션은 해당 커밋에서 시작됩니다. 커밋되지 않은 변경 사항은 여전히 손실됩니다.697 * **커밋된 작업을 보존하려면**: 환경의 모든 러너에 [`--push-outcome-on-release`](/docs/ko/self-hosted-environments-reference#runner-cli-flags)를 설정합니다. 플래그가 없는 러너는 세션을 시작 브랜치에서 재개하기 때문입니다. 플래그가 있는 러너는 해제하기 전에 세션의 결과 브랜치를 최선의 노력으로 푸시하며, 재개된 세션은 해당 커밋에서 시작됩니다. 푸시에는 [Anthropic 관리 git](#use-the-anthropic-git-proxy)을 사용하는 러너를 포함하여 러너 호스트 자체의 git 자격 증명이 사용됩니다. 커밋되지 않은 변경 사항은 여전히 손실됩니다.

698 * **`checkout` 훅을 사용하는 경우**: [`checkout` 라이프사이클 훅](/docs/ko/self-hosted-environments-configuration#checkout)을 통해 체크아웃된 저장소는 푸시되지 않습니다. 대신 [`post-session` 훅](/docs/ko/self-hosted-environments-configuration#post-session)에서 해당 저장소의 스냅샷을 만듭니다.

584 * **플래그를 활성화하기 전에**: 소스 원격의 `claude/*` refs에 푸시할 수 있는 사람을 제한합니다. 재개 시 러너는 이전에 푸시된 브랜치를 누가 푸시했는지 확인하지 않고 가져옵니다.699 * **플래그를 활성화하기 전에**: 소스 원격의 `claude/*` refs에 푸시할 수 있는 사람을 제한합니다. 재개 시 러너는 이전에 푸시된 브랜치를 누가 푸시했는지 확인하지 않고 가져옵니다.

585* **세션 중간에 추가한 저장소는 클론에 실패할 수 있음**: Claude는 HTTPS를 통해 `git clone`으로 저장소를 클론합니다. [`--use-anthropic-git-proxy`](#use-the-anthropic-git-proxy)가 없는 러너에서는 호스트에서 해당 저장소를 읽을 수 있는 수단이 없으면 git 인증 오류로 클론이 실패합니다. 가능하면 세션을 만들 때 세션에 필요한 모든 저장소를 선택합니다.700* **세션 중간에 추가한 저장소는 클론에 실패할 수 있음**: Claude는 HTTPS를 통해 `git clone`으로 저장소를 클론합니다. [`--use-anthropic-git-proxy`](#use-the-anthropic-git-proxy)가 없는 러너에서는 호스트에서 해당 저장소를 읽을 수 있는 수단이 없으면 git 인증 오류로 클론이 실패합니다. 가능하면 세션을 만들 때 세션에 필요한 모든 저장소를 선택합니다.

586* **일부 커넥터는 자체 호스팅 세션에 나타나지 않음**: claude.ai 설정에서 아직 연결하지 않은 커넥터는 자체 호스팅 세션에 나열되지 않으며, 세션은 연결하라는 메시지를 표시하지 않습니다. 먼저 설정에서 연결한 후 새로운 세션을 시작합니다. 이미 실행 중인 세션에 커넥터를 추가해도 Claude에서 해당 도구를 사용할 수 없습니다. 새로 추가된 커넥터를 선택하려면 새로운 세션을 시작합니다.701* **일부 커넥터는 자체 호스팅 세션에 나타나지 않음**: claude.ai 설정에서 아직 연결하지 않은 커넥터는 자체 호스팅 세션에 나열되지 않으며, 세션은 연결하라는 메시지를 표시하지 않습니다. 먼저 설정에서 연결한 후 새로운 세션을 시작합니다. 이미 실행 중인 세션에 커넥터를 추가해도 Claude에서 해당 도구를 사용할 수 없습니다. 새로 추가된 커넥터를 선택하려면 새로운 세션을 시작합니다.

606* **러너가 환경에 나타나지 않음**: 호스트가 HTTPS를 통해 `api.anthropic.com`에 도달할 수 있는지, 환경 시크릿이 현재인지, 호스트 시계가 실제 시간의 5분 이내인지 확인하세요. 더 큰 스큐는 인증 실패를 유발합니다. 러너는 인증 실패 시 거부 이유와 함께 `[runner:fatal]`을 기록합니다.721* **러너가 환경에 나타나지 않음**: 호스트가 HTTPS를 통해 `api.anthropic.com`에 도달할 수 있는지, 환경 시크릿이 현재인지, 호스트 시계가 실제 시간의 5분 이내인지 확인하세요. 더 큰 스큐는 인증 실패를 유발합니다. 러너는 인증 실패 시 거부 이유와 함께 `[runner:fatal]`을 기록합니다.

607* **러너가 `cannot create or write to base directory`로 시작 시 종료됨**: 러너가 `--base-dir`을 생성하거나 쓸 수 없습니다. 기본값은 `/workspace`입니다. 디렉토리의 소유권을 수정하거나 `--base-dir`을 쓰기 가능한 경로로 가리키세요. [기본 디렉토리 및 용량을 러너 간에 동일하게 유지](#keep-the-base-directory-and-capacity-identical-across-runners)에서 설명합니다. 러너가 대신 기본 디렉토리 확인이 시간 초과되었다고 `[runner:fatal]`을 기록하면 디렉토리는 행(hung) NFS 또는 CSI 마운트에 있습니다. 권한이 아닌 마운트 상태를 확인하세요. 러너는 `--log-file`을 열기 전에 이러한 시작 실패를 stderr에 인쇄하므로 로그 파일이 아닌 터미널 또는 플랫폼의 컨테이너 로그에서 찾으세요. v2.1.225 이전에 러너는 시작 시 기본 디렉토리를 확인하지 않았으며, 이 잘못된 구성은 대신 선택 후 세션에 실패했습니다.722* **러너가 `cannot create or write to base directory`로 시작 시 종료됨**: 러너가 `--base-dir`을 생성하거나 쓸 수 없습니다. 기본값은 `/workspace`입니다. 디렉토리의 소유권을 수정하거나 `--base-dir`을 쓰기 가능한 경로로 가리키세요. [기본 디렉토리 및 용량을 러너 간에 동일하게 유지](#keep-the-base-directory-and-capacity-identical-across-runners)에서 설명합니다. 러너가 대신 기본 디렉토리 확인이 시간 초과되었다고 `[runner:fatal]`을 기록하면 디렉토리는 행(hung) NFS 또는 CSI 마운트에 있습니다. 권한이 아닌 마운트 상태를 확인하세요. 러너는 `--log-file`을 열기 전에 이러한 시작 실패를 stderr에 인쇄하므로 로그 파일이 아닌 터미널 또는 플랫폼의 컨테이너 로그에서 찾으세요. v2.1.225 이전에 러너는 시작 시 기본 디렉토리를 확인하지 않았으며, 이 잘못된 구성은 대신 선택 후 세션에 실패했습니다.

608* **세션이 대기 중 상태로 유지됨**: 모든 온라인 러너는 다른 소유자로 잠길 수 있습니다. 각 러너의 `claude_code_self_hosted_runner_locked_account` [메트릭](/docs/ko/self-hosted-environments-reference#prometheus-metrics) 또는 `[runner:health]` 로그 라인의 `locked_account` 필드를 확인하여 누가 보유하는지 확인하세요. 둘 다 러너가 `act.email` 클레임을 전달하는 세션 토큰을 발급받은 후에만 소유자의 이메일을 표시합니다. Claude Tag 에이전트의 세션은 절대 이를 수행하지 않습니다. 클레임 없이 러너는 `locked_account` 시리즈를 내보내지 않으며 `locked_account=yes`를 기록합니다. 이는 러너가 잠겨 있지만 어느 소유자에게 잠겨 있는지 알려줍니다. 복제본을 추가하거나 기존 러너가 드레인되고 재시작될 때까지 기다리세요. 환경이 온디맨드 러너를 사용하면 대신 오케스트레이터를 확인하세요. [온디맨드 러너](/docs/ko/self-hosted-environments-configuration#on-demand-runners)를 참조하세요.723* **세션이 대기 중 상태로 유지됨**: 모든 온라인 러너는 다른 소유자로 잠길 수 있습니다. 각 러너의 `claude_code_self_hosted_runner_locked_account` [메트릭](/docs/ko/self-hosted-environments-reference#prometheus-metrics) 또는 `[runner:health]` 로그 라인의 `locked_account` 필드를 확인하여 누가 보유하는지 확인하세요. 둘 다 러너가 `act.email` 클레임을 전달하는 세션 토큰을 발급받은 후에만 소유자의 이메일을 표시합니다. Claude Tag 에이전트의 세션은 절대 이를 수행하지 않습니다. 클레임 없이 러너는 `locked_account` 시리즈를 내보내지 않으며 `locked_account=yes`를 기록합니다. 이는 러너가 잠겨 있지만 어느 소유자에게 잠겨 있는지 알려줍니다. 복제본을 추가하거나 기존 러너가 드레인되고 재시작될 때까지 기다리세요. 환경이 온디맨드 러너를 사용하면 대신 오케스트레이터를 확인하세요. [온디맨드 러너](/docs/ko/self-hosted-environments-configuration#on-demand-runners)를 참조하세요.

609* **세션이 선택 직후 실패함**: claude.ai/code에서 세션을 열어 오류를 확인하세요. 가장 일반적인 원인은 러너 이미지의 누락된 [git 자격증명](#configure-git) 및 설치되지 않은 빌드 도구입니다. 쓰기 불가능한 기본 디렉토리는 세션 실패 대신 시작 시 러너를 중지합니다. 이 목록의 **러너가 `cannot create or write to base directory`로 시작 시 종료됨** 항목을 참조하세요.724* **세션이 선택 직후 실패함**: claude.ai/code에서 세션을 열어 오류를 확인하세요. 가장 일반적인 원인은 러너 이미지의 누락된 [git 자격 증명](#configure-git) 및 설치되지 않은 빌드 도구입니다. `--use-anthropic-git-proxy`로 시작된 러너에서는 [git 프록시를 사용하는 러너에서 세션이 시작되지 않을 때](#when-anthropic-doesnt-serve-a-session)를 참조하세요. 쓰기 불가능한 기본 디렉터리는 세션 실패 대신 시작 시 러너를 중지합니다. 이 목록의 **러너가 `cannot create or write to base directory`로 시작 시 종료됨** 항목을 참조하세요.

725* **`--use-anthropic-git-proxy`를 설정한 러너에서 세션이 시작되지 않음**: 러너의 로그에서 `access denied by the git proxy`를 찾거나, `/git_proxy/`를 포함하는 `api.anthropic.com` 주소를 명시하는 git 오류를 찾으세요. Anthropic이 세션을 처리했는지 판단하고 원인을 해결하려면 [git 프록시를 사용하는 러너에서 세션이 시작되지 않을 때](#when-anthropic-doesnt-serve-a-session)를 참조하세요.

610* **세션이 인증하는 이그레스 프록시를 통해 네트워크에 도달할 수 없음**: [`--proxy-authorization-command` 또는 `--proxy-authorization-file`](#authenticate-to-an-egress-proxy)로 설정한 소스가 실패하거나 30초 후 시간 초과되거나 빈 값을 생성하면 러너는 해당 연결에 `502 Bad Gateway`로 응답하고 이유를 기록합니다. 러너는 해당 로그에서 명령의 stderr를 수정하고 헤더 값을 절대 기록하지 않습니다. `--proxy-authorization-command`로 호스트에서 명령을 직접 실행하여 전체 헤더 값을 stdout에 인쇄하는지 확인하세요. 러너가 대신 `could not start the proxy-authorization listener`로 시작 시 종료되면 루프백 리스너를 열 수 없습니다.726* **세션이 인증하는 이그레스 프록시를 통해 네트워크에 도달할 수 없음**: [`--proxy-authorization-command` 또는 `--proxy-authorization-file`](#authenticate-to-an-egress-proxy)로 설정한 소스가 실패하거나 30초 후 시간 초과되거나 빈 값을 생성하면 러너는 해당 연결에 `502 Bad Gateway`로 응답하고 이유를 기록합니다. 러너는 해당 로그에서 명령의 stderr를 수정하고 헤더 값을 절대 기록하지 않습니다. `--proxy-authorization-command`로 호스트에서 명령을 직접 실행하여 전체 헤더 값을 stdout에 인쇄하는지 확인하세요. 러너가 대신 `could not start the proxy-authorization listener`로 시작 시 종료되면 루프백 리스너를 열 수 없습니다.

611* **러너 로그에 `rejecting the malformed poll response`를 포함하는 `Poll failed` 라인**: 러너가 큐의 예상 JSON이 아닌 본문을 가진 작업 폴 응답을 받았습니다. 가장 자주 러너와 `api.anthropic.com` 사이의 무언가(예: 가로채는 프록시 또는 캡티브 포털)가 자신의 페이지로 응답했기 때문입니다. 러너는 응답을 거부하고 [`claude_code_self_hosted_runner_poll_errors_total` 메트릭](/docs/ko/self-hosted-environments-reference#prometheus-metrics)의 `transport` 종류 아래에서 계산하고 [세션 수명 주기](/docs/ko/self-hosted-environments#session-lifecycle)에서 설명하는 실패한 폴 일정에서 재시도합니다. 러너는 라이브 세션을 계속 제공합니다. 프록시를 구성하여 `api.anthropic.com`의 응답을 변경되지 않은 상태로 전달하세요. v2.1.246 이전에 러너는 그러한 응답을 빈 작업 큐로 읽었으며, 이는 라이브 세션을 종료하거나 종료하게 할 수 있습니다.727* **러너 로그에 `rejecting the malformed poll response`를 포함하는 `Poll failed` 라인**: 러너가 큐의 예상 JSON이 아닌 본문을 가진 작업 폴 응답을 받았습니다. 가장 자주 러너와 `api.anthropic.com` 사이의 무언가(예: 가로채는 프록시 또는 캡티브 포털)가 자신의 페이지로 응답했기 때문입니다. 러너는 응답을 거부하고 [`claude_code_self_hosted_runner_poll_errors_total` 메트릭](/docs/ko/self-hosted-environments-reference#prometheus-metrics)의 `transport` 종류 아래에서 계산하고 [세션 수명 주기](/docs/ko/self-hosted-environments#session-lifecycle)에서 설명하는 실패한 폴 일정에서 재시도합니다. 러너는 라이브 세션을 계속 제공합니다. 프록시를 구성하여 `api.anthropic.com`의 응답을 변경되지 않은 상태로 전달하세요. v2.1.246 이전에 러너는 그러한 응답을 빈 작업 큐로 읽었으며, 이는 라이브 세션을 종료하거나 종료하게 할 수 있습니다.

612* **세션의 분기가 원격에 더 이상 존재하지 않음**: 세션이 읽기만 하는 git 소스의 경우 러너는 해당 소스를 건너뛰고 나머지에서 계속합니다. 세션이 결과를 푸시하는 소스의 경우 삭제된 분기(일반적으로 병합되고 자동 삭제되었기 때문)는 리포지토리 및 분기를 이름 지정하고 분기를 복원하고 재시도하도록 요청하는 오류로 세션을 실패합니다. 러너는 건너뛰기가 리포지토리 없이 남겨질 때 동일한 오류로 세션을 실패합니다. v2.1.228 이전에 그러한 세션은 빈 디렉토리에서 시작했습니다.728* **세션의 분기가 원격에 더 이상 존재하지 않음**: 세션이 읽기만 하는 git 소스의 경우 러너는 해당 소스를 건너뛰고 나머지에서 계속합니다. 세션이 결과를 푸시하는 소스의 경우 삭제된 분기(일반적으로 병합되고 자동 삭제되었기 때문)는 리포지토리 및 분기를 이름 지정하고 분기를 복원하고 재시도하도록 요청하는 오류로 세션을 실패합니다. 러너는 건너뛰기가 리포지토리 없이 남겨질 때 동일한 오류로 세션을 실패합니다. v2.1.228 이전에 그러한 세션은 빈 디렉토리에서 시작했습니다.

616 732 

617 액세스 확인은 세션이 러너에서 시작될 때마다 다시 실행되므로, 러너의 git 아이덴티티가 읽기 액세스를 가지면 다음 시작은 리포지토리를 복제합니다. v2.1.274 이전에 이러한 각 거부는 세션 시작을 실패했습니다.733 액세스 확인은 세션이 러너에서 시작될 때마다 다시 실행되므로, 러너의 git 아이덴티티가 읽기 액세스를 가지면 다음 시작은 리포지토리를 복제합니다. v2.1.274 이전에 이러한 각 거부는 세션 시작을 실패했습니다.

618* **세션이 시작하는 데 분이 걸림**: 초기 클론이 일반적으로 지배합니다. `claude_code_self_hosted_runner_session_init_duration_seconds` [메트릭](/docs/ko/self-hosted-environments-reference#prometheus-metrics)을 확인하여 확인하고 [사전 준비된 체크아웃](#reuse-a-pre-warmed-checkout) 또는 더 작은 `CLAUDE_RUNNER_FETCH_DEPTH`로 클론을 자르세요.734* **세션이 시작하는 데 분이 걸림**: 초기 클론이 일반적으로 지배합니다. `claude_code_self_hosted_runner_session_init_duration_seconds` [메트릭](/docs/ko/self-hosted-environments-reference#prometheus-metrics)을 확인하여 확인하고 [사전 준비된 체크아웃](#reuse-a-pre-warmed-checkout) 또는 더 작은 `CLAUDE_RUNNER_FETCH_DEPTH`로 클론을 자르세요.

619* **턴이 401로 실패함**: 각 세션은 러너가 Anthropic에서 가져오고 세션의 stdin을 통해 회전하는 단기 [`CLAUDE_CODE_OAUTH_TOKEN`](/docs/ko/self-hosted-environments-configuration#wrapper-scripts)으로 모델 호출을 인증합니다. 턴이 모델 API에서 401 또는 403으로 끝나면 러너는 새로운 토큰을 가져오고 세션에 전달합니다. 실패한 턴은 재시도되지 않습니다.735* **턴이 401로 실패함**: 턴이 Anthropic API의 401 또는 403으로 끝나면 러너는 Anthropic에서 새로운 [`CLAUDE_CODE_OAUTH_TOKEN`](/docs/ko/self-hosted-environments-configuration#wrapper-scripts)을 가져와 세션에 전달합니다. 실패한 턴은 재시도되지 않습니다. 이 토큰은 수명이 짧으며, 러너는 세션의 stdin을 통해 이를 교체합니다.

620 736 

621 가져오기가 실패하면 러너는 언제 재시도할지 말하는 `inference_token refresh failed` 라인을 기록하고 세션이 실행되는 동안 계속 재시도합니다.737 가져오기가 실패하면 러너는 언제 재시도할지 말하는 `inference_token refresh failed` 라인을 기록하고 세션이 실행되는 동안 계속 재시도합니다.

622 738 

637 753 

638* **정상 종료**: 러너가 세션을 완료하고 드레인했거나, 은퇴 시간에 도달했거나, 중지하도록 지시받았습니다. 환경이 다시 용량을 가지도록 다시 시작하세요. [러너 수명 주기](/docs/ko/self-hosted-environments#runner-lifecycle)는 이러한 종료를 설명합니다.754* **정상 종료**: 러너가 세션을 완료하고 드레인했거나, 은퇴 시간에 도달했거나, 중지하도록 지시받았습니다. 환경이 다시 용량을 가지도록 다시 시작하세요. [러너 수명 주기](/docs/ko/self-hosted-environments#runner-lifecycle)는 이러한 종료를 설명합니다.

639* **실패한 시작**: 러너가 주어진 구성 또는 호스트로 시작할 수 없으므로 시작 후 몇 초 후에 종료되며, 다시 시작할 때마다 동일한 방식으로 종료됩니다. 더 빠르게 다시 시작하는 것은 도움이 되지 않습니다. 누군가가 출력을 읽고 원인을 수정해야 합니다.755* **실패한 시작**: 러너가 주어진 구성 또는 호스트로 시작할 수 없으므로 시작 후 몇 초 후에 종료되며, 다시 시작할 때마다 동일한 방식으로 종료됩니다. 더 빠르게 다시 시작하는 것은 도움이 되지 않습니다. 누군가가 출력을 읽고 원인을 수정해야 합니다.

756* **연결 끊김**: 예를 들어 호스트가 절전 상태인 동안처럼 [임대](/docs/ko/self-hosted-environments#session-lifecycle) 기간보다 오래 Anthropic에 도달할 수 없는 러너는 환경에서 제거될 수 있습니다. 제거된 러너가 다시 연결되면 종료됩니다. 로그에는 `runner record gone server-side`를 포함하는 `[runner:fatal]` 라인이 표시되거나, 더 긴 중단 이후에는 [`poll auth failed`](/docs/ko/self-hosted-environments-quickstart#set-up-an-environment-and-runner)가 표시될 수 있습니다. 러너는 스스로 다시 등록하지 않으므로 다시 시작하세요.

640 757 

641러너가 종료될 때마다 다시 시작하도록 감독자를 구성하고, 러너가 시작 직후에 계속 종료될 때 재시작 사이에 더 오래 기다리고, 그것이 계속 발생할 때 누군가에게 알리세요.758러너가 종료될 때마다 다시 시작하도록 감독자를 구성하고, 러너가 시작 직후에 계속 종료될 때 재시작 사이에 더 오래 기다리고, 그것이 계속 발생할 때 누군가에게 알리세요.

642 759 

195 195 

196래퍼는 `CLAUDE_RUNNER_CLAUDE_BIN`에서 실행기 자신의 바이너리에 대한 절대 경로를 받습니다. PATH 해석 `claude` 대신 해당 경로를 사용하여 디코드가 실행기 자체가 사용하는 동일한 바이너리에서 실행되도록 합니다.196래퍼는 `CLAUDE_RUNNER_CLAUDE_BIN`에서 실행기 자신의 바이너리에 대한 절대 경로를 받습니다. PATH 해석 `claude` 대신 해당 경로를 사용하여 디코드가 실행기 자체가 사용하는 동일한 바이너리에서 실행되도록 합니다.

197 197 

198`jq -r` 대신 `jq -re`를 사용하여 누락된 클레임이 0이 아닌 종료를 발생시킵니다. `-r`만 사용하면 누락된 클레임은 리터럴 문자열 `null`을 인쇄하고 0으로 종료되어 잘못된 값을 조용히 다운스트림으로 전달합니다. JWKS 엔드포인트에 도달할 수 없는 오프라인 검사의 경우에만 `decode-token`에 `--no-verify`를 전달합니다.198`jq -r` 대신 `jq -re`를 사용하여 누락된 클레임이 0이 아닌 종료를 발생시킵니다. `-r`만 사용하면 누락된 클레임은 리터럴 문자열 `null`을 인쇄하고 0으로 종료되어 잘못된 값을 조용히 다운스트림으로 전달합니다.

199 

200`decode-token`이 JWKS 엔드포인트에서 키를 가져올 수 없거나 토큰을 확인할 수 없으면 stderr에 이유를 인쇄하고, 클레임을 인쇄하지 않으며, 코드 1로 종료됩니다. JWKS 엔드포인트에 도달할 수 없는 오프라인 검사의 경우에만 `decode-token`에 `--no-verify`를 전달합니다.

199 201 

200<h2 id="claims-reference">202<h2 id="claims-reference">

201 클레임 참조203 클레임 참조

34러너 호스트에 필요한 사항:34러너 호스트에 필요한 사항:

35 35 

36* `api.anthropic.com`, `claude.ai` 및 아래 설치 단계를 위해 리디렉션되는 다운로드 호스트, 그리고 클론을 위해 git 호스트로의 아웃바운드 HTTPS를 사용하는 Linux 또는 macOS 호스트 또는 컨테이너입니다. [네트워크 요구 사항 표](/docs/ko/self-hosted-environments-deploy#network-requirements)에 전체 목록이 있습니다. Windows는 러너 호스트로 지원되지 않습니다. 대신 Linux 컨테이너에서 러너를 실행하세요. 개발자 워크스테이션은 영향을 받지 않습니다. 세션은 브라우저의 claude.ai에서 시작되기 때문입니다.36* `api.anthropic.com`, `claude.ai` 및 아래 설치 단계를 위해 리디렉션되는 다운로드 호스트, 그리고 클론을 위해 git 호스트로의 아웃바운드 HTTPS를 사용하는 Linux 또는 macOS 호스트 또는 컨테이너입니다. [네트워크 요구 사항 표](/docs/ko/self-hosted-environments-deploy#network-requirements)에 전체 목록이 있습니다. Windows는 러너 호스트로 지원되지 않습니다. 대신 Linux 컨테이너에서 러너를 실행하세요. 개발자 워크스테이션은 영향을 받지 않습니다. 세션은 브라우저의 claude.ai에서 시작되기 때문입니다.

37* 테스트 세션용 저장소입니다. 공개 저장소이거나, 이 호스트가 자격 증명을 요청받지 않고 HTTPS URL로 이미 클론할 수 있는 저장소여야 합니다.

37* NTP와 같은 실시간으로 동기화된 시계입니다. 시계가 5분 이상 차이나면 인증이 실패합니다. [문제 해결](/docs/ko/self-hosted-environments-deploy#troubleshooting)을 참조하세요.38* NTP와 같은 실시간으로 동기화된 시계입니다. 시계가 5분 이상 차이나면 인증이 실패합니다. [문제 해결](/docs/ko/self-hosted-environments-deploy#troubleshooting)을 참조하세요.

38 39 

39<h3 id="software-on-the-runner-host">40<h3 id="software-on-the-runner-host">

57 환경 및 러너 설정58 환경 및 러너 설정

58</h2>59</h2>

59 60 

60Claude Code에는 안내식 설정이 포함되어 있습니다. 관리자 UI에서 환경 생성을 안내하는 대화형 Claude Code 세션으로, 저장한 비밀 파일로 로컬 러너를 시작하고, 러너가 등록되었는지 확인하고, `./runner-setup/CHEAT-SHEET.md`에 치트 시트를 작성합니다. Owner 역할을 보유한 계정으로 `claude auth login`을 사용하여 로그인한 머신에서 실행하세요. API 키 또는 타사 모델 제공자와는 사용할 수 없습니다. 대화형 세션이 불가능한 호스트에서는 대신 아래의 수동 단계를 사용하세요. [버전 확인](#software-on-the-runner-host)이 통과했는지 확인하세요. 2.1.224보다 이전 버전에서는 이 명령이 안내식 설정 대신 단어를 프롬프트로 하는 일반 Claude 세션을 시작합니다. 안내식 설정을 시작하려면 설정 서브 명령을 실행하고 프롬프트를 따르세요:61[안내식 설정](#run-the-guided-setup) 또는 [수동 단계](#set-up-manually) 중 하나를 사용하세요. 안내식 설정은 대화형 Claude Code 세션을 시작하고 나머지 과정을 안내하는 단일 명령입니다. 대화형 세션이 불가능한 호스트에서는 대신 수동 단계를 사용하세요. Owner 역할을 보유한 다른 사람이 환경을 생성하고 그 비밀을 전달한 경우에도 수동 단계를 사용하세요. 안내식 설정에는 Owner 로그인이 필요하기 때문입니다.

62 

63<h3 id="run-the-guided-setup">

64 안내식 설정 실행

65</h3>

66 

67안내식 설정은 관리자 UI에서 환경 생성을 안내하고, 저장한 비밀 파일로 로컬 러너를 시작하고, 러너가 등록되었는지 확인하고, `./runner-setup/CHEAT-SHEET.md`에 치트 시트를 작성합니다. 실행하기 전에 로그인과 버전을 확인하세요:

68 

69* **로그인**: Owner 역할을 보유한 계정으로 `claude auth login`을 사용하여 로그인한 머신에서 실행하세요. API 키 또는 타사 모델 제공자만 있는 경우 세션은 시작되지만 조직 확인이 실패합니다.

70* **버전**: [버전 확인](#software-on-the-runner-host)이 통과했는지 확인하세요. 2.1.224보다 이전 버전에서는 setup 명령이 안내식 설정 대신 단어를 프롬프트로 하는 Claude 세션을 시작합니다.

71 

72안내식 설정을 시작하려면 셸에서 setup 서브 명령을 실행하고 프롬프트를 따르세요:

61 73 

62```bash theme={null}74```bash theme={null}

63claude self-hosted-runner setup75claude self-hosted-runner setup

64```76```

65 77 

66대신 수동으로 설정하려면:78설정 자체는 테스트 세션을 시작하지 않으며, claude.ai/code에서 세션을 시작하도록 안내합니다. 설정의 마지막 단계는 설정이 시작한 러너를 중지합니다. 해당 단계 이전에 설정을 떠나면 러너는 계속 실행됩니다. 마지막 단계 이후에도 계속하려면 `./runner-setup/CHEAT-SHEET.md`에 있는 명령으로 셸에서 러너를 다시 시작한 다음 [세션을 환경으로 라우팅](#route-a-session)하세요.

79 

80<h3 id="set-up-manually">

81 수동으로 설정

82</h3>

83 

84claude.ai에서 환경을 생성하고, 호스트의 터미널에서 러너를 시작한 다음, claude.ai로 돌아가 러너가 나타나는지 확인하고 세션을 러너로 라우팅합니다. Owner 역할을 보유한 사람이 이미 환경을 생성하고 그 비밀을 전달한 경우 2단계부터 시작하세요.

67 85 

68<Steps>86<Steps>

69 <Step title="환경 생성">87 <Step title="환경 생성">

73 </Step>91 </Step>

74 92 

75 <Step title="러너 시작">93 <Step title="러너 시작">

76 비밀 디렉토리를 생성하세요. 이 단계와 다음 단계에는 `/etc/claude` 경로에 대한 루트가 필요합니다. 러너 프로세스가 읽을 수 있는 모든 경로가 작동하므로, 다른 경로를 사용하는 경우 두 명령과 `--environment-secret-file` 값을 함께 조정하세요.94 비밀 디렉토리를 생성하세요. 이 명령과 다음 명령은 루트 권한이 필요한 `/etc/claude`를 사용하며, 이 명령들이 생성하는 비밀 파일은 명령을 실행한 사용자만 읽을 수 있습니다. 러너가 다른 사용자로 실행되면 `error: Failed to read environment secret file <path> (EACCES: permission denied, open '<path>')`와 함께 종료됩니다. 이 경우 `/etc/claude` 대신 러너의 사용자가 쓸 수 있는 디렉토리를 사용하여 두 명령을 러너의 사용자로 실행하고, 같은 경로를 `--environment-secret-file`에 전달하세요. 러너 프로세스가 읽을 수 있는 모든 경로가 작동합니다.

77 95 

78 ```bash theme={null}96 ```bash theme={null}

79 mkdir -p /etc/claude97 mkdir -p /etc/claude

89 107 

90 러너가 경로를 생성하거나 쓸 수 없으면, 등록하지 않고 시작 시 디렉토리의 이름을 지정하는 오류로 종료됩니다. [문제 해결](/docs/ko/self-hosted-environments-deploy#troubleshooting)을 참조하세요.108 러너가 경로를 생성하거나 쓸 수 없으면, 등록하지 않고 시작 시 디렉토리의 이름을 지정하는 오류로 종료됩니다. [문제 해결](/docs/ko/self-hosted-environments-deploy#troubleshooting)을 참조하세요.

91 109 

92 그런 다음 `--environment-secret-file` 및 `--base-dir`로 러너를 시작하세요. 러너는 환경에 등록하고 작업을 폴링하기 시작합니다. 러너가 종료되면 수동으로 다시 시작하세요. 프로덕션 배포는 종료된 러너를 다시 시작하는 오케스트레이터 아래에서 러너를 실행하며, 일반적으로 재시작당 새로운 파일 시스템을 사용합니다. [사전 준비된 체크아웃 재사용](/docs/ko/self-hosted-environments-deploy#reuse-a-pre-warmed-checkout)은 지원되는 영구 디스크 설정을 다룹니다.110 그런 다음 `--environment-secret-file` 및 `--base-dir`로 러너를 시작하세요:

93 111 

94 ```bash theme={null}112 ```bash theme={null}

95 claude self-hosted-runner --environment-secret-file '/etc/claude/environment-secret' --base-dir '<writable-dir>'113 claude self-hosted-runner --environment-secret-file '/etc/claude/environment-secret' --base-dir '<writable-dir>'

96 ```114 ```

115 

116 러너는 환경에 등록되면 `Registered: runner_id=<runner-id>`를 기록한 다음 작업 폴링을 시작합니다. 이후 러너가 종료되면 직접 다시 시작하세요. 종료되는 경우에 대해서는 [러너가 종료되는 경우](#if-the-runner-exits)를 참조하세요.

97 </Step>117 </Step>

98 118 

99 <Step title="러너가 나타나는지 확인">119 <Step title="러너가 나타나는지 확인">

100 [**클라우드 환경** 페이지](https://claude.ai/admin-settings/cloud-environments)로 돌아가세요. 환경의 상태는 러너 시작 후 몇 초 내에 **배포된 러너 없음**에서 **정상**으로 변경됩니다. 환경을 열고 **활동**을 선택하여 러너 자체를 확인하세요.120 [**클라우드 환경** 페이지](https://claude.ai/admin-settings/cloud-environments)로 돌아가세요. 환경의 상태는 러너 시작 후 몇 초 내에 **배포된 러너 없음**에서 **정상**으로 변경됩니다. 환경을 열고 **활동**을 선택하여 러너 자체를 확인하세요. 관리자 페이지에 접근할 수 없는 경우, 이전 단계의 러너 로그에 있는 `Registered: runner_id=<runner-id>` 줄이 같은 신호를 제공합니다.

101 </Step>121 </Step>

102 122 

103 <Step title="세션을 환경으로 라우팅">123 <Step title="세션을 환경으로 라우팅">

104 claude.ai/code에서 세션을 시작하고 환경 선택기에서 환경을 선택하세요. 자체 호스팅 환경은 Anthropic 호스팅 환경과 함께 나타납니다. 러너는 호스트가 이미 가지고 있는 git 자격 증명으로 클론하므로, 이 호스트가 이미 클론할 수 있는 저장소 또는 공개 저장소를 선택하세요. 프로덕션의 비공개 저장소에 대한 자격 증명 옵션은 [Git 구성](/docs/ko/self-hosted-environments-deploy#configure-git)에 있습니다. 다음 사용 가능한 러너가 대기 중인 세션을 선택하고 `Picked up session <session-id>`를 기록하며, 활성 개수 및 용량을 함께 기록하므로, 러너의 자체 출력에서 어느 호스트가 세션을 선택했는지 확인할 수 있습니다. [claude.ai/code](https://claude.ai/code)에서 세션이 작동하는 것을 보고 Claude의 답변을 읽으세요. 세션이 대기 중인 경우 [문제 해결](/docs/ko/self-hosted-environments-deploy#troubleshooting)을 참조하세요.124 <span id="route-a-session" />claude.ai/code에서 세션을 시작하고 환경 선택기에서 환경을 선택하세요. 자체 호스팅 환경은 Anthropic 호스팅 환경과 함께 나타납니다. 저장소는 [사전 요구 사항](#host-and-network)에서 정한 것, 즉 공개 저장소나 이 호스트가 이미 클론할 수 있는 저장소를 선택하세요. 러너는 호스트가 이미 가지고 있는 git 자격 증명으로 클론합니다.

125 

126 다음 사용 가능한 러너가 대기 중인 세션을 선택하고 `Picked up session <session-id>`를 기록하며, 활성 개수 및 용량을 함께 기록하므로, 러너의 자체 출력에서 어느 호스트가 세션을 선택했는지 확인할 수 있습니다. [claude.ai/code](https://claude.ai/code)에서 세션이 작동하는 것을 보고 Claude의 답변을 읽으세요.

127 

128 세션이 작업을 시작하지 않으면 보이는 상황에 맞춰 확인하세요:

129 

130 * **세션이 대기 상태로 머무는 경우**: [문제 해결](/docs/ko/self-hosted-environments-deploy#troubleshooting)을 참조하세요.

131 * **세션이 git 오류로 시작에 실패하는 경우**: 오류는 세션과 러너의 로그에 나타납니다. 오류에 git의 `could not read Username for`와 그 뒤에 git 호스트의 URL이 포함되어 있다면, 러너에 해당 호스트에 대한 HTTPS 자격 증명이 없는 것입니다. [Git 구성](/docs/ko/self-hosted-environments-deploy#configure-git)을 참조하세요. 이 문서는 프로덕션의 비공개 저장소에 대한 자격 증명 옵션도 다룹니다.

105 </Step>132 </Step>

106</Steps>133</Steps>

107 134 

108러너는 활성 세션이 완료되면 설계상 종료됩니다. [러너 수명 주기](/docs/ko/self-hosted-environments#runner-lifecycle)를 참조하세요. 프로덕션의 경우, 종료 시 다시 시작하는 오케스트레이터 아래에 배포하세요. [프로덕션에 배포](/docs/ko/self-hosted-environments-deploy) 및 [러너가 종료될 때](/docs/ko/self-hosted-environments-deploy#when-the-runner-exits)를 참조하세요.135<h3 id="if-the-runner-exits">

136 러너가 종료되는 경우

137</h3>

138 

139이 빠른 시작 중에 러너가 종료되면 같은 명령으로 다시 시작하세요. 러너는 스스로 종료될 수 있습니다:

140 

141* **세션 완료**: 로그에 `[runner:exit] account workload drained — exiting`이 표시됩니다. 러너는 활성 세션이 완료되면 설계상 종료됩니다. [러너 수명 주기](/docs/ko/self-hosted-environments#runner-lifecycle)를 참조하세요.

142* **연결 끊김**: 로그에 `runner record gone server-side` 또는 `poll auth failed`가 포함된 `[runner:fatal]` 줄이 표시됩니다. 호스트가 절전 상태가 되는 등의 이유로 러너가 한동안 Anthropic과 연결이 끊기면, 다음에 Anthropic에 연결될 때 종료될 수 있습니다.

143 

144턴이 완료되어도 테스트 세션은 끝나지 않습니다. 첫 번째 턴 이후에도 세션은 계속 연결되어 있고 러너도 계속 실행 중이므로, 러너를 먼저 다시 시작하지 않고도 [세션에 후속 메시지를 보낼](#send-a-follow-up-message-to-a-running-session) 수 있습니다.

145 

146프로덕션의 경우, 종료 시 러너를 다시 시작하고 러너가 시작 직후 계속 종료될 때는 재시작 간격을 더 길게 두는 오케스트레이터 아래에 러너를 배포하세요. [프로덕션에 배포](/docs/ko/self-hosted-environments-deploy) 및 [러너가 종료될 때](/docs/ko/self-hosted-environments-deploy#when-the-runner-exits)를 참조하세요.

109 147 

110<h2 id="send-a-follow-up-message-to-a-running-session">148<h2 id="send-a-follow-up-message-to-a-running-session">

111 실행 중인 세션에 후속 메시지 전송149 실행 중인 세션에 후속 메시지 전송

52| `--release-idle-session-min <n>` | `SELF_HOSTED_RUNNER_SESSION_IDLE_MS` | `0` | 턴이 완료되거나 세션이 사용자의 작업을 기다린 후 N분의 비활성 상태 후 세션 슬롯을 해제합니다. 여전히 턴 중간에 있는 세션(절대 완료되지 않는 백그라운드 작업을 보유하거나 실행 중인 도구 호출 내에서 요청된 승인을 포함)은 유휴로 계산되지 않습니다. `--kill-session-after-min`과 쌍을 이루어 하드 백스톱으로 사용하십시오. 세션의 백그라운드 작업이 완료된 후, 러너는 최대 [`SELF_HOSTED_RUNNER_BG_RESULT_GRACE_MS`](#environment-variable-only-settings) 윈도우 동안 결과를 읽는 후속 턴이 시작될 때까지 세션을 바쁜 것으로 간주합니다. 러너가 종료 신호를 받거나 은퇴 시간에 도달할 때까지, 러너를 활성 세션 없이 남겨두는 해제는 `--drain-grace-sec`에 의해 관리되는 정상 드레인과 동일한 종료 경로를 시작합니다. [`--defer-shutdown-max-min`](/docs/ko/self-hosted-environments-deploy#defer-the-drain-past-the-first-signal)으로 연기한 첫 번째 신호 이후, 러너는 해제로 인해 세션을 보유하지 않는 즉시 종료됩니다. `0`은 비활성화합니다. |52| `--release-idle-session-min <n>` | `SELF_HOSTED_RUNNER_SESSION_IDLE_MS` | `0` | 턴이 완료되거나 세션이 사용자의 작업을 기다린 후 N분의 비활성 상태 후 세션 슬롯을 해제합니다. 여전히 턴 중간에 있는 세션(절대 완료되지 않는 백그라운드 작업을 보유하거나 실행 중인 도구 호출 내에서 요청된 승인을 포함)은 유휴로 계산되지 않습니다. `--kill-session-after-min`과 쌍을 이루어 하드 백스톱으로 사용하십시오. 세션의 백그라운드 작업이 완료된 후, 러너는 최대 [`SELF_HOSTED_RUNNER_BG_RESULT_GRACE_MS`](#environment-variable-only-settings) 윈도우 동안 결과를 읽는 후속 턴이 시작될 때까지 세션을 바쁜 것으로 간주합니다. 러너가 종료 신호를 받거나 은퇴 시간에 도달할 때까지, 러너를 활성 세션 없이 남겨두는 해제는 `--drain-grace-sec`에 의해 관리되는 정상 드레인과 동일한 종료 경로를 시작합니다. [`--defer-shutdown-max-min`](/docs/ko/self-hosted-environments-deploy#defer-the-drain-past-the-first-signal)으로 연기한 첫 번째 신호 이후, 러너는 해제로 인해 세션을 보유하지 않는 즉시 종료됩니다. `0`은 비활성화합니다. |

53| `--remove-session-state [bool]` | `SELF_HOSTED_RUNNER_REMOVE_SESSION_STATE` | 꺼짐 | 세션이 이 러너에서 종료될 때 결과와 관계없이 `<base-dir>/_sessions/` 아래의 세션별 디렉터리를 제거합니다. [사전 준비된 체크아웃 재사용](/docs/ko/self-hosted-environments-deploy#reuse-a-pre-warmed-checkout)은 이들이 보유한 내용과 유지될 때 이를 읽을 수 있는 사람을 설명합니다. 제거는 최선의 노력입니다: 러너가 종료되거나 정리가 실행되기 전에 드레인 마감에 도달하면 세션별 디렉터리가 제자리에 남아 있습니다. 플래그가 켜져 있으면 실패하거나 중단된 세션의 디버그 로그가 디스크에 유지되지 않습니다. Claude Code v2.1.268 이상이 필요합니다. |53| `--remove-session-state [bool]` | `SELF_HOSTED_RUNNER_REMOVE_SESSION_STATE` | 꺼짐 | 세션이 이 러너에서 종료될 때 결과와 관계없이 `<base-dir>/_sessions/` 아래의 세션별 디렉터리를 제거합니다. [사전 준비된 체크아웃 재사용](/docs/ko/self-hosted-environments-deploy#reuse-a-pre-warmed-checkout)은 이들이 보유한 내용과 유지될 때 이를 읽을 수 있는 사람을 설명합니다. 제거는 최선의 노력입니다: 러너가 종료되거나 정리가 실행되기 전에 드레인 마감에 도달하면 세션별 디렉터리가 제자리에 남아 있습니다. 플래그가 켜져 있으면 실패하거나 중단된 세션의 디버그 로그가 디스크에 유지되지 않습니다. Claude Code v2.1.268 이상이 필요합니다. |

54| `--retire-at <epoch-seconds>` | `SELF_HOSTED_RUNNER_RETIRE_AT` | 설정되지 않음 | 러너가 알려진 시간에 종료되는 인프라를 위해 절대 Unix 타임스탬프(초)에서 러너를 은퇴시킵니다. [러너 라이프사이클](/docs/ko/self-hosted-environments#runner-lifecycle)은 해제 시퀀스 및 여유를 크기 조정하는 방법을 설명합니다. 2001 이전 또는 5138년 이후의 값은 플래그에 의해 거부되고 환경 변수에 의해 무시됩니다. |54| `--retire-at <epoch-seconds>` | `SELF_HOSTED_RUNNER_RETIRE_AT` | 설정되지 않음 | 러너가 알려진 시간에 종료되는 인프라를 위해 절대 Unix 타임스탬프(초)에서 러너를 은퇴시킵니다. [러너 라이프사이클](/docs/ko/self-hosted-environments#runner-lifecycle)은 해제 시퀀스 및 여유를 크기 조정하는 방법을 설명합니다. 2001 이전 또는 5138년 이후의 값은 플래그에 의해 거부되고 환경 변수에 의해 무시됩니다. |

55| `--server-auto-mode-lists <mode>` | `SELF_HOSTED_RUNNER_SERVER_AUTO_MODE_LISTS` | `no-allow` | 컨트롤 플레인이 세션과 함께 보내는 [자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode) 분류기 규칙 목록 중 어떤 것이 해당 세션에 도달할 수 있는지 지정합니다: `all`, `no-allow` 또는 `none`. 각 값이 적용하는 내용은 [자동 모드 규칙 목록](#auto-mode-rule-lists)을 참조하십시오. 잘못된 값은 시작 시 러너를 중지시킵니다. Claude Code v2.1.295 이상이 필요합니다. |

55| `--session-stop-grace-sec <n>` | `SELF_HOSTED_RUNNER_SESSION_STOP_GRACE_MS` | `5` | 세션이 종료된 후 Claude 프로세스가 깔끔하게 종료될 때까지 기다린 후 강제 종료하기 전까지 기다리는 시간입니다. 자식의 자체 `SessionEnd` 훅에 더 많은 시간이 필요한 경우 값을 높이십시오. |56| `--session-stop-grace-sec <n>` | `SELF_HOSTED_RUNNER_SESSION_STOP_GRACE_MS` | `5` | 세션이 종료된 후 Claude 프로세스가 깔끔하게 종료될 때까지 기다린 후 강제 종료하기 전까지 기다리는 시간입니다. 자식의 자체 `SessionEnd` 훅에 더 많은 시간이 필요한 경우 값을 높이십시오. |

56| `--startup-timeout-min <n>` | `SELF_HOSTED_RUNNER_STARTUP_TIMEOUT_MS` | `15` | 자식이 생성 후 N분 이내에 [활동 채널](/docs/ko/self-hosted-environments-configuration#keep-stdin-and-file-descriptor-3-attached)에서 초기화되었음을 신호하지 않은 경우 세션 슬롯을 해제합니다. 일반 출력이 아닌 자식의 초기화 신호로 지워지며, 그 후 `--release-idle-session-min`이 인수합니다. `0`은 비활성화합니다. |57| `--startup-timeout-min <n>` | `SELF_HOSTED_RUNNER_STARTUP_TIMEOUT_MS` | `15` | 자식이 생성 후 N분 이내에 초기화되었음을 신호하지 않은 경우 세션 슬롯을 해제합니다. 복제는 생성 전에 이루어지므로 복제 시간은 계산되지 않습니다. 일반 출력이 아닌 [활동 채널](/docs/ko/self-hosted-environments-configuration#keep-stdin-and-file-descriptor-3-attached)의 자식 초기화 신호로 지워지며, 그 후 `--release-idle-session-min`이 인수합니다. `0`은 비활성화합니다. |

57| `--trust-workspace [bool]` | `SELF_HOSTED_RUNNER_TRUST_WORKSPACE` | 켜짐 | 각 세션의 저장소 경로에 대해 지속된 신뢰를 시드하여 저장소 커밋된 `permissions.allow` 및 `additionalDirectories`가 준수되도록 합니다. 저장소 커밋된 권한 부여를 삭제하고 대신 호스트 구성의 `settings.json`에서 허용 규칙을 구성하려면 `false`로 설정하십시오. 저장소 커밋된 `sandbox.*` 설정은 여전히 어느 쪽이든 적용되며, 이것이 [저장소 설정 가드](/docs/ko/self-hosted-environments-deploy#harden-your-deployment)가 이 플래그와 관계없이 이를 스캔하는 이유입니다. |58| `--trust-workspace [bool]` | `SELF_HOSTED_RUNNER_TRUST_WORKSPACE` | 켜짐 | 각 세션의 저장소 경로에 대해 지속된 신뢰를 시드하여 저장소 커밋된 `permissions.allow` 및 `additionalDirectories`가 준수되도록 합니다. 저장소 커밋된 권한 부여를 삭제하고 대신 호스트 구성의 `settings.json`에서 허용 규칙을 구성하려면 `false`로 설정하십시오. 저장소 커밋된 `sandbox.*` 설정은 여전히 어느 쪽이든 적용되며, 이것이 [저장소 설정 가드](/docs/ko/self-hosted-environments-deploy#harden-your-deployment)가 이 플래그와 관계없이 이를 스캔하는 이유입니다. |

58| `--use-anthropic-git-proxy` | `CLAUDE_RUNNER_USE_GIT_PROXY=1` | 꺼짐 | 고객 관리 git 인증 대신 [Anthropic git 프록시](/docs/ko/self-hosted-environments-deploy#use-the-anthropic-git-proxy)를 통해 복제합니다. `--capacity 1` 및 git 2.32 이상이 필요합니다. 러너는 그렇지 않으면 시작을 거부합니다. 다시 작성 플래그를 대체합니다. |59| `--use-anthropic-git-proxy` | `CLAUDE_RUNNER_USE_GIT_PROXY=1` | 꺼짐 | 고객 관리 git 인증 대신 [Anthropic git 프록시](/docs/ko/self-hosted-environments-deploy#use-the-anthropic-git-proxy)를 통해 github.com의 저장소를 복제합니다. `--capacity 1` 및 git 2.32 이상이 필요합니다. 러너는 그렇지 않으면 시작을 거부합니다. 다시 작성 플래그를 대체합니다. |

59 60 

60대부분의 기간 플래그에는 최대값이 있으며, 각 타임아웃을 런타임의 32비트 타이머 상한인 약 24.85일 이내로 유지하도록 선택됩니다. `--*-min` 플래그는 10080분(7일)에서 상한선을 설정합니다. `--drain-grace-sec`는 604800초(역시 7일)에서 상한선을 설정합니다. `--drain-wait-sec`는 86400초(24시간)에서 상한선을 설정합니다. `--session-stop-grace-sec` 및 `--post-session-hook-timeout-sec`는 상한선이 없습니다. 상한선을 초과하는 동작은 표면별로 다릅니다:61대부분의 기간 플래그에는 최대값이 있으며, 각 타임아웃을 런타임의 32비트 타이머 상한인 약 24.85일 이내로 유지하도록 선택됩니다. `--*-min` 플래그는 10080분(7일)에서 상한선을 설정합니다. `--drain-grace-sec`는 604800초(역시 7일)에서 상한선을 설정합니다. `--drain-wait-sec`는 86400초(24시간)에서 상한선을 설정합니다. `--session-stop-grace-sec` 및 `--post-session-hook-timeout-sec`는 상한선이 없습니다. 상한선을 초과하는 동작은 표면별로 다릅니다:

61 62 

62* **플래그**: 시작이 오류로 실패합니다.63* **플래그**: 시작이 오류로 실패합니다.

63* **환경 변수**: 러너는 값을 거부하는 대신 타이머 상한선으로 고정합니다.64* **환경 변수**: 러너는 값을 거부하는 대신 타이머 상한선으로 고정합니다.

64 65 

66<h3 id="auto-mode-rule-lists">

67 자동 모드 규칙 목록

68</h3>

69 

70`--server-auto-mode-lists`를 사용하면 러너 외부에서 오는 [자동 모드](/docs/ko/permission-modes#eliminate-prompts-with-auto-mode) 분류기 규칙 중 어떤 것이 러너의 세션에 도달할지 결정할 수 있습니다. Anthropic의 컨트롤 플레인은 세션과 함께 규칙 목록을 보내고 러너에 이를 적용하도록 요청할 수 있습니다. 일부 항목은 조직의 관리자가 작성한 규칙일 수 있습니다. 목록은 `environment`, `soft_deny`, `allow`입니다:

71 

72* **`environment`**: 항목이 분류기가 더 많이 허용하도록 만들 수도 있고, 더 적게 허용하도록 만들 수도 있습니다.

73* **`soft_deny`**: 사용자가 명시적으로 요청했거나 `allow` 예외가 적용되지 않는 한 항목이 작업을 차단합니다.

74* **`allow`**: `soft_deny` 항목에 대한 예외입니다.

75 

76플래그의 값은 러너가 적용할 목록을 선택합니다:

77 

78* **`no-allow`**: 기본값입니다. `environment`와 `soft_deny`를 적용하고 `allow`는 보류합니다. `environment` 항목은 여전히 분류기가 더 많이 허용하도록 만들 수 있으므로, 기본값이 모든 완화를 배제하지는 않습니다.

79* **`all`**: 세 목록을 모두 적용합니다.

80* **`none`**: 어떤 목록도 적용하지 않습니다. 이러한 목록에서 오는 모든 완화를 배제하려면 `none`을 선택하십시오. 이 경우 `soft_deny` 제한도 함께 제외됩니다.

81 

82컨트롤 플레인이 러너에 목록 적용을 요청하도록 만드는 러너 설정은 없습니다. 요청하지 않으면 어떤 값을 설정하든 세션은 목록을 받지 않습니다. 어느 쪽이었는지 확인하려면 `--log-level debug`로 러너를 시작하십시오. 그러면 러너는 각 세션에 대해 `the server asked this runner to apply`가 포함된 줄 또는 `the server did not ask this runner to apply the auto mode lists it sends`가 포함된 줄을 로그에 기록합니다.

83 

65<h2 id="orchestrator-cli-flags">84<h2 id="orchestrator-cli-flags">

66 오케스트레이터 CLI 플래그85 오케스트레이터 CLI 플래그

67</h2>86</h2>

72| :- | :- | :- |91| :- | :- | :- |

73| `--hook-concurrency <n>` | `4` | 병렬로 실행되는 최대 `spawn-runner` 훅입니다. 또한 폴링당 청구되는 스폰 요청 수를 제한합니다. |92| `--hook-concurrency <n>` | `4` | 병렬로 실행되는 최대 `spawn-runner` 훅입니다. 또한 폴링당 청구되는 스폰 요청 수를 제한합니다. |

74| `--hook-timeout <sec>` | `60` | 이 많은 초 후 훅의 프로세스 트리를 종료합니다. 타임아웃과 5초 킬 유예는 `--expected-spawn-seconds` 아래에 있어야 합니다. 오케스트레이터는 시작 시 이를 적용합니다. |93| `--hook-timeout <sec>` | `60` | 이 많은 초 후 훅의 프로세스 트리를 종료합니다. 타임아웃과 5초 킬 유예는 `--expected-spawn-seconds` 아래에 있어야 합니다. 오케스트레이터는 시작 시 이를 적용합니다. |

75| `--expected-spawn-seconds <sec>` | `120` | 생성된 러너의 예상 p99 부팅 시간(서버 적용 범위 10\~3600). 모든 폴링에서 서버 측 임차로 전송됩니다. 경과하기 전에 러너가 등록되지 않으면 세션이 새 주문 ID로 다시 제공됩니다. 모든 복제본은 이 값을 공유해야 합니다. |94| `--expected-spawn-seconds <sec>` | `120` | 오케스트레이터가 스폰 요청을 받은 시점부터 러너가 등록될 때까지의 예상 p99 시간이며, 플랫폼에서 용량을 기다리는 시간도 포함됩니다. 서버는 10\~3600 범위를 적용합니다. 모든 폴링에서 서버 측 임차로 전송됩니다. 경과하기 전에 러너가 등록되지 않으면 세션이 새 주문 ID로 다시 제공됩니다. 모든 복제본은 이 값을 공유해야 합니다. |

76| `--min-idle <n>` | `0` | 대기 중인 러너를 사전에 생성하여 최소 N개의 유휴 세션 슬롯을 무료로 유지합니다. `0`은 사전 워밍을 비활성화합니다. 러너의 `--exit-if-unused-min`과 쌍을 이루어 잉여 대기 러너가 자신을 회수하도록 합니다. |95| `--min-idle <n>` | `0` | 대기 중인 러너를 사전에 생성하여 최소 N개의 유휴 세션 슬롯을 무료로 유지합니다. `0`은 사전 워밍을 비활성화합니다. 러너의 `--exit-if-unused-min`과 쌍을 이루어 잉여 대기 러너가 자신을 회수하도록 합니다. |

77| `--debug-dir <path>` | 설정되지 않음 | 각 스폰 요청의 작업 주문 및 훅 stderr을 디스크에 씁니다. 디버그 전용이며 프로덕션에서 설정하지 마세요. |96| `--debug-dir <path>` | 설정되지 않음 | 각 스폰 요청의 작업 주문 및 훅 stderr을 디스크에 씁니다. 디버그 전용이며 프로덕션에서 설정하지 마세요. |

78 97 

108| `SELF_HOSTED_RUNNER_POST_TURN_SETTLE_MS` | `7000` | 턴이 완료된 후 세션의 프로세스가 턴의 끝을 Anthropic에 보고하는 동안 러너가 `--drain-wait-sec` 드레인에 대해 세션을 바쁜 것으로 계산하는 시간의 상한입니다. `0` 또는 사용할 수 없는 값은 기본값으로 폴백되므로 보유를 끌 수 없습니다. Claude Code v2.1.275 이상이 필요합니다. |127| `SELF_HOSTED_RUNNER_POST_TURN_SETTLE_MS` | `7000` | 턴이 완료된 후 세션의 프로세스가 턴의 끝을 Anthropic에 보고하는 동안 러너가 `--drain-wait-sec` 드레인에 대해 세션을 바쁜 것으로 계산하는 시간의 상한입니다. `0` 또는 사용할 수 없는 값은 기본값으로 폴백되므로 보유를 끌 수 없습니다. Claude Code v2.1.275 이상이 필요합니다. |

109| `SELF_HOSTED_RUNNER_SIGKILL_GRACE_MS` | `30000` | 러너가 중단 불가능한 I/O에 갇혀 있는 자식에게 OS가 `SIGKILL`을 전달할 때까지 기다린 후 자신을 종료하기 전까지 기다리는 시간입니다. `--post-session-hook-timeout-sec` 더하기 15초로 바닥이 정해지며, `--push-outcome-on-release`가 설정되면 30초 더 추가되므로 효과적인 최소값은 기본값에서 75초입니다. |128| `SELF_HOSTED_RUNNER_SIGKILL_GRACE_MS` | `30000` | 러너가 중단 불가능한 I/O에 갇혀 있는 자식에게 OS가 `SIGKILL`을 전달할 때까지 기다린 후 자신을 종료하기 전까지 기다리는 시간입니다. `--post-session-hook-timeout-sec` 더하기 15초로 바닥이 정해지며, `--push-outcome-on-release`가 설정되면 30초 더 추가되므로 효과적인 최소값은 기본값에서 75초입니다. |

110| `CLAUDE_RUNNER_FETCH_DEPTH` | `50` | 신선한 복제를 위한 Git 페치 깊이입니다. 양의 정수 또는 완전한 페치를 위해 `full` 또는 `0`을 설정하세요. 작업 공간에 이미 있는 저장소는 기존 깊이를 유지합니다. |129| `CLAUDE_RUNNER_FETCH_DEPTH` | `50` | 신선한 복제를 위한 Git 페치 깊이입니다. 양의 정수 또는 완전한 페치를 위해 `full` 또는 `0`을 설정하세요. 작업 공간에 이미 있는 저장소는 기존 깊이를 유지합니다. |

130| `CLAUDE_RUNNER_FETCH_SERVER_PROGRESS_CAP_MS` | `600000` | 서버가 대규모 저장소의 팩을 준비할 때처럼 Git 서버 자체의 진행률 수치가 계속 증가하는 동안, Git 페치가 첫 데이터를 기다릴 수 있는 시도당 시간(밀리초)입니다. `0` 또는 `off`는 이 대기를 끕니다. 이 경우 해당 페치는 데이터 없이 2분이 지나면 중단됩니다. 그 외의 정수는 `120000`에서 `1800000` 사이, 즉 2분에서 30분 사이로 제한됩니다. Claude Code v2.1.295 이상이 필요합니다. |

111| `CLAUDE_RUNNER_SKIP_GIT_VERIFY` | 설정되지 않음 | `1`일 때, `checkout` 훅이 실행된 후 `.git` 존재 확인을 건너뜁니다. 훅이 비git 소스를 구체화할 때 이를 설정하세요. |131| `CLAUDE_RUNNER_SKIP_GIT_VERIFY` | 설정되지 않음 | `1`일 때, `checkout` 훅이 실행된 후 `.git` 존재 확인을 건너뜁니다. 훅이 비git 소스를 구체화할 때 이를 설정하세요. |

112| `FORCE_AUTOUPDATE_PLUGINS` | 설정되지 않음 | `1`일 때, 바이너리가 고정되어 있어도 플러그인 마켓플레이스가 자동 업데이트되도록 합니다. |132| `FORCE_AUTOUPDATE_PLUGINS` | 설정되지 않음 | `1`일 때, 바이너리가 고정되어 있어도 플러그인 마켓플레이스가 자동 업데이트되도록 합니다. |

113| `CLAUDE_CODE_DISABLE_ARTIFACT` | 설정되지 않음 | `1`일 때, 조직의 관리자 설정과 관계없이 세션에서 Artifact 도구를 비활성화하고 `*.frame.claudeusercontent.com` 이그레스 요구 사항을 삭제합니다. |133| `CLAUDE_CODE_DISABLE_ARTIFACT` | 설정되지 않음 | `1`일 때, 조직의 관리자 설정과 관계없이 세션에서 Artifact 도구를 비활성화하고 `*.frame.claudeusercontent.com` 이그레스 요구 사항을 삭제합니다. |

178| `claude_code_self_hosted_orchestrator_poll_errors_total{error_kind}` | 종류별 누적 PollSpawnHints 실패: `transport`, `timeout`, `5xx`, `429` 또는 `4xx`. 모든 5개 시리즈는 프로세스 시작부터 존재합니다. `rate(...[5m]) > 0`에서 경고하세요. |198| `claude_code_self_hosted_orchestrator_poll_errors_total{error_kind}` | 종류별 누적 PollSpawnHints 실패: `transport`, `timeout`, `5xx`, `429` 또는 `4xx`. 모든 5개 시리즈는 프로세스 시작부터 존재합니다. `rate(...[5m]) > 0`에서 경고하세요. |

179| `claude_code_self_hosted_orchestrator_queue_pending_sessions` | 지금 청구 가능한 스폰 요청 |199| `claude_code_self_hosted_orchestrator_queue_pending_sessions` | 지금 청구 가능한 스폰 요청 |

180| `claude_code_self_hosted_orchestrator_queue_backing_off_sessions` | 재시도 가능한 훅 실패 후 재시도 백오프의 스폰 요청 |200| `claude_code_self_hosted_orchestrator_queue_backing_off_sessions` | 재시도 가능한 훅 실패 후 재시도 백오프의 스폰 요청 |

181| `claude_code_self_hosted_orchestrator_queue_circuit_broken_sessions` | Owner가 환경의 **Activity** 탭에서 재시도할 때까지 차단된 스폰 요청입니다. 0 이상이면 경고하세요. |201| `claude_code_self_hosted_orchestrator_queue_circuit_broken_sessions` | 스폰이 차단된 세션입니다. 각 세션은 사용자가 새 메시지를 보내거나 Owner가 환경의 **Activity** 탭에서 재시도할 때까지 차단된 상태로 유지됩니다. 원인을 수정한 후에도 수가 0보다 크게 유지될 수 있습니다. 0 이상이면 경고하세요. |

182| `claude_code_self_hosted_orchestrator_pool_pending_sessions` | 이 환경의 러너를 기다리는 총 세션입니다. 환경 전체 집계이며, 모든 오케스트레이터 인스턴스에서 동일합니다: 인스턴스 전체에서 `SUM` 대신 `MAX`를 사용하세요. |202| `claude_code_self_hosted_orchestrator_pool_pending_sessions` | 이 환경의 러너를 기다리는 총 세션입니다. 환경 전체 집계이며, 모든 오케스트레이터 인스턴스에서 동일합니다: 인스턴스 전체에서 `SUM` 대신 `MAX`를 사용하세요. |

183| `claude_code_self_hosted_orchestrator_pool_active_sessions` | 현재 이 환경의 살아있는 러너에 할당된 세션입니다. 환경 전체 집계이며, 모든 오케스트레이터 인스턴스에서 동일합니다: 인스턴스 전체에서 `SUM` 대신 `MAX`를 사용하세요. |203| `claude_code_self_hosted_orchestrator_pool_active_sessions` | 현재 이 환경의 살아있는 러너에 할당된 세션입니다. 환경 전체 집계이며, 모든 오케스트레이터 인스턴스에서 동일합니다: 인스턴스 전체에서 `SUM` 대신 `MAX`를 사용하세요. |

184| `claude_code_self_hosted_orchestrator_spawn_hooks_total{result}` | 누적 `spawn-runner` 훅 결과: `ok`, `retryable`, `non_retryable`. 오케스트레이터 훅 호출을 계산하며, 러너가 생성하는 세션 자식이 아닙니다: 용량이 1 이상, 웜 풀 및 동일한 세션에 대해 다시 생성된 러너가 둘을 분산시키므로 `sessions_started_total`과 비교할 수 없습니다. |204| `claude_code_self_hosted_orchestrator_spawn_hooks_total{result}` | 누적 `spawn-runner` 훅 결과: `ok`, `retryable`, `non_retryable`. 오케스트레이터 훅 호출을 계산하며, 러너가 생성하는 세션 자식이 아닙니다: 용량이 1 이상, 웜 풀 및 동일한 세션에 대해 다시 생성된 러너가 둘을 분산시키므로 `sessions_started_total`과 비교할 수 없습니다. |

283 for: 1m303 for: 1m

284 labels: {severity: critical}304 labels: {severity: critical}

285 annotations:305 annotations:

286 summary: "{{ $value }}개 세션이 회로 차단됨 — spawn-runner 훅이 반복적으로 재시도 불가능합니다. 인프라를 수정한 후 Activity 탭에서 재시도하세요."306 summary: "스폰이 차단된 세션: {{ $value }}개. Activity 탭에서 각 세션의 오류를 확인하고 원인을 수정한 후 Retry를 선택하세요."

287 - alert: ClaudeOrchestratorPollErrors307 - alert: ClaudeOrchestratorPollErrors

288 expr: sum by (pod) (rate(claude_code_self_hosted_orchestrator_poll_errors_total[5m])) > 0308 expr: sum by (pod) (rate(claude_code_self_hosted_orchestrator_poll_errors_total[5m])) > 0

289 for: 2m309 for: 2m

318 338 

319v2.1.260 이전에는 러너가 `--kill-session-after-min` 한계에 도달한 모든 세션을 종료하고 `sessions_interrupted_total`에서 계산했습니다.339v2.1.260 이전에는 러너가 `--kill-session-after-min` 한계에 도달한 모든 세션을 종료하고 `sessions_interrupted_total`에서 계산했습니다.

320 340 

321[`post-session` 훅](/docs/ko/self-hosted-environments-configuration#post-session)의 `CLAUDE_RUNNER_EXIT_REASON`은 이러한 깔끔한 슬롯 반환을 다르게 분류합니다. 훅은 해제, 시작 타임아웃 및 서버 할당 해제를 `interrupted`로 보고합니다. 러너가 자식을 중지했기 때문입니다. 이러한 카운터는 동일한 이벤트를 `completed`로 기록합니다. 슬롯이 깔끔하게 반환되었기 때문입니다.341[`post-session` 훅](/docs/ko/self-hosted-environments-configuration#post-session)의 `CLAUDE_RUNNER_EXIT_REASON`은 깔끔한 슬롯 반환을 다르게 분류합니다. 훅은 해제, 시작 타임아웃, 서버 할당 해제, 그리고 폴이 먼저 알아챈 보관 또는 삭제를 `interrupted`로 보고합니다. 러너가 자식을 중지했기 때문입니다. 이러한 카운터는 동일한 이벤트를 `completed`로 기록합니다. 슬롯이 깔끔하게 반환되었기 때문입니다.

322 342 

323훅 수신을 `sessions_completed_total`에 직접 조정하면 완료를 과소 계산합니다. 세션별 보장을 위해 훅을 사용하고 집계 비율을 위해 카운터를 사용하세요.343훅 수신을 `sessions_completed_total`에 직접 조정하면 완료를 과소 계산합니다. 세션별 보장을 위해 훅을 사용하고 집계 비율을 위해 카운터를 사용하세요.

324 344 

87 87 

88`--environment` 및 `--ref` 디스패치 플래그는 스크립트를 실행하는 머신(러너 자체와 동일한 수준)에서 Claude Code v2.1.224 이상이 필요합니다. 훅이 설치되고 이 호스트에서 러너가 시작된 상태에서 테스트 스크립트는:88`--environment` 및 `--ref` 디스패치 플래그는 스크립트를 실행하는 머신(러너 자체와 동일한 수준)에서 Claude Code v2.1.224 이상이 필요합니다. 훅이 설치되고 이 호스트에서 러너가 시작된 상태에서 테스트 스크립트는:

89 89 

901. `claude -p "<prompt>" --environment <environment-id> --output-format json`으로 테스트 환경에서 세션을 생성합니다. `origin` 원격에서 저장소를 자동 감지할 수 있도록 git 체크아웃에서 실행합니다. 선택적 `--ref <branch>`는 로컬 HEAD 대신 명명된 ref를 기반으로 세션의 체크아웃을 설정합니다. 명령은 세션을 생성하고, `session_id`를 포함하는 한 줄의 JSON을 인쇄하고, Claude의 응답을 기다리지 않고 종료합니다.901. `claude -p "<prompt>" --environment <environment-id> --output-format json`으로 테스트 환경에서 세션을 생성합니다. CLI가 `origin` 원격에서 저장소를 자동 감지할 수 있도록 git 체크아웃에서 명령을 실행합니다. 선택적 `--ref <branch>`는 로컬 HEAD 대신 명명된 ref를 기반으로 세션의 체크아웃을 설정합니다. 명령은 Claude의 응답을 기다리지 않고 종료합니다. 출력되는 내용을 통해 스크립트는 결과를 알 수 있습니다:

91 * **세션 생성됨**: `{"ok":true,"session_id":"session_...","title":"...","url":"...","pool_id":"..."}`와 같은 한 줄의 JSON

92 * **세션 생성 실패**: `{"ok":false,"error":"..."}` 줄이 출력되고, 명령은 상태 1로 종료됩니다

93 * **일부 이전 단계의 오류**(예: 조직에서 클라우드 세션을 사용할 수 없거나 프롬프트가 누락된 경우): JSON 줄 없이 stderr에 오류가 출력되고, 명령은 상태 1로 종료됩니다

912. 러너의 Stop 훅이 턴을 완료한 후 `$E2E_REPLY_DIR/<session_id>.txt`에 기록된 응답이 나타날 때까지 기다립니다.942. 러너의 Stop 훅이 턴을 완료한 후 `$E2E_REPLY_DIR/<session_id>.txt`에 기록된 응답이 나타날 때까지 기다립니다.

923. `claude -p "<message>" --cloud <session_id> --output-format json`으로 후속 메시지를 보냅니다([실행 중인 세션에 후속 메시지 보내기](/docs/ko/claude-code-on-the-web#send-follow-ups-from-the-cli) 참조). 이는 기존 세션에 사용자 이벤트를 게시하고 종료합니다.953. `claude -p "<message>" --cloud <session_id> --output-format json`으로 후속 메시지를 보냅니다([실행 중인 세션에 후속 메시지 보내기](/docs/ko/claude-code-on-the-web#send-follow-ups-from-the-cli) 참조). 이는 기존 세션에 사용자 이벤트를 게시하고 종료합니다.

934. 2단계와 동일한 방식으로 후속 응답을 기다립니다.964. 2단계와 동일한 방식으로 후속 응답을 기다립니다.

104 예제 스크립트107 예제 스크립트

105</h2>108</h2>

106 109 

107아래 스크립트는 `$CLAUDE_TEST_ENVIRONMENT_ID`에 대해 전체 루프를 실행합니다. 이는 테스트 환경의 `ccpool_...` ID이며, 관리 페이지의 환경 상세 대화상자에 표시되거나 [환경 생성 호출](#create-a-dedicated-test-environment)에서 반환됩니다. 각 응답의 센티널 구문을 어설션합니다. 캡처 훅이 설치되고 `E2E_REPLY_DIR`이 내보내진 이 호스트에서 러너를 시작한 후, 작업하려는 저장소의 git 체크아웃에서 실행합니다. 먼저 [CI에서 인증하기](#authenticate-from-ci)에 설명된 대로 스크립트를 실행하는 머신에서 claude.ai 계정으로 로그인합니다. 로그인하지 않으면 첫 번째 디스패치가 `Unable to get organization UUID for cloud session creation`과 같은 오류와 함께 실패합니다.110예제 스크립트는 테스트 러너와 같은 머신에서 실행됩니다. 실행하기 전에 해당 머신을 준비합니다.

111 

112* **저장소 체크아웃**: 세션이 작업할 저장소의 git 체크아웃에서 스크립트를 실행합니다.

113* **러너**: 캡처 훅이 설치되고 `E2E_REPLY_DIR`이 내보내진 상태로 이 호스트에서 러너를 시작합니다.

114* **로그인**: [CI에서 인증하기](#authenticate-from-ci)에 설명된 대로 스크립트를 실행하는 머신에서 claude.ai 계정으로 로그인합니다.

115* **환경 ID**: `CLAUDE_TEST_ENVIRONMENT_ID`를 테스트 환경의 `ccpool_...` ID로 설정합니다. 이 ID는 관리 페이지의 환경 상세 대화상자에 표시되거나 [환경 생성 호출](#create-a-dedicated-test-environment)에서 반환됩니다.

116 

117아래 스크립트는 `$CLAUDE_TEST_ENVIRONMENT_ID`에 대해 전체 루프를 실행하고 각 응답의 센티널 구문을 어설션합니다.

108 118 

109```bash theme={null}119```bash theme={null}

110#!/usr/bin/env bash120#!/usr/bin/env bash

152TURN1="e2e-probe-$(date +%s)-$$: say exactly 'ok: custom tools are reachable' and nothing else"162TURN1="e2e-probe-$(date +%s)-$$: say exactly 'ok: custom tools are reachable' and nothing else"

153EXPECT1="ok: custom tools are reachable"163EXPECT1="ok: custom tools are reachable"

154create_json=$(claude -p "$TURN1" --environment "$CLAUDE_TEST_ENVIRONMENT_ID" \164create_json=$(claude -p "$TURN1" --environment "$CLAUDE_TEST_ENVIRONMENT_ID" \