Documentation — Spybara

artifacts.md +3 −3

Details

326각 아티팩트는 하나의 자체 포함된 페이지입니다. Claude Code는 게시하는 파일을 HTML 문서 셸로 래핑하고 엄격한 콘텐츠 보안 정책(CSP)에 따라 제공하며, 이는 페이지가 수행할 수 있는 작업을 결정합니다.326각 아티팩트는 하나의 자체 포함된 페이지입니다. Claude Code는 게시하는 파일을 HTML 문서 셸로 래핑하고 엄격한 콘텐츠 보안 정책(CSP)에 따라 제공하며, 이는 페이지가 수행할 수 있는 작업을 결정합니다.

327 327

328| 제약 사항 | 효과 |328| 제약 사항 | 효과 |

329| :------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |329| :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

330| 외부 요청 | 페이지는 Google Fonts에서 글꼴을 로드할 수 있으며, [4개의 공개 CDN 호스트](#allowlist-the-viewer-domain)에서 스크립트를 로드할 수 있습니다: cdnjs, Tailwind 및 jQuery CDN, 그리고 jsDelivr의 선택된 경로(예: `/npm/`). CSP는 모든 외부 이미지와 다른 모든 외부 스크립트, 스타일시트 및 글꼴을 차단하며, `fetch`, XHR 및 WebSocket 호출이 페이지 자체 원본과 Google Fonts 호스트에만 도달하도록 합니다. Claude는 따라서 페이지가 필요로 하는 모든 라이브러리를 이러한 CDN 중 하나에서 로드하고, 다른 모든 CSS 및 JavaScript를 인라인으로 처리하며, 이미지를 데이터 URI로 임베드합니다. [커넥터 호출](#pull-live-data-with-mcp-connectors)은 claude.ai를 통해 진행되며, 이는 네트워크 호출을 자체적으로 수행합니다. |330| 외부 요청 | 페이지는 Google Fonts에서 글꼴을 로드할 수 있으며, [5개의 공개 CDN 호스트](#allowlist-the-viewer-domain)에서 스크립트를 로드할 수 있습니다: cdnjs, unpkg, Tailwind 및 jQuery CDN, 그리고 jsDelivr의 선택된 경로(예: `/npm/`). CSP는 모든 외부 이미지와 다른 모든 외부 스크립트, 스타일시트 및 글꼴을 차단하며, `fetch`, XHR 및 WebSocket 호출이 페이지 자체 원본과 Google Fonts 호스트에만 도달하도록 합니다. Claude는 따라서 페이지가 필요로 하는 모든 라이브러리를 이러한 CDN 중 하나에서 로드하고, 다른 모든 CSS 및 JavaScript를 인라인으로 처리하며, 이미지를 데이터 URI로 임베드합니다. [커넥터 호출](#pull-live-data-with-mcp-connectors)은 claude.ai를 통해 진행되며, 이는 네트워크 호출을 자체적으로 수행합니다. |

332| 다운로드 | 페이지는 자체적으로 다운로드를 시작할 수 없습니다. 뷰어가 페이지에서 생성하는 파일을 저장할 수 있도록 하려면 Claude가 다운로드 기능을 선언합니다. [파일 다운로드 제공](#offer-a-file-download)을 참조하십시오. |332| 다운로드 | 페이지는 자체적으로 다운로드를 시작할 수 없습니다. 뷰어가 페이지에서 생성하는 파일을 저장할 수 있도록 하려면 Claude가 다운로드 기능을 선언합니다. [파일 다운로드 제공](#offer-a-file-download)을 참조하십시오. |

417 417

418[Google Fonts](#improve-the-visual-design)에서 글꼴을 로드하는 아티팩트는 `fonts.googleapis.com` 및 `fonts.gstatic.com`도 요청합니다. 두 호스트 모두 선택 사항입니다. 이들을 차단하면 아티팩트는 대체 글꼴로 렌더링됩니다. 글꼴 요청이 페이지의 첫 렌더링을 지연시키는 대신 즉시 실패하도록 빠른 거부로 차단하십시오.418[Google Fonts](#improve-the-visual-design)에서 글꼴을 로드하는 아티팩트는 `fonts.googleapis.com` 및 `fonts.gstatic.com`도 요청합니다. 두 호스트 모두 선택 사항입니다. 이들을 차단하면 아티팩트는 대체 글꼴로 렌더링됩니다. 글꼴 요청이 페이지의 첫 렌더링을 지연시키는 대신 즉시 실패하도록 빠른 거부로 차단하십시오.

419 419

420아티팩트는 또한 React 또는 차트 패키지와 같은 JavaScript 라이브러리를 `cdnjs.cloudflare.com`, `cdn.jsdelivr.net`, `cdn.tailwindcss.com`, `code.jquery.com`에서 로드할 수 있으며 다른 외부 호스트에서는 로드할 수 없습니다. 이러한 호스트를 차단하면 라이브러리에 의존하는 아티팩트의 부분이 작동하지 않으며, 차단된 글꼴과 달리 차단된 라이브러리는 대체 기능이 없습니다. 차단된 라이브러리 요청이 시간 초과될 때까지 중단되는 대신 즉시 실패하도록 여기서도 빠른 거부로 차단하십시오.420아티팩트는 또한 React 또는 차트 패키지와 같은 JavaScript 라이브러리를 `cdnjs.cloudflare.com`, `cdn.jsdelivr.net`, `cdn.tailwindcss.com`, `code.jquery.com`, `unpkg.com`에서 로드할 수 있으며 다른 외부 호스트에서는 로드할 수 없습니다. 이러한 호스트를 차단하면 라이브러리에 의존하는 아티팩트의 부분이 작동하지 않으며, 차단된 글꼴과 달리 차단된 라이브러리는 대체 기능이 없습니다. 차단된 라이브러리 요청이 시간 초과될 때까지 중단되는 대신 즉시 실패하도록 여기서도 빠른 거부로 차단하십시오.

421 421

422<h3 id="list-and-delete-artifacts-with-the-compliance-api">422<h3 id="list-and-delete-artifacts-with-the-compliance-api">

423 Compliance API를 사용하여 아티팩트 나열 및 삭제423 Compliance API를 사용하여 아티팩트 나열 및 삭제

claude-apps-gateway.md +9 −2

Details

172 volumes: { pgdata: }172 volumes: { pgdata: }

173 ```173 ```

174 174

175 게이트웨이는 구성을 읽고, Postgres에 연결하고 스키마 마이그레이션을 적용하고, IdP에 대해 OIDC 검색을 실행하고, 업스트림 클라이언트를 빌드하고, 수신 대기를 시작하는 단일 Linux 바이너리입니다. 부팅은 구성, 5초 타임아웃이 있는 Postgres 연결, OIDC 검색 및 업스트림 클라이언트 구성에 대해 실패 폐쇄됩니다. 이 중 하나가 도달 불가능하거나 잘못 구성된 경우, 게이트웨이는 저하된 상태에서 트래픽을 제공하는 대신 오류로 종료됩니다.175 게이트웨이는 구성을 읽고, Postgres에 연결하고 스키마 마이그레이션을 적용하고, IdP에 대해 OIDC 검색을 실행하고, 업스트림 클라이언트를 빌드하고, 수신 대기를 시작하는 단일 Linux 바이너리입니다. 부팅은 구성, Postgres 연결, OIDC 검색 및 업스트림 클라이언트 구성에 대해 실패 폐쇄됩니다. 이 중 하나가 도달 불가능하거나 잘못 구성된 경우, 게이트웨이는 저하된 상태에서 트래픽을 제공하는 대신 오류로 종료됩니다.

176 176

177 성공적인 부팅은 Bedrock 및 Agent Platform 인스턴스 자격증명이 부팅 시가 아닌 첫 요청에서 확인되기 때문에 추론 경로를 검증하지 않습니다.177 성공적인 부팅은 Amazon Bedrock 및 Google Cloud의 Agent Platform 인스턴스 자격증명이 부팅 시가 아닌 첫 요청에서 확인되기 때문에 추론 경로를 검증하지 않습니다.

178 178

179 부팅 시퀀스에 대해 stderr를 감시하세요. 로그 라인은 `[gateway] <timestamp> <level> <message>` 형식을 사용하고, 감사 이벤트는 `evt` 필드가 있는 단일 라인 JSON이며, 시작 배너(아래 생략됨)는 마이그레이션과 수신 대기 라인 사이에 인쇄됩니다. 신규 데이터베이스는 스키마 마이그레이션당 하나의 `migration N applied` 라인을 인쇄합니다; 이미 마이그레이션된 데이터베이스는 없습니다. 순서대로 다음을 볼 수 있습니다:179 부팅 시퀀스에 대해 stderr를 감시하세요. 로그 라인은 `[gateway] <timestamp> <level> <message>` 형식을 사용하고, 감사 이벤트는 `evt` 필드가 있는 단일 라인 JSON이며, 시작 배너(아래 생략됨)는 마이그레이션과 수신 대기 라인 사이에 인쇄됩니다. 신규 데이터베이스는 스키마 마이그레이션당 하나의 `migration N applied` 라인을 인쇄합니다; 이미 마이그레이션된 데이터베이스는 없습니다. 순서대로 다음을 볼 수 있습니다:

180 180

273 273

274인증서가 회전하면 모든 개발자가 신뢰 프롬프트를 다시 보므로, 회전을 계획된 이벤트로 취급하고 지문을 다시 게시하세요. 게이트웨이 정책에 [승인이 필요한 설정](/docs/ko/server-managed-settings#security-approval-dialogs)이 포함되어 있으면, 개발자는 새 인증서를 수락한 후 승인 대화상자를 다시 보게 됩니다. Claude Code는 [승인 메모리](/docs/ko/server-managed-settings#approval-memory)를 고정된 인증서에 키 지정하기 때문입니다.274인증서가 회전하면 모든 개발자가 신뢰 프롬프트를 다시 보므로, 회전을 계획된 이벤트로 취급하고 지문을 다시 게시하세요. 게이트웨이 정책에 [승인이 필요한 설정](/docs/ko/server-managed-settings#security-approval-dialogs)이 포함되어 있으면, 개발자는 새 인증서를 수락한 후 승인 대화상자를 다시 보게 됩니다. Claude Code는 [승인 메모리](/docs/ko/server-managed-settings#approval-memory)를 고정된 인증서에 키 지정하기 때문입니다.

275 275

276게이트웨이는 토큰 응답에서 선택적 `email` 필드를 반환하여 로그인이 사용한 계정의 이름을 지정할 수 있습니다. 이렇게 하면, 개발자는 Claude Code가 자격증명을 저장하기 전에 계정을 확인합니다. 확인된 로그인 후, `/status`는 계정을 표시합니다.

277

278확인은 개발자 머신의 Claude Code v2.1.275 이상이 필요합니다; 해당 버전 아래의 클라이언트는 필드를 무시합니다. `claude` 바이너리의 게이트웨이 서버는 필드를 반환하지 않으므로, 해당 로그인은 확인 없이 완료됩니다.

279

276개발자가 로그인하면, [모델 선택기](/docs/ko/model-config)는 개발자의 `availableModels` 허용 목록의 모델을 표시합니다. 관리 설정은 시작 시 적용되고 매시간 새로 고쳐지며, 텔레메트리는 수집기로 라우팅됩니다.280개발자가 로그인하면, [모델 선택기](/docs/ko/model-config)는 개발자의 `availableModels` 허용 목록의 모델을 표시합니다. 관리 설정은 시작 시 적용되고 매시간 새로 고쳐지며, 텔레메트리는 수집기로 라우팅됩니다.

277 281

278세션은 `ttl_hours` 만료 전에 자동으로 새로 고쳐집니다. IdP 프로비저닝 해제 후 새로 고침이 실패하면, Claude Code는 개발자에게 다시 로그인하도록 프롬프트합니다.282세션은 `ttl_hours` 만료 전에 자동으로 새로 고쳐집니다. IdP 프로비저닝 해제 후 새로 고침이 실패하면, Claude Code는 개발자에게 다시 로그인하도록 프롬프트합니다.

487* **게이트웨이에 도달할 수 없는 상태에서 시작**: 로그인한 세션은 설정 없이 시작하는 대신 약 10초 후 시작 시 오류로 종료됩니다.491* **게이트웨이에 도달할 수 없는 상태에서 시작**: 로그인한 세션은 설정 없이 시작하는 대신 약 10초 후 시작 시 오류로 종료됩니다.

488* **게이트웨이가 세션을 종료한 후 시작**: [실패 폐쇄 시작 적용](/docs/ko/server-managed-settings#enforce-fail-closed-startup)을 참조하여 어느 시작이 게이트웨이에서 로그아웃된 상태로 열리고 어느 시작이 게이트웨이가 `401`로 응답할 때 종료되는지 확인하세요.492* **게이트웨이가 세션을 종료한 후 시작**: [실패 폐쇄 시작 적용](/docs/ko/server-managed-settings#enforce-fail-closed-startup)을 참조하여 어느 시작이 게이트웨이에서 로그아웃된 상태로 열리고 어느 시작이 게이트웨이가 `401`로 응답할 때 종료되는지 확인하세요.

489* **프로비저닝 해제**: 사용자가 IdP에서 비활성화된 세션은 다음 새로 고침이 실패할 때 `ttl_hours` 내에 만료됩니다.493* **프로비저닝 해제**: 사용자가 IdP에서 비활성화된 세션은 다음 새로 고침이 실패할 때 `ttl_hours` 내에 만료됩니다.

494* **로그아웃**: `/logout`은 개발자의 머신에서 게이트웨이 자격증명을 삭제합니다.

495 * 게이트웨이의 검색 문서가 게이트웨이 URL의 자신의 스킴, 호스트, 포트에서 `revocation_endpoint`를 광고할 때, `/logout`은 또한 저장된 토큰을 해당 엔드포인트로 보내므로 게이트웨이가 자신의 측에서 세션을 종료할 수 있습니다. 요청은 최선의 노력이므로, 엔드포인트가 응답하는지 여부와 관계없이 로그아웃은 개발자의 머신에서 완료됩니다. 취소는 개발자 머신의 Claude Code v2.1.275 이상이 필요합니다.

496 * `claude` 바이너리의 게이트웨이 서버는 광고하지 않으므로, 로그아웃은 개발자의 머신에서만 세션을 종료합니다. 서버 측에서 세션을 강제로 종료하려면, [JWT 비밀 회전](/docs/ko/claude-apps-gateway-deploy#jwt-secret-rotation)을 참조하세요.

490 497

491<h3 id="what-the-organization-can-see">498<h3 id="what-the-organization-can-see">

492 조직이 볼 수 있는 것499 조직이 볼 수 있는 것

claude-apps-gateway-config.md +292 −185

Details

94| `id_token_signed_response_alg` | 아니오 | 예상되는 id\_token 서명 알고리즘입니다. 기본값 `RS256`. ES256, PS256, 또는 EdDSA로 서명하는 IdP에 대해 설정합니다. |94| `id_token_signed_response_alg` | 아니오 | 예상되는 id\_token 서명 알고리즘입니다. 기본값 `RS256`. ES256, PS256, 또는 EdDSA로 서명하는 IdP에 대해 설정합니다. |

95| `additional_authorized_parties` | 아니오 | `client_id` 이외에 수락할 추가 `azp` 값입니다. Keycloak 브로커 및 토큰 교환 흐름의 경우입니다. |95| `additional_authorized_parties` | 아니오 | `client_id` 이외에 수락할 추가 `azp` 값입니다. Keycloak 브로커 및 토큰 교환 흐름의 경우입니다. |

96| `discovery_url` | 아니오 | `issuer`에서 파생시키는 대신 이 URL에서 검색 문서를 가져옵니다. 발급자 호스트를 다시 작성하는 프록시 뒤의 IdP의 경우입니다. 경로는 `/.well-known/`을 포함해야 합니다. |96| `discovery_url` | 아니오 | `issuer`에서 파생시키는 대신 이 URL에서 검색 문서를 가져옵니다. 발급자 호스트를 다시 작성하는 프록시 뒤의 IdP의 경우입니다. 경로는 `/.well-known/`을 포함해야 합니다. |

97| `use_proxy` | 아니오 | 게이트웨이의 자체 IdP 요청을 `HTTPS_PROXY` 또는 `HTTP_PROXY`의 정방향 프록시를 통해 보내고, `NO_PROXY`를 준수합니다. 설정 해제되거나 `false`이면 이 요청들은 직접 이동합니다. v2.1.227 이상이 필요합니다. 아래의 [정방향 프록시를 통한 IdP 요청](#idp-requests-through-a-forward-proxy)을 참조하세요. |97| `use_proxy` | 아니오 | 게이트웨이의 자체 IdP 요청을 `HTTPS_PROXY` 또는 `HTTP_PROXY`의 정방향 프록시를 통해 보내고, `NO_PROXY`를 준수합니다. `false`로 설정하면 이 요청들은 직접 이동합니다. v2.1.227 이상이 필요합니다. 아래의 [정방향 프록시를 통한 IdP 요청](#idp-requests-through-a-forward-proxy)을 참조하세요. |

98| `form_action_origins` | 아니오 | `/device` 페이지의 `Content-Security-Policy: form-action` 지시문에 대한 추가 원본입니다. 게이트웨이는 이미 `'self'`와 검색된 `authorization_endpoint` 원본을 허용하지만, Chrome은 전체 리디렉션 체인에 대해 `form-action`을 적용합니다. IdP가 Azure AD가 ADFS로 페더레이션되거나, 허브-스포크 Okta, 또는 회사 SSO 인터셉터 같은 두 번째 호스트를 통해 리디렉션하는 경우, 인증 요청이 리디렉션될 수 있는 모든 원본을 나열합니다. |98| `form_action_origins` | 아니오 | `/device` 페이지의 `Content-Security-Policy: form-action` 지시문에 대한 추가 원본입니다. 게이트웨이는 이미 `'self'`와 검색된 `authorization_endpoint` 원본을 허용하지만, Chrome은 전체 리디렉션 체인에 대해 `form-action`을 적용합니다. IdP가 Azure AD가 ADFS로 페더레이션되거나, 허브-스포크 Okta, 또는 회사 SSO 인터셉터 같은 두 번째 호스트를 통해 리디렉션하는 경우, 인증 요청이 리디렉션될 수 있는 모든 원본을 나열합니다. |

99| `ca_cert_pem` | 아니오 | PEM 인코딩된 CA 인증서 자체이며, 파일 경로가 아닙니다. IdP 요청에만 시스템 신뢰 저장소를 대체합니다. 마운트된 파일을 로드하려면 `${file:/etc/gateway/idp-ca.pem}`을 작성합니다. 회사 PKI 뒤의 Keycloak 또는 Dex에 사용합니다. |99| `ca_cert_pem` | 아니오 | PEM 인코딩된 CA 인증서 자체이며, 파일 경로가 아닙니다. IdP 요청에만 시스템 신뢰 저장소를 대체합니다. 마운트된 파일을 로드하려면 `${file:/etc/gateway/idp-ca.pem}`을 작성합니다. 회사 PKI 뒤의 Keycloak 또는 Dex에 사용합니다. |

100 100

106 106

107`use_proxy: true`를 사용하면, 포드는 각 IdP 엔드포인트의 호스트명을 자체적으로 해석하고 프록시에 해석된 IP 주소로 `CONNECT`하도록 요청합니다. 따라서 프록시는 발급자뿐만 아니라 검색 문서가 이름을 지정하는 모든 호스트의 IP 주소로 `CONNECT`를 수락해야 합니다. `http://` 프록시 URL을 사용합니다. `ca_cert_pem`과 [SSRF 가드](/docs/ko/claude-apps-gateway-deploy#threat-model-summary)는 프록시된 경로에도 적용됩니다.107`use_proxy: true`를 사용하면, 포드는 각 IdP 엔드포인트의 호스트명을 자체적으로 해석하고 프록시에 해석된 IP 주소로 `CONNECT`하도록 요청합니다. 따라서 프록시는 발급자뿐만 아니라 검색 문서가 이름을 지정하는 모든 호스트의 IP 주소로 `CONNECT`를 수락해야 합니다. `http://` 프록시 URL을 사용합니다. `ca_cert_pem`과 [SSRF 가드](/docs/ko/claude-apps-gateway-deploy#threat-model-summary)는 프록시된 경로에도 적용됩니다.

108 108

109[프록시 전용 이그레스](#proxy-only-egress)는 이 둘을 변경합니다: 활성화되는 동안, IdP 요청은 `use_proxy: false`를 설정하지 않는 한 프록시를 따르며, 게이트웨이는 먼저 해석하지 않고 프록시에 각 IdP 호스트명을 전달합니다.

110

111<h4 id="proxy-only-egress">

112 프록시 전용 이그레스

113</h4>

114

115게이트웨이의 환경에서 `HTTPS_PROXY` 옆에 `CLAUDE_GATEWAY_PROXY_IS_EGRESS_BOUNDARY=1`을 설정합니다. 포드가 해당 정방향 프록시를 통해서만 다른 호스트에 도달하고 공개 DNS 이름을 자체적으로 해석할 수 없거나, 프록시가 IP 주소로 `CONNECT`를 거부할 때입니다. v2.1.277 이상이 필요합니다. 이것은 `gateway.yaml` 키가 아닌 환경 변수이므로 구성 파일의 아무것도 게이트웨이의 주소 확인을 완화할 수 없습니다.

116

117```bash theme={null}

118export HTTPS_PROXY=http://proxy.corp.example.com:3128

119export NO_PROXY=

120export no_proxy=

121export CLAUDE_GATEWAY_PROXY_IS_EGRESS_BOUNDARY=1

122```

123

124게이트웨이는 프록시 전용 이그레스가 활성화되는 동안 부팅 시 하나의 `network:` 줄을 기록합니다.

125

126아래의 각 행은 `HTTPS_PROXY`가 설정된 게이트웨이의 아웃바운드 요청 클래스 하나이며, 기본적으로 그리고 프록시 전용 이그레스가 활성화되는 동안입니다.

127

128| 아웃바운드 요청 | 기본값 | 프록시 전용 이그레스 활성화 |

129| ------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |

130| `provider: anthropic` 업스트림, Workload Identity Federation 토큰 교환, `telemetry.forward_to` 내보내기 | 로컬에서 해석되고 확인된 후 확인된 IP 주소로 프록시를 통해 `CONNECT`. `NO_PROXY`에 나열된 텔레메트리 수집기는 대신 직접 도달합니다. | 프록시에 전달된 호스트명 |

131| IdP 검색, JWKS, 토큰, 및 userinfo | [`oidc.use_proxy: true`](#idp-requests-through-a-forward-proxy)가 아닌 한 직접, 그러면 확인된 IP 주소로 `CONNECT` | 호스트명이 프록시에 전달됩니다. `oidc.use_proxy: false`가 내부 IdP를 직접 유지하지 않는 한 |

132| Amazon Bedrock, Claude Platform on AWS, Google Cloud의 Agent Platform, 및 Microsoft Foundry 업스트림; Google 그룹 조회 | 호스트명이 프록시에 전달됩니다. | 변경되지 않음 |

133

134프록시 전용 이그레스는 게이트웨이의 환경이 이 세 가지 조건을 모두 충족하지 않는 한 꺼져 있습니다:

135

136* `HTTPS_PROXY` 또는 `HTTP_PROXY`가 설정됩니다.

137* `NO_PROXY` 및 `no_proxy`는 비어 있습니다. 플랫폼이 둘 중 하나를 포드에 주입하면, 게이트웨이 컨테이너에서 둘 다 빈 값으로 설정합니다. `NO_PROXY`에 텔레메트리 수집기를 나열하면 프록시 전용 이그레스가 꺼져 있습니다.

138* `CLAUDE_GATEWAY_ALLOW_LOOPBACK`이 켜져 있지 않습니다. 포드의 자체 루프백의 수집기 또는 IdP는 프록시 전용 이그레스와 결합될 수 없습니다. 루프백 주소가 프록시에 전달되면 프록시 호스트 자신의 것이 되기 때문입니다. 대신 이 서비스들에 프록시가 도달할 수 있는 주소를 제공합니다. 같은 이유로 게이트웨이는 프록시 전용 이그레스가 활성화되는 동안 `localhost` 스타일 이름을 완전히 거부합니다.

139

140이 조건 중 하나가 충족되지 않으면, 게이트웨이는 부팅 시 경고를 기록하고 이를 중지한 변수의 이름을 지정하며 기본 동작을 유지합니다.

141

142프록시 전용 이그레스가 활성화되면, 내부 수집기 및 IP 주소로 구성된 모든 호스트를 포함하여 프록시의 모든 대상을 허용합니다. [`oidc.use_proxy: false`](#idp-requests-through-a-forward-proxy)로 내부 IdP를 직접 유지할 수 있습니다.

143

144<Warning>

145 프록시의 허용 목록이 게이트웨이의 자체 확인만큼 엄격할 때만 이것을 켭니다. 프록시는 `169.254.169.254` 및 `metadata.google.internal` 같은 클라우드 메타데이터 엔드포인트, 링크 로컬 주소, 및 프록시 호스트의 자체 루프백을 거부해야 하며, 이름뿐만 아니라 이름이 해석되는 주소로 이들을 거부해야 합니다. 게이트웨이는 더 이상 호스트명이 이들 중 하나로 해석되는 것을 잡지 않기 때문입니다. 요청한 곳 어디든 연결하는 프록시는 이 요청들에 대해 게이트웨이의 [SSRF 가드](/docs/ko/claude-apps-gateway-deploy#threat-model-summary)를 제거합니다.

146</Warning>

147

109<h3 id="session">148<h3 id="session">

110 `session`149 `session`

111</h3>150</h3>

124`store` 블록은 게이트웨이를 PostgreSQL 데이터베이스로 지정합니다. 이는 장치 부여 및 속도 제한 카운터를 보유합니다.163`store` 블록은 게이트웨이를 PostgreSQL 데이터베이스로 지정합니다. 이는 장치 부여 및 속도 제한 카운터를 보유합니다.

125 164

126| 필드 | 필수 | 설명 |165| 필드 | 필수 | 설명 |

127| ----------------- | --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |166| ------------------------- | --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

128| `postgres_url` | 예 | `postgres://` 또는 `postgresql://` URL입니다. 필수: 장치 부여 랑데부(브라우저 콜백이 작성하고 폴링 CLI가 읽는)는 교차 복제본 상태가 필요합니다. 게이트웨이는 부팅 및 업그레이드 시 자체 스키마 마이그레이션을 실행하므로, 역할은 대상 스키마에서 테이블을 생성하고 변경할 권리가 필요합니다. [업그레이드](/docs/ko/claude-apps-gateway-deploy#upgrades) 및 [Postgres](/docs/ko/claude-apps-gateway-deploy#postgres)를 참조하세요. |167| `postgres_url` | 예 | `postgres://` 또는 `postgresql://` URL입니다. 필수: 장치 부여 랑데부(브라우저 콜백이 작성하고 폴링 CLI가 읽는)는 교차 복제본 상태가 필요합니다. 게이트웨이는 부팅 및 업그레이드 시 자체 스키마 마이그레이션을 실행하므로, 역할은 대상 스키마에서 테이블을 생성하고 변경할 권리가 필요합니다. [업그레이드](/docs/ko/claude-apps-gateway-deploy#upgrades) 및 [Postgres](/docs/ko/claude-apps-gateway-deploy#postgres)를 참조하세요. |

129| `username` | 아니오 | `postgres_url`의 사용자를 재정의합니다. |168| `username` | 아니오 | `postgres_url`의 사용자를 재정의합니다. |

130| `password` | 아니오 | 데이터베이스 자격증명입니다. 자격증명이 URL에서 벗어나도록 `postgres_url`이 아닌 여기에 설정합니다. 모든 문자를 수락하고 URL 자격증명보다 우선합니다. |169| `password` | 아니오 | 데이터베이스 자격증명입니다. 자격증명이 URL에서 벗어나도록 `postgres_url`이 아닌 여기에 설정합니다. 모든 문자를 수락하고 URL 자격증명보다 우선합니다. |

131| `max_connections` | 아니오 | 복제본당 Postgres 연결 풀 크기입니다. 기본값 `5`로 보수적이고 공유 데이터베이스에 친화적입니다. [지출 제한](#admin)이 활성화되면, 핫 경로는 추론 요청당 몇 가지 작업을 수행하므로, 로드 아래의 전용 데이터베이스에 대해 이것을 올리고, 복제본 × 이것을 데이터베이스의 `max_connections` 아래로 유지합니다. |170| `max_connections` | 아니오 | 복제본당 Postgres 연결 풀 크기입니다. 기본값 `5`로 보수적이고 공유 데이터베이스에 친화적입니다. [지출 제한](#admin)이 활성화되면, 핫 경로는 추론 요청당 몇 가지 작업을 수행하므로, 로드 아래의 전용 데이터베이스에 대해 이것을 올리고, 복제본 × 이것을 데이터베이스의 `max_connections` 아래로 유지합니다. |

171| `connect_timeout_seconds` | 아니오 | 게이트웨이가 Postgres 연결을 열 때 대기하는 초입니다. `1`에서 `60` 사이의 정수이며, 기본값 `5`입니다. 새 게이트웨이 인스턴스가 시작될 때 연결 시도가 시간 초과되면 올립니다. 게이트웨이 서버에서 Claude Code v2.1.274 이상이 필요합니다. 이전 버전은 키가 설정되어 있을 때 시작을 거부합니다. |

132 172

133로컬 개발의 경우, `postgres_url`을 일회용 Postgres 컨테이너로 지정합니다. 예를 들어 `docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres`.173로컬 개발의 경우, `postgres_url`을 일회용 Postgres 컨테이너로 지정합니다. 예를 들어 `docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres`.

134 174

366| 다른 곳 | `auth: { api_key: "${FOUNDRY_API_KEY}" }`. `{ }` 내에서 `${…}`를 인용합니다. |406| 다른 곳 | `auth: { api_key: "${FOUNDRY_API_KEY}" }`. `{ }` 내에서 `${…}`를 인용합니다. |

367 407

408<h4 id="static-headers-on-upstream-requests">

409 업스트림의 정적 헤더

410</h4>

411

412게이트웨이가 한 업스트림으로 보내는 요청에 고정 헤더를 추가하려면, 해당 업스트림에서 `headers:`를 설정합니다. 실행하는 프록시가 헤더로 트래픽을 라우팅하거나 속성화할 때 사용합니다.

413

414`headers:`는 게이트웨이 서버에서 Claude Code v2.1.277 이상이 필요합니다. 이전 게이트웨이는 키를 찾으면 시작을 거부합니다. 키를 추가하기 전에 모든 복제본을 업그레이드하고, 이전 버전으로 롤백하기 전에 키를 제거합니다.

415

416헤더는 `base_url`이 이름을 지정하는 서버로 이동하거나, `base_url`이 설정 해제되어 있을 때 공급자의 자체 엔드포인트로 이동합니다. 공급자는 프록시가 제거하지 않는 한 이들도 받습니다.

417

418이 예제는 `upstream-proxy.internal.example.com`의 프록시를 통해 `provider: vertex` 업스트림에 도달합니다. 프록시가 읽는 `x-source` 헤더를 설정하고, `PROXY_TOKEN` 환경 변수의 토큰을 `x-proxy-token`으로 보냅니다:

419

420```yaml theme={null}

421upstreams:

422 - provider: vertex

423 region: us-east5

424 project_id: example-prod

425 base_url: https://upstream-proxy.internal.example.com

426 auth: {}

427 headers:

428 x-source: claude-apps-gateway

429 x-proxy-token: ${PROXY_TOKEN}

430```

431

432값은 양쪽 끝에 공백이 없는 인쇄 가능한 ASCII 텍스트입니다. 숫자, `true`, 또는 `false`를 인용하여 YAML이 이를 텍스트로 읽도록 합니다.

433

434비밀을 구성 파일에서 벗어나도록 유지하려면, [비밀 확장](#secret-expansion)을 사용하여 `${VAR}`로 환경 변수에서 또는 `${file:/path}`로 파일에서 값을 로드합니다. 빈 값으로 해석되는 `${VAR}`은 게이트웨이가 시작되는 것을 중지합니다.

435

436`headers:`는 모든 공급자에서 작동하며, 각 업스트림은 자신의 것만 보냅니다.

437

438게이트웨이가 업스트림으로 보내는 모든 요청이 이들을 전달하지는 않습니다:

439

440| 게이트웨이가 이 업스트림으로 보내는 요청 | `headers:` 전달 |

441| --------------------------------------------------------- | ---------------------- |

442| `/v1/messages`, 스트리밍 또는 아님, 및 `/v1/messages/count_tokens` | 예 |

443| 다른 업스트림에서 장애 조치된 요청 | 예, 이 업스트림의 `headers:`만 |

444| 클라이언트가 포기한 요청에 대한 Amazon Bedrock의 `CountTokens` 호출 | 아니오 |

445| Workload Identity Federation 토큰 교환 | 아니오 |

446

447AWS SigV4로 요청에 서명하는 Amazon Bedrock 또는 Claude Platform on AWS 업스트림에서, 이 헤더들은 서명의 일부이므로, 프록시는 이들을 변경되지 않은 상태로 통과시켜야 합니다.

448

449게이트웨이가 예약한 이름을 사용하면, 시작을 거부하고 시작 오류가 헤더의 이름을 지정합니다. 예약된 이름은 다음을 포함합니다:

450

451* `authorization` 및 `x-api-key`

452* `host`, `content-type`, 및 `user-agent`

453* `anthropic-`, `x-goog-`, `x-amz-`, 또는 `x-amzn-`으로 시작하는 모든 이름

454

368<h4 id="multiple-upstreams">455<h4 id="multiple-upstreams">

369 여러 업스트림456 여러 업스트림

370</h4>457</h4>

375 462

376`429`는 업스트림별 용량이므로, 프로비저닝된 처리량(PT) 소진은 온디맨드로 장애 조치합니다. 업스트림에서 [`forward_user_identity: true`](#per-user-identity-headers-for-a-proxy-you-run)를 설정하면, 개발자의 이메일을 전달한 요청에 대한 `429`는 사용자별 거부이고 장애 조치하지 않습니다.463`429`는 업스트림별 용량이므로, 프로비저닝된 처리량(PT) 소진은 온디맨드로 장애 조치합니다. 업스트림에서 [`forward_user_identity: true`](#per-user-identity-headers-for-a-proxy-you-run)를 설정하면, 개발자의 이메일을 전달한 요청에 대한 `429`는 사용자별 거부이고 장애 조치하지 않습니다.

377 464

465모든 요청은 첫 번째 업스트림에서 시작합니다. 요청은 앞의 모든 업스트림이 실패했거나 요청된 모델을 제공하지 않을 때만 나중 업스트림에 도달합니다.

466

467게이트웨이는 실패한 업스트림의 기록을 유지하지 않으므로, 업스트림이 다운되는 동안, 이에 도달하는 모든 요청은 여전히 이를 시도하고 실패할 때까지 기다립니다.

468

469Anthropic API 업스트림의 경우, [`timeouts.upstream_ttfb_ms`](#http-tuning)는 다운된 업스트림에서의 대기를 제한합니다. 이 설정은 다른 공급자에게 적용되지 않으며, 게이트웨이는 업스트림이 응답하기 시작할 때까지 최대 1시간을 기다립니다.

470

378`404`는 업스트림별 모델 가용성이므로, 모델을 활성화하지 않은 업스트림은 이를 제공하는 나중 업스트림을 차단하지 않습니다. 요청된 모델을 해석할 수 없는 업스트림은 네트워크 왕복 없이 건너뜁니다.471`404`는 업스트림별 모델 가용성이므로, 모델을 활성화하지 않은 업스트림은 이를 제공하는 나중 업스트림을 차단하지 않습니다. 요청된 모델을 해석할 수 없는 업스트림은 네트워크 왕복 없이 건너뜁니다.

379 472

380이 예제는 프로비저닝된 처리량 Amazon Bedrock 할당을 먼저 라우팅하고, 온디맨드 및 두 번째 계정으로 오버플로우하며, 마지막으로 Anthropic API로 폴백합니다:473이 예제는 프로비저닝된 처리량 Amazon Bedrock 할당을 먼저 라우팅하고, 온디맨드 및 두 번째 계정으로 오버플로우하며, 마지막으로 Anthropic API로 폴백합니다:

428CLI는 주어진 요청을 제공하는 업스트림과 무관하게 게이트웨이에 동일한 기능 게이팅을 적용하므로, 장애 조치는 업스트림이 거부할 본문 필드를 보내지 않습니다.521CLI는 주어진 요청을 제공하는 업스트림과 무관하게 게이트웨이에 동일한 기능 게이팅을 적용하므로, 장애 조치는 업스트림이 거부할 본문 필드를 보내지 않습니다.

429 522

430<h2 id="optional-sections">523<h2 id="optional-sections">

431 선택 사항 섹션524 선택적 섹션

432</h2>525</h2>

433 526

434<h3 id="admin">527<h3 id="admin">

435 `admin`528 `admin`

436</h3>529</h3>

437 530

438선택 사항. Anthropic의 공개 관리자 API를 미러링하는 `/v1/organizations/spend_limits`를 활성화하고 `/v1/messages`에서 개발자별 지출 적용을 활성화합니다. 한도가 설정되고 적용되는 방법은 [지출 한도](/docs/ko/claude-apps-gateway-spend-limits)를 참조하세요. 이 섹션은 기능을 켜고 조정하는 `gateway.yaml` 키를 다룹니다.531선택적입니다. `/v1/organizations/spend_limits`를 활성화하며, 이는 Anthropic의 공개 Admin API를 미러링하고 `/v1/messages`에서 개발자별 지출 강제를 수행합니다. [지출 한도](/docs/ko/claude-apps-gateway-spend-limits)에서 상한이 어떻게 설정되고 강제되는지 확인하세요. 이 섹션은 기능을 켜고 조정하는 `gateway.yaml` 키를 다룹니다.

439 532

440```yaml theme={null}533```yaml theme={null}

441admin:534admin:

442 # 관리자 엔드포인트에 대한 명명된 정적 API 키, x-api-key로 전송됨.535 # Named static API keys for the admin endpoints, sent as x-api-key.

443 # id는 감사 로그에 admin-key:<id>로 나타나므로 각 키는536 # The id appears in the audit log as admin-key:<id> so each key is

444 # 귀속 가능합니다. 회전용 배열: 새 키를 추가하고 클라이언트를 롤링하고537 # attributable. Array for rotation: add the new key, roll clients,

445 # 이전 키를 제거합니다.538 # remove the old.

446 write_keys:539 write_keys:

447 - { id: terraform, key: "${GATEWAY_ADMIN_WRITE_KEY_TF}" }540 - { id: terraform, key: "${GATEWAY_ADMIN_WRITE_KEY_TF}" }

448 - { id: ci, key: "${GATEWAY_ADMIN_WRITE_KEY_CI}" }541 - { id: ci, key: "${GATEWAY_ADMIN_WRITE_KEY_CI}" }

449 read_keys:542 read_keys:

450 - { id: reporting, key: "${GATEWAY_ADMIN_READ_KEY}" }543 - { id: reporting, key: "${GATEWAY_ADMIN_READ_KEY}" }

451 # 일반 게이트웨이 JWT를 통해 전체 관리자 권한이 부여된 IdP 그룹(API 키 없음).544 # IdP groups granted full admin via the normal gateway JWT (no API key).

452 admin_groups: [platform-finops]545 admin_groups: [platform-finops]

453 blocked_message: request an increase at https://go.example.com/claude-limits546 blocked_message: request an increase at https://go.example.com/claude-limits

454```547```

455 548

456| 필드 | 필수 | 설명 |549| 필드 | 필수 | 설명 |

457| ------------------------- | --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |550| ------------------------- | --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

458| `write_keys` | 아니요 | `{id, key}` 배열. 이 중 하나와 일치하는 `x-api-key`는 지출 한도를 나열, 설정 및 삭제할 수 있습니다. 키 값은 최소 32자여야 합니다. `id`는 `read_keys` 및 `write_keys`에서 고유해야 합니다. |551| `write_keys` | 아니요 | `{id, key}` 배열입니다. 이 중 하나와 일치하는 `x-api-key`는 지출 한도를 나열, 설정 및 삭제할 수 있습니다. 키 값은 최소 32자 이상이어야 하며, `id`는 `read_keys`와 `write_keys` 전체에서 고유해야 합니다. |

459| `read_keys` | 아니요 | `{id, key}` 배열. 읽기 전용: 모든 `GET` 엔드포인트, 한도 나열, ID별 가져오기 및 [`/effective`](/docs/ko/claude-apps-gateway-spend-limits#%2Feffective) 및 [`/audit`](/docs/ko/claude-apps-gateway-spend-limits#%2Faudit) 읽기 포함. |552| `read_keys` | 아니요 | `{id, key}` 배열입니다. 읽기 전용: 상한 나열, ID로 하나 가져오기, [`/effective`](/docs/ko/claude-apps-gateway-spend-limits#%2Feffective) 및 [`/audit`](/docs/ko/claude-apps-gateway-spend-limits#%2Faudit) 읽기를 포함한 모든 `GET` 엔드포인트입니다. |

460| `admin_groups` | 아니요 | IdP 그룹 이름. `groups` 클레임이 이 중 하나를 포함하는 게이트웨이 JWT는 전체 관리자 액세스(읽기 및 쓰기)를 가지며 `oidc:<sub>`로 감사합니다. 인간 관리자에게 사용합니다. 기계에는 API 키를 사용합니다. 이 목록의 빈 항목은 게이트웨이를 부팅 시 중지합니다. [게이트웨이를 부팅 시 중지하는 매처 값](#matcher-values-that-stop-the-gateway-at-boot)을 참조하세요. |553| `admin_groups` | 아니요 | IdP 그룹 이름입니다. `groups` 클레임이 이 중 하나를 포함하는 gateway JWT는 전체 관리자 액세스(읽기 및 쓰기)를 가지며 `oidc:<sub>`로 감사됩니다. 인간 관리자에게는 이를 사용하고, 머신에는 API 키를 사용하세요. 이 목록의 빈 항목은 부팅 시 gateway를 중지합니다. [gateway 부팅 시 중지되는 Matcher 값](#matcher-values-that-stop-the-gateway-at-boot)을 참조하세요. |

461| `blocked_message` | 아니요 | 차단된 개발자가 보는 `429 billing_error`에 그대로 추가됩니다. URL 또는 Slack 채널과 같은 전체 지침을 작성합니다. 설정하지 않으면 게이트웨이는 기본 메시지만 보냅니다. [적용이 작동하는 방식](/docs/ko/claude-apps-gateway-spend-limits#how-enforcement-works)을 참조하세요. |554| `blocked_message` | 아니요 | 차단된 개발자가 보는 `429 billing_error`에 그대로 추가됩니다. URL이나 Slack 채널과 같은 전체 지시사항을 작성하세요. 설정하지 않으면 gateway는 기본 메시지만 보냅니다. [강제 작동 방식](/docs/ko/claude-apps-gateway-spend-limits#how-enforcement-works)을 참조하세요. |

462| `audit_retention_days` | 아니요 | 기본값 `365`. 더 오래된 `admin_audit` 행은 정리됩니다. |555| `audit_retention_days` | 아니요 | 기본값 `365`입니다. 더 오래된 `admin_audit` 행은 정리됩니다. |

463| `spend_retention_months` | 아니요 | 기본값 `13`. 이보다 오래된 `spend` 카운터 행은 정리됩니다. 기본값은 연간 비교 보고를 위해 전체 연도와 현재 부분 월을 유지합니다. |556| `spend_retention_months` | 아니요 | 기본값 `13`입니다. 이보다 오래된 `spend` 카운터 행은 정리됩니다. 기본값은 연간 비교 보고를 위해 전체 연도와 현재 부분 월을 유지합니다. |

464| `identity_retention_days` | 아니요 | 기본값 `90`. `principal_emails` 행의 마지막 표시 TTL(각 개발자의 이메일, 표시 이름 및 그룹 포함, PII). 의도적으로 지출 보유보다 짧으므로 프로비저닝 해제된 ID는 익명 지출 카운터가 유지되는 동안 만료됩니다. |557| `identity_retention_days` | 아니요 | 기본값 `90`입니다. 각 개발자의 이메일, 표시 이름 및 그룹(PII)을 보유하는 `principal_emails` 행의 마지막 확인 TTL입니다. 의도적으로 지출 보존보다 짧아서 프로비저닝 해제된 ID가 익명 지출 카운터가 남아있는 동안 만료됩니다. |

465| `group_limit_mode` | 아니요 | `min`(기본값) 또는 `max`. 개발자가 한도가 있는 여러 그룹에 있을 때 `min`은 가장 제한적인 것을 적용하고 `max`는 가장 제한적이지 않은 것을 적용합니다. 적용 및 `/effective` 모두에서 사용됩니다. |558| `group_limit_mode` | 아니요 | `min`(기본값) 또는 `max`입니다. 개발자가 상한이 있는 여러 그룹에 속할 때, `min`은 가장 제한적인 것을 강제하고 `max`는 가장 제한적이지 않은 것을 강제합니다. 강제 및 `/effective` 모두에서 사용됩니다. |

466 559

467<h3 id="enforcement">560<h3 id="enforcement">

468 `enforcement`561 `enforcement`

469</h3>562</h3>

470 563

471`enforcement` 블록은 저장소를 사용할 수 없을 때 지출 한도 확인이 어떻게 동작하는지 제어합니다.564`enforcement` 블록은 저장소를 사용할 수 없을 때 지출 한도 확인이 어떻게 작동하는지 제어합니다.

472 565

473| 필드 | 필수 | 설명 |566| 필드 | 필수 | 설명 |

474| ---------------------- | --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |567| ---------------------- | --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

475| `fail_closed_on_error` | 아니요 | 기본값 `false`. 지출 적용은 Postgres 중단 시 개방되므로 추론이 계속됩니다. `true`로 설정하여 폐쇄: 초과 용량 개발자는 차단되지만 저장소에 도달할 수 없으면 모두가 차단됩니다. [`admin:`](#admin) 블록이 필요합니다: 지출 적용은 `admin`이 구성될 때만 실행되며, 게이트웨이는 이를 `true`로 설정하지 않고 시작하기를 거부합니다. |568| `fail_closed_on_error` | 아니요 | 기본값 `false`입니다. Postgres 중단 시 지출 강제는 열린 상태로 실패하므로 추론이 계속 작동합니다. `true`로 설정하여 닫힌 상태로 실패: 초과 용량 개발자는 차단되지만, 저장소에 도달할 수 없으면 모든 사람이 차단됩니다. [`admin:`](#admin) 블록이 필요합니다. 지출 강제는 `admin`이 구성될 때만 실행되며, 이를 `true`로 설정하면 gateway는 시작을 거부합니다. |

476 569

477<h3 id="pricing">570<h3 id="pricing">

478 `pricing`571 `pricing`

479</h3>572</h3>

480 573

481`pricing` 블록은 지출 미터에 USD 정가 대신 청구할 금액을 알려주므로 한도 및 [`/effective`](/docs/ko/claude-apps-gateway-spend-limits#%2Feffective)는 계약된 요금을 반영합니다. 금액은 USD로 유지되며 청구서가 아닌 추정치입니다. 두 가지 전제 조건:574`pricing` 블록은 지출 미터에 USD 정가 대신 청구할 금액을 알려주므로 상한과 [`/effective`](/docs/ko/claude-apps-gateway-spend-limits#%2Feffective)는 계약 요금을 반영합니다. 금액은 USD로 유지되며 청구서가 아닌 추정치입니다. 두 가지 전제 조건:

482 575

483* 게이트웨이 서버의 Claude Code v2.1.227 이상. 이전 버전은 부팅 시 알 수 없는 키를 거부합니다.576* gateway 서버의 Claude Code v2.1.227 이상입니다. 이전 버전은 부팅 시 알 수 없는 키를 거부합니다.

484* [`admin:`](#admin) 블록 또는 v2.1.268 이상에서 최소 하나의 정책이 있는 [`managed:`](#managed) 블록. 게이트웨이는 `pricing`이 설정되고 두 블록 모두 없으면 시작을 거부합니다. 아무것도 읽지 않기 때문입니다.577* [`admin:`](#admin) 블록 또는 v2.1.268 이상에서 최소 하나의 정책이 있는 [`managed:`](#managed) 블록입니다. gateway는 `pricing`이 설정되었지만 두 블록 모두 없으면 시작을 거부합니다.

485 578

486```yaml theme={null}579```yaml theme={null}

487pricing:580pricing:

496```589```

497 590

498| 필드 | 필수 | 설명 |591| 필드 | 필수 | 설명 |

499| ------------ | --- | ------------------------------------------------------------------------------------------------------------------------------------- |592| ------------ | --- | ---------------------------------------------------------------------------------------------------------------------------------------- |

500| `multiplier` | 아니요 | 기본값 `1`. 미터는 정가 또는 재정의 여부에 관계없이 모든 미터링된 금액에 이를 곱하므로 `0.85`는 가격의 85%를 청구합니다. 0보다 크고 최대 10이어야 하며, 1 이상의 값은 [가격 인상](#mark-prices-up)입니다. |593| `multiplier` | 아니요 | 기본값 `1`입니다. 미터는 정가 또는 재정의 여부에 관계없이 모든 미터링된 금액에 이를 곱하므로 `0.85`는 가격의 85%를 청구합니다. 0보다 크고 최대 10이어야 하며, 1 이상의 값은 [가격 인상](#mark-prices-up)입니다. |

501| `overrides` | 아니요 | 백만 토큰당 USD의 `{upstream, model, input, output, cache_read, cache_write}` 행. 4개의 요금이 모두 필요합니다. 각각 0보다 크고 최대 10000이어야 합니다. |594| `overrides` | 아니요 | 백만 토큰당 USD의 `{upstream, model, input, output, cache_read, cache_write}` 행입니다. 네 가지 요금 모두 필수입니다. 각각 0보다 크고 최대 10000이어야 합니다. |

502 595

503미터가 재정의 행을 일치시키는 방법:596미터가 재정의 행과 일치하는 방식:

504 597

505* 행은 `upstream`(업스트림 [`upstreams[].name`](#upstreams))이 `model`에 대해 제공하는 요청의 정가를 대체합니다. 여기에는 더 높은 [빠른 모드](/docs/ko/fast-mode#understand-the-cost-tradeoff) 요금이 포함되므로 빠른 및 표준 요청은 동일한 4개 요금으로 미터링됩니다.598* 행은 `upstream`(즉, [`upstreams[].name`](#upstreams))이 `model`에 대해 제공하는 요청의 정가를 대체합니다. 여기에는 더 높은 [빠른 모드](/docs/ko/fast-mode#understand-the-cost-tradeoff) 요금이 포함되므로 빠른 요청과 표준 요청은 동일한 네 가지 요금으로 미터링됩니다.

506* `claude-sonnet-4-6`과 같은 기본 제공 ID는 [`models[].id`](#models)처럼 일치하며 미터가 해당 모델로 가격을 책정하는 모든 날짜 형식, 지역 Amazon Bedrock 형식 또는 Google Cloud의 Agent Platform 형식을 다룹니다. 별칭 또는 추론 프로필 ARN과 같은 다른 문자열은 클라이언트가 보낸 ID 또는 업스트림으로 보낸 문자열과 대소문자를 구분하지 않고 일치합니다.599* `claude-sonnet-4-6`과 같은 기본 제공 ID는 [`models[].id`](#models)처럼 일치하며, 미터가 해당 모델로 가격을 책정하는 모든 날짜 형식, 지역 Amazon Bedrock 형식 또는 Google Cloud의 Agent Platform 형식을 포함합니다. 다른 문자열(예: 별칭 또는 추론 프로필 ARN)은 클라이언트가 보낸 ID 또는 upstream으로 보낸 문자열과 대소문자를 구분하지 않고 일치합니다.

507* 행이 겹치는 경우 미터는 첫 번째 행이 아닌 가장 구체적인 행을 선택합니다: 업스트림으로 보낸 정확한 모델 문자열인 행, 그 다음 클라이언트가 보낸 정확한 ID와 일치하는 행, 그 다음 기본 제공 모델을 명명하는 행.600* 행이 겹칠 경우, 미터는 첫 번째 행이 아닌 가장 구체적인 행을 선택합니다. upstream으로 보낸 정확한 모델 문자열인 행, 그 다음 클라이언트가 보낸 정확한 ID와 일치하는 행, 그 다음 기본 제공 모델을 명명하는 행입니다.

508* 알 수 없는 업스트림 이름은 부팅을 실패하게 하며, 한 업스트림에 대해 동일한 모델을 명명하는 두 행도 마찬가지입니다(기본 제공 모델의 두 가지 철자 포함). 게이트웨이는 부팅 시 요청 가능한 모델이 사용할 수 없는 행에 대해 경고합니다.601* 알 수 없는 upstream 이름은 부팅을 실패하게 하며, 하나의 upstream에 대해 동일한 모델을 명명하는 두 행도 마찬가지입니다(기본 제공 모델의 두 가지 철자 포함). gateway는 부팅 시 요청 가능한 모델이 사용할 수 없는 행에 대해 경고합니다.

509* 웹 검색 요청은 \$0.01 정가로 유지됩니다. 승수는 여전히 이에 적용됩니다.602* 웹 검색 요청은 \$0.01 정가로 유지됩니다. 승수는 여전히 이에 적용됩니다.

510 603

511지역별 요금의 경우 각 지역에 자신의 명명된 업스트림을 제공하고 업스트림당 하나의 행을 제공합니다.604지역별 요금의 경우, 각 지역에 자체 명명된 upstream을 제공하고 upstream당 하나의 행을 제공하세요.

512 605

513<h4 id="mark-prices-up">606<h4 id="mark-prices-up">

514 가격 인상607 가격 인상

515</h4>608</h4>

516 609

517게이트웨이 서버의 v2.1.271 이상에서 `multiplier`를 1 이상 10까지 설정하여 공급자가 청구하는 것보다 더 많이 미터링할 수 있습니다(예: 내부 차지백 요금). 이 예제는 모든 요청을 가격의 120%로 미터링합니다:610gateway 서버의 v2.1.271 이상에서는 `multiplier`를 1 이상 10까지 설정하여 공급자가 청구하는 것보다 더 많이 미터링할 수 있습니다(예: 내부 청구 요금). 이 예제는 모든 요청을 가격의 120%로 미터링합니다:

518 611

519```yaml theme={null}612```yaml theme={null}

520pricing:613pricing:

521 multiplier: 1.2614 multiplier: 1.2

522```615```

523 616

524[`admin:`](#admin) 블록이 있으면 인상은 지출 한도에도 적용됩니다. 미터는 가격의 120%를 계산하므로 개발자는 한도에 더 빨리 도달합니다. 게이트웨이는 부팅 시 그렇다고 말하는 경고를 기록합니다.617[`admin:`](#admin) 블록이 있으면 인상은 지출 한도에도 적용됩니다. 미터는 가격의 120%를 계산하므로 개발자는 상한에 더 빨리 도달합니다. gateway는 부팅 시 그렇다고 말하는 경고를 기록합니다.

525 618

526승수는 업스트림 공급자가 요청에 청구하는 금액을 변경하지 않습니다.619승수는 upstream 공급자가 요청에 대해 청구하는 금액을 변경하지 않습니다.

527 620

528게이트웨이가 또한 [서명된 클라이언트에 요금을 보내면](#send-the-rates-to-signed-in-clients) 개발자는 인상을 보기 위해 Claude Code v2.1.271 이상이 필요합니다. 이전 클라이언트는 1 이상의 `multiplier`를 무시하고 이 없이 비용을 표시합니다.621gateway가 [서명된 클라이언트에 요금을 보내는](#send-the-rates-to-signed-in-clients) 경우, 개발자는 인상을 보기 위해 Claude Code v2.1.271 이상이 필요합니다. 이전 클라이언트는 1 이상의 `multiplier`를 무시하고 이 없이 비용을 표시합니다.

529 622

530v2.1.271보다 이전인 게이트웨이 서버는 1 이상의 `multiplier`를 설정하면 시작을 거부합니다.623v2.1.271보다 이전인 gateway 서버는 1 이상의 `multiplier`를 설정하면 시작을 거부합니다.

531 624

532<h4 id="send-the-rates-to-signed-in-clients">625<h4 id="send-the-rates-to-signed-in-clients">

533 서명된 클라이언트에 요금 보내기626 서명된 클라이언트에 요금 보내기

534</h4>627</h4>

535 628

536게이트웨이 서버의 v2.1.268 이상에서 게이트웨이는 또한 `pricing`의 요금을 제공하는 [`managed`](#managed) 정책에 [`modelPricing`](/docs/ko/settings-reference#modelpricing) 관리형 설정으로 넣습니다. 정책과 일치하는 개발자는 `/usage`, 상태 줄 및 OpenTelemetry에서 각 모델 ID를 제공하는 첫 번째 업스트림의 `pricing` 요금을 봅니다. 정책과 일치하지 않는 개발자는 관리형 설정을 받지 않으므로 해당 수치는 정가로 유지됩니다. 클라이언트는 Claude Code v2.1.242 이상에서 설정을 적용합니다.629gateway 서버의 v2.1.268 이상에서는 gateway가 `pricing`의 요금을 제공하는 [`managed`](#managed) 정책에 [`modelPricing`](/docs/ko/settings-reference#modelpricing) 관리 설정으로 넣습니다. 정책과 일치하는 개발자는 `/usage`, 상태 줄 및 OpenTelemetry에서 각 모델 ID를 제공하는 첫 번째 upstream의 `pricing` 요금을 봅니다. 정책과 일치하지 않는 개발자는 관리 설정을 받지 않으므로 해당 수치는 정가로 유지됩니다. 클라이언트는 Claude Code v2.1.242 이상에서 설정을 적용합니다.

537 630

538* 게이트웨이가 추가하는 것: 정책의 `cli` 블록이 이미 `modelPricing`을 설정하지 않으면 게이트웨이는 `multiplier`와 클라이언트가 요청할 수 있는 모든 모델 ID에 대해 해당 ID를 제공하는 첫 번째 업스트림의 재정의 행을 추가합니다. 페일오버 업스트림만 청구하는 요금은 게이트웨이에 유지됩니다.631* gateway가 추가하는 것: 정책의 `cli` 블록이 이미 `modelPricing`을 설정하지 않으면, gateway는 `multiplier`와 클라이언트가 요청할 수 있는 모든 모델 ID에 대해 해당 ID를 제공하는 첫 번째 upstream의 재정의 행을 추가합니다. 장애 조치 upstream만 청구하는 요금은 gateway에 유지됩니다.

539* 한 정책을 옵트아웃: 해당 정책의 `cli` 블록에서 `modelPricing`을 `{}`로 설정하면 개발자는 정가로 유지됩니다.632* 하나의 정책 제외: 정책의 `cli` 블록에서 `modelPricing`을 `{}`로 설정하면, 해당 개발자는 정가로 유지됩니다.

540* 정책의 자체 요금 유지: `cli` 블록이 자신의 `multiplier` 또는 `overrides`로 `modelPricing`을 설정하는 정책은 해당 `modelPricing`을 전체로 유지하며 게이트웨이는 자신의 요금을 추가하지 않습니다.633* 정책의 자체 요금 유지: `cli` 블록이 자체 `multiplier` 또는 `overrides`로 `modelPricing`을 설정하는 정책은 해당 `modelPricing`을 유지하며, gateway는 자체 요금을 추가하지 않습니다.

541 634

542<h3 id="models">635<h3 id="models">

543 `models`636 `models`

544</h3>637</h3>

545 638

546`models` 블록은 선택적 관리자 선별 모델 목록이며 `/v1/models`에서 제공되고 업스트림별 모델 ID를 변환하는 데 사용됩니다. US가 아닌 Amazon Bedrock 지역, Amazon Bedrock 프로비저닝된 처리량 ARN 및 Microsoft Foundry 배포 이름에 필수입니다.639`models` 블록은 선택적 관리자 큐레이션 모델 목록이며, `/v1/models`에서 제공되고 upstream당 모델 ID를 변환하는 데 사용됩니다. 미국 이외의 Amazon Bedrock 지역, Amazon Bedrock 프로비저닝된 처리량 ARN 및 Microsoft Foundry 배포 이름에 필수입니다.

547 640

548```yaml theme={null}641```yaml theme={null}

549auto_include_builtin_models: true # false: 아래 목록만 노출642auto_include_builtin_models: true # false: expose only the list below

550models:643models:

551 - id: claude-opus-4-8644 - id: claude-opus-4-8

552 label: Claude Opus 4.8645 label: Claude Opus 4.8

553 # description: 선택적 텍스트가 표시되는 클라이언트에 표시됨646 # description: optional text shown in clients that surface it

554 upstream_model:647 upstream_model:

555 anthropic: claude-opus-4-8648 anthropic: claude-opus-4-8

556 bedrock: us.anthropic.claude-opus-4-8 # 또는 추론 프로필 ARN649 bedrock: us.anthropic.claude-opus-4-8 # or an inference-profile ARN

557 foundry: your-opus-deployment-name650 foundry: your-opus-deployment-name

558```651```

559 652

560`upstream_model` 아래의 각 키는 구성된 업스트림의 `name`과 일치해야 하며, 기본값은 공급자 이름입니다. 업스트림과 일치하지 않는 키는 부팅을 실패하게 하므로 사용하지 않는 공급자의 줄을 생략합니다.653`upstream_model` 아래의 각 키는 구성된 upstream의 `name`과 일치해야 하며, 기본값은 공급자 이름입니다. upstream과 일치하지 않는 키는 부팅을 실패하게 하므로 사용하지 않는 공급자의 줄은 생략하세요.

561 654

562<h3 id="managed">655<h3 id="managed">

563 `managed`656 `managed`

564</h3>657</h3>

565 658

566`managed` 블록은 IdP 그룹 또는 이메일 도메인을 기반으로 하는 역할 기반 액세스 정책을 정의합니다. 정책은 순서대로 평가됩니다. 첫 번째 일치가 선택되고 `match: {}` 캐치올 기본에 병합됩니다. 사용자별로 `GET /managed/settings`에서 ETag/304 캐싱으로 제공됩니다.659`managed` 블록은 IdP 그룹 또는 이메일 도메인을 기반으로 한 역할 기반 액세스 정책을 정의합니다. 정책은 순서대로 평가되며, 첫 번째 일치가 선택된 후 `match: {}` catch-all 기본값에 병합됩니다. 이들은 ETag/304 캐싱과 함께 `GET /managed/settings`에서 사용자별로 제공됩니다.

567 660

568```yaml theme={null}661```yaml theme={null}

569managed:662managed:

570 policies:663 policies:

571 # 특정 그룹을 먼저.664 # Specific groups first.

572 - match: { groups: [eng-contractors] }665 - match: { groups: [eng-contractors] }

573 cli:666 cli:

574 availableModels: [claude-sonnet-4-6]667 availableModels: [claude-sonnet-4-6]

575 permissions: { deny: ["WebFetch", "WebSearch"] }668 permissions: { deny: ["WebFetch", "WebSearch"] }

576 # 기본 캐치올 마지막: 인증된 모든 사용자와 일치.669 # Default catch-all last: matches everyone who authenticated.

577 - match: {}670 - match: {}

578 cli:671 cli:

579 availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]672 availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]

580```673```

581 674

582`match: {}` 캐치올(관례상 마지막에 나열됨)은 기본 계층으로 처리됩니다. 모든 다른 정책은 설정하지 않은 모든 키를 캐치올에서 상속하므로 역할별 항목은 조직 기본값과 다른 것만 나열하면 됩니다. 병합 규칙은 키 유형에 따라 다릅니다:675`match: {}` catch-all은 관례상 마지막에 나열되며 기본 계층으로 취급됩니다. 다른 모든 정책은 설정하지 않은 모든 키를 catch-all에서 상속하므로 역할별 항목은 조직 기본값과 다른 것만 나열하면 됩니다. 병합 규칙은 키 유형에 따라 다릅니다:

583 676

584* **허용 목록**: `availableModels` 및 `permissions.allow`. 특정 정책의 목록은 기본값을 완전히 대체합니다.677* **허용 목록**: `availableModels` 및 `permissions.allow`입니다. 특정 정책의 목록은 기본값의 목록을 완전히 대체합니다.

585* **거부 목록 및 후크 배열**: `permissions.deny`, `permissions.ask`, `disabledMcpjsonServers`, `deniedMcpServers`, `blockedMarketplaces` 및 모든 `hooks` 이벤트 유형 배열. 이들은 기본값과 정책의 합집합을 사용하므로 조직 전체 거부 또는 감사 후크는 역할별 재정의로 실수로 삭제될 수 없습니다.678* **거부 목록 및 후크 배열**: `permissions.deny`, `permissions.ask`, `disabledMcpjsonServers`, `deniedMcpServers`, `blockedMarketplaces` 및 모든 `hooks` 이벤트 유형 배열입니다. 이들은 기본값과 정책의 합집합을 취하므로 조직 전체 거부 또는 감사 후크는 역할별 재정의로 실수로 삭제될 수 없습니다.

586* **레코드 유형 키**: `env`, `modelOverrides` 및 `skillOverrides`. 이들은 얕게 병합되므로 역할별 `env` 블록은 설정하는 키를 재정의하고 나머지는 기본값에서 상속합니다.679* **레코드 유형 키**: `env`, `modelOverrides` 및 `skillOverrides`입니다. 이들은 얕게 병합되므로 역할별 `env` 블록은 설정하는 키를 재정의하고 나머지는 기본값에서 상속합니다.

587 680

588`availableModels`는 또한 `/v1/messages`에서 서버 측으로 적용되므로 거부된 모델은 클라이언트가 보내는 것과 무관하게 `400`을 반환합니다.681`availableModels`는 `/v1/messages`에서 서버 측으로도 강제되므로 거부된 모델은 클라이언트가 보내는 것에 관계없이 `400`을 반환합니다.

589 682

590게이트웨이는 요청을 중계하기 전에 `model` 값 자체를 검증하므로 잘못된 형식의 값은 업스트림에 도달하지 않습니다. 두 가지 경우에 `400`으로 요청을 거부합니다:683gateway는 요청을 릴레이하기 전에 `model` 값 자체를 검증하므로 잘못된 형식의 값은 upstream에 도달하지 않습니다. 두 가지 경우에 `400`으로 요청을 거부합니다:

591 684

592* 값이 누락되거나 비어 있으면 게이트웨이는 `model is required` 메시지로 요청을 거부합니다. 이 확인에는 Claude Code v2.1.228 이상을 실행하는 게이트웨이가 필요합니다.685* 값이 누락되었거나 비어있을 때, gateway는 `model is required` 메시지로 요청을 거부합니다. 이 확인에는 Claude Code v2.1.228 이상을 실행하는 gateway가 필요합니다.

593* 값이 있지만 문자열이 아니면 게이트웨이는 `model must be a string` 메시지로 요청을 거부합니다. Claude Code v2.1.221 이상을 실행하는 게이트웨이가 필요합니다.686* 값이 있지만 문자열이 아닐 때, gateway는 `model must be a string` 메시지로 요청을 거부합니다. Claude Code v2.1.221 이상을 실행하는 gateway가 필요합니다.

594 687

595| 매처 | 동작 |688| Matcher | 동작 |

596| --------------------------------------------------- | --------------------------------------------------------------------------------- |689| --------------------------------------------------- | --------------------------------------------------------------------------------- |

597| `match: {}` | 인증된 모든 사용자와 일치합니다. 이 중 하나로 시작하고 나중에 그룹 범위 정책을 위에 추가합니다. |690| `match: {}` | 모든 인증된 사용자와 일치합니다. 이 중 하나로 시작하고 나중에 위에 그룹 범위 정책을 추가하세요. |

598| `match: { groups: [a, b] }` | JWT의 `groups` 클레임이 나열된 그룹 중 하나를 포함하면 일치합니다. 대소문자 구분: 그룹은 IdP의 정확한 대소문자와 일치해야 합니다. |691| `match: { groups: [a, b] }` | JWT의 `groups` 클레임이 나열된 그룹 중 하나를 포함하면 일치합니다. 대소문자 구분: 그룹은 IdP의 정확한 대소문자와 일치해야 합니다. |

599| `match: { email_domain: example.com }` | JWT의 `email` 클레임에서 마지막 `@` 뒤의 부분과 일치합니다(대소문자 구분 안 함). 정책당 하나의 도메인을 허용합니다. |692| `match: { email_domain: example.com }` | JWT의 `email` 클레임에서 마지막 `@` 뒤의 부분과 일치하며, 대소문자를 구분하지 않습니다. 정책당 하나의 도메인을 허용합니다. |

600| `match: { groups: [a], email_domain: example.com }` | 두 조건 모두 일치해야 합니다 |693| `match: { groups: [a], email_domain: example.com }` | 두 조건 모두 일치해야 합니다 |

601 694

602정책과 일치하지 않는 인증된 사용자는 게이트웨이의 기본값을 가져옵니다. 이는 카탈로그의 모든 모델과 관리형 설정이 없음을 의미합니다. 보장된 기본 정책을 원하면 마지막에 `match: {}` 캐치올을 추가합니다.695인증된 사용자가 정책과 일치하지 않으면 gateway의 기본값을 받으며, 이는 카탈로그의 모든 모델과 관리 설정이 없음을 의미합니다. 보장된 기본 정책을 원하면 마지막에 `match: {}` catch-all을 추가하세요.

603 696

604<Note>697<Note>

605 게이트웨이는 자신의 사용자 디렉토리를 유지하지 않습니다. 사용자의 IdP 토큰에서 각 요청을 승인하고 토큰의 `groups` 클레임에서 그룹 멤버십을 읽으며 이에 대해 정책을 평가합니다. 열거할 명단이 없고 사전 생성할 계정이 없으므로 SCIM 엔드포인트가 없습니다. 동기화할 것이 없기 때문입니다.698 gateway는 자체 사용자 디렉토리를 유지하지 않습니다. 사용자의 IdP 토큰에서 각 요청을 인증하여 토큰의 `groups` 클레임에서 그룹 멤버십을 읽고 이에 대해 정책을 평가합니다. 열거할 명단이 없고 사전 생성할 계정이 없으므로 SCIM 엔드포인트가 없습니다. SCIM이 동기화할 것이 없기 때문입니다.

606 699

607 사용자 및 그룹 수명 주기 관리를 진실의 원본(IdP의 기본 SCIM 프로비저닝 또는 전용 ID 거버넌스 플랫폼)에서 실행합니다. 거기서 관리되는 멤버십 및 프로비저닝 해제는 토큰을 통해 게이트웨이에 자동으로 흐릅니다. Claude 계정 자체의 SCIM 프로비저닝을 원하면 이는 [Claude for Enterprise](/docs/ko/admin-setup) 기능입니다.700 사용자 및 그룹 수명 주기 관리를 진실의 원천인 IdP의 기본 SCIM 프로비저닝 또는 전용 ID 거버넌스 플랫폼에서 실행하세요. 거기서 관리되는 멤버십 및 프로비저닝 해제는 토큰을 통해 gateway로 자동으로 흐릅니다. Claude 계정 자체의 SCIM 프로비저닝을 원하면 이는 [Claude for Enterprise](/docs/ko/admin-setup) 기능입니다.

608 701

609 두 가지 전파 시계가 적용됩니다:702 두 가지 전파 시계가 적용됩니다:

610 703

611 * **정책 내용**: 정책을 편집하고 재배포하면 연결된 클라이언트가 다음 관리형 설정 폴링 시 1시간 이내에 도달합니다. [다음 시작 시에만 적용되는 변경 사항](/docs/ko/server-managed-settings#fetch-and-caching-behavior) 제외.704 * **정책 내용**: 정책을 편집하고 재배포하면 연결된 클라이언트의 다음 관리 설정 폴에서 1시간 이내에 도달합니다([다음 시작에만 적용되는 변경](/docs/ko/server-managed-settings#fetch-and-caching-behavior) 제외).

612 * **그룹 멤버십**: 사용자의 그룹 멤버십을 변경하면 어떤 정책이 일치하는지 변경됩니다. 이는 다음 세션 재발급 시(다음 자동 새로 고침 의미)에 적용되며 `session.ttl_hours`로 제한됩니다.705 * **그룹 멤버십**: 사용자의 그룹 멤버십을 변경하면 어떤 정책이 일치하는지 변경됩니다. 이는 다음 세션 재발급, 즉 다음 자동 새로고침에서 적용되며, `session.ttl_hours`로 제한됩니다.

613</Note>706</Note>

614 707

615<h4 id="matcher-values-that-stop-the-gateway-at-boot">708<h4 id="matcher-values-that-stop-the-gateway-at-boot">

616 게이트웨이를 부팅 시 중지하는 매처 값709 gateway 부팅 시 중지되는 Matcher 값

617</h4>710</h4>

618 711

619부팅 시 게이트웨이는 모든 정책의 `match` 블록과 [`admin_groups`](#admin) 목록을 확인합니다. 이 값 중 하나라도 필드의 이름을 지정하는 오류로 게이트웨이를 중지합니다:712부팅 시 gateway는 모든 정책의 `match` 블록과 [`admin_groups`](#admin) 목록을 확인합니다. 이 값 중 하나라도 필드를 명명하는 오류로 gateway를 중지합니다:

620 713

621* 빈 `groups` 목록714* 빈 `groups` 목록

622* `groups` 또는 `admin_groups`의 빈 항목715* `groups` 또는 `admin_groups`의 빈 항목

623* 빈 `email_domain`716* 빈 `email_domain`

624* `@`, 공백 또는 쉼표를 포함하는 `email_domain`. 게이트웨이는 값을 자르고 이 확인 전에 하나의 선행 `@`를 제거합니다. `example.com`과 같은 하나의 베어 도메인을 작성합니다.717* `@`, 공백 또는 쉼표를 포함하는 `email_domain`입니다. gateway는 값을 자르고 이 확인 전에 선행 `@` 하나를 제거합니다. `example.com`과 같은 하나의 베어 도메인을 작성하세요.

625 718

626v2.1.232 이전에는 게이트웨이가 이 값으로 시작했습니다. 각 값은 이 효과를 가졌습니다:719v2.1.232 이전에는 gateway가 이 값으로 시작했습니다. 각 값은 다음과 같은 효과를 가졌습니다:

627 720

628* 빈 `email_domain`: 게이트웨이는 도메인 확인을 건너뛰었으므로 빈 `email_domain`과 `groups` 목록이 없는 정책은 인증된 모든 사용자와 일치했습니다.721* 빈 `email_domain`: gateway는 도메인 확인을 건너뛰었으므로 빈 `email_domain`과 `groups` 목록이 없는 정책은 모든 인증된 사용자와 일치했습니다.

629* 빈 `groups` 목록: 정책은 아무도 일치하지 않았습니다.722* 빈 `groups` 목록: 정책은 아무도 일치하지 않았습니다.

630* `@`, 공백 또는 쉼표를 포함하는 `email_domain`: 정책은 아무도 일치하지 않았습니다.723* `@`, 공백 또는 쉼표를 포함하는 `email_domain`: 정책은 아무도 일치하지 않았습니다.

631* `groups` 또는 `admin_groups`의 빈 항목: 항목은 해당 사용자의 IdP `groups` 클레임도 빈 항목을 포함할 때만 사용자와 일치했습니다. `admin_groups`에서 해당 일치는 관리자 액세스를 부여했습니다. `admin_groups` 목록이 빈 항목을 포함하지 않으면 아무도 이 방식으로 관리자 액세스를 얻지 못했습니다.724* `groups` 또는 `admin_groups`의 빈 항목: 항목은 해당 사용자의 IdP `groups` 클레임도 빈 항목을 포함할 때만 사용자와 일치했습니다. `admin_groups`에서 해당 일치는 관리자 액세스를 부여했습니다. `admin_groups` 목록이 빈 항목을 포함하지 않으면 아무도 이 방식으로 관리자 액세스를 얻지 못했습니다.

634 `cli`에 들어가는 것727 `cli`에 들어가는 것

635</h4>728</h4>

636 729

637각 `cli` 값은 완전한 Claude Code `managed-settings.json` 문서이며, MDM 또는 `/etc/claude-code/managed-settings.json`을 통해 배포할 동일한 스키마이며, 여기서는 YAML로 표현됩니다. CLI는 관리형 계층에서 전달된 문서를 적용합니다. 사용자 및 프로젝트 설정 위에 있습니다. 따라서 [OS 수준 정책 소스로 제한된 설정](/docs/ko/server-managed-settings#current-limitations)(예: `policyHelper` 및 `wslInheritsWindowsSettings`)을 무시합니다.730각 `cli` 값은 완전한 Claude Code `managed-settings.json` 문서이며, MDM을 통해 배포하거나 `/etc/claude-code/managed-settings.json`에 배포할 동일한 스키마이며, 여기서는 YAML로 표현됩니다. CLI는 전달된 문서를 관리 계층에서 적용하며, 사용자 및 프로젝트 설정 위에 있고, 서버 관리 설정 대신입니다. 따라서 `policyHelper` 및 `wslInheritsWindowsSettings`와 같이 [OS 수준 정책 소스로 제한된 설정](/docs/ko/server-managed-settings#current-limitations)을 무시합니다.

638 731

639게이트웨이는 부팅 시 각 문서를 CLI의 설정 스키마에 대해 검증하므로 인식되지 않는 최상위 키는 모든 위반 키의 이름을 지정하는 오류로 부팅을 실패합니다. 의도적으로 개방된 스키마 부분은 여전히 임의의 값을 허용합니다. 더 새로운 클라이언트가 게이트웨이의 스키마가 인식하지 못하는 항목을 인식할 수 있기 때문입니다. 이러한 개방 키는 `env`, `pluginConfigs` 및 `permissions` 아래에 중첩된 키입니다.732gateway는 부팅 시 각 문서를 CLI의 설정 스키마에 대해 검증하므로 인식되지 않는 최상위 키는 모든 위반 키를 명명하는 오류로 부팅을 실패합니다. 스키마의 의도적으로 열린 부분은 여전히 임의의 값을 허용합니다. 더 새로운 클라이언트가 gateway의 스키마가 인식하지 못하는 항목을 인식할 수 있기 때문입니다. 이 열린 키에는 `env`, `pluginConfigs` 및 `permissions` 아래에 중첩된 키가 포함됩니다.

640 733

641검증이 게이트웨이의 설치된 버전과 함께 번들된 스키마를 사용하므로 더 새로운 Claude Code 릴리스에서 도입된 최상위 설정 키를 관리형 구성에 넣으려면 먼저 게이트웨이를 업그레이드해야 합니다. 한 클라이언트에서 새 정책을 연기 테스트한 후 롤아웃합니다.734검증은 gateway의 설치된 버전과 함께 번들된 스키마를 사용하므로, 더 새로운 Claude Code 릴리스에서 도입한 최상위 설정 키를 관리 구성에 넣으려면 먼저 gateway를 업그레이드해야 합니다. 전체 조직에 배포하기 전에 하나의 클라이언트에서 새 정책을 스모크 테스트하세요.

642 735

643전체 키 참조는 [Claude Code 설정](/docs/ko/settings-reference#all-settings)에 있습니다. 운영자가 먼저 도달하는 키:736전체 키 참조는 [Claude Code 설정](/docs/ko/settings-reference#all-settings)에 있습니다. 운영자가 가장 먼저 찾는 키:

644 737

645```yaml theme={null}738```yaml theme={null}

646managed:739managed:

647 policies:740 policies:

648 - match: {}741 - match: {}

649 cli:742 cli:

650 # 모델 액세스(/v1/messages에서도 서버 측으로 적용됨)743 # Model access (also enforced server-side at /v1/messages)

651 availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]744 availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]

652 745

653 # 권한 정책746 # Permission policy

654 permissions:747 permissions:

655 deny:748 deny:

656 - "WebFetch"749 - "WebFetch"

657 - "Read(./.env)"750 - "Read(./.env)"

658 - "Read(./secrets/**)"751 - "Read(./secrets/**)"

659 disableBypassPermissionsMode: disable # --dangerously-skip-permissions 차단752 disableBypassPermissionsMode: disable # blocks --dangerously-skip-permissions

660 allowManagedPermissionRulesOnly: true # 사용자/프로젝트 권한 규칙 무시753 allowManagedPermissionRulesOnly: true # ignore user/project permission rules

661 754

662 # CLI 프로세스에 푸시된 환경. DISABLE_UPDATES는 배경 및 수동 업데이트를 차단합니다.755 # Environment pushed into the CLI process. DISABLE_UPDATES blocks

663 # DISABLE_AUTOUPDATER는 배경 업데이트만 중지합니다.756 # background and manual updates; DISABLE_AUTOUPDATER stops only

757 # background updates.

664 env:758 env:

665 DISABLE_UPDATES: "1" # 자신의 배포를 통해 버전 고정759 DISABLE_UPDATES: "1" # pin versions via your own distribution

666 760

667 # 조직 전체 후크. 후크 명령은 게이트웨이가 아닌 개발자 머신에서 실행되므로761 # Org-wide hooks. Hook commands run on developer machines, not the

668 # 경로는 정책의 모든 클라이언트 OS에 존재해야 합니다.762 # gateway, so the path must exist on every client OS in the policy.

669 hooks:763 hooks:

670 PostToolUse:764 PostToolUse:

671 - matcher: "Edit|Write"765 - matcher: "Edit|Write"

673 - { type: command, command: /usr/local/bin/audit-edit.sh }767 - { type: command, command: /usr/local/bin/audit-edit.sh }

674```768```

675 769

676| 키 | 적용 대상 | 효과 |770| 키 | 강제 대상 | 효과 |

677| ------------------------------------------ | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |771| ------------------------------------------ | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

679| `permissions.allow` / `.deny` | CLI | 도구 및 명령 규칙. [권한](/docs/ko/permissions)을 참조하세요. |773| `permissions.allow` / `.deny` | CLI | 도구 및 명령 규칙입니다. [권한](/docs/ko/permissions)을 참조하세요. |

680| `permissions.disableBypassPermissionsMode` | CLI | [`bypassPermissions`](/docs/ko/permission-modes#skip-all-checks-with-bypasspermissions-mode) 모드를 차단하도록 `disable`으로 설정하고 `--dangerously-skip-permissions` 플래그 |774| `permissions.disableBypassPermissionsMode` | CLI | [`bypassPermissions`](/docs/ko/permission-modes#skip-all-checks-with-bypasspermissions-mode) 모드(권한 프롬프트를 건너뛰는 모드)와 `--dangerously-skip-permissions` 플래그를 차단하려면 `disable`로 설정하세요. |

681| `allowManagedPermissionRulesOnly` | CLI | `true`일 때 관리형 설정이 권한 규칙의 유일한 설정 소스가 됩니다. [`allowManagedPermissionRulesOnly`](/docs/ko/settings-reference#allowmanagedpermissionrulesonly) 항목은 Claude Code가 무시하는 모든 소스를 나열합니다. |775| `allowManagedPermissionRulesOnly` | CLI | `true`일 때, 관리 설정은 권한 규칙의 유일한 설정 소스가 됩니다. [`allowManagedPermissionRulesOnly`](/docs/ko/settings-reference#allowmanagedpermissionrulesonly) 항목은 Claude Code가 무시하는 모든 소스를 나열합니다. |

682| `env` | CLI | CLI 프로세스에 병합된 환경 변수. 텔레메트리, 자동 업데이트 및 모델 이름 재정의에 사용합니다. |776| `env` | CLI | CLI 프로세스에 병합된 환경 변수입니다. 원격 측정, 자동 업데이트 및 모델 이름 재정의에 사용하세요. |

683| `hooks` | CLI | 조직 전체 [후크](/docs/ko/hooks) |777| `hooks` | CLI | 조직 전체 [후크](/docs/ko/hooks) |

684| `managedMcpServers` | CLI | [모든 일치하는 개발자에게 제공되는](/docs/ko/managed-mcp#provide-servers-through-managed-settings) 원격 MCP 서버, 자신이 추가하는 서버 및 `http`, `sse` 전용과 함께. [정책의 MCP 서버](#mcp-servers-in-a-policy)를 참조하세요. 게이트웨이 서버 및 클라이언트에서 Claude Code v2.1.259 이상이 필요합니다. 이전 클라이언트는 키를 무시합니다. |778| `managedMcpServers` | CLI | 정책과 일치하는 모든 개발자에게 [제공되는](/docs/ko/managed-mcp#provide-servers-through-managed-settings) 원격 MCP 서버(`http` 및 `sse`만). [정책의 MCP 서버](#mcp-servers-in-a-policy)를 참조하세요. gateway 서버 및 클라이언트에서 Claude Code v2.1.259 이상이 필요합니다. 이전 클라이언트는 키를 무시합니다. |

685 779

686이러한 설정은 네트워크를 통해 도착하므로 CLI는 각 개발자에게 보안 승인 대화를 표시한 후 아래에 나열된 설정을 적용합니다:780이 설정은 네트워크를 통해 도착하므로 CLI는 아래 나열된 설정을 적용하기 전에 각 개발자에게 보안 승인 대화 상자를 표시합니다:

687 781

688* `hooks`782* `hooks`

689* 개발자의 승인이 필요한 `env` 변수(예: 프록시 및 기본 URL 변수)783* 프록시 및 기본 URL 변수와 같이 개발자의 승인이 필요한 `env` 변수

690* `apiKeyHelper` 및 `statusLine`과 같은 셸 실행 설정784* `apiKeyHelper` 및 `statusLine`과 같은 셸 실행 설정

691* 샌드박스 바이너리 설정 `sandbox.bwrapPath`, `sandbox.socatPath` 및 `sandbox.ripgrep`785* 샌드박스 바이너리 설정 `sandbox.bwrapPath`, `sandbox.socatPath` 및 `sandbox.ripgrep`

692* 트래픽을 가로채거나 자격 증명을 주입하거나 격리를 약화시키는 샌드박스 설정(예: `sandbox.network.tlsTerminate` 및 프록시 포트 설정). [보안 승인 대화](/docs/ko/server-managed-settings#security-approval-dialogs)는 모두 나열합니다.786* `sandbox.network.tlsTerminate` 및 프록시 포트 설정과 같이 트래픽을 가로채고, 자격 증명을 주입하거나, 격리를 약화시키는 샌드박스 설정입니다. [보안 승인 대화 상자](/docs/ko/server-managed-settings#security-approval-dialogs)는 모두 나열합니다.

693 787

694[승인 메모리](/docs/ko/server-managed-settings#approval-memory)는 승인이 지속되는 기간과 대화가 다시 나타나는 시기를 다룹니다.788[승인 메모리](/docs/ko/server-managed-settings#approval-memory)는 승인이 얼마나 오래 지속되는지와 대화 상자가 다시 나타나는 시기를 다룹니다.

695 789

696Claude Code는 모델 선택 설정 및 숫자 제한과 같은 개발자 승인 대화를 표시하지 않고 전달된 일부 `env` 변수를 적용합니다. 다른 전달된 변수는 적용되기 전에 개발자의 승인이 필요할 수 있습니다. 비어 있지 않은 프록시, 기본 URL 또는 `OTEL_EXPORTER_OTLP_ENDPOINT` 값은 항상 그렇습니다. 전달된 변수가 승인이 필요하면 대화가 이름을 지정합니다.790Claude Code는 모델 선택 설정 및 숫자 제한과 같이 개발자에게 승인 대화 상자를 표시하지 않고 전달된 일부 `env` 변수를 적용합니다. 다른 전달된 변수는 적용 전에 개발자의 승인이 필요할 수 있습니다. 비어있지 않은 프록시, 기본 URL 또는 `OTEL_EXPORTER_OTLP_ENDPOINT` 값은 항상 그렇습니다. 전달된 변수가 승인이 필요하면 대화 상자가 이를 명명합니다.

697 791

698[환경 변수 및 승인 대화](/docs/ko/server-managed-settings#environment-variables-and-the-approval-dialog)는 세부 사항을 포함하며, 전달된 값이 승인이 필요한지 여부를 결정하는 4개의 개인 정보 보호 토글을 포함합니다. v2.1.218 이전에는 Claude Code가 더 적은 변수를 개발자에게 묻지 않고 적용했으므로 더 많은 전달된 변수가 대화를 트리거했습니다.792[환경 변수 및 승인 대화 상자](/docs/ko/server-managed-settings#environment-variables-and-the-approval-dialog)는 세부 사항과 전달된 값이 승인이 필요한지 여부를 결정하는 네 가지 개인 정보 보호 토글을 포함합니다. v2.1.218 이전에는 Claude Code가 더 적은 변수를 개발자에게 묻지 않고 적용했으므로 더 많은 전달된 변수가 대화 상자를 트리거했습니다.

699 793

700게이트웨이의 [텔레메트리](#telemetry) 구성은 `OTEL_EXPORTER_OTLP_ENDPOINT`를 푸시하므로 `telemetry.forward_to`를 설정하면 각 대화형 클라이언트에서 대화를 트리거합니다. 대화는 조직으로부터 개발자를 보호하지 않고 손상되거나 적대적인 게이트웨이로부터 개발자의 머신을 보호합니다.794gateway의 [원격 측정](#telemetry) 구성은 `OTEL_EXPORTER_OTLP_ENDPOINT`를 푸시하므로 `telemetry.forward_to`를 설정하면 각 대화형 클라이언트에서 대화 상자를 트리거합니다. 대화 상자는 손상되었거나 적대적인 gateway로부터 개발자의 머신을 보호하며, 개발자로부터 조직을 보호하지 않습니다.

701 795

702`-p` 플래그를 사용한 비대화형 실행은 대화를 표시할 수 없습니다. 해당 실행에 대해서만 푸시된 설정을 적용하고 승인된 것으로 기록하지 않으므로 개발자의 다음 대화형 세션은 여전히 대화를 표시합니다. v2.1.207 이전에는 비대화형 실행이 설정을 승인된 것으로 저장했고 이후 대화형 세션은 이에 대한 대화를 표시하지 않았습니다.796`-p` 플래그가 있는 비대화형 실행은 대화 상자를 표시할 수 없습니다. 해당 실행에 대해서만 푸시된 설정을 적용하고 이를 승인된 것으로 기록하지 않으므로 개발자의 다음 대화형 세션은 여전히 대화 상자를 표시합니다. v2.1.207 이전에는 비대화형 실행이 설정을 승인된 것으로 저장했고 나중의 대화형 세션은 이에 대한 대화 상자를 표시하지 않았습니다.

703 797

704개발자가 거부하면 Claude Code는 정책을 적용하지 않고 종료됩니다. 새 후크 또는 비안전 env 변수를 광범위한 정책에 푸시하면 일치하는 모든 개발자의 다음 시작 시 승인 프롬프트가 표시됩니다.798개발자가 거부하면 Claude Code는 정책을 적용하지 않고 해당 세션을 종료합니다. 새 후크 또는 대화 상자를 트리거하는 env 변수를 광범위한 정책에 푸시하면 Claude Code는 일치하는 모든 개발자에게 대화 상자를 표시합니다. 실행 중인 세션에서 다음 시간별 폴에 대화 상자를 표시하고, 그렇지 않으면 개발자의 다음 시작 시 표시합니다.

705 799

706`cli` 키는 이전 릴리스에서 `settings`로 명명되었습니다. 해당 철자는 여전히 별칭으로 허용되지만 새 배포는 `cli`를 사용해야 합니다.800`cli` 키는 이전 릴리스에서 `settings`로 명명되었습니다. 해당 철자는 여전히 별칭으로 허용되지만 새 배포는 `cli`를 사용해야 합니다.

707 801

709 정책의 MCP 서버803 정책의 MCP 서버

710</h4>804</h4>

711 805

712정책이 일치하는 Claude Code 클라이언트에 MCP 서버를 제공하려면 해당 정책의 `cli` 블록에서 [`managedMcpServers`](/docs/ko/managed-mcp#provide-servers-through-managed-settings)를 설정합니다. 게이트웨이 서버 및 클라이언트에서 Claude Code v2.1.259 이상이 필요합니다.806정책이 일치하는 Claude Code 클라이언트에 MCP 서버를 제공하려면 해당 정책의 `cli` 블록에서 [`managedMcpServers`](/docs/ko/managed-mcp#provide-servers-through-managed-settings)를 설정하세요. gateway 서버 및 클라이언트에서 Claude Code v2.1.259 이상이 필요합니다.

713 807

714게이트웨이는 부팅 시 [Claude Code가 클라이언트에 적용하는 동일한 규칙](/docs/ko/managed-mcp#what-an-entry-can-contain)으로 각 항목을 확인하며, 항목이 확인을 실패하면 게이트웨이는 시작을 거부하고 항목의 이름을 지정합니다.808gateway는 [Claude Code가 클라이언트에서 적용하는 동일한 규칙](/docs/ko/managed-mcp#what-an-entry-can-contain)으로 부팅 시 각 항목을 확인하며, 항목이 확인을 실패하면 gateway는 시작을 거부하고 항목을 명명합니다.

715 809

716`gateway.yaml`에 `${VAR}` 참조를 작성하면 게이트웨이는 부팅 시 [비밀 확장](#secret-expansion)을 통해 환경에서 이를 확인하고 항목 확인을 실행한 후 모든 일치하는 클라이언트는 리터럴 값을 받고 읽을 수 있습니다. [제공된 서버에 대한 헤더 지침](/docs/ko/managed-mcp#provide-servers-through-managed-settings)은 확장된 값에 적용됩니다.810`gateway.yaml`에 `${VAR}` 참조를 작성하면 gateway는 [비밀 확장](#secret-expansion)을 통해 부팅 시 환경에서 이를 해결하므로 일치하는 모든 클라이언트는 리터럴 값을 받고 읽을 수 있습니다. [제공된 서버에 대한 헤더 지침](/docs/ko/managed-mcp#provide-servers-through-managed-settings)은 확장된 값에 적용됩니다.

717 811

718게이트웨이는 `cli` 블록에서 `.mcp.json` 철자 `mcpServers`를 거부하며 부팅 오류는 사용할 키로 `managedMcpServers`의 이름을 지정합니다. v2.1.259 이전에는 게이트웨이가 `cli` 블록의 모든 MCP 서버 정의를 거부했습니다.812gateway는 `cli` 블록에서 `.mcp.json` 철자 `mcpServers`를 거부하며, 부팅 오류는 `managedMcpServers`를 사용할 키로 명명합니다. v2.1.259 이전에는 gateway가 `cli` 블록의 모든 MCP 서버 정의를 거부했습니다.

719 813

720<h4 id="claude-desktop-overlay">814<h4 id="claude-desktop-overlay">

721 Claude Desktop 오버레이815 Claude Desktop 오버레이

722</h4>816</h4>

723 817

724조직이 또한 [Claude Desktop](/docs/ko/desktop)을 배포하면 동일한 게이트웨이가 두 클라이언트를 제공합니다. Claude Desktop의 [관리형 구성](https://claude.com/docs/third-party/claude-desktop/configuration)에서 `bootstrapUrl`을 `<listen.public_url>/user/bootstrap`으로 지정합니다. Claude Desktop은 해당 URL에서 OAuth 발급자를 파생하고 이 게이트웨이에 대해 동일한 장치 코드 로그인을 실행하며 응답에서 구성을 가져옵니다.818조직이 [Claude Desktop](/docs/ko/desktop)도 배포하면 동일한 gateway가 두 클라이언트를 제공합니다. Claude Desktop의 [관리 구성](https://claude.com/docs/third-party/claude-desktop/configuration)에서 `bootstrapUrl`을 `<listen.public_url>/user/bootstrap`으로 지정하세요. Claude Desktop은 해당 URL에서 OAuth 발급자를 파생하고, 이 gateway에 대해 동일한 장치 코드 로그인을 실행하고, 응답에서 구성을 가져옵니다.

725 819

726<Note>820<Note>

727 게이트웨이 서버의 Claude Code v2.1.203 이상이 필요하며 명시적 옵트인: `/user/bootstrap`은 정책이 사용자와 일치하지 않으면 `desktop` 키를 전달하지 않으면 404를 반환합니다. 빈 `desktop: {}`은 정책을 옵트인하며 `match: {}` 기본 계층의 `desktop` 키는 모든 정책을 옵트인합니다. 감사 로그는 각 요청을 `desktop_bootstrap.serve` 또는 `desktop_bootstrap.denied`로 기록합니다.821 gateway 서버의 Claude Code v2.1.203 이상이 필요하며, 명시적 옵트인이 필요합니다. 정책이 사용자와 일치하는 `desktop` 키를 전달하지 않으면 `/user/bootstrap`은 404를 반환합니다. 빈 `desktop: {}`은 정책을 옵트인하며, `match: {}` 기본 계층의 `desktop` 키는 이를 상속하는 모든 정책을 옵트인합니다. 감사 로그는 각 요청을 `desktop_bootstrap.serve` 또는 `desktop_bootstrap.denied`로 기록합니다.

728</Note>822</Note>

729 823

730게이트웨이는 일치하는 정책의 `cli` 블록 및 최상위 게이트웨이 구성에서 응답의 대부분을 파생합니다:824gateway는 일치하는 정책의 `cli` 블록과 최상위 gateway 구성에서 응답의 대부분을 파생합니다:

731 825

732* 모델 목록, `availableModels`에서826* `availableModels`의 모델 목록

733* 비활성화된 도구, 베어 도구 이름 `permissions.deny` 항목에서. 정책의 `desktop` 블록에서 `disabledBuiltinTools`를 설정하면 게이트웨이는 파생된 목록과 값의 합집합을 제공하므로 이 방식으로 더 많은 도구를 비활성화할 수 있지만 `permissions.deny`를 통해 비활성화한 도구를 다시 활성화할 수 없습니다.827* 베어 도구 이름 `permissions.deny` 항목의 비활성화된 도구입니다. 정책의 `desktop` 블록에서 `disabledBuiltinTools`를 설정하면 gateway는 파생된 목록과 값의 합집합을 제공하므로 이 방식으로 더 많은 도구를 비활성화할 수 있지만 `permissions.deny`를 통해 비활성화한 도구를 다시 활성화할 수 없습니다.

734* 송신 허용 목록, `sandbox.network.allowedDomains`에서. 정책의 `desktop` 블록에서 `coworkEgressAllowedHosts`를 설정하면 게이트웨이는 파생된 목록 대신 해당 값을 사용합니다.828* `sandbox.network.allowedDomains`의 송신 허용 목록입니다. 정책의 `desktop` 블록에서 `coworkEgressAllowedHosts`를 설정하면 gateway는 파생된 목록 대신 해당 값을 사용합니다.

735* 게이트웨이 자체를 가리키는 OTLP 엔드포인트 및 서명된 사용자의 ID 속성. 게이트웨이는 해당 엔드포인트에서 받는 내보내기를 `forward_to` 대상으로 중계합니다. [`telemetry.forward_to`](#telemetry) 및 `listen.public_url`을 모두 설정할 때 엔드포인트 및 속성을 포함합니다.829* gateway 자체를 가리키는 OTLP 엔드포인트 및 서명된 사용자의 ID 속성입니다. gateway는 해당 엔드포인트에서 받는 내보내기를 `forward_to` 대상으로 릴레이합니다. [`telemetry.forward_to`](#telemetry) 및 `listen.public_url`을 모두 설정할 때 엔드포인트 및 속성을 포함합니다.

736 830

737 Claude Desktop은 모든 신호를 하나의 인코딩으로 내보냅니다: `http/protobuf` 또는 정책의 `env`에서 `OTEL_EXPORTER_OTLP_PROTOCOL` 또는 신호별 변형 중 하나를 `http/json`으로 설정할 때 `http/json`. 게이트웨이 서버의 Claude Code v2.1.261 이전에는 응답이 protobuf만 허용하는 수집기가 Claude Desktop의 내보내기를 거부했으므로 `http/json`을 설정했습니다.831 Claude Desktop은 모든 신호를 하나의 인코딩으로 내보냅니다: `http/protobuf` 또는 `OTEL_EXPORTER_OTLP_PROTOCOL` 또는 해당 신호별 변형 중 하나를 `http/json`으로 설정할 때 `http/json`입니다. gateway 서버의 Claude Code v2.1.261 이전에는 응답이 관계없이 `http/json`을 설정했으므로 protobuf만 허용하는 수집기는 Claude Desktop의 내보내기를 거부했습니다.

738 832

739정책의 `desktop` 블록에서 `disabledBuiltinTools`, `coworkEgressAllowedHosts` 또는 Claude Desktop의 자체 `managedMcpServers` 설정을 설정하려면 게이트웨이 서버의 Claude Code v2.1.232 이상이 필요합니다. Claude Desktop의 `managedMcpServers`는 객체가 아닌 배열 값을 사용합니다.833정책의 `desktop` 블록에서 `disabledBuiltinTools`, `coworkEgressAllowedHosts` 또는 Claude Desktop의 자체 `managedMcpServers` 설정을 설정하려면 gateway 서버의 Claude Code v2.1.232 이상이 필요합니다. Claude Desktop의 `managedMcpServers`는 객체가 아닌 배열 값을 취합니다.

740 834

741게이트웨이는 `hooks` 및 `Bash(npm *)` 같은 범위 지정 권한 규칙과 같이 Claude Desktop 동등물이 없는 키를 생략합니다.835gateway는 Claude Desktop 동등물이 없는 키(예: `hooks` 및 `Bash(npm *)` 같은 범위 지정 권한 규칙)를 부트스트랩 응답에서 생략합니다.

742 836

743`cli` 옆에 선택적 `desktop` 블록을 추가하여 Claude Desktop 설정을 직접 설정합니다. Claude Desktop의 [관리형 구성 참조](https://claude.com/docs/third-party/claude-desktop/configuration)의 설정을 평면 키 이름으로 작성합니다. `bootstrapUrl`과 같이 Claude Desktop이 MDM 또는 로컬 파일에서만 읽는 키를 생략합니다. 게이트웨이는 부팅 시 이를 거부합니다. v2.1.232 이전에는 게이트웨이가 `chatTabEnabled` 및 `disableAutoUpdates`와 같은 고정된 11개의 기능 게이트 키 목록을 허용했고 부팅 시 다른 모든 키를 거부했습니다. v2.1.227 이전에는 게이트웨이가 또한 `chatTabEnabled` 및 `chatAdvancedFileAnalysisEnabled`를 부팅 시 거부했습니다.837`cli` 옆에 선택적 `desktop` 블록을 추가하여 Claude Desktop 설정을 직접 설정하세요. Claude Desktop의 [관리 구성 참조](https://claude.com/docs/third-party/claude-desktop/configuration)의 설정을 평면 키 이름으로 작성하세요. `bootstrapUrl`과 같이 Claude Desktop이 MDM 또는 로컬 파일에서만 읽는 키는 생략하세요. gateway는 부팅 시 이를 거부합니다. v2.1.232 이전에는 gateway가 `chatTabEnabled` 및 `disableAutoUpdates`와 같은 고정된 11개의 기능 게이트 키 목록을 허용했고 부팅 시 다른 모든 키를 거부했습니다. v2.1.227 이전에는 gateway가 부팅 시 `chatTabEnabled` 및 `chatAdvancedFileAnalysisEnabled`도 거부했습니다.

744 838

745```yaml theme={null}839```yaml theme={null}

746managed:840managed:

754 banner: { text: "Contractor build: internal use only" }848 banner: { text: "Contractor build: internal use only" }

755```849```

756 850

757모든 키는 선택 사항입니다. Claude Desktop은 생략한 모든 키에 대해 자신의 기본값을 적용합니다. 게이트웨이는 부팅 시 각 `desktop` 블록을 Claude Desktop 자체가 사용하는 구성 스키마에 대해 검증하므로 실수는 게이트웨이 시작 시 키의 이름을 지정하는 오류로 표시되며 모든 연결된 데스크톱에 도달하지 않습니다. 게이트웨이는 다음을 포함하는 블록에서 부팅 시 실패합니다:851모든 키는 선택적입니다. Claude Desktop은 생략한 모든 키에 대해 자체 기본값을 적용합니다. gateway는 부팅 시 각 `desktop` 블록을 Claude Desktop 자체가 사용하는 구성 스키마에 대해 검증하므로 실수는 전체 연결된 데스크톱에 도달하지 않고 키를 명명하는 오류로 gateway 시작에 표시됩니다. gateway는 블록이 다음을 포함할 때 부팅을 실패합니다:

758 852

759* 알 수 없는 키853* 알 수 없는 키

760* Claude Desktop이 거부하거나 자동으로 삭제할 값(예: 빈 값 또는 중첩된 항목 내의 오타 필드)을 가진 인식된 키. v2.1.260 이전에는 게이트웨이가 `managedMcpServers` 또는 `orgPluginSettings` 항목의 중첩된 객체 내의 오타 필드를 자동으로 삭제했습니다.854* Claude Desktop이 거부하거나 자동으로 삭제할 값을 가진 인식된 키(예: 빈 값 또는 중첩된 항목 내의 오타 부분 키). v2.1.260 이전에는 gateway가 `managedMcpServers` 또는 `orgPluginSettings` 항목의 중첩된 객체 내에서 오타 필드를 자동으로 삭제했습니다.

761* 게이트웨이가 자체적으로 계산하는 키: 추론 연결, 모델 목록 및 OTLP 중계. [`upstreams`](#upstreams), [`models`](#models) 및 [`telemetry`](#telemetry) 섹션의 `forward_to`를 통해 이를 구성합니다.855* gateway가 자체 계산하는 키: 추론 연결, 모델 목록 및 OTLP 릴레이입니다. [`upstreams`](#upstreams), [`models`](#models) 및 [`telemetry`](#telemetry) 섹션의 `forward_to`를 통해 이를 구성하세요.

762* 현재 키의 레거시 별칭. 부팅 오류에서 게이트웨이는 작성할 정규 키의 이름을 지정합니다.856* 현재 키의 레거시 별칭입니다. 부팅 오류에서 gateway는 작성할 정규 키를 명명합니다.

763 857

764더 이상 사용되지 않는 값 또는 항목 형태(예: `transport` 없는 `managedMcpServers` 항목)를 사용하면 게이트웨이가 시작되고 대체를 명명하는 경고를 기록합니다.858더 이상 사용되지 않는 값 또는 항목 형태(예: `transport` 없는 `managedMcpServers` 항목)를 사용하면 gateway는 시작하고 대체를 명명하는 경고를 기록합니다.

765 859

766게이트웨이는 `cli` 블록과 마찬가지로 설치된 버전과 함께 번들된 스키마에 대해 `desktop` 블록을 검증합니다. 더 새로운 Claude Desktop 릴리스에서 도입된 설정을 전달하려면 먼저 게이트웨이를 업그레이드합니다. 예를 들어 `userPluginMarketplacesEnabled` 및 `userPluginUploadsEnabled`는 게이트웨이 서버의 Claude Code v2.1.260 이상 및 멤버 머신의 Claude Desktop 1.37937.0 이상이 필요합니다.860gateway는 `cli` 블록과 마찬가지로 설치된 버전과 함께 번들된 스키마에 대해 `desktop` 블록을 검증합니다. 더 새로운 Claude Desktop 릴리스에서 도입한 설정을 전달하려면 먼저 gateway를 업그레이드하세요. 예를 들어 `userPluginMarketplacesEnabled` 및 `userPluginUploadsEnabled`는 gateway 서버의 Claude Code v2.1.260 이상과 멤버 머신의 Claude Desktop 1.37937.0 이상이 필요합니다.

767 861

768정책의 `desktop` 블록에서 `orgPluginSettings`를 설정하면 게이트웨이는 Claude Desktop 1.15200.0 이상이 읽는 배열 형식으로 제공합니다. 더 오래된 데스크톱은 배열을 무시하고 플러그인 도구 정책을 적용하지 않으므로 이에 의존하기 전에 멤버를 1.15200.0 이상으로 업데이트합니다.862정책의 `desktop` 블록에서 `orgPluginSettings`를 설정하면 gateway는 Claude Desktop 1.15200.0 이상이 읽는 배열 형식으로 제공합니다. 더 오래된 데스크톱은 배열을 무시하고 플러그인 도구 정책을 강제하지 않으므로 이에 의존하기 전에 멤버를 1.15200.0 이상으로 업데이트하세요.

769 863

770게이트웨이는 정책의 `desktop` 블록이 설정하지 않은 키를 `match: {}` 캐치올의 `desktop` 블록에서 채웁니다. 정책의 `cli` 블록을 기본에서 채우는 것과 동일한 방식입니다. 기본 및 역할 정책 모두에서 `disabledBuiltinTools` 또는 `builtinToolPolicy`를 설정하면 게이트웨이는 기본의 제한을 유지합니다:864gateway는 정책의 `desktop` 블록이 설정하지 않은 키를 `match: {}` catch-all의 `desktop` 블록에서 채웁니다. 기본값의 `cli` 블록을 채우는 방식과 동일합니다. 기본값과 역할 정책 모두에서 `disabledBuiltinTools` 또는 `builtinToolPolicy`를 설정하면 gateway는 기본값의 제한을 유지합니다:

771 865

772* `disabledBuiltinTools`: 게이트웨이는 기본의 목록과 정책의 목록의 합집합을 사용합니다.866* `disabledBuiltinTools`: gateway는 기본값의 목록과 정책의 목록의 합집합을 사용합니다.

773* `builtinToolPolicy`: 기본에서 도구를 `allow` 이외의 값으로 설정하면 역할 정책에서 동일한 도구에 대해 `allow`를 설정하더라도 게이트웨이는 해당 값을 유지합니다.867* `builtinToolPolicy`: 기본값에서 도구를 `allow` 이외의 값으로 설정하면 역할 정책에서 동일한 도구에 대해 `allow`를 설정해도 gateway는 해당 값을 유지합니다.

774 868

775다른 모든 키의 경우 역할 정책에서 설정하면 게이트웨이는 역할 정책의 값을 사용합니다. 게이트웨이는 배열 또는 `banner`와 같은 중첩된 객체를 전체적으로 대체하므로 역할 정책에서 `banner.text`를 설정하면 게이트웨이는 기본의 `banner.backgroundColor`를 삭제합니다.869다른 모든 키의 경우 역할 정책에서 설정하면 gateway는 역할 정책의 값을 사용합니다. gateway는 배열 또는 `banner`와 같은 중첩된 객체를 전체적으로 대체하므로 역할 정책에서 `banner.text`를 설정하면 gateway는 기본값의 `banner.backgroundColor`를 삭제합니다.

776 870

777Claude Desktop을 배포하지 않으면 정책에서 `desktop`을 완전히 생략합니다. 게이트웨이는 모든 사용자에 대해 `/user/bootstrap`에서 404를 반환합니다.871Claude Desktop을 배포하지 않으면 정책에서 `desktop`을 완전히 생략하세요. gateway는 모든 사용자에 대해 `/user/bootstrap`에서 404를 반환합니다.

778 872

779<h4 id="precedence-with-other-managed-sources">873<h4 id="precedence-with-other-managed-sources">

780 다른 관리형 소스와의 우선순위874 다른 관리 소스와의 우선 순위

781</h4>875</h4>

782 876

783장치에 MDM 전달 정책 또는 로컬 `managed-settings.json`도 있으면 게이트웨이 전달 설정이 우선합니다. [관리형 계층 내 우선순위](/docs/ko/managed-settings#precedence-within-the-managed-tier)는 로컬 소스가 적용되는 시기를 말하며, [모든 관리 소스에서 읽는 Claude Code 키](/docs/ko/managed-settings#keys-read-from-every-admin-source)를 가지고 있습니다(예: 샌드박스 잠금 키, `forceRemoteSettingsRefresh` 및 변수별 `env` 병합). MDM 프로필 또는 관리형 설정 파일에 구성된 [`policyHelper`](/docs/ko/settings-reference#policyhelper)는 게이트웨이가 설정을 전달하지 않을 때만 실행됩니다. 항목은 출력이 대체하는 것을 말합니다.877장치에 MDM 전달 정책 또는 로컬 `managed-settings.json`도 있으면 gateway 전달 설정이 우선합니다. 관리 설정 페이지의 [관리 계층 내 우선 순위](/docs/ko/managed-settings#precedence-within-the-managed-tier)는 로컬 소스가 적용되는 시기를 말하며, 샌드박스 잠금 키, `forceRemoteSettingsRefresh` 및 변수별 `env` 병합과 같이 어떤 소스를 선택했는지 관계없이 Claude Code가 모든 관리 소스에서 읽는 [키](/docs/ko/managed-settings#keys-read-from-every-admin-source)를 포함합니다. MDM 프로필 또는 관리 설정 파일에서 구성된 [`policyHelper`](/docs/ko/settings-reference#policyhelper)는 gateway가 설정을 전달하지 않을 때만 실행됩니다. 항목은 해당 출력이 대체하는 것을 말합니다.

784 878

785[Claude Desktop](/docs/ko/desktop)과 같은 포함 호스트는 SDK `managedSettings` 옵션을 통해 정책을 제공할 수 있습니다. [포함 호스트의 부모 설정](/docs/ko/managed-settings#parent-settings-from-embedding-hosts)은 Claude Code가 이를 적용하는 시기를 말하며, [부모 설정 제한](/docs/ko/claude-apps-gateway#restrict-parent-settings)은 `allowManaged*Only` 잠금 없이도 여전히 적용되는 허용 방향 설정을 나열합니다.879[Claude Desktop](/docs/ko/desktop)과 같은 임베딩 호스트는 SDK `managedSettings` 옵션을 통해 정책을 제공할 수 있습니다. [임베딩 호스트의 부모 설정](/docs/ko/managed-settings#parent-settings-from-embedding-hosts)은 Claude Code가 이를 적용하는 시기를 말하며, [부모 설정 제한](/docs/ko/claude-apps-gateway#restrict-parent-settings)은 `allowManaged*Only` 잠금 없이도 여전히 적용되는 허용 방향 설정을 나열합니다.

786 880

787게이트웨이 정책은 비대화형 `claude -p` 실행 및 Agent SDK에서 생성된 세션을 포함하여 머신의 모든 Claude Code 호출에 적용됩니다. 게이트웨이가 시작 시 도달할 수 없으면 서명된 세션은 정책 없이 실행하지 않고 오류로 종료됩니다.881gateway 정책은 비대화형 `claude -p` 실행 및 Agent SDK에서 생성된 세션을 포함하여 머신의 모든 Claude Code 호출에 적용됩니다. gateway가 시작 시 도달할 수 없으면 서명된 세션은 정책 없이 실행하지 않고 오류로 종료됩니다.

788 882

789<h3 id="telemetry">883<h3 id="telemetry">

790 `telemetry`884 `telemetry`

791</h3>885</h3>

792 886

793CLI는 OpenTelemetry Protocol(OTLP) over HTTP를 통해 메트릭, 로그 및 활성화 시 추적을 게이트웨이로 보내며, 게이트웨이는 각 구성된 대상으로 그대로 중계합니다. 내보내기는 OpenTelemetry Protocol(OTLP) over HTTP를 사용합니다. 중계를 건너뛰고 세션이 수집기로 직접 내보내도록 하려면 [정책에서 수집기의 이름을 지정](#export-directly-to-your-collector)합니다. CLI가 내보내는 메트릭 및 이벤트는 [사용 모니터링](/docs/ko/monitoring-usage)을 참조하세요.887CLI는 메트릭, 로그 및 활성화되면 추적을 gateway로 보내며, gateway는 이를 각 구성된 대상으로 그대로 릴레이합니다. 내보내기는 OpenTelemetry Protocol(OTLP)을 HTTP를 통해 사용합니다. 릴레이를 건너뛰고 세션이 수집기로 직접 내보내도록 하려면 [정책에서 수집기를 명명하세요](#export-directly-to-your-collector). 사용 모니터링]\(/ko/monitoring-usage)에서 CLI가 내보내는 메트릭 및 이벤트를 참조하세요.

794 888

795CLI는 각 내보내기에 게이트웨이 발급 JWT에서 읽은 인증된 사용자의 ID를 스탬프합니다: `user.id`, `user.email` 및 `user.groups` 속성. 개발자별 비용 및 사용 귀속은 개발자 측 구성 없이 작동합니다.889CLI는 gateway 발급 JWT에서 읽은 인증된 사용자의 ID로 각 내보내기에 스탬프를 찍습니다: `user.id`, `user.email` 및 `user.groups` 속성입니다. 개발자별 비용 및 사용 귀속은 따라서 개발자 측 구성 없이 작동합니다.

796 890

797[Claude Desktop](#claude-desktop-overlay) 및 게이트웨이를 통해 서명된 Cowork 세션은 `enduser.id` 옆에 `user.email` 및 `user.groups`로 텔레메트리를 스탬프하므로 `user.email` 또는 `user.groups`에 대한 하나의 쿼리로 터미널, Desktop 및 Cowork 사용을 다룰 수 있습니다. `user.groups`는 쉼표로 구분된 IdP 그룹 목록입니다.891[Claude Desktop](#claude-desktop-overlay) 및 gateway를 통해 서명된 Cowork 세션은 `user.email` 및 `user.groups`와 함께 `enduser.id`로 원격 측정에 스탬프를 찍으므로 `user.email` 또는 `user.groups`에 대한 하나의 쿼리로 터미널, Desktop 및 Cowork 사용을 포함할 수 있습니다. `user.groups`는 쉼표로 구분된 IdP 그룹 목록입니다.

892

893Desktop 및 Cowork 원격 측정은 또한 `enduser.sub`를 전달하며, 이는 사용자의 이메일이 변경될 때 동일하게 유지되는 ID 공급자가 사용자에게 발급하는 `sub` 클레임입니다. 터미널 세션은 동일한 값을 `user.id` 아래에 스탬프를 찍으므로 `enduser.sub`를 터미널 `user.id`와 일치시키는 쿼리는 한 사용자의 터미널, Desktop 및 Cowork 사용을 함께 포함합니다. Desktop 및 Cowork 내보내기에서 `user.id`는 주제가 아닌 익명 식별자입니다.

798 894

799Claude Code의 모든 OpenTelemetry 데이터와 마찬가지로 이 속성은 조직이 구성하는 대상으로만 이동하며 Anthropic으로는 이동하지 않습니다.895Claude Code의 모든 OpenTelemetry 데이터와 마찬가지로 이 속성은 조직이 구성하는 대상으로만 이동하며 Anthropic으로는 이동하지 않습니다.

800 896

801사용자의 그룹 목록이 퍼센트 인코딩 후 255자보다 길거나 그룹 이름에 쉼표 또는 등호 기호가 포함되면 게이트웨이는 해당 사용자의 Desktop 및 Cowork 텔레메트리에서 `user.groups`를 생략합니다. 그 사용자의 터미널 세션은 여전히 전체 목록을 전달합니다.897사용자의 그룹 목록이 퍼센트 인코딩 후 255자보다 길거나 그룹 이름에 쉼표 또는 등호 기호가 포함되면 gateway는 이를 자르지 않고 해당 사용자의 Desktop 및 Cowork 원격 측정에서 `user.groups`를 생략합니다. 해당 사용자의 터미널 세션은 여전히 전체 목록을 전달합니다.

898

899주제가 퍼센트 인코딩 후 255자보다 길거나 공백, 인쇄 가능한 ASCII 외의 문자 또는 `,` `;` `=` `\` `"` `%` 중 하나를 포함하면 gateway는 `enduser.sub`를 생략합니다. 해당 사용자의 Desktop 및 Cowork 원격 측정은 다른 속성을 유지합니다.

900

901Desktop 및 Cowork 원격 측정에서 `user.email` 및 `user.groups`를 위해 gateway 서버의 Claude Code v2.1.265 이상이 필요하며, 각 개발자의 머신에서 `user.groups`를 위해 Claude Desktop 1.24012 이상이 필요합니다.

802 902

803Desktop 및 Cowork 텔레메트리에서 `user.email` 및 `user.groups`에 대해 게이트웨이 서버의 Claude Code v2.1.265 이상 및 각 개발자 머신의 Claude Desktop 1.24012 이상이 필요합니다.903`enduser.sub`를 위해 gateway 서버의 Claude Code v2.1.274 이상이 필요합니다.

804 904

805```yaml theme={null}905```yaml theme={null}

806telemetry:906telemetry:

808 - url: https://otel-collector.internal.example.com908 - url: https://otel-collector.internal.example.com

809 headers:909 headers:

810 Authorization: ${OTLP_TOKEN}910 Authorization: ${OTLP_TOKEN}

811 # 신호별 옵트인. 기본값: 메트릭만.911 # Per-signal opt-in. Default: metrics only.

812 metrics: true912 metrics: true

813 logs: false913 logs: false

814 traces: false914 traces: false

818```918```

819 919

820<Warning>920<Warning>

821 각 대상은 `metrics`, `logs` 및 `traces`에 독립적으로 옵트인하며 기본값은 메트릭만입니다. 신호는 민감도가 다릅니다:921 각 대상은 `metrics`, `logs` 및 `traces`에 독립적으로 옵트인하며, 기본값은 메트릭만입니다. 신호는 민감도가 다릅니다:

822 922

823 * **메트릭**: 토큰 수, 요청 수 및 지연 시간과 같은 집계 카운터923 * **메트릭**: 토큰 수, 요청 수 및 지연 시간과 같은 집계 카운터

824 * **로그 및 추적**: 전체 bash 명령, 도구 입력 및 파일 경로를 전달할 수 있으며 Claude Code가 개발자 머신에서 수행하는 모든 것을 다룹니다.924 * **로그 및 추적**: 전체 Bash 명령, 도구 입력 및 파일 경로를 전달할 수 있으며, Claude Code가 개발자의 머신에서 수행하는 모든 것을 포함합니다.

825 925

826 로그 및 추적은 해당 데이터가 보증하는 액세스 제어 및 보유 정책이 있는 대상에서만 활성화합니다.926 로그 및 추적을 해당 데이터가 보증하는 액세스 제어 및 보존 정책이 있는 대상에서만 활성화하세요.

827</Warning>927</Warning>

828 928

829각 `forward_to` URL은 게이트웨이의 자체 루프백 인터페이스의 수집기에 대한 하나의 예외를 제외하고 `https://`를 사용해야 합니다:929각 `forward_to` URL은 gateway의 자체 루프백 인터페이스의 수집기에 대한 하나의 예외를 제외하고 `https://`를 사용해야 합니다:

830 930

831* `http://localhost:<port>`는 구성 검증을 통과하지만 [SSRF 가드](/docs/ko/claude-apps-gateway-deploy#threat-model-summary)는 `ECONNREFUSED_SSRF`로 모든 내보내기를 차단합니다. 게이트웨이의 환경에서 `CLAUDE_GATEWAY_ALLOW_LOOPBACK=1`을 설정하지 않으면.931* `http://localhost:<port>`는 구성 검증을 통과하지만 [SSRF 가드](/docs/ko/claude-apps-gateway-deploy#threat-model-summary)는 `ECONNREFUSED_SSRF`로 모든 내보내기를 차단합니다. gateway의 환경에서 `CLAUDE_GATEWAY_ALLOW_LOOPBACK=1`을 설정하지 않으면 차단됩니다.

832* `http://127.0.0.1:<port>` 또는 `http://[::1]:<port>`는 해당 변수가 설정되지 않으면 부팅을 실패합니다.932* `http://127.0.0.1:<port>` 또는 `http://[::1]:<port>`는 해당 변수가 설정되지 않으면 부팅을 실패합니다.

833 933

834클러스터 내 수집기의 경우 자신의 내부 주소에서 HTTPS로 노출하거나 변수가 설정된 사이드카로 실행합니다.934클러스터 내 수집기의 경우 자체 내부 주소에서 HTTPS를 통해 노출하거나 변수가 설정된 사이드카로 실행하세요.

935

936`HTTPS_PROXY`가 설정되면 gateway는 해당 프록시를 통해 내보내기를 보냅니다.

937

938내부 수집기에 직접 도달하려면 호스트 이름으로 또는 `.internal.example.com`과 같은 선행 점이 있는 도메인으로 `NO_PROXY`에 추가하세요. gateway 서버의 Claude Code v2.1.277 이상이 필요합니다. gateway가 프록시 없이 수집기에 도달할 수 있는지 확인하세요. 선행 점이 없는 항목은 정확한 이름만 일치하며 그 아래의 이름은 일치하지 않습니다. CIDR 범위는 일치하지 않습니다.

939

940[프록시 전용 송신](#proxy-only-egress)이 켜져 있으면 프록시 전용 송신이 꺼지므로 프록시에서 수집기를 허용하세요.

835 941

836텔레메트리는 CLI에서 기본적으로 꺼져 있습니다. `telemetry.forward_to` 및 `listen.public_url`을 모두 설정하면 게이트웨이는 `/managed/settings`를 통해 연결된 클라이언트에 대해 켜집니다:942원격 측정은 CLI에서 기본적으로 꺼져 있습니다. `telemetry.forward_to` 및 `listen.public_url`을 모두 설정하면 gateway는 `/managed/settings`를 통해 6개의 환경 변수를 푸시하여 연결된 클라이언트에 대해 켭니다:

837 943

838* `CLAUDE_CODE_ENABLE_TELEMETRY=1`944* `CLAUDE_CODE_ENABLE_TELEMETRY=1`

839* `OTEL_METRICS_EXPORTER`, `OTEL_LOGS_EXPORTER` 및 `OTEL_TRACES_EXPORTER`, 각각 최소 하나의 `forward_to` 대상이 해당 신호를 활성화하면 `otlp`로 설정되고 그렇지 않으면 `none`으로 설정됨945* `OTEL_METRICS_EXPORTER`, `OTEL_LOGS_EXPORTER` 및 `OTEL_TRACES_EXPORTER`는 각각 최소 하나의 `forward_to` 대상이 해당 신호를 활성화하면 `otlp`로 설정되고, 그렇지 않으면 `none`으로 설정됩니다.

840* `OTEL_EXPORTER_OTLP_ENDPOINT=<public_url>`946* `OTEL_EXPORTER_OTLP_ENDPOINT=<public_url>`

841* `OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf`947* `OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf`

842 948

843게이트웨이 서버의 Claude Code v2.1.265 이전에는 게이트웨이가 대상이 옵트인하지 않은 신호를 포함하여 3개의 내보내기 선택기를 모두 `otlp`로 푸시했습니다.949gateway 서버의 Claude Code v2.1.265 이전에는 gateway가 신호가 옵트인하지 않은 신호를 포함하여 세 개의 내보내기 선택기를 모두 `otlp`로 푸시했습니다.

844 950

845푸시된 엔드포인트는 공개 URL에서 구축되므로 메트릭 및 로그는 개발자 또는 정책의 OTEL 구성이 필요하지 않습니다.951푸시된 엔드포인트는 공개 URL에서 빌드되므로 메트릭 및 로그는 개발자 또는 정책의 OTEL 구성이 필요하지 않습니다.

846 952

847`/login`을 통해 서명된 개발자는 자신의 OTEL 구성으로 내보내기를 리디렉션할 수 없습니다:953`/login`을 통해 서명된 개발자는 자체 OTEL 구성으로 내보내기를 리디렉션할 수 없습니다:

848 954

849* **로컬로 설정된 변수**: Claude Code는 푸시된 변수를 관리형 계층에서 적용하므로 각 변수는 개발자가 로컬로 설정하는 값을 재정의합니다.955* **로컬로 설정된 변수**: Claude Code는 푸시된 변수를 관리 계층에서 적용하므로 각 변수는 개발자가 로컬로 설정한 값을 재정의합니다.

850* **로컬로 구성된 엔드포인트**: OTLP/HTTP 내보내기가 활성화되면 CLI는 로컬로 구성된 엔드포인트를 무시합니다(게이트웨이가 텔레메트리 변수를 푸시했는지 여부). 내보내기는 정책이 [수집기를 엔드포인트로 명명](#export-directly-to-your-collector)하지 않으면 게이트웨이로 이동합니다.956* **로컬로 구성된 엔드포인트**: OTLP/HTTP 내보내기가 활성화되면 CLI는 gateway가 원격 측정 변수를 푸시했는지 여부에 관계없이 로컬로 구성된 엔드포인트를 무시합니다. 정책이 [수집기를 엔드포인트로 명명](#export-directly-to-your-collector)하지 않으면 내보내기는 gateway로 이동합니다.

851 957

852신호에 대한 `forward_to` 대상이 없으면 게이트웨이는 이를 수락하고 삭제합니다. 개발자가 이미 Claude Code 텔레메트리를 수집기 중 하나로 내보내면 `forward_to` 대상으로 추가하고 로그 또는 추적을 내보내면 활성화하여 서명 후 데이터를 계속 받도록 합니다. 중계를 건너뛰려면 [정책에서 수집기의 이름을 지정](#export-directly-to-your-collector)합니다.958신호에 대한 `forward_to` 대상이 없으면 gateway는 이를 수락하고 삭제합니다. 개발자가 이미 Claude Code 원격 측정을 수집기 중 하나로 내보내면 `forward_to` 대상으로 추가하고 로그 또는 추적을 내보내면 활성화하여 서명 후 데이터를 계속 받도록 하세요. 릴레이를 건너뛰려면 [정책에서 수집기를 명명하세요](#export-directly-to-your-collector).

853 959

854[추적](/docs/ko/monitoring-usage#traces-beta)은 또한 각 클라이언트에서 `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1`이 필요합니다. 게이트웨이는 해당 변수를 푸시하지 않으므로 관리형 정책의 `env` 블록에서 설정합니다. 개발자는 푸시된 엔드포인트가 이미 트리거하는 동일한 [보안 승인 대화](#managed)에서 이를 승인합니다.960[추적](/docs/ko/monitoring-usage#traces-beta)은 또한 각 클라이언트에서 `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1`이 필요합니다. gateway가 푸시하지 않으므로 관리 정책의 `env` 블록에서 설정하세요. 개발자는 푸시된 엔드포인트가 이미 트리거하는 동일한 [보안 승인 대화 상자](#managed)에서 이를 승인합니다.

855 961

8561로 설정하면 추적을 원하는 그룹에서만 설정합니다. 설정하지 않은 정책은 [병합 규칙](#managed)에 따라 `match: {}` 캐치올 정책에서 값을 상속합니다. 그룹의 클라이언트가 개발자가 로컬로 변수를 설정하더라도 추적을 보내지 않도록 하려면 해당 그룹의 정책에서 0으로 설정합니다.962추적하려는 그룹의 정책에서만 `1`로 설정하세요. 정책이 설정하지 않으면 `match: {}` catch-all 정책이 설정한 경우 해당 값을 상속합니다([병합 규칙](#managed) 참조). 개발자가 로컬로 변수를 설정해도 그룹의 클라이언트가 추적을 보내지 않도록 하려면 해당 그룹의 정책에서 `0`으로 설정하세요.

857 963

858Protobuf 및 JSON OTLP 인코딩 모두 중계되며 모든 OpenTelemetry 호환 백엔드가 대상으로 작동합니다.964protobuf 및 JSON OTLP 인코딩 모두 릴레이되며 모든 OpenTelemetry 호환 백엔드가 대상으로 작동합니다.

859 965

860<h4 id="export-directly-to-your-collector">966<h4 id="export-directly-to-your-collector">

861 수집기로 직접 내보내기967 수집기로 직접 내보내기

862</h4>968</h4>

863 969

864중계를 통해 수집기로 직접 텔레메트리를 보내도록 `/login`을 통해 서명된 세션을 가지려면 [관리형 정책](#managed)의 `env` 블록에서 `OTEL_EXPORTER_OTLP_ENDPOINT`를 수집기의 `https://` 기본 URL로 설정합니다. Claude Code는 `/v1/metrics`, `/v1/logs` 또는 `/v1/traces`를 설정한 URL에 추가합니다(예: `https://otel-collector.example.com:4318`). 각 신호를 OTLP/HTTP를 통해 거기로 내보냅니다. 각 개발자 머신의 Claude Code v2.1.265 이상이 필요합니다. 이전 클라이언트는 중계를 통해 내보냅니다.970`/login`을 통해 서명된 세션이 릴레이를 통해 수집기로 직접 원격 측정을 보내도록 하려면 [관리 정책](#managed)의 `env` 블록에서 `OTEL_EXPORTER_OTLP_ENDPOINT`를 수집기의 `https://` 기본 URL로 설정하세요. Claude Code는 `/v1/metrics`, `/v1/logs` 또는 `/v1/traces`를 설정한 URL에 추가합니다(예: `https://otel-collector.example.com:4318`). 각 신호는 OTLP/HTTP를 통해 거기로 내보냅니다. 각 개발자의 머신에서 Claude Code v2.1.265 이상이 필요합니다. 이전 클라이언트는 릴레이를 통해 내보냅니다.

865 971

866수집기에 인증하려면 동일한 `env` 블록에서 `OTEL_EXPORTER_OTLP_HEADERS`를 설정합니다. 세션은 이 방식으로 명명된 수집기에 개발자의 게이트웨이 세션 토큰을 보내지 않습니다.972수집기에 인증하려면 동일한 `env` 블록에서 `OTEL_EXPORTER_OTLP_HEADERS`를 설정하세요. 세션은 이 방식으로 명명된 수집기에 개발자의 gateway 세션 토큰을 보내지 않습니다.

867 973

868정책에서 이 엔드포인트를 추가하거나 변경하면 Claude Code는 대화형 세션에서 적용하기 전에 각 개발자에게 [보안 승인 대화](#managed)에서 승인을 요청합니다.974정책에서 이 엔드포인트를 추가하거나 변경하면 Claude Code는 각 개발자에게 [보안 승인 대화 상자](#managed)에서 이를 승인하도록 요청한 후 대화형 세션에서 이를 적용합니다.

869 975

870Claude Code는 신호를 직접 내보내기 전에 엔드포인트를 확인하고 확인이 실패하면 해당 신호를 중계에 유지합니다. 확인은 다음을 포함합니다:976Claude Code는 신호를 직접 내보내기 전에 엔드포인트를 확인하고 확인이 실패하면 해당 신호를 릴레이에 유지합니다. 확인에는 다음이 포함됩니다:

871 977

872* 엔드포인트는 게이트웨이 자체에서 옵니다. MDM 프로필 또는 로컬 `managed-settings.json`에서 동일한 변수를 설정하면 내보내기는 중계에 유지됩니다.978* 엔드포인트는 gateway 자체에서 옵니다. MDM 프로필 또는 로컬 `managed-settings.json`에서 동일한 변수를 설정하면 내보내기는 릴레이에 유지됩니다.

873* URL은 `https://`를 사용하거나 루프백 주소에 `http://`를 사용합니다.979* URL은 `https://`를 사용하거나 루프백 주소에 `http://`를 사용합니다.

874* URL은 `/v1/<signal>`으로 끝나는 경로로 확인되며 쿼리 또는 조각이 없습니다. Claude Code는 일반 변수에서 해당 경로를 자체적으로 구축합니다. `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT`와 같은 신호별 변수를 작성된 대로 사용하므로 전체 경로를 포함합니다.980* URL은 쿼리 또는 조각이 없는 `/v1/<signal>`로 끝나는 경로로 확인됩니다. Claude Code는 일반 변수에서 해당 경로를 자체 빌드합니다. `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT`와 같은 신호별 변수를 작성된 대로 사용하므로 전체 경로를 거기에 포함하세요.

875* URL은 게이트웨이의 자체 호스트가 아닙니다. 게이트웨이로 주소 지정된 엔드포인트는 중계 경로 및 세션 토큰을 유지합니다.981* URL은 gateway의 자체 호스트가 아닙니다. gateway로 주소 지정된 엔드포인트는 릴레이 경로와 세션 토큰을 유지합니다.

876* 당신도 개발자도 어떤 설정 소스에서도 [`otelHeadersHelper`](/docs/ko/settings-reference#otelheadershelper)를 구성하지 않았습니다. 도우미가 구성되면 모든 신호는 중계에 유지됩니다.982* 어떤 설정 소스에서도 [`otelHeadersHelper`](/docs/ko/settings-reference#otelheadershelper)를 구성하지 않았습니다. 도우미가 구성되면 모든 신호는 릴레이에 유지됩니다.

877 983

878명명한 엔드포인트는 내보내기가 이동하는 위치만 변경합니다. 여전히 `OTEL_*_EXPORTER` 선택기로 어떤 신호가 내보내는지 선택합니다.984명명한 엔드포인트는 내보내기가 가는 위치만 변경합니다. 여전히 `OTEL_*_EXPORTER` 선택기로 어떤 신호를 내보낼지 선택합니다.

879 985

880엔드포인트 단독은 내보내기를 켜지 않으므로 게이트웨이가 이미 푸시하지 않으면 내보내기를 켜는 변수도 설정합니다:986엔드포인트 자체는 내보내기를 켜지 않으므로 gateway가 이미 푸시하지 않으면 변수도 설정하세요:

881 987

882* 게이트웨이가 이미 [텔레메트리 변수를 푸시](#telemetry)하면 활성화, 선택기 및 프로토콜을 다룹니다. 푸시된 `<public_url>` 값을 재정의합니다. `forward_to` 대상이 활성화하지 않는 신호에 대해서만 `OTEL_*_EXPORTER` 선택기를 `otlp`로 설정합니다.988* gateway가 이미 [원격 측정 변수를 푸시](#telemetry)하면 활성화, 선택기 및 프로토콜을 포함하고 푸시된 `<public_url>` 값을 재정의합니다. `forward_to` 대상이 활성화하지 않는 신호에 대해서만 `OTEL_*_EXPORTER` 선택기를 `otlp`로 직접 설정하세요.

883* 그렇지 않으면 `CLAUDE_CODE_ENABLE_TELEMETRY=1`, `OTEL_*_EXPORTER` 선택기 및 `OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf`도 설정합니다.989* 그렇지 않으면 `CLAUDE_CODE_ENABLE_TELEMETRY=1`, `OTEL_*_EXPORTER` 선택기 및 `OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf`도 설정하세요.

884 990

885개발자가 서명을 해제하거나 다른 게이트웨이에 서명하면 수집기로의 내보내기가 중지되고 Claude Code는 각 남은 배치를 늦게 전달하지 않고 삭제합니다.991개발자가 로그아웃하거나 다른 gateway에 로그인하면 수집기로의 내보내기가 중지되고 Claude Code는 각 남은 배치를 늦게 전달하지 않고 삭제합니다.

886 992

887<h4 id="when-a-destination-fails">993<h4 id="when-a-destination-fails">

888 대상이 실패할 때994 대상이 실패할 때

889</h4>995</h4>

890 996

891게이트웨이는 버퍼링, 재시도 또는 텔레메트리를 저장하지 않으므로 대상에 도달하지 않는 내보내기를 늦게 전달하지 않고 삭제합니다. 각 대상은 자체적으로 성공하거나 실패하며 내보내는 클라이언트는 어느 쪽이든 성공 응답을 받으므로 실패한 전달은 게이트웨이의 로그에만 나타납니다.997gateway는 버퍼링, 재시도 또는 원격 측정 저장을 하지 않으므로 대상에 도달하지 않는 내보내기는 늦게 전달되지 않고 삭제됩니다. 각 대상은 독립적으로 성공하거나 실패하며 내보내는 클라이언트는 어느 쪽이든 성공 응답을 받으므로 실패한 전달은 gateway의 로그에만 나타납니다.

892 998

893대상에 대한 5개의 연속 실패한 전달 후 게이트웨이는 30초 스트레치에서 전달을 일시 중지하고 전달이 성공할 때까지 각 일시 중지를 기록합니다. 모든 오류 응답, 시간 초과 또는 연결 오류는 실패한 전달로 계산됩니다. `400`, `413`, `415`, `422` 및 `431` 제외. 이들은 수집기가 해당 내보내기의 페이로드를 잘못된 형식 또는 너무 큼으로 거부했음을 의미합니다.999대상에 대해 5번 연속 실패한 후 gateway는 30초 단위로 전달을 일시 중지하고 각 일시 중지를 기록하며 전달이 성공할 때까지 계속합니다. 모든 오류 응답, 시간 초과 또는 연결 오류는 실패한 전달로 계산됩니다. `400`, `413`, `415`, `422` 및 `431`은 제외되며, 이들은 수집기가 해당 내보내기의 페이로드를 잘못되었거나 너무 크다고 거부했음을 의미합니다.

894 1000

895거부된 페이로드는 실패 카운트를 진행하거나 재설정하지 않습니다: 게이트웨이는 대상으로 전달을 계속하고 대상의 첫 번째 거부 및 이후 100번째마다 이름을 지정하는 경고를 기록합니다.1001거부된 페이로드는 실패 카운트를 진행하거나 재설정하지 않습니다. gateway는 대상으로 전달을 계속하고 첫 거부 및 그 후 100번마다 경고를 기록하며 대상을 명명합니다.

896 1002

897<h3 id="http-tuning">1003<h3 id="http-tuning">

898 HTTP 조정1004 HTTP 튜닝

899</h3>1005</h3>

900 1006

9014개의 선택적 최상위 블록 `access_control`, `limits`, `timeouts` 및 `rate_limits`는 HTTP 표면을 조정합니다. 기본값은 대부분의 배포에 적합합니다.10074개의 선택적 최상위 블록 `access_control`, `limits`, `timeouts` 및 `rate_limits`는 HTTP 표면을 조정합니다. 기본값은 대부분의 배포에 적합합니다.

902 1008

903| 블록 | 키 | 기본값 | 설명 |1009| 블록 | 키 | 기본값 | 설명 |

904| ---------------- | ---------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |1010| ---------------- | ---------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

905| `access_control` | `allow_cidrs` / `deny_cidrs` | 비어 있음 | 클라이언트 주소별 인바운드 IP 허용/거부, `trusted_proxies` 확인 후. `deny_cidrs`가 먼저 확인됩니다. 일치하는 클라이언트는 `allow_cidrs`도 일치하더라도 거부됩니다. `allow_cidrs`가 비어 있지 않으면 게이트웨이는 기본 거부입니다. `/healthz` 및 `/readyz`는 `allow_cidrs`에서 제외됩니다. 신뢰할 수 있는 프록시가 IP 주소가 아닌 `X-Forwarded-For` 항목을 보내면 실제 클라이언트는 알 수 없으며 게이트웨이는 확인할 내용의 이름을 지정하는 경고를 한 번 기록합니다. 목록 중 하나가 요청에 적용되면 `403` 및 감사 이유 `xff_unparseable`로 거부합니다. 둘 다 적용되지 않으면 요청을 제공하고 프록시의 자체 주소를 IP당 속도 제한 및 감사의 클라이언트 IP로 사용합니다. |1011| `access_control` | `allow_cidrs` / `deny_cidrs` | 비어있음 | `trusted_proxies` 해결 후 클라이언트 주소별 인바운드 IP 허용/거부입니다. `deny_cidrs`가 먼저 확인됩니다. 일치하는 클라이언트는 `allow_cidrs`도 일치해도 거부됩니다. `allow_cidrs`가 비어있지 않으면 gateway는 기본 거부입니다. `/healthz` 및 `/readyz`는 `allow_cidrs`에서 제외됩니다. 신뢰할 수 있는 프록시가 IP 주소가 아닌 `X-Forwarded-For` 항목을 보내면 실제 클라이언트는 알 수 없으며 gateway는 확인할 내용을 명명하는 경고를 한 번 기록합니다. 목록이 요청에 적용되는 경우 `403`으로 거부하고 감사 이유 `xff_unparseable`입니다. 어느 것도 적용되지 않으면 요청을 제공하고 프록시의 자체 주소를 IP별 요금 제한 및 감사의 클라이언트 IP로 사용합니다. |

910| `rate_limits` | `device_authorization.max` / `.window_seconds` | 30 / 600 | 인증되지 않은 장치 인증 엔드포인트에 대한 IP당 속도 제한. 공유 송신 IP 또는 NAT 뒤의 큰 조직에 대해 올립니다. 이러한 한도는 장치 권한 부여 로그인 흐름에만 적용되며 `/v1/messages` 추론에는 적용되지 않습니다. [사용자 코드 무차별 대입 공격 저항](/docs/ko/claude-apps-gateway-deploy#user-code-brute-force-resistance)을 참조하세요. |1016| `rate_limits` | `device_authorization.max` / `.window_seconds` | 30 / 600 | 인증되지 않은 장치 인증 엔드포인트의 IP별 요금 제한입니다. 공유 송신 IP 또는 NAT 뒤의 큰 조직에 대해 올립니다. [대규모 배포](/docs/ko/claude-apps-gateway-deploy#large-rollouts)는 크기를 조정하는 방법을 보여줍니다. 이 제한은 장치 부여 로그인 흐름에만 적용되며 `/v1/messages` 추론에는 적용되지 않습니다. [사용자 코드 무차별 대입 공격 저항](/docs/ko/claude-apps-gateway-deploy#user-code-brute-force-resistance)을 참조하세요. |

912 1018

913`access_control` 목록을 모두 비워 두면(기본값) 게이트웨이는 모든 클라이언트 주소를 제공하므로 네트워크만 도달할 수 있는 사람을 제한합니다. 게이트웨이가 개발자 머신에서 명령을 실행할 수 있는 [관리형 설정](#managed)을 푸시할 수 있기 때문에 중요합니다.1019두 `access_control` 목록을 비어있게 두면(기본값) gateway는 모든 클라이언트 주소를 제공하므로 네트워크만 도달할 수 있는 사람을 제한합니다. gateway는 개발자 머신에서 명령을 실행하는 [관리 설정](#managed)을 푸시할 수 있기 때문에 중요합니다.

914 1020

915`allow_cidrs`가 비어 있는 동안 게이트웨이는 요청에 답하는 방식을 변경하지 않고 두 곳에서 경고합니다:1021`allow_cidrs`가 비어있는 동안 gateway는 요청에 응답하는 방식을 변경하지 않고 두 위치에서 경고합니다:

916 1022

917* **부팅 시**: 운영 로그의 경고는 개인 범위 `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `100.64.0.0/10`, `127.0.0.0/8`, `::1/128` 및 `fc00::/7`만 허용할 것을 권장합니다. 개발자가 연결하는 다른 내부 범위도 포함합니다. 게이트웨이를 루프백 주소에 바인드하고 `trusted_proxies` 또는 `public_url`을 설정하지 않으면(로컬 개발처럼) 경고가 나타나지 않습니다.1023* **부팅 시**: 운영 로그의 경고는 개인 범위 `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `100.64.0.0/10`, `127.0.0.0/8`, `::1/128` 및 `fc00::/7`만 허용하고 개발자가 연결하는 다른 내부 범위를 권장합니다. gateway를 루프백 주소에 바인드하고 `trusted_proxies` 또는 `public_url`을 설정하지 않으면(로컬 개발처럼) 경고가 나타나지 않습니다.

918* **런타임**: 요청이 해당 개인 범위 외부의 주소에서 처음 도착할 때 게이트웨이는 경고를 기록하고 클라이언트 IP를 전달하는 [`access.public_client` 감사 이벤트](/docs/ko/claude-apps-gateway-deploy#logs)를 내보냅니다. 둘 다 프로세스당 한 번 발생합니다. 링크 로컬 주소 `169.254.0.0/16` 및 `fe80::/10`은 공개로 계산되지 않습니다. 게이트웨이는 이 확인이 실행되기 전에 `/healthz` 및 `/readyz`에 응답하므로 공개 범위의 상태 프로브는 이를 트리거하지 않습니다.1024* **런타임**: 요청이 처음 해당 개인 범위 외의 주소에서 도착하면 gateway는 경고를 기록하고 클라이언트 IP를 전달하는 [`access.public_client` 감사 이벤트](/docs/ko/claude-apps-gateway-deploy#logs)를 내보냅니다. 둘 다 프로세스당 한 번 실행됩니다. 링크 로컬 주소 `169.254.0.0/16` 및 `fe80::/10`은 공개로 계산되지 않습니다. gateway는 이 확인이 실행되기 전에 `/healthz` 및 `/readyz`에 응답하므로 공개 범위의 상태 프로브는 이를 트리거하지 않습니다.

919 1025

920두 신호 모두 게이트웨이가 확인하는 클라이언트 주소를 사용합니다. 로드 밸런서, 포트 포워드 또는 터널이 트래픽을 중계하고 `listen.trusted_proxies`에 나열되지 않으면 게이트웨이는 중계의 주소를 보므로 일반적으로 개인이므로 런타임 경고도 개인 허용 목록도 중계된 트래픽을 포착하지 않습니다.1026두 신호 모두 gateway가 해결하는 클라이언트 주소를 사용합니다. 로드 밸런서, 포트 포워드 또는 터널이 트래픽을 릴레이하고 `listen.trusted_proxies`에 나열되지 않으면 gateway는 릴레이의 주소를 보며, 이는 보통 개인이므로 런타임 경고나 개인 허용 목록이 이를 포착하지 않습니다.

921 1027

922그러한 프론트 엔드 뒤에서 먼저 [`listen.trusted_proxies`](#listen)를 설정하여 게이트웨이가 실제 클라이언트 주소를 보도록 하고 게이트웨이 및 그 앞의 모든 것을 공개 인터넷에서 도달할 수 없도록 유지합니다.1028그러한 프론트 엔드 뒤에서 먼저 [`listen.trusted_proxies`](#listen)를 설정하여 gateway가 실제 클라이언트 주소를 보도록 하고 gateway와 그 앞의 모든 것을 공개 인터넷에서 도달할 수 없도록 유지하세요.

923 1029

924<h2 id="complete-example">1030<h2 id="complete-example">

925 완전한 예제1031 완전한 예제

972store:1078store:

973 postgres_url: ${GATEWAY_POSTGRES_URL}1079 postgres_url: ${GATEWAY_POSTGRES_URL}

974 # max_connections: 51080 # max_connections: 5

1081 # connect_timeout_seconds: 5

975 1082

976# /v1/organizations/spend_limits(Anthropic Admin API를 미러링함)를 활성화합니다.1083# /v1/organizations/spend_limits(Anthropic Admin API를 미러링함)를 활성화합니다.

977# 및 /v1/messages에서 개발자별 지출 적용. 비활성화하려면 생략합니다.1084# 및 /v1/messages에서 개발자별 지출 적용. 비활성화하려면 생략합니다.

desktop.md +1 −1

Details

926 926

927[Google Fonts](/docs/ko/artifacts#improve-the-visual-design)에서 글꼴을 로드하는 [아티팩트](/docs/ko/artifacts)도 `fonts.googleapis.com` 및 `fonts.gstatic.com`을 요청합니다. 두 호스트 모두 선택 사항입니다. 이들을 차단하면 아티팩트는 대체 글꼴로 렌더링됩니다. 글꼴 요청이 페이지의 첫 렌더링을 지연시키는 대신 즉시 실패하도록 빠른 거부로 차단합니다.927[Google Fonts](/docs/ko/artifacts#improve-the-visual-design)에서 글꼴을 로드하는 [아티팩트](/docs/ko/artifacts)도 `fonts.googleapis.com` 및 `fonts.gstatic.com`을 요청합니다. 두 호스트 모두 선택 사항입니다. 이들을 차단하면 아티팩트는 대체 글꼴로 렌더링됩니다. 글꼴 요청이 페이지의 첫 렌더링을 지연시키는 대신 즉시 실패하도록 빠른 거부로 차단합니다.

928 928

929아티팩트는 또한 React 또는 차트 패키지와 같은 JavaScript 라이브러리를 `cdnjs.cloudflare.com`, `cdn.jsdelivr.net`, `cdn.tailwindcss.com`, 및 `code.jquery.com`에서 로드할 수 있으며, 다른 외부 호스트에서는 로드할 수 없습니다. 이러한 호스트를 차단하면 라이브러리에 의존하는 아티팩트의 부분이 작동하지 않으며, 차단된 글꼴과 달리 차단된 라이브러리는 대체가 없습니다. 차단된 라이브러리 요청이 시간 초과될 때까지 중단되는 대신 즉시 실패하도록 빠른 거부로 차단합니다.929아티팩트는 또한 React 또는 차트 패키지와 같은 JavaScript 라이브러리를 `cdnjs.cloudflare.com`, `cdn.jsdelivr.net`, `cdn.tailwindcss.com`, `code.jquery.com`, 및 `unpkg.com`에서 로드할 수 있으며, 다른 외부 호스트에서는 로드할 수 없습니다. 이러한 호스트를 차단하면 라이브러리에 의존하는 아티팩트의 부분이 작동하지 않으며, 차단된 글꼴과 달리 차단된 라이브러리는 대체가 없습니다. 차단된 라이브러리 요청이 시간 초과될 때까지 중단되는 대신 즉시 실패하도록 빠른 거부로 차단합니다.

930 930

931<h3 id="authentication-and-sso">931<h3 id="authentication-and-sso">

932 인증 및 SSO932 인증 및 SSO

interactive-mode.md +13 −4

Details

39| `Up/Down arrows` 또는 `Ctrl+P`/`Ctrl+N` | 커서 이동 또는 명령 기록 탐색 | 입력이 래핑되거나 여러 줄인지 여부에 관계없이 한 줄 이상의 시각적 행에 걸쳐 있으면 먼저 프롬프트 내에서 커서를 이동합니다. 커서가 첫 번째 또는 마지막 시각적 행에 있으면 다시 누르면 명령 기록을 탐색합니다. 메시지가 대기 중이면 첫 번째 행에서 `Up`은 대신 [대기 중인 메시지를 되돌립니다](#take-back-what-you-queued) |39| `Up/Down arrows` 또는 `Ctrl+P`/`Ctrl+N` | 커서 이동 또는 명령 기록 탐색 | 입력이 래핑되거나 여러 줄인지 여부에 관계없이 한 줄 이상의 시각적 행에 걸쳐 있으면 먼저 프롬프트 내에서 커서를 이동합니다. 커서가 첫 번째 또는 마지막 시각적 행에 있으면 다시 누르면 명령 기록을 탐색합니다. 메시지가 대기 중이면 첫 번째 행에서 `Up`은 대신 [대기 중인 메시지를 되돌립니다](#take-back-what-you-queued) |

40| `Esc` | Claude 중단 또는 대화 상자 닫기 | 현재 응답 또는 도구 호출을 중간에 중지하여 리디렉션할 수 있습니다. Claude는 지금까지 수행한 작업을 유지합니다. [메시지가 대기 중](#queue-messages-while-claude-works)이면 Claude Code는 이어서 그 메시지를 보냅니다. 대화 상자가 열려 있으면 `Esc`는 대화 상자를 닫습니다. 권한 프롬프트에서 `Esc`는 [**No** 주석 없음](/docs/ko/permissions#add-a-comment-when-you-answer-a-permission-prompt)과 동일하게 작업을 거부합니다 |40| `Esc` | Claude 중단 또는 대화 상자 닫기 | 현재 응답 또는 도구 호출을 중간에 중지하여 리디렉션할 수 있습니다. Claude는 지금까지 수행한 작업을 유지합니다. [메시지가 대기 중](#queue-messages-while-claude-works)이면 Claude Code는 이어서 그 메시지를 보냅니다. 대화 상자가 열려 있으면 `Esc`는 대화 상자를 닫습니다. 권한 프롬프트에서 `Esc`는 [**No** 주석 없음](/docs/ko/permissions#add-a-comment-when-you-answer-a-permission-prompt)과 동일하게 작업을 거부합니다 |

41| `Esc` + `Esc` | 입력 초안 지우기 또는 되감기 | 프롬프트 입력에 텍스트가 있으면 이중 `Esc`는 이를 지우고 초안을 기록에 저장하여 `Up`이 이를 회상할 수 있습니다. 입력이 비어 있으면 이중 `Esc`는 [되감기 메뉴](/docs/ko/checkpointing)를 열어 이전 지점에서 코드 및 대화를 복원하거나 요약합니다 |41| `Esc` + `Esc` | 입력 초안 지우기 또는 되감기 | 프롬프트 입력에 텍스트가 있으면 이중 `Esc`는 이를 지우고 초안을 기록에 저장하여 `Up`이 이를 회상할 수 있습니다. 입력이 비어 있으면 이중 `Esc`는 [되감기 메뉴](/docs/ko/checkpointing)를 열어 이전 지점에서 코드 및 대화를 복원하거나 요약합니다 |

42| `Ctrl+Enter` 또는 `Ctrl+X Ctrl+S` | 대기 중인 메시지 지금 보내기 | 현재 턴을 중단하여 [대기 중인 메시지](#queue-messages-while-claude-works)와 초안이 턴이 끝날 때가 아니라 지금 바로 나갑니다. [셸 모드](#shell-mode-with-prefix)에서 키는 중단하지 않고 명령을 대기열에 넣습니다. 확장 키를 보고하지 않는 터미널에서 `Ctrl+Enter`는 일반 `Enter`로 도착합니다. `Ctrl+X Ctrl+S`는 모든 터미널에서 작동합니다. Claude Code v2.1.275 이상 필요 |

42| `Shift+Tab` 또는 Node 또는 Bun 런타임이 VT 입력 모드를 활성화하지 않을 때 Windows의 `Alt+M` | 권한 모드 순환 | `default` (모드 표시기에서 Manual로 표시됨), `acceptEdits`, `plan` 및 사용 가능할 때 `bypassPermissions` 및 `auto`를 순환합니다. `auto`에서 첫 번째 누름은 `default`로 전환합니다. [권한 모드](/docs/ko/permission-modes)를 참조하세요. 파일 권한 프롬프트에서 동일한 키는 열린 [주석 필드](/docs/ko/permissions#add-a-comment-when-you-answer-a-permission-prompt)를 닫습니다. 필드가 열려 있지 않으면 프롬프트가 나머지 세션에 대해 작업을 허용하는 옵션을 선택합니다 |43| `Shift+Tab` 또는 Node 또는 Bun 런타임이 VT 입력 모드를 활성화하지 않을 때 Windows의 `Alt+M` | 권한 모드 순환 | `default` (모드 표시기에서 Manual로 표시됨), `acceptEdits`, `plan` 및 사용 가능할 때 `bypassPermissions` 및 `auto`를 순환합니다. `auto`에서 첫 번째 누름은 `default`로 전환합니다. [권한 모드](/docs/ko/permission-modes)를 참조하세요. 파일 권한 프롬프트에서 동일한 키는 열린 [주석 필드](/docs/ko/permissions#add-a-comment-when-you-answer-a-permission-prompt)를 닫습니다. 필드가 열려 있지 않으면 프롬프트가 나머지 세션에 대해 작업을 허용하는 옵션을 선택합니다 |

44| `Option+T` (macOS) 또는 `Alt+T` (Windows/Linux) | 확장 사고 전환 | 확장 사고 모드를 활성화하거나 비활성화합니다. Fable 5.1 또는 Fable 5에는 영향을 주지 않으며, 이들은 항상 확장 사고를 사용합니다. Option을 Meta로 구성하지 않고도 macOS에서 작동합니다 |45| `Option+T` (macOS) 또는 `Alt+T` (Windows/Linux) | 확장 사고 전환 | 확장 사고 모드를 활성화하거나 비활성화합니다. Fable 5.1 또는 Fable 5에는 영향을 주지 않으며, 이들은 항상 확장 사고를 사용합니다. Option을 Meta로 구성하지 않고도 macOS에서 작동합니다 |

348* 백그라운드 작업은 Claude Code가 종료될 때 자동으로 정리됩니다. macOS 및 Linux에서 [`/tasks`](/docs/ko/commands)에서 백그라운드 작업을 중지하거나 Claude Code가 종료 시 중지할 때, `setsid` 또는 `timeout` 아래에서 시작된 것처럼 작업의 셸에서 분리된 프로세스도 중지됩니다.349* 백그라운드 작업은 Claude Code가 종료될 때 자동으로 정리됩니다. macOS 및 Linux에서 [`/tasks`](/docs/ko/commands)에서 백그라운드 작업을 중지하거나 Claude Code가 종료 시 중지할 때, `setsid` 또는 `timeout` 아래에서 시작된 것처럼 작업의 셸에서 분리된 프로세스도 중지됩니다.

349* 세션을 종료하는 대신 백그라운드로 설정하면, 백그라운드 작업이 백그라운드 세션에서 계속 실행됩니다. [백그라운드 세션 실행](/docs/ko/agent-view#from-inside-a-session)을 참조하세요.350* 세션을 종료하는 대신 백그라운드로 설정하면, 백그라운드 작업이 백그라운드 세션에서 계속 실행됩니다. [백그라운드 세션 실행](/docs/ko/agent-view#from-inside-a-session)을 참조하세요.

350* 백그라운드 작업은 출력이 5GB를 초과하면 자동으로 종료되며, stderr에 이유를 설명하는 메모가 표시됩니다.351* 백그라운드 작업은 출력이 5GB를 초과하면 자동으로 종료되며, stderr에 이유를 설명하는 메모가 표시됩니다.

351* macOS 및 Linux에서 Claude Code는 운영 체제가 메모리 압박 신호를 보낼 때 실행 중인 백그라운드 작업을 종료합니다. 단, 세션이 최소 30분 동안 유휴 상태이고 턴 또는 서브에이전트가 실행 중이지 않아야 합니다. [`CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP`](/docs/ko/env-vars)을 `1`로 설정하여 이를 비활성화합니다. Claude Code v2.1.193 이상이 필요합니다.352* macOS 및 Linux에서 Claude Code는 운영 체제가 메모리 압박 신호를 보낼 때 실행 중인 백그라운드 작업을 종료합니다. 단, 세션이 최소 30분 동안 유휴 상태이고 턴 또는 서브에이전트가 실행 중이지 않아야 합니다. Claude Code v2.1.193 이상이 필요합니다.

353 * [디버그 로그](/docs/ko/debug-your-config)에 작업이 중지된 이유 또는 압박 이벤트가 작업을 실행 중인 상태로 둔 이유가 표시됩니다.

354 * [`CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP`](/docs/ko/env-vars)을 `1`로 설정하여 메모리 압박 중지를 비활성화합니다.

352* [서브에이전트](/docs/ko/sub-agents)가 소유한 백그라운드 명령어는 시간 제한이 없습니다. 단, 포그라운드에서 실행 중인 서브에이전트가 소유한 명령어는 해당 서브에이전트가 최종 응답을 제공할 때 종료됩니다. 도구 참조의 [백그라운드 명령어](/docs/ko/tools-reference#background-commands)를 참조하세요. v2.1.218 이전에는 메모리 압박 수거 또는 이전의 서브에이전트 명령어에 대한 60분 제한이 `Ctrl+B`로 백그라운드로 이동된 명령어를 포함하지 않았습니다.355* [서브에이전트](/docs/ko/sub-agents)가 소유한 백그라운드 명령어는 시간 제한이 없습니다. 단, 포그라운드에서 실행 중인 서브에이전트가 소유한 명령어는 해당 서브에이전트가 최종 응답을 제공할 때 종료됩니다. 도구 참조의 [백그라운드 명령어](/docs/ko/tools-reference#background-commands)를 참조하세요. v2.1.218 이전에는 메모리 압박 수거 또는 이전의 서브에이전트 명령어에 대한 60분 제한이 `Ctrl+B`로 백그라운드로 이동된 명령어를 포함하지 않았습니다.

353 356

354모든 백그라운드 작업 기능을 비활성화하려면 `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` 환경 변수를 `1`로 설정합니다. 자세한 내용은 [환경 변수](/docs/ko/env-vars)를 참조하세요.357모든 백그라운드 작업 기능을 비활성화하려면 `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` 환경 변수를 `1`로 설정합니다. 자세한 내용은 [환경 변수](/docs/ko/env-vars)를 참조하세요.

394 397

395Claude가 작업 중인 동안 메시지를 입력하고 `Enter`를 누르면 Claude Code가 턴을 중단하지 않고 메시지를 큐에 추가합니다. 큐에 추가된 항목은 입력 상자 위에 나열되며 전송될 때까지 표시됩니다. `!` [셸 명령](#shell-mode-with-prefix)과 대부분의 [명령](/docs/ko/commands)을 같은 방식으로 큐에 추가할 수 있습니다. 단, `/status`와 같이 Claude Code가 전송 시 즉시 실행하는 명령은 제외됩니다.398Claude가 작업 중인 동안 메시지를 입력하고 `Enter`를 누르면 Claude Code가 턴을 중단하지 않고 메시지를 큐에 추가합니다. 큐에 추가된 항목은 입력 상자 위에 나열되며 전송될 때까지 표시됩니다. `!` [셸 명령](#shell-mode-with-prefix)과 대부분의 [명령](/docs/ko/commands)을 같은 방식으로 큐에 추가할 수 있습니다. 단, `/status`와 같이 Claude Code가 전송 시 즉시 실행하는 명령은 제외됩니다.

396 399

400전송된 메시지와 큐에 추가된 메시지는 Claude가 응답하기 시작할 때까지 회색으로 표시되므로, Claude가 아직 처리하지 않은 메시지를 구분할 수 있습니다.

401

397<h3 id="when-claude-code-sends-what-you-queued">402<h3 id="when-claude-code-sends-what-you-queued">

398 Claude Code가 큐에 추가한 항목을 전송하는 시점403 Claude Code가 큐에 추가한 항목을 전송하는 시점

399</h3>404</h3>

400 405

401큐에 추가된 항목이 Claude에게 전달되는 시점은 큐에 추가한 항목의 종류에 따라 다릅니다.406큐에 추가된 항목이 Claude에게 전달되는 시점은 큐에 추가한 항목의 종류에 따라 다릅니다.

402 407

403* 메시지: Claude가 도구 호출을 실행 중인 동안 메시지를 큐에 추가하면, Claude Code는 해당 도구 호출이 완료되는 즉시 같은 턴 내에서 Claude에게 메시지를 전달합니다. 턴이 끝났을 때 메시지가 여전히 큐에 있으면, Claude Code는 가장 오래된 메시지만 다음 턴으로 전송합니다. 나머지는 큐에 남아 있으며 같은 규칙을 따릅니다. Claude Code는 해당 턴의 도구 호출이 완료될 때 메시지를 Claude에게 전달하거나, 그 다음 턴에 다음으로 오래된 메시지를 전송합니다.408* 메시지: Claude가 도구 호출을 실행 중인 동안 메시지를 큐에 추가하면, Claude Code는 해당 도구 호출이 완료되는 즉시 같은 턴 내에서 Claude에게 메시지를 전달합니다. 턴이 끝났을 때 메시지가 여전히 큐에 있으면, Claude Code는 다른 키 입력 없이 입력한 순서대로 메시지를 전송합니다.

404* 명령 및 셸 명령: Claude Code는 턴이 끝날 때까지 이들을 보관했다가 한 번에 하나씩 실행합니다.409* 명령 및 셸 명령: Claude Code는 턴이 끝날 때까지 이들을 보관했다가 한 번에 하나씩 실행하며, 큐에 추가한 순서를 유지합니다.

410

411큐에 추가한 항목을 턴이 끝날 때까지 기다리지 않고 전송하려면 `Ctrl+Enter`를 누르세요. Claude Code는 턴을 중단하고, 큐에 추가된 메시지가 즉시 전송되며, 입력한 초안이 있으면 그 뒤에 큐에 추가됩니다. [셸 모드](#shell-mode-with-prefix)에서는 이 키가 턴을 중단하지 않고 명령을 큐에 추가합니다. Claude Code v2.1.275 이상이 필요합니다.

412

413확장 키를 보고하지 않는 터미널에서는 `Ctrl+Enter`가 일반 `Enter`로 인식되어 초안을 큐에 추가합니다. `Ctrl+X Ctrl+S`는 모든 터미널에서 작동합니다. 두 키 모두 [`chat:sendNow` 작업](/docs/ko/keybindings#chat-actions)의 바인딩입니다.

405 414

406`Esc`를 눌러 턴을 중단할 수 있습니다. Claude Code는 큐에 추가한 항목을 유지하고 즉시 전송합니다.415`Esc`를 눌러 초안을 제출하지 않고 턴을 중단할 수 있습니다. Claude Code는 큐에 추가한 항목을 유지하고 즉시 전송합니다.

407 416

408Claude Code는 일부 명령을 큐에 추가하지 않고 전송 시 즉시 실행합니다. 그 중에는 `/model`, `/effort`, `/fast`가 있습니다. 이 세 명령은 각각 설정을 변경합니다. 모델, 노력 수준, 또는 빠른 모드입니다. Claude Code가 새 설정을 Claude가 이미 작업 중인 턴에 적용할지, 아니면 다음 턴부터만 적용할지는 명령에 따라 다릅니다.417Claude Code는 일부 명령을 큐에 추가하지 않고 전송 시 즉시 실행합니다. 그 중에는 `/model`, `/effort`, `/fast`가 있습니다. 이 세 명령은 각각 설정을 변경합니다. 모델, 노력 수준, 또는 빠른 모드입니다. Claude Code가 새 설정을 Claude가 이미 작업 중인 턴에 적용할지, 아니면 다음 턴부터만 적용할지는 명령에 따라 다릅니다.

409 418

keybindings.md +9 −5

Details

112`Chat` 컨텍스트에서 사용 가능한 작업:112`Chat` 컨텍스트에서 사용 가능한 작업:

113 113

114| 작업 | 기본값 | 설명 |114| 작업 | 기본값 | 설명 |

115| :-------------------- | :----------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |115| :-------------------- | :----------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

125| `chat:queueSubmit` | Ctrl+X Enter | 메시지를 제출하고 대기 표시: Claude가 작업 중일 때 Claude Code [이를 대기열에 넣고](/docs/ko/interactive-mode#queue-messages-while-claude-works) 턴을 중단하지 않습니다. `chat:submit`과 달리 자동 완성 제안이 열려 있어도 초안을 제출합니다. v2.1.247 이상 필요 |125| `chat:queueSubmit` | Ctrl+X Enter | 메시지를 제출하고 대기 표시: Claude가 작업 중일 때 Claude Code [이를 대기열에 넣고](/docs/ko/interactive-mode#queue-messages-while-claude-works) 턴을 중단하지 않습니다. `chat:submit`과 달리 자동 완성 제안이 열려 있어도 초안을 제출합니다. v2.1.247 이상 필요 |

126| `chat:sendNow` | Ctrl+Enter, Ctrl+X Ctrl+S | 실행 중인 턴을 중단하여 [대기 중인 메시지](/docs/ko/interactive-mode#queue-messages-while-claude-works)와 초안이 즉시 전송됩니다. 실행 중인 것이 없으면 초안을 제출하고 [셸 모드](/docs/ko/interactive-mode#shell-mode-with-prefix)에서는 중단하지 않고 명령을 대기열에 넣습니다. 확장 키를 보고하지 않는 터미널은 `Ctrl+Enter`를 일반 `Enter`로 전달하므로 `Ctrl+X Ctrl+S`는 모든 터미널에서 작동하는 바인딩입니다. v2.1.275 이상 필요 |

525 기본 단축키 바인딩 해제526 기본 단축키 바인딩 해제

526</h2>527</h2>

527 528

528작업을 `null`로 설정하여 기본 단축키를 바인딩 해제합니다:529작업을 `null`로 설정하여 기본 단축키 바인딩을 해제합니다:

529 530

530```json theme={null}531```json theme={null}

531{532{

540}541}

541```542```

542 543

543이는 코드 바인딩에도 작동합니다. 접두사를 공유하는 모든 코드를 바인딩 해제하면 해당 접두사를 단일 키 바인딩으로 사용할 수 있습니다. 모든 활성 컨텍스트의 코드는 해당 접두사를 예약된 상태로 유지하므로 해당 코드를 정의하는 컨텍스트에서 각 코드를 바인딩 해제해야 합니다.544이는 코드 바인딩에도 작동합니다. 접두사를 공유하는 모든 코드를 바인딩 해제하면 해당 접두사를 단일 키 바인딩으로 사용할 수 있습니다. 활성 컨텍스트의 코드는 접두사를 예약된 상태로 유지하므로 해당 코드를 정의하는 컨텍스트에서 각 코드를 바인딩 해제해야 합니다.

544 545

545Claude Code는 `ctrl+x` 접두사에서 다음과 같은 기본 코드를 바인딩합니다: `Chat`의 `ctrl+x ctrl+k`, `ctrl+x ctrl+e`, `ctrl+x enter`, `ctrl+x ctrl+a`, 그리고 `ctrl+x tab`, `Task`의 `ctrl+x ctrl+b`, 그리고 `DiffPanel`의 `ctrl+x b`. `ctrl+x enter` 코드는 v2.1.247 이상이 필요하며, `ctrl+x b`, `ctrl+x ctrl+a`, 그리고 `ctrl+x tab`은 v2.1.260 이상이 필요합니다. `ctrl+x` 자체를 단일 키 바인딩으로 되찾으려면 모두 바인딩 해제합니다:546Claude Code는 `ctrl+x` 접두사에서 다음과 같은 기본 코드를 바인딩합니다: `Chat`에서 `ctrl+x ctrl+k`, `ctrl+x ctrl+e`, `ctrl+x enter`, `ctrl+x ctrl+a`, `ctrl+x ctrl+s`, `ctrl+x tab`, `Task`에서 `ctrl+x ctrl+b`, `DiffPanel`에서 `ctrl+x b`. `ctrl+x enter` 코드는 v2.1.247 이상이 필요하며, `ctrl+x b`, `ctrl+x ctrl+a`, `ctrl+x tab`은 v2.1.260 이상이 필요하고, `ctrl+x ctrl+s`는 v2.1.275 이상이 필요합니다.

547

548`ctrl+x` 자체를 단일 키 바인딩으로 되찾으려면 모두 바인딩 해제합니다:

546 549

547```json theme={null}550```json theme={null}

548{551{

566 "ctrl+x ctrl+e": null,569 "ctrl+x ctrl+e": null,

567 "ctrl+x enter": null,570 "ctrl+x enter": null,

568 "ctrl+x ctrl+a": null,571 "ctrl+x ctrl+a": null,

572 "ctrl+x ctrl+s": null,

569 "ctrl+x tab": null,573 "ctrl+x tab": null,

570 "ctrl+x": "chat:newline"574 "ctrl+x": "chat:newline"

571 }575 }

574}578}

575```579```

576 580

577접두사의 일부 코드만 바인딩 해제하고 다른 코드는 바인딩 해제하지 않으면 접두사를 누르면 여전히 남은 바인딩에 대해 코드 대기 모드로 진입합니다.581접두사의 일부 코드만 바인딩 해제하고 모두 바인딩 해제하지 않으면 접두사를 누르면 여전히 남은 바인딩에 대한 코드 대기 모드로 진입합니다.

578 582

579<h2 id="reserved-shortcuts">583<h2 id="reserved-shortcuts">

580 예약된 단축키584 예약된 단축키

model-config.md +4 −4

Details

467 467

468이는 계획을 위한 Opus의 추론과 실행을 위한 Sonnet의 효율성을 결합합니다.468이는 계획을 위한 Opus의 추론과 실행을 위한 Sonnet의 효율성을 결합합니다.

469 469

470계획 모드 Opus 단계는 `opus` 모델 설정과 동일한 컨텍스트 윈도우를 사용합니다. Opus가 [자동으로 1M 컨텍스트로 업그레이드](#extended-context)되는 구독 계층에서 `opusplan`은 계획 모드에서도 업그레이드를 받습니다. 자동 업그레이드 계층이 아닌 경우 두 단계 모두에 1M 컨텍스트를 강제하려면 모델을 `opusplan[1m]`으로 [설정](#setting-your-model)하세요. 예를 들어 `/model opusplan[1m]`을 사용하세요. 이를 `/model`로 설정하려면 Claude Code v2.1.265 이상이 필요합니다. 이전 버전에서는 `--model` 플래그 또는 `model` 설정을 대신 사용하세요.470계획 모드 Opus 단계는 `opus` 모델 설정과 동일한 컨텍스트 윈도우를 사용하고, 실행 단계는 `sonnet`과 동일한 윈도우를 사용합니다. `opus`와 `sonnet`이 [1M 컨텍스트 윈도우](#extended-context)로 기본적으로 실행되는 모델로 확인될 때(현재 모델이 Anthropic API에서 그렇듯이), 두 단계 모두 이를 사용하여 실행됩니다. 그렇지 않은 경우 두 단계 모두에 1M 컨텍스트를 요청하려면 모델을 `opusplan[1m]`으로 [설정](#setting-your-model)하세요. 예를 들어 `/model opusplan[1m]`을 사용하세요. 이를 `/model`로 설정하려면 Claude Code v2.1.265 이상이 필요합니다. 이전 버전에서는 `--model` 플래그 또는 `model` 설정을 대신 사용하세요.

471 471

472[`availableModels`](#restrict-model-selection)가 최신 Opus를 제외하지만 `["sonnet", "claude-opus-4-6"]`과 같은 이전 버전을 허용하는 경우, `opusplan`은 계획을 위해 허용된 최신 Opus를 사용하고 모든 Opus가 제외된 경우에만 Sonnet에만 유지됩니다. 계획 모드에서 일반적으로 Sonnet으로 업그레이드되는 Haiku 세션은 마찬가지로 허용된 최신 Sonnet을 사용하고, 모든 Sonnet이 제외된 경우에만 Haiku에만 유지됩니다. v2.1.205 이전에는 허용 목록이 이전 버전을 허용했더라도 업그레이드 제품군의 최신 버전이 제외되면 계획 모드가 세션의 모델에 유지되었습니다.472[`availableModels`](#restrict-model-selection)가 최신 Opus를 제외하지만 `["sonnet", "claude-opus-4-6"]`과 같은 이전 버전을 허용하는 경우, `opusplan`은 계획을 위해 허용된 최신 Opus를 사용하고 모든 Opus가 제외된 경우에만 Sonnet에만 유지됩니다. 계획 모드에서 일반적으로 Sonnet으로 업그레이드되는 Haiku 세션은 마찬가지로 허용된 최신 Sonnet을 사용하고, 모든 Sonnet이 제외된 경우에만 Haiku에만 유지됩니다. v2.1.205 이전에는 허용 목록이 이전 버전을 허용했더라도 업그레이드 제품군의 최신 버전이 제외되면 계획 모드가 세션의 모델에 유지되었습니다.

473 473

712 712

713Fable 5.1, Fable 5, Sonnet 5, Opus 4.6 이상, Sonnet 4.6은 큰 코드베이스가 있는 긴 세션을 위해 [1백만 토큰 컨텍스트 윈도우](https://platform.claude.com/docs/en/build-with-claude/context-windows#context-window-sizes-by-model)를 지원합니다.713Fable 5.1, Fable 5, Sonnet 5, Opus 4.6 이상, Sonnet 4.6은 큰 코드베이스가 있는 긴 세션을 위해 [1백만 토큰 컨텍스트 윈도우](https://platform.claude.com/docs/en/build-with-claude/context-windows#context-window-sizes-by-model)를 지원합니다.

714 714

715가용성은 모델 및 플랜에 따라 다릅니다. Anthropic API에서 Fable 5.1, Fable 5, Sonnet 5, Opus 4.7 이상은 기본적으로 1M 윈도우로 실행됩니다.715Anthropic API에서 Fable 5.1, Fable 5, Sonnet 5, Opus 4.7 이상은 모든 플랜(Pro 포함)에서 1M 윈도우로 실행됩니다. 이러한 모델에서 `[1m]` 변형을 선택하거나 1M 윈도우에 대해 사용 크레딧을 켤 필요가 없습니다. Fable 사용 자체는 일부 플랜에서 사용 크레딧으로 청구될 수 있습니다. [Fable 및 사용 크레딧](#fable-and-usage-credits)을 참조하세요.

716 716

717Max, Team, Enterprise 플랜(Team Standard 및 Team Premium 좌석 모두 포함)에서 Opus는 추가 구성 없이 자동으로 1M 컨텍스트로 업그레이드됩니다. Sonnet 4.6 with 1M 컨텍스트는 자동 업그레이드의 일부가 아니며 Max를 포함한 모든 구독 플랜에서 [사용 크레딧](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)이 필요합니다.717Opus 4.6 및 Sonnet 4.6은 `[1m]` 변형을 통해서만 1M에 도달하며, 해당 변형에 대한 액세스는 플랜에 따라 다릅니다. Max, Team, Enterprise 플랜(Team Standard 및 Team Premium 좌석 모두 포함)에서 1M 컨텍스트가 있는 Opus 4.6은 구독에 포함됩니다. 1M 컨텍스트가 있는 Sonnet 4.6은 Max를 포함한 모든 구독 플랜에서 [사용 크레딧](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)이 필요합니다.

718 718

719| 플랜 | 1M 컨텍스트가 있는 Opus | 1M 컨텍스트가 있는 Sonnet 4.6 |719| 플랜 | 1M 컨텍스트가 있는 Opus 4.6 | 1M 컨텍스트가 있는 Sonnet 4.6 |

720| --------------------- | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |720| --------------------- | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |

722| Pro | [사용 크레딧](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) 필요 | [사용 크레딧](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) 필요 |722| Pro | [사용 크레딧](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) 필요 | [사용 크레딧](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) 필요 |

network-config.md +1 −1

Details

286 286

287[Google Fonts](/docs/ko/artifacts#improve-the-visual-design)에서 글꼴을 로드하는 [Artifact](/docs/ko/artifacts)는 `fonts.googleapis.com` 및 `fonts.gstatic.com`도 요청합니다. 두 호스트 모두 선택 사항입니다. 차단하면 Artifact는 대체 글꼴로 렌더링됩니다. 글꼴 요청이 페이지의 첫 렌더링을 지연시키는 대신 즉시 실패하도록 빠른 거부로 차단하십시오.287[Google Fonts](/docs/ko/artifacts#improve-the-visual-design)에서 글꼴을 로드하는 [Artifact](/docs/ko/artifacts)는 `fonts.googleapis.com` 및 `fonts.gstatic.com`도 요청합니다. 두 호스트 모두 선택 사항입니다. 차단하면 Artifact는 대체 글꼴로 렌더링됩니다. 글꼴 요청이 페이지의 첫 렌더링을 지연시키는 대신 즉시 실패하도록 빠른 거부로 차단하십시오.

288 288

289Artifact는 또한 React 또는 차트 패키지와 같은 JavaScript 라이브러리를 `cdnjs.cloudflare.com`, `cdn.jsdelivr.net`, `cdn.tailwindcss.com` 및 `code.jquery.com`에서 로드할 수 있으며, 다른 외부 호스트에서는 로드할 수 없습니다. 해당 호스트를 차단하면 라이브러리에 종속된 Artifact의 부분이 작동하지 않으며, 차단된 글꼴과 달리 차단된 라이브러리는 대체가 없습니다. 차단된 라이브러리 요청이 시간 초과될 때까지 중단되는 대신 즉시 실패하도록 빠른 거부로 차단하십시오.289Artifact는 또한 React 또는 차트 패키지와 같은 JavaScript 라이브러리를 `cdnjs.cloudflare.com`, `cdn.jsdelivr.net`, `cdn.tailwindcss.com`, `code.jquery.com` 및 `unpkg.com`에서 로드할 수 있으며, 다른 외부 호스트에서는 로드할 수 없습니다. 해당 호스트를 차단하면 라이브러리에 종속된 Artifact의 부분이 작동하지 않으며, 차단된 글꼴과 달리 차단된 라이브러리는 대체가 없습니다. 차단된 라이브러리 요청이 시간 초과될 때까지 중단되는 대신 즉시 실패하도록 빠른 거부로 차단하십시오.

290 290

291<h2 id="additional-resources">291<h2 id="additional-resources">

292 추가 리소스292 추가 리소스

settings-reference.md +2 −0

Details

3170 3170

3171Claude Code가 Bash 명령이 Git 저장소에서 변경하는 파일을 기록할지 여부를 선택합니다. 기록하면 터미널에서 명령 후 diff를 보고, [PostToolUse Bash hooks](/docs/ko/hooks#bash)는 변경된 파일 목록을 받습니다.3171Claude Code가 Bash 명령이 Git 저장소에서 변경하는 파일을 기록할지 여부를 선택합니다. 기록하면 터미널에서 명령 후 diff를 보고, [PostToolUse Bash hooks](/docs/ko/hooks#bash)는 변경된 파일 목록을 받습니다.

3172 3172

3173나열된 파일이 항상 명령이 변경한 파일인 것은 아닙니다. 명령이 실행되는 동안 다른 프로그램이나 다른 Bash 호출이 만든 변경 사항도 거기에 나타날 수 있습니다.

3174

3173모든 권한 모드에서 기록하려면 키를 `true`로 설정합니다. Claude Code v2.1.269 이상이 필요합니다.3175모든 권한 모드에서 기록하려면 키를 `true`로 설정합니다. Claude Code v2.1.269 이상이 필요합니다.

3174 3176

3175* **범위**: [`사용자 또는 관리됨`](#scopes). `true`는 사용자 설정, `--settings`로 전달된 JSON 또는 [관리 설정](/docs/ko/managed-settings)에서만 계산되므로, 저장소의 `.claude/settings.json` 또는 `.claude/settings.local.json`의 `true`는 기록을 켤 수 없습니다. 저장소 파일의 `false`는 [더 높은 우선순위](/docs/ko/settings#settings-precedence) 파일이 `true`를 설정하지 않으면 여전히 끕니다.3177* **범위**: [`사용자 또는 관리됨`](#scopes). `true`는 사용자 설정, `--settings`로 전달된 JSON 또는 [관리 설정](/docs/ko/managed-settings)에서만 계산되므로, 저장소의 `.claude/settings.json` 또는 `.claude/settings.local.json`의 `true`는 기록을 켤 수 없습니다. 저장소 파일의 `false`는 [더 높은 우선순위](/docs/ko/settings#settings-precedence) 파일이 `true`를 설정하지 않으면 여전히 끕니다.

Documentation 2026-09-20 23:59 UTC to 2026-09-21 22:59 UTC