Documentation — Spybara

claude-apps-gateway-deploy.md +76 −5

Details

126 126

127각 메커니즘이 정책을 저장하는 위치는 [각 메커니즘이 정책을 저장하는 위치](/docs/ko/managed-settings#where-each-mechanism-stores-the-policy)를 참조하고, Claude Desktop `bootstrapUrl` 동등물은 [클라이언트 측 관리형 설정](/docs/ko/claude-apps-gateway-config#client-side-managed-settings)을 참조하세요.127각 메커니즘이 정책을 저장하는 위치는 [각 메커니즘이 정책을 저장하는 위치](/docs/ko/managed-settings#where-each-mechanism-stores-the-policy)를 참조하고, Claude Desktop `bootstrapUrl` 동등물은 [클라이언트 측 관리형 설정](/docs/ko/claude-apps-gateway-config#client-side-managed-settings)을 참조하세요.

128 128

129<h3 id="large-rollouts">

130 대규모 롤아웃

131</h3>

132

133로그인은 클라이언트 IP 주소별로 속도 제한되며, 기본값은 소규모 팀에 적합합니다. 각 주소는 10분마다 30개의 로그인 시작과 10개의 코드 제출을 받습니다. 수천 명의 개발자로의 롤아웃은 첫 번째 아침에 해당 제한에 도달할 수 있으며, 두 가지 이유 중 하나입니다:

134

135* **게이트웨이가 로드 밸런서를 볼 수 없습니다.** [`listen.trusted_proxies`](/docs/ko/claude-apps-gateway-config#listen)가 없으면, 모든 개발자가 로드 밸런서의 주소에서 오는 것으로 나타나고 하나의 제한을 공유합니다. 다른 모든 것보다 먼저 설정하세요. 게이트웨이는 `X-Forwarded-For` 헤더를 무시할 때 처음으로 경고를 기록합니다.

136* **많은 개발자가 몇 개의 NAT 또는 VPN 송신 주소를 공유합니다.** `trusted_proxies`가 올바를 때도 해당 주소의 제한을 공유합니다. [`rate_limits`](/docs/ko/claude-apps-gateway-config#http-tuning)를 맞추도록 올리세요.

137

138`max`를 크기 조정하려면, 개발자를 공유하는 송신 주소로 나누세요. 기본값인 10분인 하나의 `window_seconds` 기간 내에 그 중 몇 명이 로그인하는지 추정하세요. 그런 다음 재시도 및 Claude Code와 Claude Desktop 모두에 로그인하는 개발자를 포함하도록 두 배로 늘리세요.

139

140예를 들어, 4개의 송신 주소 뒤에 있는 10,000명의 개발자가 1시간에 걸쳐 균등하게 로그인합니다. 이는 주소당 2,500명의 개발자이고 각 10분마다 약 420명이며, 이를 두 배로 늘리고 1,000으로 올림합니다. 아래 예제는 두 제한을 모두 1,000으로 설정합니다:

141

142```yaml theme={null}

143rate_limits:

144 device_authorization: { max: 1000, window_seconds: 600 }

145 device_verify: { max: 1000, window_seconds: 600 }

146```

147

148`device_verify`는 누군가가 다른 개발자의 로그인 코드를 추측하는 것을 막는 것이므로, 추정이 필요한 만큼만 올리세요. 이 제한에서도, 코드는 20자 알파벳에서 8자이고 10분 후에 만료되므로, 추측은 비실용적으로 유지됩니다. [사용자 코드 무차별 대입 공격 저항](#user-code-brute-force-resistance)을 참조하세요.

149

150IdP가 새로고침 토큰을 발급할 때, Claude Code는 세션을 자동으로 갱신하므로, 롤아웃 후 제한을 다시 설정할 수 있습니다. 새로고침 토큰이 없으면, 개발자는 [`session.ttl_hours`](/docs/ko/claude-apps-gateway-config#session)마다 다시 로그인합니다. 해당 정상 상태 속도에 대해 두 제한을 모두 크기 조정하고 올린 상태로 유지하세요.

151

152제한에 도달하면, Claude Code v2.1.274 이상은 `The gateway is limiting sign-in attempts right now`를 표시합니다. v2.1.274 이상의 게이트웨이는 확인 페이지에 `Too many attempts came from your network address`를 표시하며, 확인할 설정이 있습니다. 또한 변경할 설정의 이름을 지정하는 `sign-in refused` 로그 라인을 작성합니다.

153

129<h2 id="operations">154<h2 id="operations">

130 운영155 운영

131</h2>156</h2>

160 185

161`/.well-known/oauth-authorization-server`의 OAuth 검색 문서는 구성 로드, OIDC 검색, 업스트림 클라이언트 구성 및 Postgres 마이그레이션이 모두 성공한 후에만 `200`을 반환하므로, 엔드 투 엔드 부팅 확인으로도 작동합니다.186`/.well-known/oauth-authorization-server`의 OAuth 검색 문서는 구성 로드, OIDC 검색, 업스트림 클라이언트 구성 및 Postgres 마이그레이션이 모두 성공한 후에만 `200`을 반환하므로, 엔드 투 엔드 부팅 확인으로도 작동합니다.

162 187

188<h3 id="concurrent-upstream-requests">

189 동시 업스트림 요청

190</h3>

191

192기본적으로 각 게이트웨이 복제본은 동시에 최대 256개의 요청을 업스트림으로 보냅니다. 스트리밍 응답은 스트림이 끝날 때까지 제한에 대해 계산됩니다.

193

194복제본이 제한에 있을 때 도착하는 요청은 게이트웨이 내에서 빈 슬롯을 기다립니다. 개발자는 시작이 느리거나 중단된 것처럼 보이는 응답을 봅니다. `provider: anthropic` 업스트림에서, [`timeouts.upstream_ttfb_ms`](/docs/ko/claude-apps-gateway-config#http-tuning)보다 오래 기다리는 요청은 해당 업스트림을 포기하고, 나중 업스트림이 이를 제공하지 않으면 502로 실패합니다.

195

196`upstream requests:`를 포함하는 시작 로그 줄은 적용 중인 제한을 보여줍니다. 복제본이 제한보다 더 많은 요청을 열어 두는 동안, 또한 `client requests are open`을 포함하는 경고를 최대 분당 한 번 기록합니다.

197

198동시에 더 많은 요청을 제공하려면 두 가지 옵션이 있습니다:

199

200* 복제본을 추가합니다.

201* 각 복제본의 제한을 높입니다. 게이트웨이 컨테이너에서 `BUN_CONFIG_MAX_HTTP_REQUESTS` 환경 변수를 1에서 65535 사이의 정수로 설정한 다음 컨테이너를 다시 시작합니다.

202

203복제본은 요청이 열려 있는 평균 초 수로 나눈 제한 정도의 요청 속도로 제한을 채웁니다. 예를 들어, 요청이 평균 10초 동안 열려 있으면, 기본 제한 256의 복제본은 약 초당 26개 요청으로 제한을 채웁니다.

204

205CPU에서 자동 스케일링하면, 제한의 복제본은 스케일 아웃을 트리거하지 않고 요청을 큐에 넣으므로, 복제본이 `client requests are open` 경고를 기록할 때 표시하는 CPU 수준 아래로 대상을 설정합니다.

206

207<Warning>

208 모든 열린 요청은 스트리밍 중 및 슬롯을 기다리는 동안 게이트웨이 프로세스에서 메모리를 보유합니다. 제한을 256으로 유지하면, 과부하 복제본의 메모리는 여전히 증가합니다. 대기 요청이 요청 본문을 유지하기 때문입니다. 컨테이너의 메모리를 피크 시 열린 요청 수에 맞게 크기를 조정하고, 제한을 변경할 때 메모리를 감시합니다. 메모리가 부족한 복제본은 종료되고 보유한 모든 스트림을 삭제합니다.

209</Warning>

210

163<h3 id="outage-behavior">211<h3 id="outage-behavior">

164 중단 동작212 중단 동작

165</h3>213</h3>

207 업그레이드255 업그레이드

208</h3>256</h3>

209 257

210복제본은 상태 비저장이므로 롤링 재시작은 언제든지 안전합니다. 게이트웨이는 부팅 시 스키마 마이그레이션을 실행하므로, 새 바이너리를 배포하면 데이터베이스가 자동으로 마이그레이션됩니다. 동시 복제본은 Postgres 자문 잠금에서 직렬화되므로 각 마이그레이션을 적용하는 것은 하나뿐입니다.258복제본은 상태 비저장이므로 롤링 재시작은 게이트웨이 상태를 잃지 않습니다. 게이트웨이는 부팅 시 스키마 마이그레이션을 실행하므로, 새 바이너리를 배포하면 데이터베이스가 자동으로 마이그레이션됩니다. 동시 복제본은 Postgres 자문 잠금에서 직렬화되므로 각 마이그레이션을 적용하는 것은 하나뿐입니다.

259

260오케스트레이터가 롤링 재시작 또는 스케일 인에서처럼 `SIGTERM`으로 복제본을 중지할 때, 게이트웨이는 새 연결을 수락하는 것을 중지하고 이미 진행 중인 요청 및 스트림이 종료되기 전에 완료되도록 합니다. 드레인 윈도우라고 불리는 최대 25초를 기다린 다음 여전히 열려 있는 것을 닫습니다. `SIGINT`(예: 터미널의 Ctrl+C)는 동일한 드레인을 시작하고, 드레인 중 두 번째 신호는 열린 요청을 닫고 즉시 종료합니다. 드레인은 게이트웨이 v2.1.274 이상이 필요합니다.

261

262긴 생성은 몇 분 동안 스트리밍할 수 있습니다. Kubernetes 및 Amazon ECS에서 이 둘을 함께 높여 해당 스트림에 더 많은 시간을 제공합니다:

263

264* **드레인 윈도우**: 게이트웨이 컨테이너에서 `CLAUDE_GATEWAY_DRAIN_TIMEOUT_MS` 환경 변수를 `120000`과 같은 양의 정수 밀리초로 설정합니다. 게이트웨이는 `120s`와 같은 다른 형식의 값을 무시하고 25초 기본값을 유지합니다

265* **오케스트레이터의 유예 기간**: Kubernetes의 `terminationGracePeriodSeconds` 또는 Amazon ECS의 `stopTimeout`

266

267유예 기간은 두 플랫폼 모두에서 기본값 30초입니다. 드레인 윈도우보다 최소 5초 이상 길게 유지하거나, 오케스트레이터가 드레인이 완료되기 전에 게이트웨이를 종료합니다. Kubernetes에서 유예 기간이 게이트웨이가 `SIGTERM`을 받을 때가 아니라 훅이 실행되기 전에 계산을 시작하기 때문에 `preStop` 훅의 기간도 추가합니다.

268

269플랫폼은 또한 드레인이 실행될 수 있는 기간을 제한할 수 있습니다:

270

271* **Amazon ECS on Fargate**: `stopTimeout`은 최대 120초를 허용합니다

272* **Cloud Run**: `SIGTERM` 후 10초 후에 인스턴스를 중지하므로, 열린 스트림은 드레인 윈도우가 무엇이든 최대 10초를 얻습니다

273

274드레인 윈도우가 여전히 열린 요청으로 끝나면, 게이트웨이는 `drain window over after`를 포함하는 경고를 기록하고, 자른 요청을 계산하며, 높일 두 설정의 이름을 지정합니다.

211 275

212마이그레이션은 추가 전용이므로 더 적은 마이그레이션을 아는 이전 바이너리로 롤백하는 것은 안전합니다. 추가 행을 무시합니다. 롤백은 또한 YAML을 이전 바이너리의 스키마에 대해 재검증하므로, 새 릴리스에서 도입한 키를 채택한 구성은 이전 바이너리에서 부팅이 실패합니다. 롤백 전에 새 키를 제거하세요.276마이그레이션은 추가 전용이므로 더 적은 마이그레이션을 아는 이전 바이너리로 롤백하는 것은 안전합니다. 추가 행을 무시합니다. 롤백은 또한 YAML을 이전 바이너리의 스키마에 대해 재검증하므로, 새 릴리스에서 도입한 키를 채택한 구성은 이전 바이너리에서 부팅이 실패합니다. 롤백 전에 새 키를 제거하세요.

213 277

239 303

240* 개발자는 원시 업스트림 키 대신 단기 JWT를 보유합니다. CLI-게이트웨이 레그는 RFC 8628 장치 부여를 사용하고, 게이트웨이의 IdP와의 인증 코드 교환은 기본 구성에서 PKCE를 실행하므로, 가로챈 IdP 인증 코드는 쓸모가 없습니다.304* 개발자는 원시 업스트림 키 대신 단기 JWT를 보유합니다. CLI-게이트웨이 레그는 RFC 8628 장치 부여를 사용하고, 게이트웨이의 IdP와의 인증 코드 교환은 기본 구성에서 PKCE를 실행하므로, 가로챈 IdP 인증 코드는 쓸모가 없습니다.

241* 장치 검증 페이지는 동일 출처 POST 및 RFC 8628 §5.1당 IP당 속도 제한을 적용합니다. [사용자 코드 무차별 대입 저항](#user-code-brute-force-resistance)을 참조하세요.305* 장치 검증 페이지는 동일 출처 POST 및 RFC 8628 §5.1당 IP당 속도 제한을 적용합니다. [사용자 코드 무차별 대입 저항](#user-code-brute-force-resistance)을 참조하세요.

242* 아웃바운드 요청은 DNS를 확인하고, 링크 로컬 및 클라우드 메타데이터 주소와 기본적으로 루프백을 차단하며, 연결을 확인된 IP에 고정하는 서버 측 요청 위조(SSRF) 가드를 통과합니다. 따라서 IdP 및 OTLP 대상과 같은 운영자 영향 URL은 클라우드 메타데이터 엔드포인트로 리디렉션될 수 없습니다. RFC 1918 프라이빗 범위는 의도적으로 허용됩니다. IdP 및 OTLP 수집기가 일반적으로 프라이빗 IP에 있기 때문입니다. 루프백 IdP 또는 `localhost`의 사이드카 OTLP 수집기와 같이 게이트웨이가 정당하게 도달해야 하는 것이 루프백에 있을 때만 게이트웨이의 환경에서 `CLAUDE_GATEWAY_ALLOW_LOOPBACK=1`을 설정하세요. 변수는 모든 운영자 구성 URL에 대해 루프백 블록을 완화하고 또한 포드가 클라우드 메타데이터 엔드포인트에 도달할 수 있는지 확인하는 부팅 시간 경고를 건너뜁니다. 따라서 수집기에 자체 내부 주소를 제공하는 것을 선호하세요.306* 게이트웨이의 IdP, OTLP 수집기 및 `provider: anthropic` 업스트림에 대한 요청은 DNS를 확인하고, 링크 로컬 및 클라우드 메타데이터 주소와 기본적으로 루프백을 차단하며, 연결을 확인된 IP에 고정하는 서버 측 요청 위조(SSRF) 가드를 통과합니다. 따라서 운영자 영향 URL은 클라우드 메타데이터 엔드포인트로 리디렉션될 수 없습니다. RFC 1918 프라이빗 범위는 의도적으로 허용됩니다. IdP 및 OTLP 수집기가 일반적으로 프라이빗 IP에 있기 때문입니다. 다른 공급자의 경우, 게이트웨이는 구성을 로드할 때 이러한 주소 또는 메타데이터 호스트명을 지정하는 `base_url`을 거부하고, 공급자의 SDK는 DNS 확인 없이 연결합니다.

307

308 [프록시 전용 송신](/docs/ko/claude-apps-gateway-config#proxy-only-egress)을 켜면, 해당 주소 확인이 포워드 프록시로 이동합니다: 게이트웨이는 호스트명을 전달하고 프록시의 허용 목록은 해당 대상을 거부해야 합니다.

309

310 게이트웨이가 정당하게 도달해야 하는 것이 루프백에 있을 때만 게이트웨이의 환경에서 `CLAUDE_GATEWAY_ALLOW_LOOPBACK=1`을 설정하세요. 예를 들어 로컬 개발 IdP 또는 `localhost`의 사이드카 OTLP 수집기. 변수는 모든 운영자 구성 URL에 대해 루프백 블록을 완화하고 또한 포드가 클라우드 메타데이터 엔드포인트에 도달할 수 있는지 확인하는 부팅 시간 경고를 건너뜁니다. 따라서 수집기에 자체 내부 주소를 제공하는 것을 선호하세요.

243 311

244자신의 송신 제어를 추가하면, 게이트웨이는 워크로드 ID와 같은 인스턴스 메타데이터 자격 증명을 사용할 때마다 메타데이터 서버에 도달해야 합니다.312자신의 송신 제어를 추가하면, 게이트웨이는 워크로드 ID와 같은 인스턴스 메타데이터 자격 증명을 사용할 때마다 메타데이터 서버에 도달해야 합니다.

245 313

254 322

255`user_code` 개발자가 `/device` 검증 페이지에 입력하는 것은 20자 알파벳에서 그려진 8자이며, 20⁸ 또는 약 2.56×10¹⁰ 조합을 산출하고 10분 후 만료됩니다.323`user_code` 개발자가 `/device` 검증 페이지에 입력하는 것은 20자 알파벳에서 그려진 8자이며, 20⁸ 또는 약 2.56×10¹⁰ 조합을 산출하고 10분 후 만료됩니다.

256 324

257게이트웨이는 [`rate_limits`](/docs/ko/claude-apps-gateway-config#http-tuning)를 통해 구성 가능한 장치 부여 엔드포인트에 IP당 속도 제한을 적용합니다. 많은 개발자가 단일 공유 회사 NAT 주소에서 로그인하면 제한을 올리세요. 제한은 로그인 흐름에만 적용되며 추론에는 적용되지 않습니다.325게이트웨이는 [`rate_limits`](/docs/ko/claude-apps-gateway-config#http-tuning)를 통해 구성 가능한 장치 부여 엔드포인트에 IP당 속도 제한을 적용합니다. 많은 개발자가 단일 공유 회사 NAT 주소에서 로그인하면 제한을 올리세요. [대규모 롤아웃](#large-rollouts)은 크기를 조정하는 방법을 보여줍니다. 제한은 로그인 흐름에만 적용되며 추론에는 적용되지 않습니다.

258 326

259<h3 id="compliance-posture">327<h3 id="compliance-posture">

260 규정 준수 태세328 규정 준수 태세

284gateway stderr에는 감사 이벤트 스트림이 포함되고, 감사 로그는 개발자 신원을 기록하며, 디버그 파일은 개발자 머신의 hook 및 MCP 서버 출력을 기록합니다. 공개 이슈에 게시하기 전에 이를 검토하고 수정하세요.352gateway stderr에는 감사 이벤트 스트림이 포함되고, 감사 로그는 개발자 신원을 기록하며, 디버그 파일은 개발자 머신의 hook 및 MCP 서버 출력을 기록합니다. 공개 이슈에 게시하기 전에 이를 검토하고 수정하세요.

285 353

286| 증상 | 원인 | 해결 방법 |354| 증상 | 원인 | 해결 방법 |

287| --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |355| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

288| 개발자의 `/login`이 **Cloud gateway** 화면 대신 표준 계정 선택기를 표시함 | 해당 머신의 관리 설정에서 `forceLoginMethod` 또는 `forceLoginGatewayUrl`이 설정되지 않음 | [관리 설정 파일](/docs/ko/claude-apps-gateway#set-the-gateway-url)을 기기에 배포하세요. `/login`은 여기서 gateway URL을 읽습니다 |356| 개발자의 `/login`이 **Cloud gateway** 화면 대신 표준 계정 선택기를 표시함 | 해당 머신의 관리 설정에서 `forceLoginMethod` 또는 `forceLoginGatewayUrl`이 설정되지 않음 | [관리 설정 파일](/docs/ko/claude-apps-gateway#set-the-gateway-url)을 기기에 배포하세요. `/login`은 여기서 gateway URL을 읽습니다 |

289| 개발자의 요청이 `Not signed in to the Cloud gateway — run /login.`으로 실패함 | 머신의 관리 설정이 `forceLoginMethod: "gateway"` 또는 `forceLoginGatewayUrl`을 설정했고, 세션에 gateway 로그인이 없음. 남은 claude.ai 로그인은 요구사항을 충족하지 않음 | 개발자가 `/login`을 실행하고 gateway 로그인을 완료하도록 하세요. [관리자 정책이 Cloud gateway 로그인을 요구함](/docs/ko/errors#administrator-policy-requires-a-cloud-gateway-sign-in)도 참조하세요. |357| 개발자의 요청이 `Not signed in to the Cloud gateway — run /login.`으로 실패함 | 머신의 관리 설정이 `forceLoginMethod: "gateway"` 또는 `forceLoginGatewayUrl`을 설정했고, 세션에 gateway 로그인이 없음. 남은 claude.ai 로그인은 요구사항을 충족하지 않음 | 개발자가 `/login`을 실행하고 gateway 로그인을 완료하도록 하세요. [관리자 정책이 Cloud gateway 로그인을 요구함](/docs/ko/errors#administrator-policy-requires-a-cloud-gateway-sign-in)도 참조하세요. |

290| Claude Desktop이 부트스트랩 구성을 가져올 수 없다고 보고함 | `/user/bootstrap`이 404를 반환함: 사용자와 일치하는 정책이 `desktop` 키를 포함하지 않거나 일치하는 정책이 없음. gateway 감사 로그는 각 거부를 `desktop_bootstrap.denied`로 이유와 함께 기록함 | 사용자와 일치하는 정책 또는 `match: {}` 기본 계층에 `desktop` 블록을 추가하세요. 빈 `desktop: {}`으로 충분합니다. [Claude Desktop 오버레이](/docs/ko/claude-apps-gateway-config#claude-desktop-overlay)를 참조하세요. |358| Claude Desktop이 부트스트랩 구성을 가져올 수 없다고 보고함 | `/user/bootstrap`이 404를 반환함: 사용자와 일치하는 정책이 `desktop` 키를 포함하지 않거나 일치하는 정책이 없음. gateway 감사 로그는 각 거부를 `desktop_bootstrap.denied`로 이유와 함께 기록함 | 사용자와 일치하는 정책 또는 `match: {}` 기본 계층에 `desktop` 블록을 추가하세요. 빈 `desktop: {}`으로 충분합니다. [Claude Desktop 오버레이](/docs/ko/claude-apps-gateway-config#claude-desktop-overlay)를 참조하세요. |

291| 시작 시 `Gateway login is configured in managed settings, but this Claude Code build does not include Cloud gateway support.`를 표시함 | 설치된 Claude Code 빌드가 gateway 지원보다 이전 버전임 | 개발자가 Cloud gateway 지원을 포함하는 릴리스로 Claude Code를 업데이트하도록 하세요 |359| 시작 시 `Gateway login is configured in managed settings, but this Claude Code build does not include Cloud gateway support.`를 표시함 | 설치된 Claude Code 빌드가 gateway 지원보다 이전 버전임 | 개발자가 Cloud gateway 지원을 포함하는 릴리스로 Claude Code를 업데이트하도록 하세요 |

292| 시작이 `Administrator policy requires a Cloud gateway sign-in on this machine`으로 종료됨 | 개발자의 환경이 `ANTHROPIC_API_KEY` 또는 `ANTHROPIC_AUTH_TOKEN`을 설정하거나, 설정이 [`apiKeyHelper`](/docs/ko/settings-reference#apikeyhelper)를 구성하거나, 이전 Claude Console 로그인의 API 키가 여전히 저장되어 있음 | 해당하는 각각을 지우도록 개발자에게 지시하세요: 변수를 설정 해제하거나, `apiKeyHelper` 항목을 제거하거나, `claude auth logout`을 실행하여 저장된 키를 제거합니다. 그런 다음 `claude`를 시작하고 `/login`으로 로그인하도록 하세요. [관리자 정책이 Cloud gateway 로그인을 요구함](/docs/ko/errors#administrator-policy-requires-a-cloud-gateway-sign-in)도 참조하세요. |360| 시작이 `Administrator policy requires a Cloud gateway sign-in on this machine`으로 종료됨 | 개발자의 환경이 `ANTHROPIC_API_KEY` 또는 `ANTHROPIC_AUTH_TOKEN`을 설정하거나, 설정이 [`apiKeyHelper`](/docs/ko/settings-reference#apikeyhelper)를 구성하거나, 이전 Claude Console 로그인의 API 키가 여전히 저장되어 있음 | 해당하는 각각을 지우도록 개발자에게 지시하세요: 변수를 설정 해제하거나, `apiKeyHelper` 항목을 제거하거나, `claude auth logout`을 실행하여 저장된 키를 제거합니다. 그런 다음 `claude`를 시작하고 `/login`으로 로그인하도록 하세요. [관리자 정책이 Cloud gateway 로그인을 요구함](/docs/ko/errors#administrator-policy-requires-a-cloud-gateway-sign-in)도 참조하세요. |

293| 시작 또는 `/login`이 `/managed/settings` 로드에서 403 후 `Claude Code may not be enabled for your organization`을 보고함 | gateway 또는 그 앞의 무언가가 `/managed/settings` 요청에 403으로 응답함. gateway 자체 설정 경로는 절대 403으로 응답하지 않음. 상태는 [`access_control`](/docs/ko/claude-apps-gateway-config#http-tuning) IP 확인 또는 gateway 앞의 프록시 또는 WAF에서 옴. 감사 로그는 IP 확인 거부를 `access.denied`로 이유와 함께 기록함. 개발자는 로그인 상태를 유지함 | 실패 시간에 `access.denied`에 대한 감사 로그를 확인하고 `access_control` 목록 또는 프론트 엔드를 수정한 후 개발자가 `claude`를 다시 시작하도록 하세요 |361| 시작 또는 `/login`이 `/managed/settings` 로드에서 403 후 `Claude Code may not be enabled for your organization`을 보고함 | gateway 또는 그 앞의 무언가가 `/managed/settings` 요청에 403으로 응답함. gateway 자체 설정 경로는 절대 403으로 응답하지 않음. 상태는 [`access_control`](/docs/ko/claude-apps-gateway-config#http-tuning) IP 확인 또는 gateway 앞의 프록시 또는 WAF에서 옴. 감사 로그는 IP 확인 거부를 `access.denied`로 이유와 함께 기록함. 개발자는 로그인 상태를 유지함 | 실패 시간에 `access.denied`에 대한 감사 로그를 확인하고 `access_control` 목록 또는 프론트 엔드를 수정한 후 개발자가 `claude`를 다시 시작하도록 하세요 |

362| CLI `/login`: `The gateway is limiting sign-in attempts right now`, 또는 이전 버전에서 `Request failed with status code 429`. `/device` 페이지는 이전에 시도하지 않은 개발자에게 `Too many attempts`를 표시할 수 있음 | IP당 로그인 속도 제한에 도달함. `listen.trusted_proxies`가 로드 밸런서를 포함하지 않아 모든 개발자가 해당 주소를 공유하거나, 많은 개발자가 NAT 또는 VPN 송신 주소를 공유함. `result: rate_limited`가 있는 감사 이벤트는 동일한 하나 또는 몇 개의 `client_ip` 값을 표시함. | 먼저 `listen.trusted_proxies`를 로드 밸런서의 소스 범위로 설정한 후, 개발자가 여전히 주소를 공유하는 경우 `rate_limits`를 높이세요. [대규모 롤아웃](#large-rollouts)을 참조하세요. |

294| CLI `/login`: `Gateway hosts must be on your organization's private network; <host> resolves to the public (or unrecognized) address <ip>` | gateway 호스트명이 최소 하나의 공개 IP 주소로 확인됨. Claude Code는 각 확인된 주소를 확인하고 모든 주소가 비공개여야 함. 일반적인 원인은 한 패밀리가 공개 주소로 확인되는 이중 스택 이름이며, AWS 내부 이중 스택 로드 밸런서를 포함하여 공개 범위 AAAA 주소를 반환함 | gateway 이름이 개발자 머신에서 비공개 주소로만 확인되도록 하세요. 이중 스택 이름의 경우 공개 범위 레코드를 삭제하거나 별도의 내부 전용 DNS 이름을 제공하세요. [비공개 네트워크 전제 조건](/docs/ko/claude-apps-gateway#prerequisites)을 참조하세요. 주소가 조직이 소유하고 내부적으로 사용하는 공개 공간인 경우 [해당 블록을 선언](/docs/ko/claude-apps-gateway#allow-a-gateway-on-public-address-space-you-own)하세요. |363| CLI `/login`: `Gateway hosts must be on your organization's private network; <host> resolves to the public (or unrecognized) address <ip>` | gateway 호스트명이 최소 하나의 공개 IP 주소로 확인됨. Claude Code는 각 확인된 주소를 확인하고 모든 주소가 비공개여야 함. 일반적인 원인은 한 패밀리가 공개 주소로 확인되는 이중 스택 이름이며, AWS 내부 이중 스택 로드 밸런서를 포함하여 공개 범위 AAAA 주소를 반환함 | gateway 이름이 개발자 머신에서 비공개 주소로만 확인되도록 하세요. 이중 스택 이름의 경우 공개 범위 레코드를 삭제하거나 별도의 내부 전용 DNS 이름을 제공하세요. [비공개 네트워크 전제 조건](/docs/ko/claude-apps-gateway#prerequisites)을 참조하세요. 주소가 조직이 소유하고 내부적으로 사용하는 공개 공간인 경우 [해당 블록을 선언](/docs/ko/claude-apps-gateway#allow-a-gateway-on-public-address-space-you-own)하세요. |

295| CLI `/login`: `Gateway login would go through proxy <proxy>, which is not on a private network` | `HTTPS_PROXY` 또는 `HTTP_PROXY`가 gateway 호스트에 적용되고 프록시의 호스트명이 공개 주소로 확인됨. 호스트가 비공개 주소로만 확인되는 프록시는 허용되며 이 오류를 트리거하지 않음 | 개발자 머신의 `NO_PROXY`에 gateway 호스트를 추가하여 연결이 직접 이루어지도록 하거나, 호스트명이 비공개 주소로 확인되는 프록시를 사용하세요. 메시지는 추가할 정확한 `NO_PROXY` 항목을 이름으로 지정합니다 |364| CLI `/login`: `Gateway login would go through proxy <proxy>, which is not on a private network` | `HTTPS_PROXY` 또는 `HTTP_PROXY`가 gateway 호스트에 적용되고 프록시의 호스트명이 공개 주소로 확인됨. 호스트가 비공개 주소로만 확인되는 프록시는 허용되며 이 오류를 트리거하지 않음 | 개발자 머신의 `NO_PROXY`에 gateway 호스트를 추가하여 연결이 직접 이루어지도록 하거나, 호스트명이 비공개 주소로 확인되는 프록시를 사용하세요. 메시지는 추가할 정확한 `NO_PROXY` 항목을 이름으로 지정합니다 |

296| CLI `/login`: `Claude Code only signs in to <host> from inside its declared network <block> (managed settings), and this machine is connecting from <ip>, outside it` | gateway가 [`gatewayInternalNetworks`](/docs/ko/claude-apps-gateway#allow-a-gateway-on-public-address-space-you-own)에 선언된 블록에 있고, 개발자 머신이 해당 블록 외부의 주소에서 도달함: VPN 주소 풀, 컨테이너 또는 WSL2 NAT 세그먼트, 또는 조직의 네트워크가 아님 | 개발자가 네트워크의 호스트 OS에서 `/login`을 실행하도록 하세요. 표시된 주소도 조직의 공개 공간인 경우 gateway 항목을 두 주소를 모두 포함하는 블록으로 바꾸세요(`/8`까지). 두 번째 겹치는 항목은 거부됩니다 |365| CLI `/login`: `Claude Code only signs in to <host> from inside its declared network <block> (managed settings), and this machine is connecting from <ip>, outside it` | gateway가 [`gatewayInternalNetworks`](/docs/ko/claude-apps-gateway#allow-a-gateway-on-public-address-space-you-own)에 선언된 블록에 있고, 개발자 머신이 해당 블록 외부의 주소에서 도달함: VPN 주소 풀, 컨테이너 또는 WSL2 NAT 세그먼트, 또는 조직의 네트워크가 아님 | 개발자가 네트워크의 호스트 OS에서 `/login`을 실행하도록 하세요. 표시된 주소도 조직의 공개 공간인 경우 gateway 항목을 두 주소를 모두 포함하는 블록으로 바꾸세요(`/8`까지). 두 번째 겹치는 항목은 거부됩니다 |

302| 부트가 `store.postgres_url`을 이름으로 지정하는 구성 검증 오류로 종료됨 | Postgres가 구성되지 않음. gateway는 Postgres를 요구함 | `store.postgres_url`을 설정하세요. 로컬 개발의 경우 일회용 컨테이너를 사용하세요: `docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres`. |371| 부트가 `store.postgres_url`을 이름으로 지정하는 구성 검증 오류로 종료됨 | Postgres가 구성되지 않음. gateway는 Postgres를 요구함 | `store.postgres_url`을 설정하세요. 로컬 개발의 경우 일회용 컨테이너를 사용하세요: `docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres`. |

304| 부트가 `config.load` 후 OIDC 검색 오류로 종료됨 | `oidc.issuer`에 도달할 수 없거나 TLS 체인을 신뢰하지 않음 | 발급자가 포드에서 도달 가능하고 `/.well-known/openid-configuration`을 제공하는지 확인하세요. 비공개 PKI의 경우 `ca_cert_pem`을 설정하세요. 포드가 정방향 프록시를 통해서만 IdP에 도달하는 경우 [`oidc.use_proxy: true`](/docs/ko/claude-apps-gateway-config#idp-requests-through-a-forward-proxy)를 설정하세요. v2.1.227 이전 버전에서는 대신 포드에 IdP의 각 엔드포인트에 대한 직접 경로를 제공하세요. |373| 부트가 `config.load` 후 OIDC 검색 오류로 종료됨 | `oidc.issuer`에 도달할 수 없거나 TLS 체인을 신뢰하지 않음 | 발급자가 포드에서 도달 가능하고 `/.well-known/openid-configuration`을 제공하는지 확인하세요. 비공개 PKI의 경우 `ca_cert_pem`을 설정하세요. 포드가 정방향 프록시를 통해서만 IdP에 도달하는 경우 [`oidc.use_proxy: true`](/docs/ko/claude-apps-gateway-config#idp-requests-through-a-forward-proxy)를 설정하세요. v2.1.227 이전 버전에서는 대신 포드에 IdP의 각 엔드포인트에 대한 직접 경로를 제공하세요. 포드가 IdP의 호스트명을 확인할 수 없거나 프록시가 IP 주소에 대한 `CONNECT`를 거부하는 경우 [프록시 전용 송신](/docs/ko/claude-apps-gateway-config#proxy-only-egress)을 참조하세요. v2.1.277 이상이 필요합니다. |

375| 로그: `could not connect to Postgres at boot, attempt 1 of 3` | gateway가 시작될 때 데이터베이스에 도달할 수 없었음. 예를 들어 네트워크가 아직 시작 중인 콜드 인스턴스 | gateway가 부팅을 완료하면 조치가 필요하지 않습니다. 데이터베이스에 도달할 수 없을 때 gateway는 종료되기 전에 2초 간격으로 연결을 3번 시도합니다. `could not connect to Postgres`로 종료되면 `store.postgres_url`과 데이터베이스로의 네트워크 경로를 확인하세요. 시도가 거부되지 않고 시간 초과되면 각 시도에 더 많은 시간을 주기 위해 [`store.connect_timeout_seconds`](/docs/ko/claude-apps-gateway-config#store)를 높이세요. |

306| `/oauth/callback`이 "Sign-in could not be completed"를 표시함 | 이메일 도메인이 거부됨, id\_token 검증 실패, 또는 `email_verified`가 명시적으로 `false`이며 gateway는 항상 재정의 없이 거부함 | `allowed_email_domains`을 확인하고 IdP가 확인된 `email` 클레임을 반환하는지 확인하세요. `email_verified: false`의 경우 IdP 측 검증을 수정하세요. IdP가 다른 클레임 이름 아래에서 이메일을 내보내는 경우 `oidc.email_claim`을 설정하세요. |376| `/oauth/callback`이 "Sign-in could not be completed"를 표시함 | 이메일 도메인이 거부됨, id\_token 검증 실패, 또는 `email_verified`가 명시적으로 `false`이며 gateway는 항상 재정의 없이 거부함 | `allowed_email_domains`을 확인하고 IdP가 확인된 `email` 클레임을 반환하는지 확인하세요. `email_verified: false`의 경우 IdP 측 검증을 수정하세요. IdP가 다른 클레임 이름 아래에서 이메일을 내보내는 경우 `oidc.email_claim`을 설정하세요. |

307| 로그: `token exchange failed request_id=<id>: id_token missing email claim` | IdP가 기본적으로 id\_token에 `email`을 포함하지 않음. 이 거부는 `allowed_email_domains`이 설정된 경우에만 발생함. 없으면 누락된 이메일이 이메일 없이 세션을 발행함 | IdP를 구성하여 id\_token에 `email`을 내보내도록 하세요. Okta: 사용자 정의 권한 부여 서버의 ID 토큰 클레임에 `email`을 추가하세요. Entra: 앱 등록에서 `email`을 선택적 클레임으로 추가하세요. PingFederate: `email`을 내보내는 OpenID Connect 정책을 활성화하세요. IdP가 userinfo 엔드포인트에서 `email`을 제공하지만 id\_token에 포함하지 않는 경우(예: Okta org 권한 부여 서버) `oidc.userinfo_fallback: true`를 설정하세요. |377| 로그: `token exchange failed request_id=<id>: id_token missing email claim` | IdP가 기본적으로 id\_token에 `email`을 포함하지 않음. 이 거부는 `allowed_email_domains`이 설정된 경우에만 발생함. 없으면 누락된 이메일이 이메일 없이 세션을 발행함 | IdP를 구성하여 id\_token에 `email`을 내보내도록 하세요. Okta: 사용자 정의 권한 부여 서버의 ID 토큰 클레임에 `email`을 추가하세요. Entra: 앱 등록에서 `email`을 선택적 클레임으로 추가하세요. PingFederate: `email`을 내보내는 OpenID Connect 정책을 활성화하세요. IdP가 userinfo 엔드포인트에서 `email`을 제공하지만 id\_token에 포함하지 않는 경우(예: Okta org 권한 부여 서버) `oidc.userinfo_fallback: true`를 설정하세요. |

308| 로그: `refresh failed request_id=<id>: invalid_token (…) (at userinfo_no_id_token, …)`, 개발자가 매 `session.ttl_hours`마다 `Cloud gateway session expired`를 봄 | IdP가 새로 고침 토큰을 수락했지만 함께 id\_token을 반환하지 않았으므로 gateway가 IdP의 userinfo 엔드포인트에 사용자의 클레임을 요청했습니다. IdP가 새로 고쳐진 액세스 토큰을 거기서 거부했습니다. gateway가 `temporarily_unavailable`으로 응답하므로 Claude Code는 새로 고침 토큰을 유지하지만 세션을 갱신할 수 없습니다. v2.1.260 이전의 gateway 버전은 `(at …)` 세부 정보 없이 동일한 줄을 기록합니다. | [`oidc.scope_on_refresh: true`](/docs/ko/claude-apps-gateway-config#oidc)를 설정하세요. gateway v2.1.260 이상에서 사용 가능하므로 새로 고침 요청이 `openid`를 다시 요청합니다. Okta와 같은 일부 IdP는 요청할 때만 새로 고침 시 id\_token을 반환합니다. PingFederate에서는 대신 **Applications > OAuth > OpenID Connect Policy Management** 아래에서 **Return ID Token On Refresh Grant**를 활성화하세요. 키는 PingFederate의 동작을 변경하지 않습니다. 여전히 생략하는 다른 IdP의 경우 userinfo 엔드포인트가 새로 고침으로 발급된 액세스 토큰을 수락하는지 확인하세요. 임시 방편으로 [`session.ttl_hours`](/docs/ko/claude-apps-gateway-config#session)를 높이세요. 프로비저닝 해제 트레이드오프는 [Identity provider setup](#identity-provider-setup)을 참조하세요. |378| 로그: `refresh failed request_id=<id>: invalid_token (…) (at userinfo_no_id_token, …)`, 개발자가 매 `session.ttl_hours`마다 `Cloud gateway session expired`를 봄 | IdP가 새로 고침 토큰을 수락했지만 함께 id\_token을 반환하지 않았으므로 gateway가 IdP의 userinfo 엔드포인트에 사용자의 클레임을 요청했습니다. IdP가 새로 고쳐진 액세스 토큰을 거기서 거부했습니다. gateway가 `temporarily_unavailable`으로 응답하므로 Claude Code는 새로 고침 토큰을 유지하지만 세션을 갱신할 수 없습니다. v2.1.260 이전의 gateway 버전은 `(at …)` 세부 정보 없이 동일한 줄을 기록합니다. | [`oidc.scope_on_refresh: true`](/docs/ko/claude-apps-gateway-config#oidc)를 설정하세요. gateway v2.1.260 이상에서 사용 가능하므로 새로 고침 요청이 `openid`를 다시 요청합니다. Okta와 같은 일부 IdP는 요청할 때만 새로 고침 시 id\_token을 반환합니다. PingFederate에서는 대신 **Applications > OAuth > OpenID Connect Policy Management** 아래에서 **Return ID Token On Refresh Grant**를 활성화하세요. 키는 PingFederate의 동작을 변경하지 않습니다. 여전히 생략하는 다른 IdP의 경우 userinfo 엔드포인트가 새로 고침으로 발급된 액세스 토큰을 수락하는지 확인하세요. 임시 방편으로 [`session.ttl_hours`](/docs/ko/claude-apps-gateway-config#session)를 높이세요. 프로비저닝 해제 트레이드오프는 [Identity provider setup](#identity-provider-setup)을 참조하세요. |

309| 모든 Amazon Bedrock 요청이 502를 반환함. 로그가 `Could not load credentials from any providers`를 표시함 | EC2에서 IMDSv2의 기본 홉 제한 1이 컨테이너 내부의 인스턴스 메타데이터 요청을 차단함. 부트 및 `/readyz`는 AWS SDK가 클라이언트 구성이 아닌 첫 번째 요청에서 인스턴스 자격 증명을 확인하므로 어쨌든 통과함 | `aws ec2 modify-instance-metadata-options --instance-id <id> --http-put-response-hop-limit 2`로 홉 제한을 높이거나 시작 템플릿에서 설정하세요. 변경 사항은 인스턴스의 모든 컨테이너에 적용됩니다. 가능한 경우 ECS 작업 역할을 선호하세요. 이는 ECS 컨테이너 자격 증명 엔드포인트에서 자격 증명을 읽고 변경을 완전히 피하거나, 노출을 제한하기 위해 전용 gateway 인스턴스에 변경을 적용하세요. |379| 모든 Amazon Bedrock 요청이 502를 반환함. 로그가 `Could not load credentials from any providers`를 표시함 | EC2에서 IMDSv2의 기본 홉 제한 1이 컨테이너 내부의 인스턴스 메타데이터 요청을 차단함. 부트 및 `/readyz`는 AWS SDK가 클라이언트 구성이 아닌 첫 번째 요청에서 인스턴스 자격 증명을 확인하므로 어쨌든 통과함 | `aws ec2 modify-instance-metadata-options --instance-id <id> --http-put-response-hop-limit 2`로 홉 제한을 높이거나 시작 템플릿에서 설정하세요. 변경 사항은 인스턴스의 모든 컨테이너에 적용됩니다. 가능한 경우 ECS 작업 역할을 선호하세요. 이는 ECS 컨테이너 자격 증명 엔드포인트에서 자격 증명을 읽고 변경을 완전히 피하거나, 노출을 제한하기 위해 전용 gateway 인스턴스에 변경을 적용하세요. |

380| 피크 로드에서 응답이 시작되기 느리거나 중단된 것처럼 보이거나, 업스트림이 정상인데도 502 `all upstreams failed`로 실패함 | 복제본이 업스트림으로 한 번에 보내는 것보다 더 많은 요청을 열어 두었으므로 추가 요청은 gateway 내부에서 대기함. `provider: anthropic` 업스트림에서 `timeouts.upstream_ttfb_ms`보다 오래 대기하는 요청은 해당 업스트림을 포기하며, 이후 업스트림이 제공하지 않으면 502를 생성함. 로그는 `client requests are open`을 포함하는 경고를 표시함. | 복제본을 추가하거나 각 복제본의 제한을 높이세요. [동시 업스트림 요청](#concurrent-upstream-requests)을 참조하세요. |

310| IdP 오류: unknown or unsupported scope | IdP가 인식하지 못하는 범위를 거부함 | `oidc.scopes`를 정확히 IdP가 수락하는 목록으로 설정하세요. `openid`를 포함해야 합니다. 기본값은 `openid profile email offline_access`입니다. |381| IdP 오류: unknown or unsupported scope | IdP가 인식하지 못하는 범위를 거부함 | `oidc.scopes`를 정확히 IdP가 수락하는 목록으로 설정하세요. `openid`를 포함해야 합니다. 기본값은 `openid profile email offline_access`입니다. |

311| `oidc.scopes` 설정 후 세션이 자동으로 갱신되지 않음 | `offline_access`가 재정의에서 삭제됨 | IdP가 지원하는 경우 `offline_access`를 다시 추가하세요. 새로 고침 토큰 없이 개발자는 매 `session.ttl_hours`마다 브라우저 로그인을 다시 실행합니다. |382| `oidc.scopes` 설정 후 세션이 자동으로 갱신되지 않음 | `offline_access`가 재정의에서 삭제됨 | IdP가 지원하는 경우 `offline_access`를 다시 추가하세요. 새로 고침 토큰 없이 개발자는 매 `session.ttl_hours`마다 브라우저 로그인을 다시 실행합니다. |

claude-apps-gateway-on-aws.md +1 −1

Details

500| Bedrock 요청이 `403 AccessDeniedException`을 반환합니다. | 계정이 Anthropic의 일회성 사용 사례 양식을 제출하지 않았거나, 계정의 첫 호출에서 시작되는 자동 AWS Marketplace 구독이 아직 완료되지 않았거나, 작업 역할의 정책이 추론 프로필 또는 기초 모델 ARN을 누락했습니다. | Bedrock 콘솔의 모델 카탈로그에서 사용 사례 양식을 제출하십시오. 방금 제출되었거나 이것이 계정의 첫 호출인 경우 몇 분 후에 다시 시도하십시오. `bedrock:InvokeModel` 및 `bedrock:InvokeModelWithResponseStream`을 두 ARN 패밀리에 부여하십시오. |500| Bedrock 요청이 `403 AccessDeniedException`을 반환합니다. | 계정이 Anthropic의 일회성 사용 사례 양식을 제출하지 않았거나, 계정의 첫 호출에서 시작되는 자동 AWS Marketplace 구독이 아직 완료되지 않았거나, 작업 역할의 정책이 추론 프로필 또는 기초 모델 ARN을 누락했습니다. | Bedrock 콘솔의 모델 카탈로그에서 사용 사례 양식을 제출하십시오. 방금 제출되었거나 이것이 계정의 첫 호출인 경우 몇 분 후에 다시 시도하십시오. `bedrock:InvokeModel` 및 `bedrock:InvokeModelWithResponseStream`을 두 ARN 패밀리에 부여하십시오. |

501| Bedrock이 온디맨드 처리량이 지원되지 않는다고 말하는 `ValidationException`을 반환합니다. | 사용자 정의 `models:` 항목이 지역이 추론 프로필을 통해서만 제공하는 일반 기초 모델 ID로 매핑됩니다. | 모델을 교차 지역 추론 프로필 ID(`us.anthropic.*`)로 매핑하십시오. 기본 제공 카탈로그는 이미 이를 수행합니다. |501| Bedrock이 온디맨드 처리량이 지원되지 않는다고 말하는 `ValidationException`을 반환합니다. | 사용자 정의 `models:` 항목이 지역이 추론 프로필을 통해서만 제공하는 일반 기초 모델 ID로 매핑됩니다. | 모델을 교차 지역 추론 프로필 ID(`us.anthropic.*`)로 매핑하십시오. 기본 제공 카탈로그는 이미 이를 수행합니다. |

502| ECS 작업이 게이트웨이가 아무것도 로깅하기 전에 `ResourceInitializationError`로 중지됩니다. | 실행 역할이 Secrets Manager 비밀을 읽을 수 없거나, 프라이빗 서브넷이 Secrets Manager 또는 ECR로의 경로가 없습니다. | 실행 역할에 3개의 `gateway-` 비밀 ARN에 대해 `secretsmanager:GetSecretValue`를 부여하고, NAT 게이트웨이를 통해 이그레스를 제공하거나, 없으면 Secrets Manager, ECR, CloudWatch Logs에 대한 인터페이스 엔드포인트를 제공하십시오. `awslogs` 드라이버는 동일한 단계에서 이들이 필요합니다. 또한 S3 게이트웨이 엔드포인트를 제공하십시오. |502| ECS 작업이 게이트웨이가 아무것도 로깅하기 전에 `ResourceInitializationError`로 중지됩니다. | 실행 역할이 Secrets Manager 비밀을 읽을 수 없거나, 프라이빗 서브넷이 Secrets Manager 또는 ECR로의 경로가 없습니다. | 실행 역할에 3개의 `gateway-` 비밀 ARN에 대해 `secretsmanager:GetSecretValue`를 부여하고, NAT 게이트웨이를 통해 이그레스를 제공하거나, 없으면 Secrets Manager, ECR, CloudWatch Logs에 대한 인터페이스 엔드포인트를 제공하십시오. `awslogs` 드라이버는 동일한 단계에서 이들이 필요합니다. 또한 S3 게이트웨이 엔드포인트를 제공하십시오. |

503| 게이트웨이 부팅이 Postgres 연결 시간 초과 오류로 종료됩니다. | 데이터베이스 보안 그룹이 5432에서 게이트웨이의 보안 그룹을 허용하지 않거나, 서비스가 데이터베이스의 VPC 외부에서 실행됩니다. 저장소는 5초 후 대기를 중지합니다. | 데이터베이스의 보안 그룹에서 게이트웨이의 보안 그룹의 5432를 허용하고, 서비스를 DB 서브넷 그룹과 동일한 VPC에서 실행하십시오. |503| 게이트웨이 부팅이 Postgres 연결 시간 초과 오류로 종료됩니다. | 데이터베이스 보안 그룹이 5432에서 게이트웨이의 보안 그룹을 허용하지 않거나, 서비스가 데이터베이스의 VPC 외부에서 실행됩니다. | 데이터베이스의 보안 그룹에서 게이트웨이의 보안 그룹의 5432를 허용하고, 서비스를 DB 서브넷 그룹과 동일한 VPC에서 실행하십시오. |

504| 게이트웨이 부팅이 Postgres TLS 인증서 확인 오류로 종료됩니다. | 연결 문자열이 `sslmode=verify-full`을 설정하지만 이미지가 RDS CA 번들을 신뢰하지 않습니다: 번들이 이미지에 복사되지 않았거나 `NODE_EXTRA_CA_CERTS`가 이를 가리키지 않습니다. | 번들을 복사하고 `NODE_EXTRA_CA_CERTS`를 설정하는 빌드 단계의 2개 Dockerfile 줄을 추가하고, 다시 빌드하고, 새 태그 아래에서 푸시하고, 다시 배포하십시오. |504| 게이트웨이 부팅이 Postgres TLS 인증서 확인 오류로 종료됩니다. | 연결 문자열이 `sslmode=verify-full`을 설정하지만 이미지가 RDS CA 번들을 신뢰하지 않습니다: 번들이 이미지에 복사되지 않았거나 `NODE_EXTRA_CA_CERTS`가 이를 가리키지 않습니다. | 번들을 복사하고 `NODE_EXTRA_CA_CERTS`를 설정하는 빌드 단계의 2개 Dockerfile 줄을 추가하고, 다시 빌드하고, 새 태그 아래에서 푸시하고, 다시 배포하십시오. |

505| 스트리밍 응답이 조용한 기간 후 중간에 떨어집니다. | v2.1.229보다 오래된 게이트웨이가 Bedrock 또는 AWS 업스트림의 Claude Platform에서 업스트림이 조용할 때 아무것도 보내지 않습니다. 예를 들어 스트리밍된 출력이 없는 확장 사고 중입니다. ALB는 기본적으로 60초 동안 데이터가 없는 연결을 닫으므로 그 간격에서 스트림을 자릅니다. v2.1.229 이상의 게이트웨이는 조용한 스트림을 해당 시간 초과 아래에서 유지합니다: 이러한 업스트림에서 게이트웨이는 스트림 데이터가 없는 약 15초가 지나면 SSE `ping` 이벤트를 한 번 내보내고, Anthropic API 업스트림에서는 API 자체의 핑을 중계합니다. | 게이트웨이를 v2.1.229 이상으로 업데이트하거나, `idle_timeout.timeout_seconds` 속성을 `3600`으로 설정하십시오. `modify-load-balancer-attributes`를 통해 또는 EKS의 `load-balancer-attributes` Ingress 주석을 통해 설정하십시오. |505| 스트리밍 응답이 조용한 기간 후 중간에 떨어집니다. | v2.1.229보다 오래된 게이트웨이가 Bedrock 또는 AWS 업스트림의 Claude Platform에서 업스트림이 조용할 때 아무것도 보내지 않습니다. 예를 들어 스트리밍된 출력이 없는 확장 사고 중입니다. ALB는 기본적으로 60초 동안 데이터가 없는 연결을 닫으므로 그 간격에서 스트림을 자릅니다. v2.1.229 이상의 게이트웨이는 조용한 스트림을 해당 시간 초과 아래에서 유지합니다: 이러한 업스트림에서 게이트웨이는 스트림 데이터가 없는 약 15초가 지나면 SSE `ping` 이벤트를 한 번 내보내고, Anthropic API 업스트림에서는 API 자체의 핑을 중계합니다. | 게이트웨이를 v2.1.229 이상으로 업데이트하거나, `idle_timeout.timeout_seconds` 속성을 `3600`으로 설정하십시오. `modify-load-balancer-attributes`를 통해 또는 EKS의 `load-balancer-attributes` Ingress 주석을 통해 설정하십시오. |

506 506

claude-apps-gateway-on-gcp.md +1 −1

Details

318| Cloud Run이 컨테이너에 도달하기 전에 `403 Forbidden`을 반환 | invoker IAM 확인이 여전히 활성화됨 | `--no-invoker-iam-check`로 배포하거나 `--allow-unauthenticated`로 `allUsers`에 `run.invoker` 역할을 부여 |318| Cloud Run이 컨테이너에 도달하기 전에 `403 Forbidden`을 반환 | invoker IAM 확인이 여전히 활성화됨 | `--no-invoker-iam-check`로 배포하거나 `--allow-unauthenticated`로 `allUsers`에 `run.invoker` 역할을 부여 |

319| `--no-invoker-iam-check`가 `invoker_iam_disabled is not currently available`로 거부됨 | `constraints/run.managed.requireInvokerIam`에 의해 차단됨 | `--allow-unauthenticated`를 사용합니다. `constraints/iam.allowedPolicyMemberDomains`를 통한 Domain Restricted Sharing도 차단하면 GKE 트랙을 사용하세요. 이는 `allUsers` 바인딩 없이 네트워크 계층에서 게이트웨이를 노출합니다. |319| `--no-invoker-iam-check`가 `invoker_iam_disabled is not currently available`로 거부됨 | `constraints/run.managed.requireInvokerIam`에 의해 차단됨 | `--allow-unauthenticated`를 사용합니다. `constraints/iam.allowedPolicyMemberDomains`를 통한 Domain Restricted Sharing도 차단하면 GKE 트랙을 사용하세요. 이는 `allUsers` 바인딩 없이 네트워크 계층에서 게이트웨이를 노출합니다. |

321| 게이트웨이 부팅이 Cloud Run의 Postgres 연결 타임아웃 오류로 종료됨 | 서비스가 VPC에 연결되지 않았거나 Cloud SQL이 해당 VPC에 프라이빗 IP가 없음. 저장소는 5초 후 대기를 중지 | Direct VPC egress를 위해 `--network` 및 `--subnet`으로 배포하고 Cloud SQL 인스턴스를 `--no-assign-ip` 및 동일한 VPC를 가리키는 `--network`로 생성 |321| 게이트웨이 부팅이 Cloud Run의 Postgres 연결 타임아웃 오류로 종료됨 | 서비스가 VPC에 연결되지 않았거나 Cloud SQL이 해당 VPC에 프라이빗 IP가 없음 | Direct VPC egress를 위해 `--network` 및 `--subnet`으로 배포하고 Cloud SQL 인스턴스를 `--no-assign-ip` 및 동일한 VPC를 가리키는 `--network`로 생성 |

322| Google Cloud의 Agent Platform 요청이 `403 PERMISSION_DENIED`를 반환 | 런타임이 `claude-gateway` 서비스 계정을 사용하지 않거나 모델이 프로젝트의 Model Garden에서 활성화되지 않음 | Cloud Run에서 `--service-account`를 설정하거나 GKE에서 Workload Identity를 바인딩하고 각 Claude 모델을 대상 지역의 Model Garden에서 활성화 |322| Google Cloud의 Agent Platform 요청이 `403 PERMISSION_DENIED`를 반환 | 런타임이 `claude-gateway` 서비스 계정을 사용하지 않거나 모델이 프로젝트의 Model Garden에서 활성화되지 않음 | Cloud Run에서 `--service-account`를 설정하거나 GKE에서 Workload Identity를 바인딩하고 각 Claude 모델을 대상 지역의 Model Garden에서 활성화 |

323| 스트리밍 응답이 고정 기간 후 차단됨 | 프론트 엔드 요청 타임아웃: GKE Ingress 뒤의 로드 밸런서 백엔드 서비스는 기본적으로 30초이고 Cloud Run은 300초 | GKE에서 `timeoutSec`이 높은 BackendConfig를 연결하거나 Cloud Run에서 `--timeout=3600`으로 배포 |323| 스트리밍 응답이 고정 기간 후 차단됨 | 프론트 엔드 요청 타임아웃: GKE Ingress 뒤의 로드 밸런서 백엔드 서비스는 기본적으로 30초이고 Cloud Run은 300초 | GKE에서 `timeoutSec`이 높은 BackendConfig를 연결하거나 Cloud Run에서 `--timeout=3600`으로 배포 |

324 324

cloud-environments.md +53 −46

Details

44 환경 구성44 환경 구성

45</h2>45</h2>

46 46

47[웹 온보딩](/docs/ko/web-quickstart) 후 [claude.ai/code](https://claude.ai/code)에서 도달하거나 [Desktop 앱](/docs/ko/desktop#cloud-sessions)의 프롬프트 상자에서 환경을 생성, 편집 및 보관합니다. 생성한 환경은 계정에 개인적입니다. Owner가 생성한 [공유 환경](#organization-shared-environments)은 동일한 선택기에 나타납니다. 구성 없이 사용 가능한 항목은 [설치된 도구](#installed-tools)를 참조하세요.47[웹 온보딩](/docs/ko/web-quickstart) 후 [claude.ai/code](https://claude.ai/code)에서 또는 [Desktop 앱](/docs/ko/desktop#cloud-sessions)의 프롬프트 상자에서 환경 선택기를 통해 환경을 생성, 편집 및 보관할 수 있습니다. 생성한 환경은 계정에 개인적으로 속하며, Owner가 생성한 [공유 환경](#organization-shared-environments)은 동일한 선택기에 나타납니다. 구성 없이 사용 가능한 항목은 [설치된 도구](#installed-tools)를 참조하십시오.

48 48

49<Steps>49<Steps>

50 <Step title="환경 선택기 열기">50 <Step title="환경 선택기 열기">

51 [claude.ai/code](https://claude.ai/code)에서 메시지 상자 위의 행에 있는 현재 환경의 이름을 표시하는 클라우드 아이콘을 선택합니다. 선택기에 대한 설정 페이지 또는 직접 URL이 없습니다.51 [claude.ai/code](https://claude.ai/code)에서 메시지 상자 위의 행에 있는 현재 환경의 이름을 표시하는 클라우드 아이콘을 선택합니다. 선택기에 대한 설정 페이지나 직접 URL은 없습니다.

52 52

53 <Frame>53 <Frame>

54 <img src="https://mintcdn.com/claude-code/ZFId6l95856c5LSw/images/cloud-environment-selector.png?fit=max&auto=format&n=ZFId6l95856c5LSw&q=85&s=cc2813a5664519eaf5a89d793ce5af26" alt="claude.ai/code의 메시지 상자 위에 열린 환경 선택기. 환경 이름 Default를 표시하는 클라우드 버튼은 메시지 상자 위의 행에 있습니다. 열린 메뉴는 Download 및 Desktop only 레이블이 있는 Local 행, Default 환경이 체크 표시로 선택되고 마우스를 가져가면 설정 기어 아이콘을 표시하는 Cloud 섹션, Add cloud environment 옵션 및 설정 지침이 있는 Remote Control 섹션을 나열합니다." width="1672" height="682" data-path="images/cloud-environment-selector.png" />54 <img src="https://mintcdn.com/claude-code/ZFId6l95856c5LSw/images/cloud-environment-selector.png?fit=max&auto=format&n=ZFId6l95856c5LSw&q=85&s=cc2813a5664519eaf5a89d793ce5af26" alt="claude.ai/code의 메시지 상자 위에 열려 있는 환경 선택기입니다. 환경 이름 Default를 표시하는 클라우드 버튼이 메시지 상자 위의 행에 있습니다. 열린 메뉴에는 Download 및 Desktop only 레이블이 있는 Local 행, Default 환경이 체크 표시로 선택되어 있고 마우스를 올리면 설정 기어 아이콘이 표시되는 Cloud 섹션, Add cloud environment 옵션, 그리고 설정 지침이 있는 Remote Control 섹션이 나열됩니다." width="1672" height="682" data-path="images/cloud-environment-selector.png" />

55 </Frame>55 </Frame>

56 </Step>56 </Step>

57 57

58 <Step title="환경 추가 또는 편집">58 <Step title="환경 추가 또는 편집">

59 **Add cloud environment**를 선택하거나 기존 환경 위에 마우스를 가져가서 오른쪽에 나타나는 설정 아이콘을 선택합니다. 대화 상자에는 이름, 네트워크 액세스 수준, 환경 변수 및 설정 스크립트가 포함됩니다. Pro 또는 Max 플랜에서 기존 클라우드 환경을 편집할 때 대화 상자에는 [API 자격 증명](#add-api-credentials)도 포함됩니다.59 **Add cloud environment**를 선택하거나, 기존 환경 위에 마우스를 올리고 오른쪽에 나타나는 설정 아이콘을 선택합니다. 대화 상자에는 이름, 네트워크 액세스 수준, 환경 변수 및 설정 스크립트가 포함됩니다. Pro 또는 Max 플랜에서 기존 클라우드 환경을 편집할 때 대화 상자에는 [API 자격 증명](#add-api-credentials)도 포함됩니다.

60 60

61 <Frame>61 <Frame>

62 <img src="https://mintcdn.com/claude-code/ZFId6l95856c5LSw/images/cloud-environment-dialog.png?fit=max&auto=format&n=ZFId6l95856c5LSw&q=85&s=30d4478b31d1f879f7ee287ddab32505" alt="New cloud environment 대화 상자. Default 자리 표시자가 있는 Name 필드, 네트워크 정책 및 액세스 수준에 대한 링크가 있는 Trusted로 설정된 Network access 선택기, .env 형식 자리 표시자 텍스트를 표시하고 환경을 사용하는 모든 사람이 값을 볼 수 있다는 참고 사항이 있는 Environment variables 상자, 새 세션이 시작될 때 Claude Code가 시작되기 전에 실행되는 Bash 스크립트로 설명되는 Setup script 상자 및 Cancel 및 Create environment 버튼." width="874" height="1372" data-path="images/cloud-environment-dialog.png" />62 <img src="https://mintcdn.com/claude-code/ZFId6l95856c5LSw/images/cloud-environment-dialog.png?fit=max&auto=format&n=ZFId6l95856c5LSw&q=85&s=30d4478b31d1f879f7ee287ddab32505" alt="New cloud environment 대화 상자입니다. 기본값 자리 표시자가 있는 Name 필드, Trusted로 설정된 Network access 선택기(네트워크 정책 및 액세스 수준에 대한 링크 포함), .env 형식 자리 표시자 텍스트가 있는 Environment variables 상자(환경을 사용하는 모든 사람이 값을 볼 수 있다는 참고 사항 포함), Claude Code가 시작되기 전에 새 세션이 시작될 때 실행되는 Bash 스크립트로 설명된 Setup script 상자, 그리고 Cancel 및 Create environment 버튼이 있습니다." width="874" height="1372" data-path="images/cloud-environment-dialog.png" />

63 </Frame>63 </Frame>

64 </Step>64 </Step>

65</Steps>65</Steps>

68 환경 변수 설정68 환경 변수 설정

69</h3>69</h3>

70 70

71환경 변수는 `.env` 형식을 사용하며, 한 줄에 하나의 `KEY=value` 쌍입니다. 일반 값은 따옴표가 필요하지 않으며, 일치하는 쌍으로 값을 인용하면 따옴표가 값의 일부가 되지 않습니다. 여러 줄에 걸쳐 있거나 `#`를 포함하는 값을 인용합니다: 인용되지 않은 값에서 `#`는 주석을 시작하고 줄의 나머지는 삭제됩니다.71환경 변수는 `.env` 형식을 사용하며, 한 줄에 하나의 `KEY=value` 쌍을 사용합니다. 일반 값은 따옴표가 필요하지 않으며, 일치하는 쌍으로 값을 인용하면 따옴표가 값의 일부가 되지 않습니다. 여러 줄에 걸쳐 있거나 `#`을 포함하는 값을 인용합니다. 인용되지 않은 값에서 `#`은 주석을 시작하고 줄의 나머지 부분은 삭제됩니다.

72 72

73다음 예제는 세 개의 변수를 정의합니다.73다음 예제는 세 개의 변수를 정의합니다.

74 74

78DATABASE_URL=postgres://localhost:5432/myapp78DATABASE_URL=postgres://localhost:5432/myapp

79```79```

80 80

81각 세션은 시작 시 환경의 값을 한 번 복사하여 Claude가 실행하는 모든 명령이 읽을 수 있는 일반 환경 변수로 변환합니다. 실행 중인 세션이 구성을 다시 읽지 않으므로 변수를 편집하거나 추가하면 이후에 시작하는 세션에 영향을 미칩니다. 이미 실행 중인 세션은 시작할 때의 값을 유지합니다.81각 세션은 시작 시 환경의 값을 한 번 복사하여 Claude가 실행하는 모든 명령이 읽을 수 있는 일반 환경 변수로 변환합니다. 실행 중인 세션이 구성을 다시 읽지 않기 때문에 변수를 편집하거나 추가하면 이후에 시작하는 세션에 영향을 미칩니다. 이미 실행 중인 세션은 시작할 때의 값을 유지합니다.

82 82

83클라우드 세션은 시작할 때 일부 변수를 자체적으로 설정합니다. [`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`](/docs/ko/claude-code-on-the-web#manage-context)의 경우 세션이 설정하는 값이 여기에 추가한 값을 재정의하므로 여기에 해당 키를 추가해도 효과가 없습니다.83클라우드 세션은 시작할 때 자체적으로 일부 변수도 설정합니다. [`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`](/docs/ko/claude-code-on-the-web#manage-context)의 경우, 세션이 설정하는 값이 여기에 추가한 값을 재정의하므로 여기에 해당 키를 추가해도 효과가 없습니다.

84 84

85환경을 사용하는 모든 사람이 값을 읽을 수 있습니다. Pro 및 Max 플랜에서는 대신 에이전트 프록시가 요청에 첨부할 수 있는 키에 대해 [API 자격 증명](#add-api-credentials)을 사용합니다. [자격 증명을 받지 않는 요청](#requests-that-never-get-the-credential)이 나열되어 있습니다.85환경을 사용하는 모든 사람이 값을 읽을 수 있습니다. Pro 및 Max 플랜에서는 에이전트 프록시가 요청에 첨부할 수 있는 키에 대해 [API 자격 증명](#add-api-credentials)을 대신 사용합니다. [자격 증명을 받지 않는 요청](#requests-that-never-get-the-credential)이 나열되어 있습니다.

86 86

87<h3 id="add-api-credentials">87<h3 id="add-api-credentials">

88 API 자격 증명 추가88 API 자격 증명 추가

89</h3>89</h3>

90 90

91API 자격 증명은 클라우드 환경에 저장하는 API 키 또는 토큰이므로 Claude는 키를 보지 않고 환경의 모든 세션에서 해당 API를 호출할 수 있습니다. Anthropic의 에이전트 프록시는 각 요청이 세션의 VM을 떠난 후 나열한 호스트에 대한 요청에 키를 추가합니다. 키는 Claude, 실행하는 명령 또는 세션의 환경 변수에 도달하지 않습니다.91API 자격 증명은 클라우드 환경에 저장하는 API 키 또는 토큰으로, Claude가 키를 보지 않고도 환경의 모든 세션에서 해당 API를 호출할 수 있습니다. Anthropic의 에이전트 프록시는 각 요청이 세션의 VM을 떠난 후 나열한 호스트에 대한 요청에 키를 추가합니다. 키는 Claude, 실행하는 명령 또는 세션의 환경 변수에 도달하지 않습니다.

92 92

93API 자격 증명은 Pro 및 Max 플랜에서 사용 가능합니다. Team 또는 Enterprise 플랜에서는 아직 사용할 수 없으므로 **API credentials** 섹션이 이러한 플랜의 환경 대화 상자에 나타나지 않습니다.93API 자격 증명은 Pro 및 Max 플랜에서 사용 가능합니다. Team 또는 Enterprise 플랜에서는 아직 사용할 수 없으므로 **API credentials** 섹션이 해당 플랜의 환경 대화 상자에 나타나지 않습니다.

94 94

95<h4 id="requirements">95<h4 id="requirements">

96 요구 사항96 요구 사항

97</h4>97</h4>

98 98

~~99이 중 두 개는 자격 증명을 추가할 수 있는지 여부를 결정하고, 두 개는 추가된 후 에이전트 프록시가 이를 사용할 수 있는지 여부를 결정합니다:~~99이 중 두 개는 자격 증명을 추가할 수 있는지 여부를 결정하고, 두 개는 추가된 후 에이전트 프록시가 사용할 수 있는지 여부를 결정합니다.

100 100

101* **역할**: claude.ai 조직의 조직 관리자 역할101* **Role**: claude.ai 조직의 조직 관리자 역할

102 * Team 및 Enterprise에서 Owner가 보유하고 Admin은 보유하지 않습니다102 * Team 및 Enterprise에서는 Owner가 보유하고 Admin은 보유하지 않습니다.

103 * Pro 및 Max에서 자신의 조직에서 보유합니다103 * Pro 및 Max에서는 자신의 조직에서 보유합니다.

104 * 이를 보유하지 않으면 자신의 환경에서도 자격 증명 목록 대신 참고 사항을 봅니다. Owner에게 공유 환경에 자격 증명을 추가하고 거기에서 세션을 실행하도록 요청합니다104 * 이 역할이 없으면 자신의 환경에서도 자격 증명 목록 대신 참고 사항이 표시됩니다. Owner에게 공유 환경에 자격 증명을 추가하고 해당 환경에서 세션을 실행하도록 요청하십시오.

105* **환경 유형**: 이미 존재하는 Anthropic 호스팅 클라우드 환경. [자체 호스팅 환경](/docs/ko/self-hosted-environments)에는 API 자격 증명이 없습니다105* **Environment type**: 이미 존재하는 Anthropic 호스팅 클라우드 환경입니다. [자체 호스팅 환경](/docs/ko/self-hosted-environments)에는 API 자격 증명이 없습니다.

106* **API 도달 가능성**: API가 인터넷에서의 연결을 수락합니다. 요청이 Anthropic의 네트워크에서 나가기 때문입니다106* **API reachability**: API가 인터넷에서의 연결을 수락합니다. 요청이 Anthropic의 네트워크에서 나가기 때문입니다.

107* **암호화 키**: 조직이 고객 관리 암호화 키를 사용하는 경우 자격 증명을 저장할 수 없습니다107* **Encryption keys**: 조직이 고객 관리 암호화 키를 사용하는 경우 자격 증명을 저장할 수 없습니다.

108 108

109<h4 id="add-a-credential">109<h4 id="add-a-credential">

110 자격 증명 추가110 자격 증명 추가

111</h4>111</h4>

112 112

113한 번에 하나씩 이미 존재하는 환경의 편집기에서 자격 증명을 추가합니다. 새 환경의 대화 상자는 이를 제공하지 않습니다. 편집도 없습니다. 자격 증명의 호스트 또는 값을 변경하려면 삭제하고 다시 추가합니다.113이미 존재하는 환경의 편집기에서 한 번에 하나씩 자격 증명을 추가합니다. 새 환경의 대화 상자는 이를 제공하지 않습니다. 편집도 없습니다. 자격 증명의 호스트 또는 값을 변경하려면 삭제하고 다시 추가합니다.

114 114

115<Steps>115<Steps>

116 <Step title="환경의 API 자격 증명 열기">116 <Step title="환경의 API 자격 증명 열기">

117 [claude.ai/code](https://claude.ai/code)에서 [편집을 위해 환경을 열고](#configure-your-environment) **Update cloud environment** 대화 상자에서 **Environment variables** 아래의 **API credentials**를 찾습니다. 환경에 이미 있는 자격 증명과 적용되는 호스트를 봅니다.117 [claude.ai/code](https://claude.ai/code)의 환경 선택기에서 [편집할 환경을 열기](#configure-your-environment)합니다. **Update cloud environment** 대화 상자에서 **Environment variables** 아래에 **API credentials**를 찾습니다. 환경에 이미 있는 자격 증명과 적용되는 호스트를 볼 수 있습니다.

118 </Step>118 </Step>

119 119

120 <Step title="자격 증명 추가">120 <Step title="자격 증명 추가">

121 **Add credential**을 선택하고 양식을 작성합니다. 요청 헤더에서 이동하는 API 키에 대해 기본 **Credential type**, **Bearer**를 유지하고 다음 필드를 작성합니다:121 **Add credential**을 선택하고 양식을 작성합니다. 요청 헤더에서 이동하는 API 키에 대해 기본 **Credential type**, **Bearer**를 유지하고 다음 필드를 작성합니다.

122 122

123 * **Name**: `Internal billing API`와 같은 자격 증명의 레이블123 * **Name**: `Internal billing API`와 같은 자격 증명의 레이블

124 * **Allowed websites**: `api.example.com`과 같은 API의 호스트. 선행 `*.`은 모든 하위 도메인과 일치합니다124 * **Allowed websites**: `api.example.com`과 같은 API의 호스트입니다. 선행 `*.`은 모든 하위 도메인과 일치합니다.

125 * **Custom headers**: 키를 전달하는 헤더에 대한 한 행. 행은 헤더의 **Name**으로 `Authorization`과 **Prefix**로 `Bearer`로 시작합니다. 키 자체를 **Value**로 붙여넣습니다. `X-Api-Key`와 같이 베어 값을 사용하는 헤더의 경우 이름을 변경하고 접두사를 지웁니다125 * **Custom headers**: 키를 전달하는 헤더에 대한 한 행입니다. 행은 헤더의 **Name**으로 `Authorization`으로 시작하고 **Prefix**로 `Bearer`로 시작합니다. 키 자체를 **Value**로 붙여넣습니다. `X-Api-Key`와 같이 기본 값을 사용하는 헤더의 경우 이름을 변경하고 접두사를 지웁니다.

126 126

127 다른 방식으로 인증하는 API의 경우 다른 **Credential type**을 선택합니다. 목록은 [Claude Tag](https://claude.com/docs/claude-tag/overview)와 Team 및 Enterprise 플랜의 Slack 통합이 [연결](https://claude.com/docs/claude-tag/admins/add-connections)에 제공하는 것과 동일합니다.127 다른 방식으로 인증하는 API의 경우 다른 **Credential type**을 선택합니다. 목록은 Team 및 Enterprise 플랜의 Slack 통합인 [Claude Tag](https://claude.com/docs/claude-tag/overview)가 [연결](https://claude.com/docs/claude-tag/admins/add-connections)에 제공하는 것과 동일합니다.

128 </Step>128 </Step>

129 129

130 <Step title="자격 증명 저장">130 <Step title="자격 증명 저장">

131 **Connect**를 선택합니다. 자격 증명은 호스트와 함께 목록에 나타나며 대화 상자의 **Save changes** 버튼 없이 저장됩니다. 저장 후 값을 다시 볼 수 없습니다.131 **Connect**를 선택합니다. 자격 증명이 호스트와 함께 목록에 나타나며, 대화 상자의 **Save changes** 버튼 없이 저장됩니다. 저장 후 값을 다시 볼 수 없습니다.

132 </Step>132 </Step>

133</Steps>133</Steps>

134 134

135자격 증명이 작동하는지 확인하려면 환경에서 세션을 시작하고 Claude에게 `curl`과 같은 API를 호출하도록 요청합니다. API는 키가 요청에 있는 것처럼 응답하고 키는 세션의 환경 변수 또는 파일에 나타나지 않습니다. 목록이 자격 증명을 **Not sent**로 표시하면 아래의 참고 사항이 이유와 수행할 작업을 설명합니다. 호스트가 정확히 일치하지 않고 겹치는 두 자격 증명은 마커를 받지 않으며 에이전트 프록시는 그 중 하나만 보냅니다.135자격 증명이 작동하는지 확인하려면 환경에서 세션을 시작하고 Claude에게 `curl`과 같은 API를 호출하도록 요청합니다. API는 키가 요청에 있는 것처럼 응답하며, 키는 세션의 환경 변수나 파일에 나타나지 않습니다. 목록이 자격 증명을 **Not sent**로 표시하는 경우, 아래의 참고 사항에 이유와 수행할 작업이 설명되어 있습니다. 호스트가 정확히 일치하지 않고 겹치는 두 자격 증명은 마커를 받지 않으며, 에이전트 프록시는 그 중 하나만 보냅니다.

136 136

137<h4 id="which-requests-get-the-credential">137<h4 id="which-requests-get-the-credential">

138 자격 증명을 받는 요청138 자격 증명을 받는 요청

139</h4>139</h4>

140 140

141에이전트 프록시는 요청의 호스트가 해당 자격 증명에 나열한 것과 일치할 때 자격 증명을 요청에 첨부합니다. 세션은 환경의 [네트워크 액세스 수준](#access-levels)이 그렇지 않으면 허용하지 않을 경우에도 이러한 호스트에 도달할 수 있습니다. 단, [자격 증명을 받지 않는 요청](#requests-that-never-get-the-credential)은 제외합니다. 자격 증명은 삭제할 때까지 환경에서 실행되는 모든 세션에 적용되며, 누가 시작했는지 관계없습니다.141에이전트 프록시는 요청의 호스트가 해당 자격 증명에 나열한 호스트 중 하나와 일치할 때 자격 증명을 요청에 첨부합니다. 세션은 환경의 [네트워크 액세스 수준](#access-levels)이 그렇지 않으면 허용하지 않을 때에도 해당 호스트에 도달할 수 있습니다. 단, [자격 증명을 받지 않는 호스트](#requests-that-never-get-the-credential)는 제외됩니다. 자격 증명은 삭제할 때까지 환경에서 실행되는 모든 세션에 적용되며, 누가 시작했는지는 상관없습니다.

142 142

143<h4 id="requests-that-never-get-the-credential">143<h4 id="requests-that-never-get-the-credential">

144 자격 증명을 받지 않는 요청144 자격 증명을 받지 않는 요청

145</h4>145</h4>

146 146

147에이전트 프록시는 추가한 자격 증명을 이러한 요청에 첨부하지 않습니다:147에이전트 프록시는 다음 요청에 추가한 자격 증명을 첨부하지 않습니다.

148 148

149* **GitHub**: [GitHub 프록시](#github-proxy)가 대신 GitHub에 대한 요청을 인증하므로 GitHub에 대한 API 자격 증명이 필요하지 않습니다149* **GitHub**: [GitHub 프록시](#github-proxy)가 대신 GitHub에 대한 요청을 인증하므로 GitHub에 대한 API 자격 증명이 필요하지 않습니다.

150* **Anthropic API 및 공개 패키지 레지스트리**: `api.anthropic.com`, `registry.npmjs.org`, `jsr.io`, `npm.jsr.io`, `pypi.org`, `files.pythonhosted.org`, `index.crates.io` 및 `proxy.golang.org`150* **Anthropic API 및 공개 패키지 레지스트리**: `api.anthropic.com`, `registry.npmjs.org`, `jsr.io`, `npm.jsr.io`, `pypi.org`, `files.pythonhosted.org`, `index.crates.io`, 및 `proxy.golang.org`

151* **설정 스크립트 요청**: Claude Code는 [설정 스크립트](#setup-scripts)가 실행된 후 시작될 때 에이전트 프록시에 연결합니다151* **Setup script 요청**: Claude Code는 [설정 스크립트](#setup-scripts)가 실행된 후 시작할 때 에이전트 프록시에 연결합니다.

152 152

153<h3 id="select-an-environment-from-the-cli">153<h3 id="select-an-environment-from-the-cli">

154 CLI에서 환경 선택154 CLI에서 환경 선택

155</h3>155</h3>

156 156

157터미널에서 `/remote-env`를 실행하여 [`claude --cloud`](/docs/ko/claude-code-on-the-web#from-terminal-to-cloud)와 같은 CLI에서 생성하는 클라우드 세션의 기본 환경을 선택합니다. 명령은 기존 환경의 선택기를 열고 선택을 [사용자 설정](/docs/ko/settings#where-settings-live)의 `remote.defaultEnvironmentId` 키에 저장하므로 변경할 때까지 머신의 모든 프로젝트에 적용되며, 리포지토리의 프로젝트 설정과 같은 더 높은 우선순위 [설정 계층](/docs/ko/settings#settings-precedence)에서 동일한 키가 설정되지 않는 한 적용됩니다.157터미널에서 `/remote-env`를 실행하여 [`claude --cloud`](/docs/ko/claude-code-on-the-web#from-terminal-to-cloud)와 같이 CLI에서 생성하는 클라우드 세션의 기본 환경을 선택합니다. 명령은 기존 환경의 선택기를 열고 선택을 [사용자 설정](/docs/ko/settings#where-settings-live)의 `remote.defaultEnvironmentId` 키에 저장하므로, 변경할 때까지 머신의 모든 프로젝트에 적용되며, 리포지토리의 프로젝트 설정과 같은 더 높은 우선 순위 [설정 레이어](/docs/ko/settings#settings-precedence)에서 동일한 키가 설정되지 않은 경우입니다.

158 158

159[자체 호스팅 환경](/docs/ko/self-hosted-environments) ID(형식 `ccpool_...`)는 더 엄격한 소스 규칙을 따릅니다. [`remote.defaultEnvironmentId`](/docs/ko/settings-reference#remote-defaultenvironmentid)를 참조하여 Claude Code가 이를 인정하는 설정 계층을 확인합니다.159[자체 호스팅 환경](/docs/ko/self-hosted-environments) ID는 `ccpool_...` 형식이며 더 엄격한 소스 규칙을 따릅니다. Claude Code가 이를 인정하는 설정 레이어는 [`remote.defaultEnvironmentId`](/docs/ko/settings-reference#remote-defaultenvironmentid)를 참조하십시오.

160 160

161`/remote-env`는 기본값만 설정합니다: 세션을 시작하지 않으며 환경을 추가하거나 편집할 수 없습니다. [환경 선택기](#configure-your-environment)에서 관리합니다.161`/remote-env`는 기본값만 설정합니다. 세션을 시작하지 않으며 환경을 추가하거나 편집할 수 없습니다. [환경 선택기](#configure-your-environment)에서 관리합니다.

162 162

163<h3 id="archive-an-environment">163<h3 id="archive-an-environment">

164 환경 보관164 환경 보관

165</h3>165</h3>

166 166

167환경을 보관하려면 편집을 위해 열고 **Archive**를 선택합니다. 환경을 삭제할 수 없으며 보관만 할 수 있습니다.167자신의 환경 중 하나를 보관하려면 편집을 위해 열고 **Archive**를 선택합니다. Owner는 관리 설정의 **Cloud environments** 페이지에서 [공유 환경](#organization-shared-environments)을 보관합니다. 환경을 삭제할 수 없으며, 보관만 할 수 있습니다.

168 168

169보관은 실행 중인 세션이 아닌 새 세션에 영향을 미칩니다:169보관은 실행 중인 세션이 아닌 새 세션에 영향을 미칩니다.

170 170

171* 환경에서 이미 실행 중인 세션은 계속 작동합니다.171* 환경에서 이미 실행 중인 세션은 계속 작동합니다.

172* 환경이 선택기 및 `/remote-env`에서 사라지므로 새 세션에 대해 선택할 수 없습니다.172* 환경이 선택기 및 `/remote-env`에서 사라지므로 새 세션에 대해 선택할 수 없습니다.

173* 환경의 API 자격 증명은 실행 중인 세션에 첨부된 상태로 유지됩니다. 보관하기 전에 더 이상 원하지 않는 것을 삭제합니다.173* 환경의 API 자격 증명은 실행 중인 세션에 첨부된 상태로 유지됩니다. 보관하기 전에 더 이상 원하지 않는 항목을 삭제합니다.

174* 모든 표면에서 보관된 환경에서 새 세션을 시작할 수 없습니다. 환경이 저장된 [CLI 기본값](#select-an-environment-from-the-cli)인 경우 Claude Code는 목록에 하나가 있으면 Anthropic 호스팅 환경에서 CLI 클라우드 세션을 시작하고, 그렇지 않으면 [Remote Control 브리지 환경](#the-default-environment)이 아닌 목록의 첫 번째 환경에서 시작합니다. [루틴](/docs/ko/routines#environments-and-network-access)과 같이 환경으로 명시적으로 구성된 모든 것은 새 세션을 시작할 수 없습니다. 다른 환경을 가리킵니다.174* 보관된 환경에서는 어떤 표면에서도 새 세션을 시작할 수 없습니다. 환경이 저장된 [CLI 기본값](#select-an-environment-from-the-cli)이었다면, 목록에 Anthropic 호스팅 환경이 있을 때 Claude Code는 CLI 클라우드 세션을 해당 환경에서 시작하고, 그렇지 않으면 [Remote Control 브리지 환경](#the-default-environment)이 아닌 목록의 첫 번째 환경에서 시작합니다. [루틴](/docs/ko/routines#environments-and-network-access)과 같이 환경으로 명시적으로 구성된 모든 항목은 새 세션을 시작할 수 없습니다. 다른 환경을 가리키도록 합니다.

175 175

176<h3 id="organization-shared-environments">176<h3 id="organization-shared-environments">

177 조직 공유 환경177 조직 공유 환경

178</h3>178</h3>

179 179

180Team 및 Enterprise 플랜에서 Owner는 조직의 모든 구성원과 공유되는 클라우드 환경을 생성할 수 있습니다. 동일한 역할이 **Cloud environments** 관리 페이지의 [자체 호스팅 환경](/docs/ko/self-hosted-environments)을 포함한 다른 모든 항목을 관리합니다. Admin 역할은 페이지를 열 수 없습니다. 이를 열 수 있는 역할의 전체 목록은 [서버 관리 설정 관리](/docs/ko/server-managed-settings#access-control)를 위한 것입니다. 공유 환경은 각 구성원의 환경 선택기에 개인 환경과 함께 나타나므로 팀이 각 구성원이 다시 생성하는 대신 하나의 구성으로 표준화할 수 있습니다.180Team 및 Enterprise 플랜에서 Owner는 조직의 모든 구성원과 공유되는 클라우드 환경을 생성할 수 있습니다. 동일한 역할은 **Cloud environments** 관리 페이지에서 [자체 호스팅 환경](/docs/ko/self-hosted-environments)을 포함한 다른 모든 항목을 관리합니다. Admin 역할은 페이지를 열 수 없습니다. 이를 열 수 있는 역할의 전체 목록은 [서버 관리 설정 관리](/docs/ko/server-managed-settings#access-control)에 대한 것입니다.

181 181

182[관리자 설정](https://claude.ai/admin-settings)의 **Cloud environments** 페이지에서 공유 환경을 생성, 편집 및 보관합니다. 공유 환경은 [claude.ai/code](https://claude.ai/code)의 [환경 선택기](#configure-your-environment)에서도 열립니다: Owner는 거기에서 편집할 수 있습니다. 다른 구성원은 읽기 전용으로 봅니다. 각 공유 환경에는 이름, [네트워크 액세스 수준](#access-levels), `.env` 형식의 [환경 변수](#set-environment-variables) 및 [설정 스크립트](#setup-scripts)가 있습니다. Owner는 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code)에서 조직의 [기본 환경](#the-default-environment)을 별도로 선택합니다.182공유 환경은 각 구성원의 [환경 선택기](#configure-your-environment)에 **Organization** 제목 아래에 나타나며, 구성원의 자신의 환경은 **Personal** 아래에 있으므로, 팀이 각 구성원이 다시 생성하는 대신 하나의 구성으로 표준화할 수 있습니다. 공유 환경의 설정 아이콘을 선택하면 모든 구성원(Owner 포함)에 대한 구성의 읽기 전용 요약이 열립니다.

183 183

184모든 구성원의 공유 환경 세션은 해당 변수를 읽으므로 비밀을 포함하지 마세요. [API 자격 증명](#add-api-credentials)은 세션이 읽을 수 없는 키를 제공하며 Team 또는 Enterprise 플랜에서는 아직 사용할 수 없습니다.184Owner는 다음 두 가지 방법 중 하나로 환경을 조직에서 사용 가능하게 만듭니다.

185

186* **공유 환경 생성**: [관리 설정](https://claude.ai/admin-settings)의 **Cloud environments** 페이지를 사용합니다. 이는 Owner가 공유 환경을 편집하고 보관하는 곳이기도 합니다. 각각은 이름, [네트워크 액세스 수준](#access-levels), `.env` 형식의 [환경 변수](#set-environment-variables), 및 [설정 스크립트](#setup-scripts)를 가집니다.

187* **개인 환경 공유**: 환경 선택기에서 자신의 환경 중 하나를 편집을 위해 열고, **Who can use it** 행에서 공유합니다. 환경은 ID를 유지하므로 이미 사용 중인 세션 및 루틴은 영향을 받지 않으며, 모든 구성원이 이를 보고 세션을 시작할 수 있습니다.

188

189Owner는 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code)에서 조직의 [기본 환경](#the-default-environment)을 별도로 선택합니다.

190

191모든 구성원의 공유 환경의 세션은 해당 변수를 읽으므로 비밀을 포함하지 마십시오. [자격 증명을 읽을 수 없는 세션을 제공하는 API 자격 증명](#add-api-credentials)은 Team 또는 Enterprise 플랜에서 아직 사용할 수 없습니다.

185 192

186<h3 id="set-the-environment-a-claude-tag-channel-uses">193<h3 id="set-the-environment-a-claude-tag-channel-uses">

187 Claude Tag 채널이 사용하는 환경 설정194 Claude Tag 채널이 사용하는 환경 설정

188</h3>195</h3>

189 196

190[Claude Tag](https://claude.com/docs/claude-tag/overview) 채널에서 Claude는 구성원이 아닌 조직의 공유 ID로 작동하므로 채널 세션은 조직 수준 환경만 사용하며, 공유 환경 또는 [자체 호스팅 환경](/docs/ko/self-hosted-environments) 중 하나입니다. 채널에 [사전 설치되지 않은](#installed-tools) .NET과 같은 도구 체인을 제공하려면 Owner는 **Cloud environments** 관리 페이지에서 [공유 환경](#organization-shared-environments)을 생성하고 설치하는 [설정 스크립트](#setup-scripts)를 사용할 수 있습니다. 두 가지 방법 중 하나로 채널을 환경에 가리킵니다:197[Claude Tag](https://claude.com/docs/claude-tag/overview) 채널에서 Claude는 모든 구성원이 아닌 조직의 공유 ID로 작동하므로, 채널 세션은 조직 수준 환경만 사용합니다. 공유 환경 또는 [자체 호스팅 환경](/docs/ko/self-hosted-environments)입니다. 채널에 .NET과 같이 [사전 설치](#installed-tools)되지 않은 도구 체인을 제공하려면 Owner는 **Cloud environments** 관리 페이지에서 [공유 환경](#organization-shared-environments)을 생성할 수 있습니다. 이를 설치하는 [설정 스크립트](#setup-scripts)를 사용합니다. 다음 두 가지 방법 중 하나로 채널을 환경에 가리킵니다.

191 198

192* [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code)에서 공유 또는 자체 호스팅 환경을 조직의 [기본 환경](#the-default-environment)으로 설정합니다.199* 공유 또는 자체 호스팅 환경을 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code)에서 조직의 [기본 환경](#the-default-environment)으로 설정합니다.

193* Claude Tag 관리자 설정에서 [채널에 하나를 고정](https://claude.com/docs/claude-tag/admins/troubleshooting#channel-sessions-use-the-wrong-environment-or-can%E2%80%99t-find-one)합니다.200* Claude Tag 관리 설정에서 [채널에 하나를 고정](https://claude.com/docs/claude-tag/admins/troubleshooting#channel-sessions-use-the-wrong-environment-or-can%E2%80%99t-find-one)합니다.

194 201

195<h2 id="network-access">202<h2 id="network-access">

196 네트워크 액세스203 네트워크 액세스

198 205

199각 환경은 하나의 네트워크 액세스 수준을 설정하며, 이는 세션이 만들 수 있는 아웃바운드 연결을 제어합니다. 기본 수준인 **Trusted**는 패키지 레지스트리 및 기타 [허용 목록 도메인](#default-allowed-domains)을 허용합니다. **Custom**은 자신의 도메인 목록을 사용합니다.206각 환경은 하나의 네트워크 액세스 수준을 설정하며, 이는 세션이 만들 수 있는 아웃바운드 연결을 제어합니다. 기본 수준인 **Trusted**는 패키지 레지스트리 및 기타 [허용 목록 도메인](#default-allowed-domains)을 허용합니다. **Custom**은 자신의 도메인 목록을 사용합니다.

200 207

201환경의 네트워크 액세스를 변경하려면 [편집을 위해 열고](#configure-your-environment) 대화 상자에서 **Network access** 선택기를 사용합니다. 선택기를 여는 클라우드 아이콘은 [Default 환경](#the-default-environment) 아래에 나열된 앱 표면 및 [루틴 편집기](/docs/ko/routines#environments-and-network-access)에 나타납니다. 개인 환경에는 claude.ai 계정 설정에 별도의 페이지가 없습니다.208환경의 네트워크 액세스를 변경하려면 [편집을 위해 열고](#configure-your-environment) 대화 상자에서 **Network access** 선택기를 사용합니다. [공유 환경](#organization-shared-environments)은 읽기 전용으로 열리므로 Owner는 [관리 설정](https://claude.ai/admin-settings)의 **Cloud environments** 페이지에서 네트워크 액세스를 변경합니다. 선택기를 여는 클라우드 아이콘은 [Default 환경](#the-default-environment) 아래에 나열된 앱 표면 및 [루틴 편집기](/docs/ko/routines#environments-and-network-access)에 나타납니다. 개인 환경에는 claude.ai 계정 설정에 별도의 페이지가 없습니다.

202 209

203<Note>210<Note>

204 세션 또는 루틴에서 활성화한 MCP 커넥터는 **Allowed domains**에 호스트를 추가하지 않고도 작동합니다. 커넥터 트래픽이 세션의 네트워크가 아닌 Anthropic의 서버를 통해 이동하기 때문입니다. 이는 [보안 및 격리](/docs/ko/claude-code-on-the-web#security-and-isolation) 아래에 언급된 동일한 Anthropic 바운드 채널에 의존합니다. 필요하지 않은 커넥터를 끄면 Claude가 도달할 수 있는 도구를 제한할 수 있습니다.211 세션 또는 루틴에서 활성화한 MCP 커넥터는 **Allowed domains**에 호스트를 추가하지 않고도 작동합니다. 커넥터 트래픽이 세션의 네트워크가 아닌 Anthropic의 서버를 통해 이동하기 때문입니다. 이는 [보안 및 격리](/docs/ko/claude-code-on-the-web#security-and-isolation) 아래에 언급된 동일한 Anthropic 바운드 채널에 의존합니다. 필요하지 않은 커넥터를 끄면 Claude가 도달할 수 있는 도구를 제한할 수 있습니다.

errors.md +2 −0

Details

1740 1740

1741**수행할 작업:**1741**수행할 작업:**

1742 1742

1743이러한 단계는 자신의 환경 중 하나를 변경합니다. [조직 공유 환경](/docs/ko/cloud-environments#organization-shared-environments)은 선택기에서 읽기 전용으로 열리므로, [관리 설정](https://claude.ai/admin-settings)의 **클라우드 환경** 페이지에서 소유자에게 네트워크 액세스를 변경하도록 요청합니다.

1744

1743* 루틴을 편집하기 위해 열거나 클라우드 세션을 시작합니다. 환경의 이름(예: **기본**)을 표시하는 클라우드 아이콘을 선택하여 선택기를 엽니다. 환경 위에 마우스를 올리고 설정 아이콘을 클릭합니다.1745* 루틴을 편집하기 위해 열거나 클라우드 세션을 시작합니다. 환경의 이름(예: **기본**)을 표시하는 클라우드 아이콘을 선택하여 선택기를 엽니다. 환경 위에 마우스를 올리고 설정 아이콘을 클릭합니다.

1744* **클라우드 환경 업데이트** 대화 상자에서 **네트워크 액세스**를 **신뢰할 수 있는**에서 **사용자 정의**로 변경한 다음 차단된 도메인을 **허용된 도메인**에 추가합니다. 한 줄에 하나의 도메인을 입력합니다. **또한 일반적인 패키지 관리자의 기본 목록 포함**을 확인하여 사용자 정의 도메인과 함께 [기본 허용 목록](/docs/ko/cloud-environments#default-allowed-domains)을 유지합니다. 제한 없는 액세스를 원하는 경우 대신 **전체**를 선택합니다.1746* **클라우드 환경 업데이트** 대화 상자에서 **네트워크 액세스**를 **신뢰할 수 있는**에서 **사용자 정의**로 변경한 다음 차단된 도메인을 **허용된 도메인**에 추가합니다. 한 줄에 하나의 도메인을 입력합니다. **또한 일반적인 패키지 관리자의 기본 목록 포함**을 확인하여 사용자 정의 도메인과 함께 [기본 허용 목록](/docs/ko/cloud-environments#default-allowed-domains)을 유지합니다. 제한 없는 액세스를 원하는 경우 대신 **전체**를 선택합니다.

1745* **변경 사항 저장**을 클릭합니다. 다음 실행은 업데이트된 허용 목록을 사용합니다.1747* **변경 사항 저장**을 클릭합니다. 다음 실행은 업데이트된 허용 목록을 사용합니다.

permission-modes.md +6 −4

Details

328 328

329v2.1.158부터 v2.1.206까지 자동 모드는 `CLAUDE_CODE_ENABLE_AUTO_MODE=1`을 설정할 때까지 이 제공자들에서 꺼져 있었고, Claude Code는 변수도 설정되지 않으면 이 제공자들에서 `defaultMode: "auto"`를 무시했습니다. 변수는 호환성을 위해 여전히 허용되며 v2.1.207 이후로는 효과가 없습니다.329v2.1.158부터 v2.1.206까지 자동 모드는 `CLAUDE_CODE_ENABLE_AUTO_MODE=1`을 설정할 때까지 이 제공자들에서 꺼져 있었고, Claude Code는 변수도 설정되지 않으면 이 제공자들에서 `defaultMode: "auto"`를 무시했습니다. 변수는 호환성을 위해 여전히 허용되며 v2.1.207 이후로는 효과가 없습니다.

330 330

331<h4 id="server-side-classifier-review">331<h3 id="server-side-classifier-review">

332 서버 측 분류기 검토332 서버 측 분류기 검토

333</h4>333</h3>

334

335Enterprise 플랜 및 Claude API를 사용하는 계정, [AWS의 Claude Platform](/docs/ko/claude-platform-on-aws), Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry에서, 그리고 `ANTHROPIC_BASE_URL`을 [LLM 게이트웨이 또는 프록시](/docs/ko/llm-gateway)로 지정할 때마다 자동 모드의 Claude Code는 서버에 [분류기로 이동하는 작업](#how-the-classifier-evaluates-actions)을 세션의 모델 요청의 일부로 검토하도록 요청합니다. 서버가 이를 검토하는 경우 해당 판정이 이러한 작업을 결정합니다. 서버가 검토하지 않는 경우 (일반적으로 LLM 게이트웨이 또는 프록시가 트래픽을 방해하기 때문이거나 플랫폼, 지역 또는 자격 증명이 아직 서버 측 검사를 갖지 않았기 때문) Claude Code는 자체 분류기 요청으로 폴백하고, 해당 폴백이 세션의 나머지 동안 유지되면 이를 요청이 청구되는 계정에서 [분류기 요청 요금에 대한 공지](/docs/ko/auto-mode-classifier-billing)를 표시합니다. 서버에 요청하는 것을 건너뛰고 항상 Claude Code의 자체 분류기 요청을 사용하려면 [`CLAUDE_CODE_AUTO_MODE_SERVER=0`](/docs/ko/env-vars)을 설정하세요. 변수는 Anthropic API에 대한 직접 연결에서 읽혀지지 않습니다. `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`을 설정하고 `CLAUDE_CODE_AUTO_MODE_SERVER`를 설정하지 않으면 Claude Code도 서버에 요청하는 것을 중지합니다.

334 336

335Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry에서 Claude Code는 기본적으로 자체 분류기 요청으로 자동 모드 작업을 검토합니다. 플랫폼의 서버 측 분류기가 [분류기로 이동하는 작업](#how-the-classifier-evaluates-actions)을 세션의 모델 요청의 일부로 검토하도록 하려면 [`CLAUDE_CODE_AUTO_MODE_SERVER=1`](/docs/ko/env-vars)을 설정하세요. 플랫폼이 분류기를 실행하는 경우 해당 판정이 이러한 작업을 결정합니다. 플랫폼이 실행하지 않는 경우 Claude Code는 자체 분류기 요청으로 폴백합니다. v2.1.271 및 v2.1.272에서는 플랫폼에 요청하는 것이 이 제공자들의 기본값이었습니다.337기본적으로 서버에 요청하려면 Claude Code v2.1.278 이상이 필요합니다.

336 338

337<h3 id="what-the-classifier-blocks-by-default">339<h3 id="what-the-classifier-blocks-by-default">

338 분류기가 기본적으로 차단하는 것340 분류기가 기본적으로 차단하는 것

515 517

516 세션의 첫 번째 자동 모드 요청은 Sonnet 5 기본값을 검증합니다. 요청이 성공하면 Sonnet 5는 세션의 분류기 모델로 유지되고, 모델을 사용할 수 없어서 실패하면 세션은 폴백을 대신 사용합니다. 해당 검증이 정착한 후 분류기의 모델은 세션 동안 변경되지 않습니다.518 세션의 첫 번째 자동 모드 요청은 Sonnet 5 기본값을 검증합니다. 요청이 성공하면 Sonnet 5는 세션의 분류기 모델로 유지되고, 모델을 사용할 수 없어서 실패하면 세션은 폴백을 대신 사용합니다. 해당 검증이 정착한 후 분류기의 모델은 세션 동안 변경되지 않습니다.

517 519

518 Enterprise 플랜 및 Claude API, [AWS의 Claude Platform](/docs/ko/claude-platform-on-aws), Amazon Bedrock, Google Cloud의 Agent Platform 또는 Microsoft Foundry를 사용하는 계정에서 분류기 호출은 토큰 사용량에 계산됩니다. 각 검사는 트랜스크립트의 일부와 보류 중인 작업을 보내며 실행 전에 왕복을 추가합니다. 읽기 및 보호된 경로 외부의 작업 디렉토리 편집은 분류기를 건너뛰므로 오버헤드는 주로 셸 명령 및 네트워크 작업에서 발생합니다. Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry에서 검토를 세션의 모델 요청으로 이동할 수 있습니다. [서버 측 분류기 검토](#server-side-classifier-review)를 참조하세요.520 Enterprise 플랜 및 Claude API, [AWS의 Claude Platform](/docs/ko/claude-platform-on-aws), Amazon Bedrock, Google Cloud의 Agent Platform 또는 Microsoft Foundry를 사용하는 계정에서 분류기 호출은 토큰 사용량에 계산됩니다. 각 검사는 트랜스크립트의 일부와 보류 중인 작업을 보내며 실행 전에 왕복을 추가합니다. 읽기 및 보호된 경로 외부의 작업 디렉토리 편집은 분류기를 건너뛰므로 오버헤드는 주로 셸 명령 및 네트워크 작업에서 발생합니다. 서버가 세션의 모델 요청의 일부로 작업을 검토하는 경우 계산할 별도의 분류기 호출이 없습니다. [서버 측 분류기 검토](#server-side-classifier-review)를 참조하세요.

519 521

520 샌드박스 네트워크 액세스는 명령별 분류기 요청을 추가하지 않습니다. 분류기는 [명령이 명명하는 호스트](/docs/ko/sandboxing#per-command-allowed-domains-in-auto-mode)를 명령과 함께 판단하고, Claude Code는 각 연결을 승인된 목록에 대해 분류기를 다시 호출하지 않고 검사합니다.522 샌드박스 네트워크 액세스는 명령별 분류기 요청을 추가하지 않습니다. 분류기는 [명령이 명명하는 호스트](/docs/ko/sandboxing#per-command-allowed-domains-in-auto-mode)를 명령과 함께 판단하고, Claude Code는 각 연결을 승인된 목록에 대해 분류기를 다시 호출하지 않고 검사합니다.

521 </Accordion>523 </Accordion>

routines.md +41 −26

Details

45**라이브러리 포트.** GitHub 트리거가 한 SDK 저장소의 병합된 PR로 필터링된 `pull_request.closed`에서 실행됩니다. 루틴은 변경 사항을 다른 언어의 병렬 SDK로 포트하고 일치하는 PR을 열어 두 라이브러리를 동기화 상태로 유지하며 인간이 각 변경 사항을 다시 구현할 필요가 없습니다.45**라이브러리 포트.** GitHub 트리거가 한 SDK 저장소의 병합된 PR로 필터링된 `pull_request.closed`에서 실행됩니다. 루틴은 변경 사항을 다른 언어의 병렬 SDK로 포트하고 일치하는 PR을 열어 두 라이브러리를 동기화 상태로 유지하며 인간이 각 변경 사항을 다시 구현할 필요가 없습니다.

46 46

47<h2 id="create-a-routine">47<h2 id="create-a-routine">

~~48 루틴 생성~~48 루틴 만들기

49</h2>49</h2>

50 50

51웹의 [claude.ai/code/routines](https://claude.ai/code/routines), 데스크톱 앱 또는 CLI에서 루틴을 생성합니다. 세 가지 표면 모두 동일한 클라우드 계정에 쓰므로 한 곳에서 생성한 루틴이 즉시 다른 곳에 표시됩니다. 데스크톱 앱의 **Code** 탭에서 사이드바의 **Routines**을 클릭하거나 사이드바의 **More** 메뉴에서 **New routine**을 클릭한 다음 **Cloud**를 선택합니다. 대신 **Local**을 선택하면 머신에서 실행되는 [데스크톱 예약 작업](/docs/ko/desktop-scheduled-tasks)이 생성되며, 클라우드에서 실행되지 않습니다.51[claude.ai/code/routines](https://claude.ai/code/routines)의 웹에서, 데스크톱 앱에서, 또는 CLI에서 루틴을 만들 수 있습니다. 세 가지 인터페이스 모두 동일한 클라우드 계정에 저장되므로, 한 곳에서 만든 루틴이 다른 곳에 즉시 나타납니다. 데스크톱 앱의 **Code** 탭에서 사이드바의 **Routines**을 클릭하거나 사이드바의 **More** 메뉴에서 **New routine**을 클릭한 후 **Cloud**를 선택합니다. 대신 **Local**을 선택하면 [데스크톱 예약 작업](/docs/ko/desktop-scheduled-tasks)이 생성되며, 이는 클라우드가 아닌 사용자의 머신에서 실행됩니다.

52 52

53생성 양식은 루틴의 프롬프트, 저장소, 환경, 커넥터 및 트리거를 설정합니다.53생성 양식은 루틴의 프롬프트, 저장소, 환경, 커넥터 및 트리거를 설정합니다.

54 54

55루틴은 완전한 Claude Code 클라우드 세션으로 자율적으로 실행됩니다. 권한 모드 선택기나 실행 중 승인 프롬프트가 없습니다. 세션은 셸 명령을 실행하고, 복제된 저장소에 커밋된 [skills](/docs/ko/skills)를 사용하고, 포함된 모든 커넥터를 호출할 수 있습니다. 루틴이 도달할 수 있는 것은 선택한 저장소, [환경의](/docs/ko/cloud-environments) 네트워크 액세스 및 변수, 그리고 포함된 커넥터에 의해 결정됩니다. 루틴이 실제로 필요한 것으로 각각을 범위 지정합니다.55루틴은 전체 Claude Code 클라우드 세션으로 자율적으로 실행됩니다. 권한 모드 선택기가 없으며, 세션은 셸 명령을 실행하고, 복제된 저장소에 커밋된 [skills](/docs/ko/skills)를 사용하며, 포함된 모든 커넥터를 호출합니다. 모두 일부 [artifact](/docs/ko/artifacts) 작업을 제외하고는 승인을 기다리지 않고 실행됩니다.

56 56

57루틴은 개별 claude.ai 계정에 속합니다. 팀원과 공유되지 않으며 계정의 일일 실행 허용량에 대해 계산됩니다. 루틴이 연결된 GitHub 신원 또는 커넥터를 통해 수행하는 모든 작업은 사용자로 표시됩니다. 커밋 및 풀 요청은 GitHub 사용자를 전달하고, Slack 메시지, Linear 티켓 또는 기타 커넥터 작업은 해당 서비스에 대해 연결된 계정을 사용합니다.57루틴이 도달할 수 있는 범위는 선택한 저장소, [환경](/docs/ko/cloud-environments)의 네트워크 액세스 및 변수, 그리고 포함된 커넥터에 의해 결정됩니다. 루틴이 실제로 필요한 것으로 각각의 범위를 제한하십시오.

59루틴의 일정이나 **Run now**가 실행을 시작할 때, Claude는 다음의 모든 조건이 충족될 때만 기존 artifact를 다시 게시합니다:

61* 사용자가 artifact를 편집할 수 있으며 자신의 조직에 속함

62* artifact가 공개적으로 공유되지 않으며, 특정 사람이나 조직과 공유되지 않으며, 최신 버전이 뷰어가 보는 버전으로 선택되지 않음

63* 게시가 페이지만 포함하며, 지원 파일이나 다른 것이 추가되지 않으며, 더 새로운 버전을 강제로 덮어쓰지 않음

64* 페이지가 [connector calls](/docs/ko/artifacts#pull-live-data-with-mcp-connectors)와 같이 페이지를 넘어서는 권한을 보유하지 않음

66다른 모든 경우, 새로운 artifact를 게시하는 경우를 포함하여 Claude는 먼저 묻습니다. 루틴의 작업이 페이지를 최신 상태로 유지하는 것일 때, 이미 게시한 artifact를 제공하십시오.

68루틴은 개별 claude.ai 계정에 속합니다. 팀원과 공유되지 않으며, 계정의 일일 실행 한도에 포함됩니다. 루틴이 연결된 GitHub 신원이나 커넥터를 통해 수행하는 모든 작업은 사용자로 표시됩니다. 커밋과 풀 요청은 GitHub 사용자를 포함하며, Slack 메시지, Linear 티켓 또는 기타 커넥터 작업은 해당 서비스에 대한 연결된 계정을 사용합니다.

58 69

59<h3 id="create-from-the-web">70<h3 id="create-from-the-web">

~~60 웹에서 생성~~71 웹에서 만들기

61</h3>72</h3>

62 73

63<Steps>74<Steps>

64 <Step title="생성 양식 열기">75 <Step title="생성 양식 열기">

~~65 [claude.ai/code/routines](https://claude.ai/code/routines)를 방문하고 **New routine**을 클릭합니다.~~76 [claude.ai/code/routines](https://claude.ai/code/routines)을 방문하고 **New routine**을 클릭합니다.

66 </Step>77 </Step>

67 78

68 <Step title="루틴 이름 지정 및 프롬프트 작성">79 <Step title="루틴 이름 지정 및 프롬프트 작성">

69 루틴에 설명적인 이름을 지정하고 Claude가 매번 실행할 프롬프트를 작성합니다. 프롬프트가 가장 중요한 부분입니다. 루틴이 자율적으로 실행되므로 프롬프트는 자체 포함되어야 하며 수행할 작업과 성공이 무엇인지에 대해 명시적이어야 합니다.80 루틴에 설명적인 이름을 지정하고 Claude가 매번 실행할 프롬프트를 작성합니다. 프롬프트가 가장 중요한 부분입니다. 루틴이 자율적으로 실행되므로 프롬프트는 자체 포함되어야 하며 무엇을 할지, 성공이 무엇처럼 보이는지에 대해 명시적이어야 합니다.

70 81

71 트리거가 발생하면 세션은 루틴의 저장된 프롬프트를 할당된 작업으로 받고 이를 수행합니다. 신뢰할 수 없는 콘텐츠로 처리하지 않습니다. 트리거는 프롬프트가 계정의 권한이 있는 세션에 의해 미리 저장되었음을 증명하므로 발생한 프롬프트는 실시간 사용자 입력이 아니며 실행 중 작업에 대한 승인 또는 동의로 작용할 수 없습니다. 세션이 실행 중에 가져오는 콘텐츠는 정상적인 처리를 유지합니다. v2.1.213 이전에는 세션이 신뢰할 수 없는 백그라운드 알림으로 프레임된 동일한 프롬프트를 받았으며 이에 대해 작동하기를 거부할 수 있었습니다.82 트리거가 발동되면, 세션은 루틴의 저장된 프롬프트를 할당된 작업으로 받고 이를 수행합니다. 신뢰할 수 없는 콘텐츠로 대화 중간에 도착한 것으로 취급하지 않습니다. 트리거는 프롬프트가 계정의 승인된 세션에 의해 미리 저장되었음을 증명할 뿐이므로, 발동된 프롬프트는 실시간 사용자 입력이 아니며 실행 중 작업에 대한 승인이나 동의로 작용할 수 없습니다. 세션이 실행 중에 가져오는 콘텐츠는 정상적인 처리를 유지합니다. v2.1.213 이전에는 세션이 동일한 프롬프트를 신뢰할 수 없는 백그라운드 알림으로 받았으며 이에 대해 작동하기를 거부할 수 있었습니다.

72 83

73 프롬프트 입력에는 모델 선택기가 포함됩니다. Claude는 모든 실행에서 선택된 모델을 사용합니다.84 프롬프트 입력에는 모델 선택기가 포함됩니다. Claude는 모든 실행에서 선택된 모델을 사용합니다.

74 </Step>85 </Step>

75 86

76 <Step title="저장소 선택">87 <Step title="저장소 선택">

77 Claude가 작업할 하나 이상의 GitHub 저장소를 추가합니다. 각 저장소는 실행 시작 시 기본 브랜치에서 시작하여 복제됩니다. Claude는 변경 사항에 대해 `claude/` 접두사가 붙은 브랜치를 생성합니다.88 Claude가 작업할 하나 이상의 GitHub 저장소를 추가합니다. 각 저장소는 실행 시작 시 기본 분기에서 시작하여 복제됩니다. Claude는 변경 사항에 대해 `claude/` 접두사가 붙은 분기를 만듭니다.

78 </Step>89 </Step>

79 90

80 <Step title="환경 선택">91 <Step title="환경 선택">

~~81 루틴에 대해 [클라우드 환경](/docs/ko/cloud-environments)을 선택합니다. 환경은 클라우드 세션이 액세스할 수 있는 것을 제어합니다.~~92 루틴에 대해 [클라우드 환경](/docs/ko/cloud-environments)을 선택합니다. 환경은 클라우드 세션이 액세스할 수 있는 것을 제어합니다:

82 93

~~83 * **Network access**: 각 실행 중에 사용 가능한 인터넷 액세스 수준 설정~~94 * **Network access**: 각 실행 중에 사용 가능한 인터넷 액세스 수준을 설정합니다

84 * **Environment variables**: Claude가 실행 중에 사용할 수 있는 값을 제공합니다. 이들은 [환경을 사용하는 모든 사람에게 표시되므로](/docs/ko/cloud-environments#what-carries-over-from-your-setup) Pro 및 Max 플랜에서는 Claude가 실행 중에 호출하는 API의 키를 [API credentials](/docs/ko/cloud-environments#add-api-credentials)로 저장합니다. 해당 섹션에는 자격 증명을 받지 않는 요청도 나열됩니다.95 * **Environment variables**: Claude가 각 실행 중에 사용할 수 있는 값을 제공합니다. 이들은 [환경을 사용하는 모든 사람에게 표시](/docs/ko/cloud-environments#what-carries-over-from-your-setup)되므로, Pro 및 Max 플랜에서는 Claude가 실행 중에 호출하는 API의 키를 [API credentials](/docs/ko/cloud-environments#add-api-credentials)로 저장합니다. 해당 섹션에는 자격 증명을 받지 않는 요청도 나열됩니다

85 * **Setup script**: 루틴이 필요한 종속성 및 도구를 설치합니다. 결과는 [캐시됩니다](/docs/ko/cloud-environments#environment-caching). 따라서 스크립트는 모든 세션에서 다시 실행되지 않습니다.96 * **Setup script**: 루틴이 필요로 하는 종속성 및 도구를 설치합니다. 결과는 [캐시됩니다](/docs/ko/cloud-environments#environment-caching)이므로 스크립트는 모든 세션에서 다시 실행되지 않습니다

86 97

87 **Default** 환경이 제공되며 **Trusted** 네트워크 액세스가 있습니다. 이는 [기본 allowlist](/docs/ko/cloud-environments#default-allowed-domains)의 패키지 레지스트리, 클라우드 공급자 API, 컨테이너 레지스트리 및 일반적인 개발 도메인만 세션의 네트워크를 통해 허용합니다. 루틴에 추가하는 커넥터는 Anthropic의 서버를 통해 해당 서비스에 도달하므로 allowlist 변경이 필요하지 않습니다. 루틴이 자신의 서비스나 해당 목록 외의 도메인에 직접 도달해야 하는 경우 실행하기 전에 환경의 [network access](/docs/ko/cloud-environments#network-access)를 편집합니다. 별도의 환경을 사용하려면 먼저 [하나를 생성](/docs/ko/cloud-environments#configure-your-environment)합니다.98 **Default** 환경은 **Trusted** 네트워크 액세스와 함께 제공되며, 이는 세션의 네트워크를 통해 [기본 허용 목록](/docs/ko/cloud-environments#default-allowed-domains)의 패키지 레지스트리, 클라우드 제공자 API, 컨테이너 레지스트리 및 일반적인 개발 도메인만 허용합니다. 루틴에 추가하는 커넥터는 Anthropic의 서버를 통해 해당 서비스에 도달하므로 허용 목록 변경이 필요하지 않습니다. 루틴이 자신의 서비스에 직접 도달해야 하거나 해당 목록 외의 도메인에 도달해야 하는 경우, 실행하기 전에 환경의 [network access](/docs/ko/cloud-environments#network-access)를 편집합니다. 별도의 환경을 사용하려면 먼저 [하나를 만듭니다](/docs/ko/cloud-environments#configure-your-environment).

88 </Step>99 </Step>

89 100

90 <Step title="트리거 선택">101 <Step title="트리거 선택">

92 103

93 <Tabs>104 <Tabs>

94 <Tab title="Schedule">105 <Tab title="Schedule">

95 반복 실행을 위해 사전 설정된 빈도를 선택하거나 특정 타임스탬프에서 일회성 실행을 예약합니다. 시간대 처리, stagger, 사용자 정의 cron 간격 및 일회성 실행은 [Add a schedule trigger](#add-a-schedule-trigger)를 참조합니다.106 반복 실행을 위해 사전 설정된 빈도를 선택하거나 특정 타임스탬프에서 일회성 실행을 예약합니다. 시간대 처리, 엇갈림, 사용자 정의 cron 간격 및 일회성 실행에 대해서는 [Add a schedule trigger](#add-a-schedule-trigger)를 참조하십시오.

96 </Tab>107 </Tab>

97 108

98 <Tab title="GitHub event">109 <Tab title="GitHub event">

99 저장소, 반응할 이벤트 및 선택적 필터를 선택합니다. 지원되는 이벤트 및 필터 필드의 전체 목록은 [Add a GitHub trigger](#add-a-github-trigger)를 참조합니다.110 저장소, 반응할 이벤트 및 선택적 필터를 선택합니다. 지원되는 이벤트 및 필터 필드의 전체 목록은 [Add a GitHub trigger](#add-a-github-trigger)를 참조하십시오.

100 </Tab>111 </Tab>

101 112

102 <Tab title="API">113 <Tab title="API">

103 여기서 **API**를 선택한 다음 루틴을 저장합니다. URL과 토큰은 루틴 ID에 따라 달라지므로 루틴이 저장된 후 생성됩니다. URL을 복사하고 토큰을 생성하려면 [Add an API trigger](#add-an-api-trigger)를 참조합니다.114 여기서 **API**를 선택한 후 루틴을 저장합니다. URL과 토큰은 루틴 ID에 따라 달라지므로 루틴이 저장된 후에 생성됩니다. URL을 복사하고 토큰을 생성하려면 [Add an API trigger](#add-an-api-trigger)를 참조하십시오.

104 </Tab>115 </Tab>

105 </Tabs>116 </Tabs>

106 </Step>117 </Step>

107 118

108 <Step title="커넥터 검토">119 <Step title="커넥터 검토">

109 양식 하단의 **Connectors** 아래에서 연결된 모든 [MCP connectors](/docs/ko/mcp)는 기본적으로 포함됩니다. 루틴이 필요하지 않은 것을 제거합니다. Claude는 실행 중에 권한을 요청하지 않고 포함된 커넥터의 모든 도구(쓰기 포함)를 사용할 수 있습니다.120 양식 하단의 **Connectors** 아래에서 연결된 모든 [MCP connectors](/docs/ko/mcp)가 기본적으로 포함됩니다. 루틴이 필요하지 않은 것을 제거합니다. Claude는 실행 중에 권한을 요청하지 않고 포함된 커넥터의 모든 도구(쓰기 포함)를 사용할 수 있습니다.

110 </Step>121 </Step>

111 122

112 <Step title="루틴 생성">123 <Step title="루틴 만들기">

113 **Create**를 클릭합니다. 루틴이 목록에 나타나고 다음 번에 트리거 중 하나가 일치할 때 실행됩니다. 즉시 실행을 시작하려면 루틴의 세부 정보 페이지에서 **Run now**를 클릭합니다.124 **Create**를 클릭합니다. 루틴이 목록에 나타나고 다음 번에 트리거 중 하나가 일치할 때 실행됩니다. 즉시 실행을 시작하려면 루틴의 세부 정보 페이지에서 **Run now**를 클릭합니다.

114 125

115 각 실행은 다른 세션과 함께 새 세션을 생성하므로 Claude가 수행한 작업을 확인하고, 변경 사항을 검토하고, 풀 요청을 생성할 수 있습니다.126 각 실행은 다른 세션과 함께 새 세션을 만들며, 여기서 Claude가 수행한 작업을 확인하고, 변경 사항을 검토하고, 풀 요청을 만들 수 있습니다.

116 </Step>127 </Step>

117</Steps>128</Steps>

118 129

119<h3 id="create-from-the-cli">130<h3 id="create-from-the-cli">

120 CLI에서 생성131 CLI에서 만들기

121</h3>132</h3>

122 133

123모든 세션에서 `/schedule`을 실행하여 예약된 루틴을 대화식으로 생성합니다. `/schedule daily PR review at 9am`과 같은 반복 루틴이나 `/schedule clean up feature flag in one week`과 같은 일회성 루틴에 대해 설명을 직접 전달할 수도 있습니다. Claude는 웹 양식이 수집하는 동일한 정보를 안내한 다음 루틴을 계정에 저장합니다. 명령은 `/routines` 별칭 아래에서도 사용 가능합니다.134모든 세션에서 `/schedule`을 실행하여 대화식으로 예약된 루틴을 만듭니다. 반복 루틴의 경우 `/schedule daily PR review at 9am` 또는 일회성의 경우 `/schedule clean up feature flag in one week`과 같이 설명을 직접 전달할 수도 있습니다. Claude는 웹 양식이 수집하는 것과 동일한 정보(일정, 저장소 및 프롬프트)를 안내한 후 루틴을 계정에 저장합니다. 이 명령은 별칭 `/routines` 아래에서도 사용할 수 있습니다.

124 135

125성공적인 시작은 대화처럼 보입니다. Claude는 저장하기 전에 일정, 저장소 및 프롬프트에 대한 후속 질문을 합니다. Claude가 대신 인증이 필요하거나 원격 claude.ai 계정에 연결할 수 없다고 회신하면 루틴이 생성되지 않았습니다. [Troubleshooting](#troubleshooting)을 참조합니다.136성공적인 시작은 대화처럼 보입니다. Claude는 저장하기 전에 일정, 저장소 및 프롬프트에 대해 후속 질문을 합니다. Claude가 대신 인증이 필요하거나 원격 claude.ai 계정에 연결할 수 없다고 응답하면 루틴이 생성되지 않았습니다. [Troubleshooting](#troubleshooting)을 참조하십시오.

126 137

127CLI의 `/schedule`은 예약된 루틴만 생성합니다. API 트리거를 추가하려면 [claude.ai/code/routines](https://claude.ai/code/routines)의 웹에서 루틴을 편집합니다. 웹 또는 CLI에서 [GitHub trigger](#add-a-github-trigger)를 추가할 수 있습니다. CLI 경로에는 Claude Code v2.1.225 이상이 필요합니다.138CLI의 `/schedule`은 예약된 루틴을 만듭니다. API 트리거를 추가하려면 [claude.ai/code/routines](https://claude.ai/code/routines)의 웹에서 루틴을 편집합니다. 웹 또는 CLI에서 [GitHub trigger](#add-a-github-trigger)를 추가할 수 있습니다. CLI 경로에는 Claude Code v2.1.225 이상이 필요합니다.

128 139

129API 호출 또는 GitHub 이벤트에 의해서만 시작되는 일정 트리거가 없는 루틴은 다음 실행 시간이 없으며, Claude가 저장하거나 업데이트할 때 CLI에 표시되지 않습니다. v2.1.211 이전에는 CLI가 이러한 루틴에 대해 연도 1의 다음 실행 시간을 보고했습니다.140API 호출이나 GitHub 이벤트로만 시작되는 것과 같이 일정 트리거가 없는 루틴은 다음 실행 시간이 없으며, Claude가 저장하거나 업데이트할 때 CLI는 없음을 표시합니다. v2.1.211 이전에는 CLI가 이러한 루틴에 대해 연도 1의 다음 실행 시간을 보고했습니다.

130 141

131<h2 id="configure-triggers">142<h2 id="configure-triggers">

132 트리거 구성143 트리거 구성

349 360

350루틴은 저장소를 복제하기 위해 GitHub 액세스가 필요합니다. CLI에서 `/schedule`로 루틴을 생성할 때 Claude는 계정에 실행한 저장소에 대한 GitHub 액세스 권한이 있는지 확인하고, 없으면 액세스 권한을 부여하는 방법을 명시하는 설정 메모를 추가합니다. [GitHub 인증 옵션](/docs/ko/claude-code-on-the-web#github-authentication-options)을 참조하여 액세스 권한을 부여하는 두 가지 방법을 확인하세요.361루틴은 저장소를 복제하기 위해 GitHub 액세스가 필요합니다. CLI에서 `/schedule`로 루틴을 생성할 때 Claude는 계정에 실행한 저장소에 대한 GitHub 액세스 권한이 있는지 확인하고, 없으면 액세스 권한을 부여하는 방법을 명시하는 설정 메모를 추가합니다. [GitHub 인증 옵션](/docs/ko/claude-code-on-the-web#github-authentication-options)을 참조하여 액세스 권한을 부여하는 두 가지 방법을 확인하세요.

351 362

363GitHub 연결이 실행 예정 시간에 누락되거나 만료된 경우 루틴은 최대 72시간 동안 재연결할 때까지 실행을 건너뜁니다. 해당 기간 내에 GitHub를 다시 연결하면 루틴이 자동으로 재개됩니다. 72시간 동안 연결이 없으면 루틴이 꺼지고, GitHub를 다시 연결한 후 다시 켜야 합니다.

364

352추가하는 각 저장소는 모든 실행에서 복제됩니다. Claude는 프롬프트에서 달리 지정하지 않는 한 저장소의 기본 브랜치에서 시작합니다.365추가하는 각 저장소는 모든 실행에서 복제됩니다. Claude는 프롬프트에서 달리 지정하지 않는 한 저장소의 기본 브랜치에서 시작합니다.

353 366

354Claude는 `claude/` 접두사가 붙은 브랜치로 작업을 푸시하며, 이는 항상 허용됩니다. 프롬프트가 Claude를 다른 브랜치로 푸시하도록 지시할 때 Claude Code는 먼저 푸시를 확인하고 다음 중 하나라도 참이면 거부합니다.367Claude는 `claude/` 접두사가 붙은 브랜치로 작업을 푸시하며, 이는 항상 허용됩니다. 프롬프트가 Claude를 다른 브랜치로 푸시하도록 지시할 때 Claude Code는 먼저 푸시를 확인하고 다음 중 하나라도 참이면 거부합니다.

377 390

378**기본** 환경은 **신뢰할 수 있는** 네트워크 액세스를 사용하며, 이는 세션의 네트워크를 통해 [기본 허용 목록](/docs/ko/cloud-environments#default-allowed-domains)만 허용합니다. 허용 목록 외부의 호스트에 대한 요청은 `403` 및 `x-deny-reason: host_not_allowed`로 실패합니다. MCP 커넥터 트래픽은 Anthropic의 서버를 통해 라우팅되므로 루틴에 추가하는 커넥터는 **허용된 도메인**에 호스트를 추가하지 않고도 작동합니다. [커넥터](#connectors) 아래에서 필요하지 않은 커넥터를 제거하세요.391**기본** 환경은 **신뢰할 수 있는** 네트워크 액세스를 사용하며, 이는 세션의 네트워크를 통해 [기본 허용 목록](/docs/ko/cloud-environments#default-allowed-domains)만 허용합니다. 허용 목록 외부의 호스트에 대한 요청은 `403` 및 `x-deny-reason: host_not_allowed`로 실패합니다. MCP 커넥터 트래픽은 Anthropic의 서버를 통해 라우팅되므로 루틴에 추가하는 커넥터는 **허용된 도메인**에 호스트를 추가하지 않고도 작동합니다. [커넥터](#connectors) 아래에서 필요하지 않은 커넥터를 제거하세요.

379 392

380추가 도메인을 허용하려면:393자신의 환경 중 하나에서 추가 도메인을 허용하려면 다음 단계를 따르세요. [조직 공유 환경](/docs/ko/cloud-environments#organization-shared-environments)은 여기서 읽기 전용으로 열리므로 소유자는 [관리 설정](https://claude.ai/admin-settings)의 **클라우드 환경** 페이지에서 네트워크 액세스를 변경합니다.

381 394

382<Steps>395<Steps>

383 <Step title="루틴을 편집하기 위해 열기">396 <Step title="루틴을 편집하기 위해 열기">

413 426

414일회성 실행은 일일 루틴 실행 상한선에 포함되지 않습니다. 다른 세션과 마찬가지로 정기 구독 사용을 소비합니다.427일회성 실행은 일일 루틴 실행 상한선에 포함되지 않습니다. 다른 세션과 마찬가지로 정기 구독 사용을 소비합니다.

415 428

429구독이 일시 중지된 동안 루틴은 보류 상태가 되며 실행되지 않습니다. 구독이 다시 활성화되면 루틴을 다시 켜세요.

430

416<h2 id="troubleshooting">431<h2 id="troubleshooting">

417 문제 해결432 문제 해결

418</h2>433</h2>

self-hosted-environments-deploy.md +13 −1

Details

168* 러너는 `GCM_INTERACTIVE=never`을 설정하므로 Git Credential Manager는 서명 대화를 열지 않습니다.168* 러너는 `GCM_INTERACTIVE=never`을 설정하므로 Git Credential Manager는 서명 대화를 열지 않습니다.

169* 러너는 `core.askPass`를 지우므로 askpass 헬퍼를 사용하는 경우 `GIT_ASKPASS` 환경 변수를 통해 설정하세요.169* 러너는 `core.askPass`를 지우므로 askpass 헬퍼를 사용하는 경우 `GIT_ASKPASS` 환경 변수를 통해 설정하세요.

170 170

171git 호스트가 자격증명을 거부하거나 구성하지 않은 경우 러너는 몇 번 재시도한 다음 리포지토리 준비에 실패합니다. 러너는 이러한 설정을 세션의 환경에 전달하지 않습니다.171git 호스트가 자격증명을 거부하거나 구성하지 않은 경우 러너는 몇 번 재시도한 다음 리포지토리 준비에 실패합니다. 세션이 결과를 푸시하는 리포지토리인 경우입니다. 세션이 읽기만 하는 리포지토리의 경우 [문제 해결](#troubleshooting)에서 러너가 대신 건너뛸 때를 다룹니다. 러너는 이러한 설정을 세션의 환경에 전달하지 않습니다.

172 172

173체크아웃 디렉토리가 러너 프로세스와 다른 uid로 소유된 경우 git은 이에 대해 작동하기를 거부합니다. `safe.directory`를 추가하세요:173체크아웃 디렉토리가 러너 프로세스와 다른 uid로 소유된 경우 git은 이에 대해 작동하기를 거부합니다. `safe.directory`를 추가하세요:

174 174

531* **세션이 인증하는 이그레스 프록시를 통해 네트워크에 도달할 수 없음**: [`--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`로 시작 시 종료되면 루프백 리스너를 열 수 없습니다.531* **세션이 인증하는 이그레스 프록시를 통해 네트워크에 도달할 수 없음**: [`--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`로 시작 시 종료되면 루프백 리스너를 열 수 없습니다.

532* **러너 로그에 `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 이전에 러너는 그러한 응답을 빈 작업 큐로 읽었으며, 이는 라이브 세션을 종료하거나 종료하게 할 수 있습니다.532* **러너 로그에 `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 이전에 러너는 그러한 응답을 빈 작업 큐로 읽었으며, 이는 라이브 세션을 종료하거나 종료하게 할 수 있습니다.

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

534* **세션이 해당 리포지토리 중 하나 없이 시작됨**: [`checkout` hook](/docs/ko/self-hosted-environments-configuration#checkout)이 없는 러너에서 git 호스트는 세션이 읽기만 하는 리포지토리에 대한 러너의 액세스 확인을 거부할 수 있습니다. 그러면 러너는 해당 리포지토리를 건너뛰고 거부를 이름 지정하는 `[runner:warn] could not access context source` 라인을 기록하고 나머지에서 세션을 시작합니다.

535

536 러너는 명확한 거부만 건너뜁니다. 호스트가 리포지토리를 찾을 수 없다고 응답하거나, git이 호스트에 대한 자격증명을 찾지 못하거나, 인증이 실패합니다. 네트워크 실패, 시간 초과, 또는 HTTP `403`은 여전히 세션 시작을 실패하게 하며, 세션이 결과를 푸시하는 리포지토리에 대한 거부도 마찬가지입니다. 러너는 여전히 건너뛰기가 리포지토리 없이 남겨질 세션을 실패합니다. [`--use-anthropic-git-proxy`](#use-the-anthropic-git-proxy)를 사용하면 러너는 git 프록시 자체가 거부하는 리포지토리만 건너뜁니다.

537

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

534* **세션이 시작하는 데 분이 걸림**: 초기 클론이 일반적으로 지배합니다. `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`로 클론을 자르세요.539* **세션이 시작하는 데 분이 걸림**: 초기 클론이 일반적으로 지배합니다. `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`로 클론을 자르세요.

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

541

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

543

544 모든 호출이 세션 약 30분 후에 실패하기 시작하면 래퍼 스크립트가 세션의 stdin을 끊었을 가능성이 높으므로 토큰 회전이 도달할 수 없습니다. [stdin 및 파일 디스크립터 3 유지](/docs/ko/self-hosted-environments-configuration#keep-stdin-and-file-descriptor-3-attached)를 참조하세요.

545

546 v2.1.274 이전에 러너는 실패한 가져오기 후 몇 번의 시도 후 재시도를 중지하고 다음 예약된 것을 기다렸습니다. 실패한 턴은 가져오기를 트리거하지 않았으므로 모든 턴은 다음 예약된 가져오기까지 401로 실패했습니다.

535* **Pod이 드레인 중간에 종료됨**: `terminationGracePeriodSeconds`를 최소한 러너가 시작 시 기록하는 값으로 올리세요. [종료 타이밍](#shutdown-timing)을 참조하세요.547* **Pod이 드레인 중간에 종료됨**: `terminationGracePeriodSeconds`를 최소한 러너가 시작 시 기록하는 값으로 올리세요. [종료 타이밍](#shutdown-timing)을 참조하세요.

536 548

537로깅이 초기화되면 러너는 수명 주기 로그(JSON이 아닌 일반 텍스트 라인으로 `[runner:fatal]` 라인 포함)를 stdout에 쓰고 디버그 출력을 stderr에 씁니다. 위의 문제 해결 항목에서 설명하는 시작 실패는 그 지점 전에 stderr에 인쇄됩니다. `--log-file`로 두 스트림을 캡처하세요. 이는 또한 `self-hosted-runner doctor`가 이들을 추적하도록 합니다. 또는 플랫폼의 로그 수집으로 캡처하세요.549로깅이 초기화되면 러너는 수명 주기 로그(JSON이 아닌 일반 텍스트 라인으로 `[runner:fatal]` 라인 포함)를 stdout에 쓰고 디버그 출력을 stderr에 씁니다. 위의 문제 해결 항목에서 설명하는 시작 실패는 그 지점 전에 stderr에 인쇄됩니다. `--log-file`로 두 스트림을 캡처하세요. 이는 또한 `self-hosted-runner doctor`가 이들을 추적하도록 합니다. 또는 플랫폼의 로그 수집으로 캡처하세요.

self-hosted-environments-reference.md +1 −0

Details

103| `SELF_HOSTED_RUNNER_BG_RESULT_GRACE_MS` | `30000` | 러너가 백그라운드 작업이 완료된 후 결과를 읽는 후속 턴이 시작되지 않은 동안 세션을 바쁜 것으로 간주하는 시간입니다. [`--drain-wait-sec` 및 `--release-idle-session-min` 행](#runner-cli-flags)은 드레인 및 유휴 해제에서 보유가 적용되는 위치를 설명하며, [Runner lifecycle](/docs/ko/self-hosted-environments#runner-lifecycle)은 `--retire-at` 은퇴에서 적용되는 위치를 설명합니다. `0` 또는 사용할 수 없는 값은 기본값으로 폴백되므로 보유를 끌 수 없습니다. Claude Code v2.1.228 이상이 필요합니다. |103| `SELF_HOSTED_RUNNER_BG_RESULT_GRACE_MS` | `30000` | 러너가 백그라운드 작업이 완료된 후 결과를 읽는 후속 턴이 시작되지 않은 동안 세션을 바쁜 것으로 간주하는 시간입니다. [`--drain-wait-sec` 및 `--release-idle-session-min` 행](#runner-cli-flags)은 드레인 및 유휴 해제에서 보유가 적용되는 위치를 설명하며, [Runner lifecycle](/docs/ko/self-hosted-environments#runner-lifecycle)은 `--retire-at` 은퇴에서 적용되는 위치를 설명합니다. `0` 또는 사용할 수 없는 값은 기본값으로 폴백되므로 보유를 끌 수 없습니다. Claude Code v2.1.228 이상이 필요합니다. |

104| `SELF_HOSTED_RUNNER_HOST_CONFIG_DIR` | `~/.claude` | 러너의 시작 스냅샷으로 캡처되고 각 세션의 `CLAUDE_CONFIG_DIR`로 시드되는 디렉토리입니다. 디스크의 변경 사항은 러너 재시작 후 적용됩니다. 변수를 설정하면 러너가 [MCP seeding](/docs/ko/self-hosted-environments-configuration#mcp-servers)을 위해 `.claude.json`을 읽는 위치도 이동하므로 설정하면 자체 기본값을 포함하여 해당 조회를 재배치합니다. 빈 디렉토리를 가리켜 시딩을 완전히 비활성화하세요. |104| `SELF_HOSTED_RUNNER_HOST_CONFIG_DIR` | `~/.claude` | 러너의 시작 스냅샷으로 캡처되고 각 세션의 `CLAUDE_CONFIG_DIR`로 시드되는 디렉토리입니다. 디스크의 변경 사항은 러너 재시작 후 적용됩니다. 변수를 설정하면 러너가 [MCP seeding](/docs/ko/self-hosted-environments-configuration#mcp-servers)을 위해 `.claude.json`을 읽는 위치도 이동하므로 설정하면 자체 기본값을 포함하여 해당 조회를 재배치합니다. 빈 디렉토리를 가리켜 시딩을 완전히 비활성화하세요. |

105| `SELF_HOSTED_RUNNER_MAX_LIFETIME_GRACE_MS` | `900000` | 세션이 `--kill-session-after-min` 제한에 도달한 후, 러너가 세션을 종료하기 전에 실행 중인 턴이 완료되거나 해제가 완료될 때까지 대기하는 시간입니다. |105| `SELF_HOSTED_RUNNER_MAX_LIFETIME_GRACE_MS` | `900000` | 세션이 `--kill-session-after-min` 제한에 도달한 후, 러너가 세션을 종료하기 전에 실행 중인 턴이 완료되거나 해제가 완료될 때까지 대기하는 시간입니다. |

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

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

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

slack.md +3 −1

Details

231 231

232이 항목은 [Claude Tag](https://claude.com/docs/claude-tag/overview)를 사용하는 워크스페이스에 적용되며, 여기서 Claude는 조직의 공유 ID로 채널에서 작동하며 어떤 멤버의 계정으로도 작동하지 않습니다. [claude.ai/code](https://claude.ai/code)에서 채널의 클라우드 환경을 생성한 경우, 이는 개인 계정에 속하며 Claude는 개인 환경에서 채널 세션을 시작할 수 없습니다. Claude Code는 세션을 즉시 실패하며, 재시도해도 도움이 되지 않습니다.232이 항목은 [Claude Tag](https://claude.com/docs/claude-tag/overview)를 사용하는 워크스페이스에 적용되며, 여기서 Claude는 조직의 공유 ID로 채널에서 작동하며 어떤 멤버의 계정으로도 작동하지 않습니다. [claude.ai/code](https://claude.ai/code)에서 채널의 클라우드 환경을 생성한 경우, 이는 개인 계정에 속하며 Claude는 개인 환경에서 채널 세션을 시작할 수 없습니다. Claude Code는 세션을 즉시 실패하며, 재시도해도 도움이 되지 않습니다.

233 233

234Owner인 경우, [admin settings](https://claude.ai/admin-settings)의 **Cloud environments** 페이지에서 환경을 [organization-shared environment](/docs/ko/cloud-environments#organization-shared-environments)로 다시 생성합니다. 두 가지 방법으로 적용할 수 있습니다:234Owner인 경우 환경이 본인 것이면, [환경 선택기에서 조직과 공유합니다](/docs/ko/cloud-environments#organization-shared-environments). 그렇지 않으면 Owner가 [admin settings](https://claude.ai/admin-settings)의 **Cloud environments** 페이지에서 조직 공유 환경으로 다시 생성합니다.

235

236두 가지 방법으로 적용할 수 있습니다:

235 237

236* [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code)에서 조직 기본값으로 설정합니다.238* [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code)에서 조직 기본값으로 설정합니다.

237* Claude Tag admin settings에서 [채널에 설정합니다](https://claude.com/docs/claude-tag/admins/troubleshooting#channel-sessions-use-the-wrong-environment-or-can%E2%80%99t-find-one).239* Claude Tag admin settings에서 [채널에 설정합니다](https://claude.com/docs/claude-tag/admins/troubleshooting#channel-sessions-use-the-wrong-environment-or-can%E2%80%99t-find-one).

web-quickstart.md +2 −0

Details

196<Steps>196<Steps>

197 <Step title="차이 보기 열기">197 <Step title="차이 보기 열기">

198 차이 표시기는 세션 전체에서 추가되고 제거된 줄을 표시합니다(예: `+42 -18`). 이를 선택하여 차이 보기를 열고, 왼쪽에 파일 목록이 있고 오른쪽에 변경 사항이 있습니다.198 차이 표시기는 세션 전체에서 추가되고 제거된 줄을 표시합니다(예: `+42 -18`). 이를 선택하여 차이 보기를 열고, 왼쪽에 파일 목록이 있고 오른쪽에 변경 사항이 있습니다.

199

200 차이 보기는 기본적으로 세션의 변경 사항을 기본 분기와 비교합니다. 다른 분기와 비교하려면 **비교 대상**을 선택하고 하나를 선택합니다.

199 </Step>201 </Step>

200 202

201 <Step title="인라인 댓글 남기기">203 <Step title="인라인 댓글 남기기">

Documentation 2026-09-18 23:58 UTC to 2026-09-19 23:57 UTC