421 421
422```yaml theme={null}422```yaml theme={null}
423models:423models:
424 - id: claude-opus-restricted # a custom id, not a built-in model name424 - id: restricted-claude-opus-4-8 # a custom id, not a built-in model name
425 upstream_model:425 upstream_model:
426 bedrock-isolated: us.anthropic.claude-opus-4-8 # the only upstream that serves it426 bedrock-isolated: us.anthropic.claude-opus-4-8 # the only upstream that serves it
427```427```
631 631
632게이트웨이는 실패한 업스트림을 기록하지 않으므로, 업스트림이 다운된 동안 그 업스트림에 도달하는 모든 요청은 여전히 해당 업스트림을 시도하고 실패할 때까지 기다린 후 다음으로 넘어갑니다.632게이트웨이는 실패한 업스트림을 기록하지 않으므로, 업스트림이 다운된 동안 그 업스트림에 도달하는 모든 요청은 여전히 해당 업스트림을 시도하고 실패할 때까지 기다린 후 다음으로 넘어갑니다.
633 633
634Anthropic API 업스트림의 경우 [`timeouts.upstream_ttfb_ms`](#http-tuning)가 다운된 업스트림에 대한 대기 시간을 제한합니다. 이 설정은 다른 공급자에는 적용되지 않으며, 그 경우 게이트웨이는 업스트림이 응답을 시작할 때까지 최대 1시간을 기다립니다.634게이트웨이는 응답이 시작될 때까지 다음 시간 동안 기다립니다.
635
636* **`provider: anthropic` 업스트림**: [`timeouts.upstream_ttfb_ms`](#http-tuning), 기본값 120초
637* **기타 공급자**: 최대 1시간. 스트리밍 요청의 대기 시간을 줄이려면 게이트웨이 v2.1.295 이상에서 `timeouts.upstream_ttfb_ms`를 설정하십시오. 비스트리밍 모델 요청은 어느 경우든 최대 1시간을 기다립니다
635 638
636`404`는 업스트림별 모델 가용성이므로, 모델을 활성화하지 않은 업스트림이 그 모델을 제공하는 뒤쪽 업스트림을 막지 않습니다. 요청된 모델을 확인할 수 없는 업스트림은 네트워크 왕복 없이 건너뜁니다.639`404`는 업스트림별 모델 가용성이므로, 모델을 활성화하지 않은 업스트림이 그 모델을 제공하는 뒤쪽 업스트림을 막지 않습니다. 요청된 모델을 확인할 수 없는 업스트림은 네트워크 왕복 없이 건너뜁니다.
637 640
689 692
690### `admin`693### `admin`
691 694
692선택 사항입니다. Anthropic의 공개 Admin API를 그대로 반영하는 `/v1/organizations/spend_limits`와 `/v1/messages`에 대한 개발자별 지출 적용을 활성화합니다. 한도를 설정하고 적용하는 방법은 [지출 한도](https://code.claude.com/docs/ko/claude-apps-gateway-spend-limits.md)를 참조하십시오. 이 섹션에서는 이 기능을 켜고 조정하는 `gateway.yaml` 키를 다룹니다.695선택 사항입니다. Anthropic의 공개 Admin API를 그대로 따르는 `/v1/organizations/spend_limits`와 `/v1/messages`에서의 개발자별 지출 한도 적용을 활성화합니다. 한도를 설정하고 적용하는 방법은 [지출 한도](https://code.claude.com/docs/ko/claude-apps-gateway-spend-limits.md)를 참조하십시오. 이 섹션에서는 이 기능을 켜고 조정하는 `gateway.yaml` 키를 다룹니다.
693 696
694```yaml theme={null}697```yaml theme={null}
695admin:698admin:
707 blocked_message: request an increase at https://go.example.com/claude-limits710 blocked_message: request an increase at https://go.example.com/claude-limits
708```711```
709 712
710| 필드 | 필수 | 설명 |713| 필드 | 필수 여부 | 설명 |
711| - | - | - |714| - | - | - |
712| `write_keys` | 아니요 | `{id, key}`의 배열입니다. 이 중 하나와 일치하는 `x-api-key`는 지출 한도를 나열, 설정, 삭제할 수 있습니다. 키 값은 최소 32자여야 하며, `id`는 `read_keys`와 `write_keys` 전체에서 고유해야 합니다. |715| `write_keys` | 아니요 | `{id, key}`의 배열입니다. 이 중 하나와 일치하는 `x-api-key`는 지출 한도를 조회, 설정, 삭제할 수 있습니다. 키 값은 32자 이상이어야 하며, `id`는 `read_keys`와 `write_keys` 전체에서 고유해야 합니다. |
713| `read_keys` | 아니요 | `{id, key}`의 배열입니다. 읽기 전용으로, 한도 나열, ID로 한도 하나 가져오기, [`/effective`](https://code.claude.com/docs/ko/claude-apps-gateway-spend-limits#%2Feffective) 및 [`/audit`](https://code.claude.com/docs/ko/claude-apps-gateway-spend-limits#%2Faudit) 읽기를 포함한 모든 `GET` 엔드포인트에 접근할 수 있습니다. |716| `read_keys` | 아니요 | `{id, key}`의 배열입니다. 읽기 전용이며, 한도 목록 조회, ID로 단일 한도 가져오기, [`/effective`](https://code.claude.com/docs/ko/claude-apps-gateway-spend-limits#%2Feffective) 및 [`/audit`](https://code.claude.com/docs/ko/claude-apps-gateway-spend-limits#%2Faudit) 읽기를 포함한 모든 `GET` 엔드포인트에 접근할 수 있습니다. |
714| `admin_groups` | 아니요 | IdP 그룹 이름입니다. `groups` 클레임에 이 중 하나가 포함된 게이트웨이 JWT는 읽기와 쓰기를 포함한 전체 관리자 접근 권한을 가지며, `oidc:<sub>`로 감사 기록됩니다. 사람 관리자에게는 이 방식을, 머신에는 API 키를 사용하십시오. 이 목록에 빈 항목이 있으면 게이트웨이가 부팅 시 중지됩니다. [부팅 시 게이트웨이를 중지시키는 matcher 값](#matcher-values-that-stop-the-gateway-at-boot)을 참조하십시오. |717| `admin_groups` | 아니요 | IdP 그룹 이름입니다. `groups` 클레임에 이 중 하나가 포함된 게이트웨이 JWT는 읽기와 쓰기를 포함한 전체 관리자 액세스 권한을 가지며, 감사 로그에 `oidc:<sub>`로 기록됩니다. 사람 관리자에게는 이 방식을, 머신에는 API 키를 사용하십시오. 이 목록에 빈 항목이 있으면 게이트웨이가 부팅 시 중지됩니다. [부팅 시 게이트웨이를 중지시키는 matcher 값](#matcher-values-that-stop-the-gateway-at-boot)을 참조하십시오. |
715| `blocked_message` | 아니요 | 차단된 개발자가 보는 `429 billing_error`에 그대로 덧붙여집니다. URL이나 Slack 채널 등 전체 안내 문구를 작성하십시오. 설정하지 않으면 게이트웨이는 기본 메시지만 보냅니다. [적용 방식](https://code.claude.com/docs/ko/claude-apps-gateway-spend-limits.md#how-enforcement-works)을 참조하십시오. |718| `blocked_message` | 아니요 | 차단된 개발자가 보는 `429 billing_error`에 그대로 덧붙여집니다. URL이나 Slack 채널 등 전체 안내 문구를 작성하십시오. 설정하지 않으면 게이트웨이는 기본 메시지만 보냅니다. [적용 방식](https://code.claude.com/docs/ko/claude-apps-gateway-spend-limits.md#how-enforcement-works)을 참조하십시오. |
716| `audit_retention_days` | 아니요 | 기본값은 `365`입니다. 이보다 오래된 `admin_audit` 행은 정리됩니다. |719| `audit_retention_days` | 아니요 | 기본값은 `365`입니다. 이보다 오래된 `admin_audit` 행은 정리됩니다. |
717| `spend_retention_months` | 아니요 | 기본값은 `13`입니다. 이보다 오래된 `spend` 카운터 행은 정리됩니다. 기본값은 전년 대비 보고를 위해 1년 전체와 진행 중인 현재 월을 보관합니다. |720| `spend_retention_months` | 아니요 | 기본값은 `13`입니다. 이보다 오래된 `spend` 카운터 행은 정리됩니다. 기본값은 전년 대비 보고를 위해 1년 전체와 진행 중인 현재 월을 보관합니다. |
718| `identity_retention_days` | 아니요 | 기본값은 `90`입니다. 각 개발자의 이메일, 표시 이름, 그룹(PII)을 담는 `principal_emails` 행의 마지막 확인 시점 기준 TTL입니다. 프로비저닝이 해제된 ID는 만료되고 익명 지출 카운터는 남도록 의도적으로 지출 보존 기간보다 짧게 설정되어 있습니다. |721| `identity_retention_days` | 아니요 | 기본값은 `90`입니다. 각 개발자의 이메일, 표시 이름, 그룹(PII)을 보관하는 `principal_emails` 행의 마지막 확인 기준 TTL입니다. 프로비저닝 해제된 ID는 만료되고 익명 지출 카운터는 남도록 지출 보관 기간보다 의도적으로 짧게 설정되어 있습니다. |
719| `group_limit_mode` | 아니요 | `min`(기본값) 또는 `max`입니다. 개발자가 한도가 설정된 여러 그룹에 속한 경우 `min`은 가장 제한적인 한도를, `max`는 가장 덜 제한적인 한도를 적용합니다. 적용과 `/effective` 모두에서 사용됩니다. |722| `group_limit_mode` | 아니요 | `min`(기본값) 또는 `max`입니다. 개발자가 한도가 설정된 여러 그룹에 속할 때 `min`은 가장 제한적인 한도를, `max`는 가장 느슨한 한도를 적용합니다. 적용 로직과 `/effective` 모두에서 사용됩니다. |
720 723
721### `enforcement`724### `enforcement`
722 725
723`enforcement` 블록은 저장소를 사용할 수 없을 때 지출 한도 검사가 어떻게 동작할지 제어합니다.726`enforcement` 블록은 저장소를 사용할 수 없을 때 지출 한도 검사가 어떻게 동작하는지 제어합니다.
724 727
725| 필드 | 필수 | 설명 |728| 필드 | 필수 여부 | 설명 |
726| - | - | - |729| - | - | - |
727| `fail_closed_on_error` | 아니요 | 기본값은 `false`입니다. Postgres 장애 시 지출 적용은 fail-open으로 동작하므로 추론은 계속 가능합니다. fail-closed로 동작하게 하려면 `true`로 설정하십시오. 이 경우 한도를 초과한 개발자가 차단되지만, 저장소에 연결할 수 없으면 다른 모든 사용자도 차단됩니다. [`admin:`](#admin) 블록이 필요합니다. 지출 적용은 `admin`이 구성된 경우에만 실행되며, `admin` 블록 없이 이 값을 `true`로 설정하면 게이트웨이가 시작을 거부합니다. |730| `fail_closed_on_error` | 아니요 | 기본값은 `false`입니다. Postgres 장애 시 지출 한도 적용은 fail-open으로 동작하므로 추론이 계속 가능합니다. fail-closed로 동작하게 하려면 `true`로 설정하십시오. 이 경우 한도를 초과한 개발자가 차단되지만, 저장소에 연결할 수 없으면 다른 모든 사용자도 차단됩니다. [`admin:`](#admin) 블록이 필요합니다. 지출 한도 적용은 `admin`이 구성된 경우에만 실행되며, `admin` 블록 없이 이 값을 `true`로 설정하면 게이트웨이가 시작되지 않습니다. |
728 731
729### `pricing`732### `pricing`
730 733
731`pricing` 블록은 지출 미터가 USD 정가 대신 어떤 요금을 부과할지 지정하므로, 한도와 [`/effective`](https://code.claude.com/docs/ko/claude-apps-gateway-spend-limits#%2Feffective)가 계약 요금을 반영합니다. 금액은 USD로 유지되며 청구서가 아닌 추정치입니다. 사전 요구 사항은 두 가지입니다.734`pricing` 블록은 지출 미터가 USD 정가 대신 어떤 요금을 적용할지 지정하므로, 한도와 [`/effective`](https://code.claude.com/docs/ko/claude-apps-gateway-spend-limits#%2Feffective)에 계약 요금이 반영됩니다. 금액은 USD로 유지되며 청구서가 아닌 추정치입니다. 사전 요구 사항은 두 가지입니다.
732 735
733* 게이트웨이 서버에 Claude Code v2.1.227 이상이 필요합니다. 이전 버전은 부팅 시 알 수 없는 키를 거부합니다.736* 게이트웨이 서버에 Claude Code v2.1.227 이상이 필요합니다. 이전 버전은 부팅 시 알 수 없는 키를 거부합니다.
734* [`admin:`](#admin) 블록 또는 v2.1.268 이상에서는 하나 이상의 정책이 있는 [`managed:`](#managed) 블록이 필요합니다. `pricing`이 설정되어 있는데 두 블록이 모두 없으면, 이를 읽을 대상이 없으므로 게이트웨이가 시작을 거부합니다.737* [`admin:`](#admin) 블록, 또는 v2.1.268 이상에서는 정책이 하나 이상 있는 [`managed:`](#managed) 블록이 필요합니다. `pricing`이 설정되어 있는데 두 블록이 모두 없으면 이를 읽는 곳이 없으므로 게이트웨이가 시작되지 않습니다.
735 738
736```yaml theme={null}739```yaml theme={null}
737pricing:740pricing:
745 cache_write: 4.125748 cache_write: 4.125
746```749```
747 750
748| 필드 | 필수 | 설명 |751| 필드 | 필수 여부 | 설명 |
749| - | - | - |752| - | - | - |
750| `multiplier` | 아니요 | 기본값은 `1`입니다. 미터는 정가든 재정의된 요금이든 측정된 모든 금액에 이 값을 곱하므로, `0.85`는 가격의 85%를 청구합니다. 0보다 크고 10 이하여야 하며, 1보다 큰 값은 [마크업](#mark-prices-up)입니다. |753| `multiplier` | 아니요 | 기본값은 `1`입니다. 미터는 정가 기반이든 재정의된 요금이든 모든 측정 금액에 이 값을 곱하므로, `0.85`는 가격의 85%를 청구합니다. 0보다 크고 10 이하여야 하며, 1보다 큰 값은 [할증](#mark-prices-up)입니다. |
751| `overrides` | 아니요 | 백만 토큰당 USD 단위의 `{upstream, model, input, output, cache_read, cache_write}` 행입니다. 네 가지 요금이 모두 필요합니다. 각 요금은 0보다 크고 10000 이하여야 합니다. |754| `overrides` | 아니요 | 백만 토큰당 USD 단위의 `{upstream, model, input, output, cache_read, cache_write}` 행입니다. 네 가지 요금이 모두 필요하며, 각 값은 0보다 크고 10000 이하여야 합니다. |
752 755
753미터가 재정의 행을 매칭하는 방식:756미터가 재정의 행을 매칭하는 방식은 다음과 같습니다.
754 757
755* 하나의 행은 [`upstreams[].name`](#upstreams)인 `upstream`이 `model`에 대해 처리하는 요청의 정가를 대체합니다. 여기에는 더 높은 [빠른 모드](https://code.claude.com/docs/ko/fast-mode.md#understand-the-cost-tradeoff) 요금도 포함되므로, 빠른 요청과 표준 요청은 동일한 네 가지 요금으로 측정됩니다.758* 행은 [`upstreams[].name`](#upstreams)인 `upstream`이 `model`에 대해 처리하는 요청의 정가를 대체합니다. 여기에는 더 높은 [빠른 모드](https://code.claude.com/docs/ko/fast-mode.md#understand-the-cost-tradeoff) 요금도 포함되므로, 빠른 요청과 일반 요청이 동일한 네 가지 요금으로 측정됩니다.
756* `claude-sonnet-4-6` 같은 기본 제공 ID는 [`models[].id`](#models)와 같은 방식으로 매칭되며, 미터가 해당 모델로 가격을 매기는 모든 날짜 포함 형식, 리전별 Amazon Bedrock 형식, Google Cloud의 Agent Platform 형식을 포괄합니다. 별칭이나 추론 프로필 ARN 같은 그 밖의 문자열은 클라이언트가 보낸 ID 또는 업스트림으로 보낸 문자열과 대소문자를 구분하지 않고 매칭됩니다.759* `claude-sonnet-4-6` 같은 기본 제공 ID는 [`models[].id`](#models)와 같은 방식으로 매칭되며, 미터가 해당 모델로 가격을 책정하는 모든 날짜 표기 형식, 리전별 Amazon Bedrock 형식, Google Cloud Agent Platform 형식을 포괄합니다. 별칭이나 추론 프로필 ARN 같은 그 밖의 문자열은 클라이언트가 보낸 ID 또는 업스트림으로 보낸 문자열과 대소문자 구분 없이 매칭됩니다.
757* 행이 겹치는 경우 미터는 첫 번째 행이 아니라 가장 구체적인 행을 선택합니다. 우선 `model`이 업스트림으로 보낸 정확한 모델 문자열인 행, 그다음 클라이언트가 보낸 정확한 ID와 일치하는 행, 그다음 기본 제공 모델을 지정하는 행 순입니다.760* 행이 겹치는 경우 미터는 첫 번째 행이 아니라 가장 구체적인 행을 선택합니다. 즉 `model`이 업스트림으로 보낸 모델 문자열과 정확히 일치하는 행, 그다음 클라이언트가 보낸 ID와 정확히 일치하는 행, 그다음 기본 제공 모델을 지정한 행 순입니다.
758* 알 수 없는 업스트림 이름은 부팅에 실패하며, 하나의 업스트림에 대해 같은 모델을 지정하는 두 행(하나의 기본 제공 모델을 두 가지 표기로 지정하는 경우 포함)도 마찬가지입니다. 요청 가능한 모델이 사용할 수 없는 행에 대해서는 게이트웨이가 부팅 시 경고합니다.761* 알 수 없는 업스트림 이름은 부팅 실패를 일으키며, 하나의 업스트림에 동일한 모델을 지정한 두 행(하나의 기본 제공 모델을 두 가지 표기로 지정한 경우 포함)도 마찬가지입니다. 요청 가능한 모델이 사용할 수 없는 행에 대해서는 게이트웨이가 부팅 시 경고합니다.
759* 웹 검색 요청은 \$0.01 정가로 유지되지만, 배수는 여전히 적용됩니다.762* 웹 검색 요청은 \$0.01 정가를 유지하며, multiplier는 여전히 적용됩니다.
760 763
761리전별 요금을 적용하려면 각 리전에 고유한 이름의 업스트림을 지정하고 업스트림마다 행 하나를 두십시오.764리전별 요금을 적용하려면 각 리전에 고유한 이름의 업스트림을 지정하고 업스트림마다 행을 하나씩 두십시오.
762 765
763#### 가격 인상766#### 가격 할증
764 767
765게이트웨이 서버에 v2.1.271 이상이 있으면 `multiplier`를 1보다 크게(최대 10까지) 설정하여 내부 차지백 요금처럼 공급자가 청구하는 금액보다 더 많이 측정할 수 있습니다. 이 예시는 모든 요청을 가격의 120%로 측정합니다.768게이트웨이 서버에 v2.1.271 이상이 있으면 `multiplier`를 1보다 크게(최대 10) 설정하여 내부 차지백 요금처럼 공급자가 청구하는 금액보다 많이 측정할 수 있습니다. 다음 예시는 모든 요청을 가격의 120%로 측정합니다.
766 769
767```yaml theme={null}770```yaml theme={null}
768pricing:771pricing:
769 multiplier: 1.2772 multiplier: 1.2
770```773```
771 774
772[`admin:`](#admin) 블록이 있으면 마크업은 지출 한도에도 적용됩니다. 미터가 가격의 120%를 집계하므로 개발자는 한도에 더 빨리 도달합니다. 게이트웨이는 부팅 시 이 사실을 알리는 경고를 로그에 기록합니다.775[`admin:`](#admin) 블록이 있으면 할증이 지출 한도에도 적용됩니다. 미터가 가격의 120%를 계산하므로 개발자가 한도에 더 빨리 도달합니다. 게이트웨이는 부팅 시 이를 알리는 경고를 로그에 기록합니다.
773 776
774배수는 업스트림 공급자가 해당 요청에 대해 청구하는 금액을 변경하지 않습니다.777multiplier는 업스트림 공급자가 요청에 대해 청구하는 금액을 변경하지 않습니다.
775 778
776게이트웨이가 [로그인한 클라이언트에 요금도 전송](#send-the-rates-to-signed-in-clients)하는 경우, 개발자가 마크업을 보려면 Claude Code v2.1.271 이상이 필요합니다. 이전 클라이언트는 1보다 큰 `multiplier`를 무시하고 마크업 없이 비용을 표시합니다.779게이트웨이가 [로그인한 클라이언트에 요금도 전송](#send-the-rates-to-signed-in-clients)하는 경우, 개발자가 할증을 확인하려면 Claude Code v2.1.271 이상이 필요합니다. 이전 클라이언트는 1보다 큰 `multiplier`를 무시하고 할증 없이 비용을 표시합니다.
777 780
778v2.1.271 이전 게이트웨이 서버는 `multiplier`를 1보다 크게 설정하면 시작을 거부합니다.781v2.1.271 이전 게이트웨이 서버는 `multiplier`를 1보다 크게 설정하면 시작되지 않습니다.
779 782
780#### 로그인한 클라이언트에 요금 전송783#### 로그인한 클라이언트에 요금 전송
781 784
782게이트웨이 서버에 v2.1.268 이상이 있으면 게이트웨이는 `pricing`의 요금을 자신이 제공하는 [`managed`](#managed) 정책에 [`modelPricing`](https://code.claude.com/docs/ko/settings-reference#modelpricing) 관리형 설정으로도 넣습니다. 그러면 정책에 매칭된 개발자는 `/usage`, 상태줄, OpenTelemetry에서 각 모델 ID를 처리하는 첫 번째 업스트림의 `pricing` 요금을 보게 됩니다. 어떤 정책에도 매칭되지 않는 개발자는 관리형 설정을 받지 않으므로 수치가 정가로 유지됩니다. 클라이언트는 Claude Code v2.1.242 이상에서 이 설정을 적용합니다.785게이트웨이 서버에 v2.1.268 이상이 있으면 게이트웨이는 `pricing`의 요금을 자신이 제공하는 [`managed`](#managed) 정책에 [`modelPricing`](https://code.claude.com/docs/ko/settings-reference#modelpricing) 관리형 설정으로도 넣습니다. 그러면 정책과 매칭되는 개발자는 `/usage`, 상태줄, OpenTelemetry에서 각 모델 ID를 처리하는 첫 번째 업스트림의 `pricing` 요금을 보게 됩니다. 어떤 정책과도 매칭되지 않는 개발자는 관리형 설정을 받지 않으므로 수치가 정가로 유지됩니다. 클라이언트는 Claude Code v2.1.242 이상에서 이 설정을 적용합니다.
783 786
784* 게이트웨이가 추가하는 항목: 정책의 `cli` 블록에 이미 `modelPricing`이 설정되어 있지 않으면, 게이트웨이는 `multiplier`와 함께 클라이언트가 요청할 수 있는 모든 모델 ID에 대해 해당 ID를 처리하는 첫 번째 업스트림의 재정의 행을 추가합니다. 장애 조치 업스트림만 청구하는 요금은 게이트웨이에 남습니다.787* 게이트웨이가 추가하는 항목: 정책의 `cli` 블록에 이미 `modelPricing`이 설정되어 있지 않으면, 게이트웨이는 `multiplier`와, 클라이언트가 요청할 수 있는 모든 모델 ID에 대해 해당 ID를 처리하는 첫 번째 업스트림의 재정의 행을 추가합니다. 장애 조치 업스트림만 청구하는 요금은 게이트웨이에만 남습니다.
785* 특정 정책 제외: 해당 정책의 `cli` 블록에서 `modelPricing`을 `{}`로 설정하면 그 정책의 개발자는 정가로 유지됩니다.788* 특정 정책 제외: 해당 정책의 `cli` 블록에서 `modelPricing`을 `{}`로 설정하면 그 정책의 개발자는 정가로 유지됩니다.
786* 정책 자체 요금 유지: `cli` 블록에서 자체 `multiplier` 또는 `overrides`로 `modelPricing`을 설정한 정책은 해당 `modelPricing`을 그대로 유지하며, 게이트웨이는 여기에 자체 요금을 추가하지 않습니다.789* 정책 자체 요금 유지: `cli` 블록에서 자체 `multiplier` 또는 `overrides`로 `modelPricing`을 설정한 정책은 해당 `modelPricing`을 그대로 유지하며, 게이트웨이는 자체 요금을 추가하지 않습니다.
787 790
788### `models`791### `models`
789 792
790`models` 블록은 관리자가 큐레이션하는 선택적 모델 목록으로, `/v1/models`에서 제공되며 업스트림별로 모델 ID를 변환하는 데 사용됩니다. 미국 외 Amazon Bedrock 리전, Amazon Bedrock 프로비저닝된 처리량 ARN, Microsoft Foundry 배포 이름에는 필수입니다.793`models` 블록은 관리자가 선별하는 선택적 모델 목록으로, `/v1/models`에서 제공되며 업스트림별로 모델 ID를 변환하는 데 사용됩니다. 미국 외 Amazon Bedrock 리전, Amazon Bedrock 프로비저닝된 처리량 ARN, Microsoft Foundry 배포 이름에는 필수입니다.
791 794
792```yaml theme={null}795```yaml theme={null}
793auto_include_builtin_models: true # false: expose only the list below796auto_include_builtin_models: true # false: expose only the list below
801 foundry: your-opus-deployment-name804 foundry: your-opus-deployment-name
802```805```
803 806
804`upstream_model` 아래의 각 키는 구성된 업스트림의 `name`과 일치해야 하며, 이 값의 기본값은 공급자 이름입니다. 어떤 업스트림과도 일치하지 않는 키는 부팅에 실패하므로, 사용하지 않는 공급자의 줄은 생략하십시오.807`upstream_model` 아래의 각 키는 구성된 업스트림의 `name`과 일치해야 하며, 기본값은 공급자 이름입니다. 어떤 업스트림과도 일치하지 않는 키는 부팅 실패를 일으키므로, 사용하지 않는 공급자의 줄은 생략하십시오.
805 808
806### `managed`809### `managed`
807 810
808`managed` 블록은 IdP 그룹 또는 이메일 도메인을 키로 하는 역할 기반 접근 정책을 정의합니다. 정책은 순서대로 평가되며, 첫 번째로 매칭된 정책이 선택된 다음 `match: {}` 캐치올 기반 위에 병합됩니다. 정책은 ETag/304 캐싱과 함께 `GET /managed/settings`에서 사용자별로 제공됩니다.811`managed` 블록은 IdP 그룹 또는 이메일 도메인을 기준으로 하는 역할 기반 액세스 정책을 정의합니다. 정책은 순서대로 평가되며, 첫 번째로 매칭되는 정책이 선택된 후 `match: {}` 캐치올 기본 정책 위에 병합됩니다. 정책은 `GET /managed/settings`에서 사용자별로 ETag/304 캐싱과 함께 제공됩니다.
809 812
810```yaml theme={null}813```yaml theme={null}
811managed:814managed:
824 enforceAvailableModels: true827 enforceAvailableModels: true
825```828```
826 829
827관례상 마지막에 나열하는 `match: {}` 캐치올은 기본 레이어로 취급됩니다. 다른 모든 정책은 자신이 설정하지 않은 키를 캐치올에서 상속하므로, 역할별 항목에는 조직 기본값과 다른 부분만 나열하면 됩니다. 병합 규칙은 키 유형에 따라 다릅니다.830관례상 마지막에 나열하는 `match: {}` 캐치올은 기본 계층으로 취급됩니다. 다른 모든 정책은 설정하지 않은 키를 캐치올에서 상속하므로, 역할별 항목에는 조직 기본값과 다른 부분만 나열하면 됩니다. 병합 규칙은 키 유형에 따라 다릅니다.
828 831
829* **허용 목록**: `availableModels` 및 `permissions.allow`. 특정 정책의 목록이 기반의 목록을 완전히 대체합니다.832* **허용 목록**: `availableModels` 및 `permissions.allow`. 특정 정책의 목록이 기본 정책의 목록을 완전히 대체합니다.
830* **거부 목록 및 훅 배열**: `permissions.deny`, `permissions.ask`, `disabledMcpjsonServers`, `deniedMcpServers`, `blockedMarketplaces`, `deniedModels`, 그리고 모든 `hooks` 이벤트 유형 배열. 이들은 기반과 정책의 합집합을 취하므로, 조직 전체의 거부 규칙이나 감사 훅이 역할별 재정의로 인해 실수로 누락되지 않습니다.833* **거부 목록 및 훅 배열**: `permissions.deny`, `permissions.ask`, `disabledMcpjsonServers`, `deniedMcpServers`, `blockedMarketplaces`, `deniedModels`, 그리고 모든 `hooks` 이벤트 유형 배열. 이들은 기본 정책과 정책의 합집합을 취하므로, 조직 전체의 거부 규칙이나 감사 훅이 역할별 재정의로 인해 실수로 누락되지 않습니다.
831* **레코드 유형 키**: `env`, `modelOverrides`, `skillOverrides`. 이들은 얕은 병합을 수행하므로, 역할별 `env` 블록은 자신이 설정한 키를 재정의하고 나머지는 기반에서 상속합니다.834* **레코드 유형 키**: `env`, `modelOverrides`, `skillOverrides`. 이들은 얕은 병합을 수행하므로, 역할별 `env` 블록은 자신이 설정한 키를 재정의하고 나머지는 기본 정책에서 상속합니다.
832 835
833`availableModels`는 `/v1/messages`에서 서버 측으로도 적용되므로, 거부된 모델은 클라이언트가 무엇을 보내든 `400`을 반환합니다. 빈 목록은 모든 모델을 거부합니다. 이 검사는 개발자가 모델을 선택하기 전에 세션이 시작되는 모델에도 적용되므로 [정책이 허용하는 모델로 세션을 시작](#start-sessions-on-a-model-the-policy-allows)하도록 설정하십시오.836`availableModels`는 `/v1/messages`에서 서버 측으로도 적용되므로, 거부된 모델은 클라이언트가 무엇을 보내든 `400`을 반환합니다. 빈 목록은 모든 모델을 거부합니다. 이 검사는 개발자가 모델을 선택하기 전 세션이 시작되는 모델에도 적용되므로, [정책이 허용하는 모델로 세션을 시작](#start-sessions-on-a-model-the-policy-allows)하도록 하십시오.
834 837
835게이트웨이는 요청을 중계하기 전에 `model` 값 자체를 검증하므로, 잘못된 형식의 값은 업스트림에 도달하지 않습니다. 다음 두 경우에 `400`으로 요청을 거부합니다.838게이트웨이는 요청을 중계하기 전에 `model` 값 자체를 검증하므로, 잘못된 형식의 값은 업스트림에 도달하지 않습니다. 다음 두 경우에 요청을 `400`으로 거부합니다.
836 839
837* 값이 없거나 비어 있으면 게이트웨이는 `model is required` 메시지와 함께 요청을 거부합니다. 이 검사에는 Claude Code v2.1.228 이상을 실행하는 게이트웨이가 필요합니다.840* 값이 없거나 비어 있으면 게이트웨이는 `model is required` 메시지와 함께 요청을 거부합니다. 이 검사에는 Claude Code v2.1.228 이상을 실행하는 게이트웨이가 필요합니다.
838* 값이 있지만 문자열이 아니면 게이트웨이는 `model must be a string` 메시지와 함께 요청을 거부합니다. Claude Code v2.1.221 이상을 실행하는 게이트웨이가 필요합니다.841* 값이 있지만 문자열이 아니면 게이트웨이는 `model must be a string` 메시지와 함께 요청을 거부합니다. Claude Code v2.1.221 이상을 실행하는 게이트웨이가 필요합니다.
839 842
840| Matcher | 동작 |843| Matcher | 동작 |
841| - | - |844| - | - |
842| `match: {}` | 인증된 모든 사용자와 매칭됩니다. 이것으로 시작하고 나중에 그 위에 그룹 범위 정책을 추가하십시오. |845| `match: {}` | 인증된 모든 사용자와 매칭됩니다. 먼저 이것으로 시작하고 나중에 그 위에 그룹 범위 정책을 추가하십시오. |
843| `match: { groups: [a, b] }` | JWT의 `groups` 클레임에 나열된 그룹 중 하나라도 포함되면 매칭됩니다. 대소문자를 구분하므로 그룹은 IdP의 정확한 대소문자와 일치해야 합니다. |846| `match: { groups: [a, b] }` | JWT의 `groups` 클레임에 나열된 그룹 중 하나라도 포함되어 있으면 매칭됩니다. 대소문자를 구분하므로 그룹은 IdP의 대소문자 표기와 정확히 일치해야 합니다. |
844| `match: { email_domain: example.com }` | JWT의 `email` 클레임에서 마지막 `@` 뒤 부분과 대소문자를 구분하지 않고 매칭됩니다. 정책당 하나의 도메인을 허용합니다. |847| `match: { email_domain: example.com }` | JWT `email` 클레임에서 마지막 `@` 뒤의 부분과 대소문자 구분 없이 매칭됩니다. 정책당 하나의 도메인만 허용합니다. |
845| `match: { groups: [a], email_domain: example.com }` | 두 조건이 모두 일치해야 합니다 |848| `match: { groups: [a], email_domain: example.com }` | 두 조건이 모두 일치해야 합니다 |
846 849
847어떤 정책에도 매칭되지 않는 인증된 사용자는 게이트웨이의 기본값, 즉 카탈로그의 모든 모델과 관리형 설정 없음을 받습니다. 기본 정책을 보장하려면 마지막에 `match: {}` 캐치올을 추가하십시오.850어떤 정책과도 매칭되지 않는 인증된 사용자는 게이트웨이 기본값을 받으며, 이는 카탈로그의 모든 모델과 관리형 설정 없음을 의미합니다. 기본 정책을 보장하려면 마지막에 `match: {}` 캐치올을 추가하십시오.
848 851
849> [!NOTE]852> [!NOTE]
850>853>
851> 게이트웨이는 자체 사용자 디렉터리를 보관하지 않습니다. 사용자의 IdP 토큰으로 각 요청을 인가하며, 토큰의 `groups` 클레임에서 그룹 멤버십을 읽고 이를 기준으로 정책을 평가합니다. 열거할 명단도, 미리 생성할 계정도 없으므로 SCIM 엔드포인트도 없습니다. SCIM이 동기화할 대상이 없기 때문입니다.854> 게이트웨이는 자체 사용자 디렉터리를 보관하지 않습니다. 사용자의 IdP 토큰으로 각 요청을 승인하며, 토큰의 `groups` 클레임에서 그룹 멤버십을 읽고 이를 기준으로 정책을 평가합니다. 열거할 명단도, 미리 생성할 계정도 없으므로 SCIM이 동기화할 대상이 없어 SCIM 엔드포인트도 없습니다.
852>855>
853> 사용자 및 그룹 수명 주기 관리는 신뢰할 수 있는 원천, 즉 IdP의 기본 SCIM 프로비저닝이나 전용 ID 거버넌스 플랫폼에서 수행하십시오. 그곳에서 관리되는 멤버십과 프로비저닝 해제는 토큰을 통해 게이트웨이에 자동으로 반영됩니다. Claude 계정 자체의 SCIM 프로비저닝이 필요하다면 이는 [Claude for Enterprise](https://code.claude.com/docs/ko/admin-setup.md) 기능입니다.856> 사용자 및 그룹 수명 주기 관리는 신뢰할 수 있는 원본, 즉 IdP의 기본 SCIM 프로비저닝이나 전용 ID 거버넌스 플랫폼에서 수행하십시오. 그곳에서 관리되는 멤버십과 프로비저닝 해제는 토큰을 통해 게이트웨이에 자동으로 반영됩니다. Claude 계정 자체의 SCIM 프로비저닝이 필요하다면 이는 [Claude for Enterprise](https://code.claude.com/docs/ko/admin-setup.md) 기능입니다.
854>857>
855> 두 가지 전파 주기가 적용됩니다.858> 두 가지 반영 주기가 적용됩니다.
856>859>
857> * **정책 내용**: 정책을 편집하고 재배포하면 연결된 Claude Code 클라이언트의 다음 관리형 설정 폴링 시, 즉 1시간 이내에 반영됩니다. 단, [다음 실행 시에만 적용되는 변경 사항](https://code.claude.com/docs/ko/server-managed-settings.md#fetch-and-caching-behavior)은 예외입니다860> * **정책 내용**: 정책을 편집하고 재배포하면 연결된 Claude Code 클라이언트의 다음 관리형 설정 폴링 시(1시간 이내) 반영됩니다. 단, [다음 실행 시에만 적용되는 변경 사항](https://code.claude.com/docs/ko/server-managed-settings.md#fetch-and-caching-behavior)은 예외입니다
858> * **그룹 멤버십**: 사용자의 그룹 멤버십을 변경하면 해당 사용자에게 매칭되는 정책이 달라집니다. 이는 다음 세션 재발급, 즉 다음 자동 갱신 시 적용되며 `session.ttl_hours`로 제한됩니다.861> * **그룹 멤버십**: 사용자의 그룹 멤버십을 변경하면 매칭되는 정책이 바뀝니다. 이는 다음 세션 재발급, 즉 `session.ttl_hours`로 제한되는 다음 자동 갱신 시 적용됩니다.
859>862>
860> Claude Desktop은 [자체 일정](#when-a-policy-change-reaches-claude-desktop)을 따릅니다.863> Claude Desktop은 [자체 일정](#when-a-policy-change-reaches-claude-desktop)을 따릅니다.
861 864
862#### 정책이 허용하는 모델로 세션 시작865#### 정책이 허용하는 모델로 세션 시작
863 866
864`availableModels`에 Claude Code의 기본 모델이 빠져 있으면, 개발자가 `/model` 등으로 목록에 있는 모델을 선택하기 전까지 세션은 `400` 응답을 받습니다. 게이트웨이 세션에서 기본값은 `opus` 별칭이 가리키는 Opus 모델이며, `availableModels`만으로는 이를 변경하지 않습니다.867`availableModels`에 Claude Code의 기본 모델이 빠져 있으면, 개발자가 `/model` 등으로 목록에 있는 모델을 선택할 때까지 세션이 `400` 응답을 받습니다. 게이트웨이 세션에서 기본 모델은 `opus` 별칭이 가리키는 Opus 모델이며, `availableModels`만으로는 이를 바꾸지 않습니다.
865 868
866이를 해결하려면 같은 `cli` 블록에 [`enforceAvailableModels: true`](https://code.claude.com/docs/ko/model-config#enforce-the-allowlist-for-the-default-model)를 설정한 다음, 목록에 어떤 종류의 항목이 있는지 확인하십시오.869이를 해결하려면 같은 `cli` 블록에 [`enforceAvailableModels: true`](https://code.claude.com/docs/ko/model-config#enforce-the-allowlist-for-the-default-model)를 설정한 다음, 목록에 어떤 종류의 항목이 있는지 확인하십시오.
867 870
868* **`sonnet` 같은 별칭 또는 `claude-sonnet-4-6` 같은 기본 제공 ID**: 세션이 해당 모델 중 하나로 시작되며, `/model`의 Default 옵션이 해당 모델로 결정됩니다871* **`sonnet` 같은 별칭 또는 `claude-sonnet-4-6` 같은 기본 제공 ID**: 세션이 그중 하나의 모델로 시작되며, `/model`의 Default 옵션이 해당 모델로 결정됩니다
869* **목록에 별칭이나 기본 제공 ID가 없음**: 세션이 계속 기본 제공 기본값으로 시작될 수 있으므로, 해당 정책의 `cli` 블록에서 [`model`](https://code.claude.com/docs/ko/model-config#control-the-model-users-run-on)도 목록에 있는 ID 중 하나로 설정하십시오872* **목록에 별칭이나 기본 제공 ID가 없는 경우**: 세션이 계속 기본 제공 기본 모델로 시작될 수 있으므로, 해당 정책의 `cli` 블록에서 [`model`](https://code.claude.com/docs/ko/model-config#control-the-model-users-run-on)도 목록의 ID 중 하나로 설정하십시오
870 873
871이 정책은 [`models`](#models)가 정의하는 사용자 지정 ID 하나를 나열하고, 해당 ID로 세션을 시작합니다.874다음 정책은 [`models`](#models)가 정의하는 사용자 지정 ID 하나를 나열하고 해당 ID로 세션을 시작합니다.
872 875
873```yaml theme={null}876```yaml theme={null}
874managed:877managed:
875 policies:878 policies:
876 - match: { groups: [restricted-projects] }879 - match: { groups: [restricted-projects] }
877 cli:880 cli:
878 availableModels: [claude-opus-restricted]881 availableModels: [restricted-claude-opus-4-8]
879 enforceAvailableModels: true882 enforceAvailableModels: true
880 model: claude-opus-restricted883 model: restricted-claude-opus-4-8
884 env:
885 ANTHROPIC_DEFAULT_OPUS_MODEL: restricted-claude-opus-4-8 # opus and Default resolve to the ID too
881```886```
882 887
883#### 부팅 시 게이트웨이를 중지시키는 matcher 값888#### 부팅 시 게이트웨이를 중지시키는 matcher 값
887* 빈 `groups` 목록892* 빈 `groups` 목록
888* `groups` 또는 `admin_groups`의 빈 항목893* `groups` 또는 `admin_groups`의 빈 항목
889* 빈 `email_domain`894* 빈 `email_domain`
890* `@`, 공백 또는 쉼표가 포함된 `email_domain`. 게이트웨이는 이 검사 전에 값을 다듬고 선행 `@` 하나를 제거합니다. `example.com`처럼 도메인 하나만 작성하십시오.895* `@`, 공백 또는 쉼표가 포함된 `email_domain`. 게이트웨이는 이 검사 전에 값의 앞뒤 공백을 제거하고 맨 앞의 `@` 하나를 제거합니다. `example.com`처럼 도메인 하나만 작성하십시오.
891 896
892v2.1.232 이전에는 게이트웨이가 이러한 값이 있어도 시작되었습니다. 각 값의 영향은 다음과 같았습니다.897v2.1.232 이전에는 게이트웨이가 이러한 값으로도 시작되었습니다. 각 값의 영향은 다음과 같았습니다.
893 898
894* 빈 `email_domain`: 게이트웨이가 도메인 검사를 건너뛰었으므로, `email_domain`이 비어 있고 `groups` 목록이 없는 정책은 인증된 모든 사용자와 매칭되었습니다899* 빈 `email_domain`: 게이트웨이가 도메인 검사를 건너뛰었으므로, 빈 `email_domain`이 있고 `groups` 목록이 없는 정책은 인증된 모든 사용자와 매칭되었습니다
895* 빈 `groups` 목록: 정책이 아무와도 매칭되지 않았습니다900* 빈 `groups` 목록: 정책이 아무와도 매칭되지 않았습니다
896* `@`, 공백 또는 쉼표가 포함된 `email_domain`: 정책이 아무와도 매칭되지 않았습니다901* `@`, 공백 또는 쉼표가 포함된 `email_domain`: 정책이 아무와도 매칭되지 않았습니다
897* `groups` 또는 `admin_groups`의 빈 항목: 해당 사용자의 IdP `groups` 클레임에도 빈 항목이 있는 경우에만 사용자와 매칭되었습니다. `admin_groups`에서는 이 매칭으로 관리자 접근 권한이 부여되었습니다. `admin_groups` 목록에 빈 항목이 한 번도 없었다면 이런 방식으로 관리자 접근 권한을 얻은 사람은 없습니다.902* `groups` 또는 `admin_groups`의 빈 항목: 해당 사용자의 IdP `groups` 클레임에도 빈 항목이 있는 경우에만 사용자와 매칭되었습니다. `admin_groups`에서는 이 매칭이 관리자 액세스 권한을 부여했습니다. `admin_groups` 목록에 빈 항목이 한 번도 없었다면 이런 방식으로 관리자 액세스 권한을 얻은 사람은 없습니다.
898 903
899#### `cli` 또는 `code` 선택904#### `cli` 또는 `code` 선택
900 905
902>907>
903> 정책이 `code` 키를 사용할 때 다음 각 항목은 게이트웨이 시작을 막습니다.908> 정책이 `code` 키를 사용할 때 다음 각 항목은 게이트웨이 시작을 막습니다.
904>909>
905> * **게이트웨이 버전**: `code`에는 게이트웨이 서버에 Claude Code v2.1.296 이상이 필요합니다. 이전 게이트웨이는 이 키를 발견하면 시작을 거부합니다. 키를 추가하기 전에 모든 레플리카를 업그레이드하고, 이전 버전으로 롤백하기 전에 `code`를 다시 `cli`로 변경하십시오.910> * **게이트웨이 버전**: `code`에는 게이트웨이 서버에 Claude Code v2.1.296 이상이 필요합니다. 이전 게이트웨이는 이 키를 발견하면 시작되지 않습니다. 키를 추가하기 전에 모든 레플리카를 업그레이드하고, 이전 버전으로 롤백하기 전에는 `code`를 다시 `cli`로 변경하십시오.
906> * **혼합 키**: `code`와 `cli`(또는 이전 표기인 `settings`)를 모두 포함하는 파일은 부팅 시 게이트웨이를 중지시킵니다. 한 번의 편집으로 모든 블록을 하나의 키 아래에 두십시오.911> * **혼합된 키**: `code`와 `cli`(또는 그 이전 표기인 `settings`)가 모두 있는 파일은 부팅 시 게이트웨이를 중지시킵니다. 한 번의 편집으로 모든 블록을 하나의 키 아래에 두십시오.
907 912
908`.env` 파일 읽기를 거부하는 규칙 같은 정책의 Claude Code 설정은 `cli` 또는 `code` 키 아래의 블록에 들어갑니다. `code`가 권장 키이며 `cli`는 레거시 키입니다. 두 키의 내용은 동일합니다. 키는 설정이 적용되는 위치를 결정합니다.913`.env` 파일 읽기를 거부하는 규칙 같은 정책의 Claude Code 설정은 `cli` 또는 `code` 키 아래의 블록에 들어갑니다. `code`가 권장 키이고 `cli`는 레거시 키입니다. 두 키는 동일한 내용을 받습니다. 키는 설정이 적용되는 위치를 결정합니다.
909 914
910* **`cli`**: 터미널, VS Code 및 JetBrains 확장 프로그램, Agent SDK. `cli`에서는 Claude Desktop의 Code 탭이 [파생 설정](#claude-desktop-overlay)을 받으므로, `Read(./.env)` 같은 범위 지정 규칙은 그곳에서 사용자를 막지 않습니다.915* **`cli`**: 터미널, VS Code 및 JetBrains 확장 프로그램, Agent SDK. `cli` 아래에서는 Claude Desktop의 Code 탭이 [파생 설정](#claude-desktop-overlay)을 받으므로, `Read(./.env)` 같은 범위 지정 규칙은 그곳에서 사용자를 막지 않습니다.
911* **`code`**: 동일한 위치에 더해 Claude Desktop의 Code 탭도 적용 대상에 포함될 수 있습니다.916* **`code`**: 동일한 위치에 더해 Claude Desktop의 Code 탭까지 적용할 수 있습니다.
912 917
913`cli`를 사용하는 파일은 기존과 같이 작동하며, [`desktop`](#claude-desktop-overlay) 키가 있는 정책에서 `cli`를 발견한 게이트웨이는 부팅 시 경고하지만 그대로 시작합니다. 설정이 Code 탭에도 적용되도록 하려면 `code`로 전환하십시오.918`cli`를 사용하는 파일은 기존대로 동작하며, [`desktop`](#claude-desktop-overlay) 키가 있는 정책에서 `cli`를 발견한 게이트웨이는 부팅 시 경고하되 그대로 시작됩니다. 설정이 Code 탭에도 적용되도록 하려면 `code`로 전환하십시오.
914 919
915전환하기 전에 [Code 탭에 `code` 설정 적용](#apply-code-settings-in-the-code-tab)을 읽으십시오. 그곳에 설정이 적용되려면 정책에 `desktop` 키가 있어야 하고 사용자 머신에 사전 설정이 필요하며, Claude Desktop에서는 웹 검색이 꺼집니다.920전환하기 전에 [Code 탭에 `code` 설정 적용](#apply-code-settings-in-the-code-tab)을 읽어 보십시오. 설정이 그곳에 적용되려면 정책에 `desktop` 키가 필요하고 사용자 머신에 설정 작업이 필요하며, Claude Desktop에서 웹 검색이 꺼집니다.
916 921
917이 정책은 거부 규칙을 `code` 아래에 두고 빈 `desktop` 키를 포함합니다.922다음 정책은 거부 규칙을 `code` 아래에 두고 빈 `desktop` 키를 함께 둡니다.
918 923
919```yaml theme={null}924```yaml theme={null}
920managed:925managed:
925 desktop: {}930 desktop: {}
926```931```
927 932
928전환할 때는 블록 이름을 바꾸는 같은 편집에서 `serve_to_desktop` 줄을 모두 삭제하십시오. 안내에서 `cli` 블록을 언급하는 경우 `code` 블록을 사용하십시오.933전환할 때는 블록 이름을 바꾸는 동일한 편집에서 `serve_to_desktop` 줄을 모두 삭제하십시오. 안내에서 `cli` 블록을 언급하는 곳에서는 `code` 블록을 사용하십시오.
929 934
930`serve_to_desktop: true`는 정책의 `cli` 설정을 Code 탭에 제공하는 레거시 방식입니다. Claude Desktop이 [`bootstrapUrl`](#claude-desktop-overlay)을 통해 연결하는 경우에는 효과가 없습니다. 정책이 `cli`를 사용하는 동안 이 키를 언급하는 부팅 경고가 나타나면 해당 설정이 Code 탭에 도달하지 않고 있다는 뜻입니다.935`serve_to_desktop: true`는 정책의 `cli` 설정을 Code 탭에 제공하는 레거시 방식입니다. Claude Desktop이 [`bootstrapUrl`](#claude-desktop-overlay)을 통해 연결하는 경우에는 효과가 없습니다. 정책이 `cli`를 사용하는 동안 이 키를 언급하는 부팅 경고가 나타나면 해당 설정이 Code 탭에 도달하지 않고 있다는 의미입니다.
931 936
932* **Code 탭에 적용하려면**: 사용자 머신이 [Code 탭에 `code` 설정 적용](#apply-code-settings-in-the-code-tab)의 조건을 충족하면 `code`로 전환하십시오937* **Code 탭에 적용하려면**: 사용자 머신이 [Code 탭에 `code` 설정 적용](#apply-code-settings-in-the-code-tab)의 조건을 충족하면 `code`로 전환하십시오
933* **`cli`를 유지하려면**: 경고를 표시하지 않도록 정책에서 `cli` 옆에 `serve_to_desktop: false`를 설정하십시오938* **`cli`를 유지하려면**: 경고를 없애기 위해 정책에서 `cli` 옆에 `serve_to_desktop: false`를 설정하십시오
934 939
935#### `cli`에 들어가는 항목940#### `cli`에 들어가는 내용
936 941
937각 `code` 또는 `cli` 값은 완전한 Claude Code `managed-settings.json` 문서로, MDM이나 `/etc/claude-code/managed-settings.json`을 통해 배포하는 것과 동일한 스키마를 여기서는 YAML로 표현한 것입니다. CLI는 전달된 문서를 사용자 및 프로젝트 설정보다 상위인 관리형 계층에서 서버 관리형 설정 대신 적용합니다. 따라서 `policyHelper` 및 `wslInheritsWindowsSettings`처럼 [OS 수준 정책 소스로 제한된](https://code.claude.com/docs/ko/server-managed-settings.md#current-limitations) 설정은 무시합니다.942각 `code` 또는 `cli` 값은 완전한 Claude Code `managed-settings.json` 문서로, MDM이나 `/etc/claude-code/managed-settings.json`을 통해 배포하는 것과 동일한 스키마를 여기서는 YAML로 표현한 것입니다. CLI는 전달된 문서를 사용자 및 프로젝트 설정보다 상위인 관리형 계층에서, 서버 관리형 설정 대신 적용합니다. 따라서 `policyHelper` 및 `wslInheritsWindowsSettings`처럼 [OS 수준 정책 소스로 제한된](https://code.claude.com/docs/ko/server-managed-settings.md#current-limitations) 설정은 무시합니다.
938 943
939게이트웨이는 부팅 시 각 문서를 CLI의 설정 스키마에 대해 검증하므로, 인식할 수 없는 최상위 키는 문제가 되는 모든 키를 명시하는 오류와 함께 부팅에 실패합니다. 스키마에서 의도적으로 열어 둔 부분은 여전히 임의의 값을 허용하는데, 이는 최신 클라이언트가 게이트웨이 스키마에 없는 항목을 인식할 수 있기 때문입니다. 이러한 열린 키에는 `env`, `pluginConfigs`, 그리고 `permissions` 아래에 중첩된 키가 포함됩니다.944게이트웨이는 부팅 시 CLI의 설정 스키마로 각 문서를 검증하므로, 인식되지 않는 최상위 키가 있으면 문제가 되는 모든 키를 명시하는 오류와 함께 부팅이 실패합니다. 스키마에서 의도적으로 열려 있는 부분은 여전히 임의의 값을 허용하는데, 이는 최신 클라이언트가 게이트웨이 스키마에 없는 항목을 인식할 수 있기 때문입니다. 이러한 열린 키에는 `env`, `pluginConfigs`, `permissions` 아래에 중첩된 키가 포함됩니다.
940 945
941검증에는 게이트웨이에 설치된 버전에 번들된 스키마가 사용되므로, 최신 Claude Code 릴리스에서 도입된 최상위 설정 키를 관리형 구성에 넣으려면 먼저 게이트웨이를 업그레이드해야 합니다. 새 정책을 배포하기 전에 클라이언트 하나에서 스모크 테스트하십시오.946검증에는 게이트웨이에 설치된 버전에 번들된 스키마가 사용되므로, 최신 Claude Code 릴리스에서 도입된 최상위 설정 키를 관리형 구성에 넣으려면 먼저 게이트웨이를 업그레이드해야 합니다. 새 정책을 배포하기 전에 클라이언트 하나에서 스모크 테스트하십시오.
942 947
943전체 키 레퍼런스는 [Claude Code 설정](https://code.claude.com/docs/ko/settings-reference.md#all-settings)에 있습니다. 운영자가 가장 먼저 찾는 키는 다음과 같습니다.948전체 키 참조는 [Claude Code 설정](https://code.claude.com/docs/ko/settings-reference.md#all-settings)에 있습니다. 운영자가 가장 먼저 사용하는 키는 다음과 같습니다.
944 949
945```yaml theme={null}950```yaml theme={null}
946managed:951managed:
978| 키 | 적용 주체 | 효과 |983| 키 | 적용 주체 | 효과 |
979| - | - | - |984| - | - | - |
980| `availableModels` | 게이트웨이 + CLI | 모델 허용 목록입니다. `/v1/messages`에서도 검사되므로 패치된 클라이언트가 우회할 수 없습니다. |985| `availableModels` | 게이트웨이 + CLI | 모델 허용 목록입니다. `/v1/messages`에서도 검사되므로 패치된 클라이언트가 우회할 수 없습니다. |
981| [`deniedModels`](https://code.claude.com/docs/ko/settings-reference#deniedmodels), [`availableModelsMatch`](https://code.claude.com/docs/ko/settings-reference#availablemodelsmatch) | 게이트웨이 + CLI | `availableModels`가 달리 허용할 [특정 모델 또는 버전을 차단](https://code.claude.com/docs/ko/model-config.md#block-specific-models-or-versions)합니다. 차단된 모델은 `/v1/messages`에서 `400`으로 거부되고 `/v1/models`에서 제외됩니다. 게이트웨이 자체 검사에는 게이트웨이 서버에 Claude Code v2.1.299 이상이 필요합니다. CLI 검사에는 클라이언트에 v2.1.283 이상이 필요하며, 이전 클라이언트는 두 키를 모두 무시합니다. |986| [`deniedModels`](https://code.claude.com/docs/ko/settings-reference#deniedmodels), [`availableModelsMatch`](https://code.claude.com/docs/ko/settings-reference#availablemodelsmatch) | 게이트웨이 + CLI | `availableModels`가 허용할 [특정 모델 또는 버전을 차단](https://code.claude.com/docs/ko/model-config.md#block-specific-models-or-versions)합니다. 차단된 모델은 `/v1/messages`에서 `400`으로 거부되며 `/v1/models`에서 제외됩니다. 게이트웨이 자체 검사에는 게이트웨이 서버에 Claude Code v2.1.299 이상이 필요합니다. CLI 검사에는 클라이언트에 v2.1.283 이상이 필요하며, 이전 클라이언트는 두 키를 모두 무시합니다. |
982| `permissions.allow` / `.deny` | CLI | 도구 및 명령 규칙입니다. [권한](https://code.claude.com/docs/ko/permissions.md) 및 [Bash 규칙이 매칭하지 않는 항목](https://code.claude.com/docs/ko/permissions.md#bash-rule-limits)을 참조하십시오. |987| `permissions.allow` / `.deny` | CLI | 도구 및 명령 규칙입니다. [권한](https://code.claude.com/docs/ko/permissions.md) 및 [Bash 규칙이 매칭하지 않는 항목](https://code.claude.com/docs/ko/permissions.md#bash-rule-limits)을 참조하십시오. |
983| `permissions.disableBypassPermissionsMode` | CLI | 권한 프롬프트를 건너뛰는 모드인 [`bypassPermissions`](https://code.claude.com/docs/ko/permission-modes#skip-all-checks-with-bypasspermissions-mode)와 `--dangerously-skip-permissions` 플래그를 차단하려면 `disable`로 설정합니다 |988| `permissions.disableBypassPermissionsMode` | CLI | 권한 프롬프트를 건너뛰는 모드인 [`bypassPermissions`](https://code.claude.com/docs/ko/permission-modes#skip-all-checks-with-bypasspermissions-mode)와 `--dangerously-skip-permissions` 플래그를 차단하려면 `disable`로 설정합니다 |
984| `allowManagedPermissionRulesOnly` | CLI | `true`이면 관리형 설정이 권한 규칙의 유일한 설정 소스가 됩니다. [`allowManagedPermissionRulesOnly`](https://code.claude.com/docs/ko/settings-reference#allowmanagedpermissionrulesonly) 항목에 이때 Claude Code가 무시하는 모든 소스가 나열되어 있습니다. |989| `allowManagedPermissionRulesOnly` | CLI | `true`이면 관리형 설정이 권한 규칙의 유일한 설정 소스가 됩니다. [`allowManagedPermissionRulesOnly`](https://code.claude.com/docs/ko/settings-reference#allowmanagedpermissionrulesonly) 항목에 Claude Code가 이때 무시하는 모든 소스가 나열되어 있습니다. |
985| `env` | CLI | CLI 프로세스에 병합되는 환경 변수입니다. 텔레메트리, 자동 업데이트, 모델 이름 재정의에 사용합니다. |990| `env` | CLI | CLI 프로세스에 병합되는 환경 변수입니다. 텔레메트리, 자동 업데이트, 모델 이름 재정의에 사용합니다. |
986| `hooks` | CLI | 조직 전체 [훅](https://code.claude.com/docs/ko/hooks.md) |991| `hooks` | CLI | 조직 전체 [훅](https://code.claude.com/docs/ko/hooks.md) |
987| `managedMcpServers` | CLI | 개발자가 직접 추가하는 서버와 함께 [매칭되는 모든 개발자에게 제공되는](https://code.claude.com/docs/ko/managed-mcp.md#provide-servers-through-managed-settings) 원격 MCP 서버로, `http`와 `sse`만 지원합니다. [정책의 MCP 서버](#mcp-servers-in-a-policy)를 참조하십시오. 게이트웨이 서버와 클라이언트 모두에 Claude Code v2.1.259 이상이 필요합니다. 이전 클라이언트는 이 키를 무시합니다. |992| `managedMcpServers` | CLI | 개발자가 직접 추가한 서버와 함께 [매칭되는 모든 개발자에게 제공](https://code.claude.com/docs/ko/managed-mcp.md#provide-servers-through-managed-settings)되는 원격 MCP 서버로, `http`와 `sse`만 해당합니다. [정책의 MCP 서버](#mcp-servers-in-a-policy)를 참조하십시오. 게이트웨이 서버와 클라이언트 모두에 Claude Code v2.1.259 이상이 필요합니다. 이전 클라이언트는 이 키를 무시합니다. |
988 993
989이러한 설정은 네트워크를 통해 전달되므로, CLI는 아래 나열된 설정을 적용하기 전에 각 개발자에게 보안 승인 대화 상자를 표시합니다.994이러한 설정은 네트워크를 통해 전달되므로, CLI는 아래 나열된 설정을 적용하기 전에 각 개발자에게 보안 승인 대화상자를 표시합니다.
990 995
991* `hooks`996* `hooks`
992* 프록시 및 기본 URL 변수처럼 개발자의 승인이 필요한 `env` 변수997* 프록시 및 기본 URL 변수처럼 개발자의 승인이 필요한 `env` 변수
993* `apiKeyHelper` 및 `statusLine` 같은 셸 실행 설정998* `apiKeyHelper` 및 `statusLine` 같은 셸 실행 설정
994* 샌드박스 바이너리 설정 `sandbox.bwrapPath`, `sandbox.socatPath`, `sandbox.ripgrep`999* 샌드박스 바이너리 설정 `sandbox.bwrapPath`, `sandbox.socatPath`, `sandbox.ripgrep`
995* `sandbox.network.tlsTerminate` 및 프록시 포트 설정처럼 트래픽을 가로채거나, 자격 증명을 주입하거나, 격리를 약화시키는 샌드박스 설정. [보안 승인 대화 상자](https://code.claude.com/docs/ko/server-managed-settings.md#security-approval-dialogs)에 모두 나열되어 있습니다.1000* `sandbox.network.tlsTerminate` 및 프록시 포트 설정처럼 트래픽을 가로채거나, 자격 증명을 주입하거나, 격리를 약화시키는 샌드박스 설정. [보안 승인 대화상자](https://code.claude.com/docs/ko/server-managed-settings.md#security-approval-dialogs)에 모두 나열되어 있습니다.
996 1001
997승인이 얼마나 유지되고 대화 상자가 언제 다시 나타나는지는 [승인 기억](https://code.claude.com/docs/ko/server-managed-settings.md#approval-memory)에서 다룹니다.1002[승인 기억](https://code.claude.com/docs/ko/server-managed-settings.md#approval-memory)에서 승인이 유지되는 기간과 대화상자가 다시 나타나는 시점을 다룹니다.
998 1003
999Claude Code는 모델 선택 설정이나 숫자 제한처럼 일부 전달된 `env` 변수를 개발자에게 승인 대화 상자를 표시하지 않고 적용합니다. 다른 전달된 변수는 개발자의 승인이 필요할 수 있으며, 비어 있지 않은 프록시, 기본 URL 또는 `OTEL_EXPORTER_OTLP_ENDPOINT` 값은 항상 승인이 필요합니다. 전달된 변수에 승인이 필요한 경우 대화 상자에 해당 변수가 표시됩니다. 전달된 값에 따라 승인 필요 여부가 결정되는 네 가지 개인정보 보호 토글을 포함한 자세한 내용은 [환경 변수와 승인 대화 상자](https://code.claude.com/docs/ko/server-managed-settings.md#environment-variables-and-the-approval-dialog)에 있습니다.1004Claude Code는 모델 선택 설정 및 숫자 제한처럼 일부 전달된 `env` 변수를 개발자에게 승인 대화상자를 표시하지 않고 적용합니다. 전달된 다른 변수는 개발자의 승인이 필요할 수 있으며, 비어 있지 않은 프록시, 기본 URL 또는 `OTEL_EXPORTER_OTLP_ENDPOINT` 값은 항상 승인이 필요합니다. 전달된 변수에 승인이 필요하면 대화상자에 해당 변수가 표시됩니다. 전달된 값에 따라 승인 필요 여부가 결정되는 네 가지 개인정보 토글을 포함한 세부 사항은 [환경 변수와 승인 대화상자](https://code.claude.com/docs/ko/server-managed-settings.md#environment-variables-and-the-approval-dialog)를 참조하십시오.
1000 1005
1001게이트웨이의 [텔레메트리](#telemetry) 구성은 `OTEL_EXPORTER_OTLP_ENDPOINT`를 푸시하므로, `telemetry.forward_to`를 설정하면 각 대화형 클라이언트에서 대화 상자가 표시됩니다. 이 대화 상자는 손상되었거나 악의적인 게이트웨이로부터 개발자의 머신을 보호하기 위한 것이지, 개발자로부터 조직을 보호하기 위한 것이 아닙니다.1006게이트웨이의 [텔레메트리](#telemetry) 구성은 `OTEL_EXPORTER_OTLP_ENDPOINT`를 푸시하므로, `telemetry.forward_to`를 설정하면 각 대화형 클라이언트에서 대화상자가 표시됩니다. 이 대화상자는 손상되었거나 악의적인 게이트웨이로부터 개발자의 머신을 보호하기 위한 것이지, 개발자로부터 조직을 보호하기 위한 것이 아닙니다.
1002 1007
1003`claude -p`, Agent SDK 세션, Claude Desktop의 Code 탭 세션 같은 [비대화형 실행](https://code.claude.com/docs/ko/server-managed-settings.md#security-approval-dialogs)은 대화 상자를 표시할 수 없습니다. 이 경우 해당 실행에 한해서만 푸시된 설정을 적용하고 승인된 것으로 기록하지 않으므로, 개발자의 다음 대화형 세션에서는 여전히 대화 상자가 표시됩니다.1008`claude -p`, Agent SDK 세션, Claude Desktop의 Code 탭 세션 같은 [비대화형 실행](https://code.claude.com/docs/ko/server-managed-settings.md#security-approval-dialogs)은 대화상자를 표시할 수 없습니다. 이 경우 푸시된 설정을 해당 실행에만 적용하고 승인된 것으로 기록하지 않으므로, 개발자의 다음 대화형 세션에서는 여전히 대화상자가 표시됩니다.
1004 1009
1005개발자가 거절하면 Claude Code는 정책을 적용하는 대신 해당 세션을 종료합니다. 따라서 새 훅이나 대화 상자를 트리거하는 환경 변수를 광범위한 정책에 푸시하면, 매칭되는 모든 개발자가 대화형 세션에서 대화 상자를 보게 됩니다. 실행 중인 대화형 세션은 다음 시간별 폴링 시 이를 표시하며, 그렇지 않으면 개발자의 다음 대화형 시작 시 나타납니다.1010개발자가 거부하면 Claude Code는 정책을 적용하지 않고 해당 세션을 종료합니다. 따라서 광범위한 정책에 새 훅이나 대화상자를 유발하는 env 변수를 푸시하면, 매칭되는 모든 개발자가 대화형 세션에서 대화상자를 보게 됩니다. 실행 중인 대화형 세션에서는 다음 1시간 단위 폴링 시 표시되며, 그렇지 않으면 개발자의 다음 대화형 시작 시 나타납니다.
1006 1011
1007`cli` 키는 이전 릴리스에서 `settings`라는 이름이었으며, 게이트웨이는 여전히 이 표기를 별칭으로 허용합니다. 새 배포에는 [`code`](#choose-cli-or-code)를 사용하십시오.1012`cli` 키는 이전 릴리스에서 `settings`라는 이름이었으며, 게이트웨이는 여전히 이 표기를 별칭으로 허용합니다. 새 배포에서는 [`code`](#choose-cli-or-code)를 사용하십시오.
1008 1013
1009#### 배포 전 정책 테스트1014#### 배포 전 정책 테스트
1010 1015
1011정책 변경을 테스트하려면 일회용 Postgres 데이터베이스를 대상으로 게이트웨이를 시작하십시오. 게이트웨이는 `cli`, `code`, `desktop` 블록의 내용을 검사하기 전에 Postgres에 연결하고 스키마 마이그레이션을 적용합니다. 데이터베이스에 연결할 수 없으면 시작이 `could not connect to Postgres`에서 멈추고 블록 내용에 대해서는 아무것도 보고하지 않습니다.1016정책 변경을 테스트하려면 임시 Postgres 데이터베이스를 대상으로 게이트웨이를 시작하십시오. 게이트웨이는 `cli`, `code`, `desktop` 블록의 내용을 검사하기 전에 Postgres에 연결하고 스키마 마이그레이션을 적용합니다. 데이터베이스에 연결할 수 없으면 시작이 `could not connect to Postgres`에서 멈추고 블록 내용에 대해서는 아무것도 보고하지 않습니다.
1012 1017
1013#### 터미널 세션의 컨텍스트 윈도우1018#### 터미널 세션의 컨텍스트 윈도우
1014 1019
1015`/login`으로 로그인한 터미널 세션은 Opus 4.7 이상, Sonnet 5 이상, Fable 모델에 1M 컨텍스트 윈도우를 사용합니다. 모델 ID에 `[1m]` 접미사가 필요하지 않으며, 세션은 약 967K 토큰에서 압축됩니다. 개발자 머신의 Claude Code v2.1.287 이전에는 모델 ID가 `[1m]`으로 끝나지 않는 한 Claude Code가 Opus 및 Fable 모델을 200K 윈도우로 취급했습니다.1020`/login`으로 로그인한 터미널 세션은 Opus 4.7 이상, Sonnet 5 이상, Fable 모델에 1M 컨텍스트 윈도우를 사용합니다. 모델 ID에 `[1m]` 접미사가 필요 없으며, 세션은 약 967K 토큰에서 압축됩니다. 개발자 머신의 Claude Code v2.1.287 이전에는 모델 ID가 `[1m]`으로 끝나지 않는 한 Claude Code가 Opus 및 Fable 모델을 200K 윈도우로 취급했습니다.
1016 1021
1017터미널 세션이 대신 200K 경계에서 압축되도록 하려면 정책의 `env`에서 [자동 압축 윈도우](https://code.claude.com/docs/ko/model-config.md#set-the-auto-compact-window)를 설정하십시오.1022대신 터미널 세션이 200K 경계에서 압축되도록 하려면 정책의 `env`에서 [자동 압축 윈도우](https://code.claude.com/docs/ko/model-config.md#set-the-auto-compact-window)를 설정하십시오.
1018 1023
1019```yaml theme={null}1024```yaml theme={null}
1020managed:1025managed:
1025 CLAUDE_CODE_AUTO_COMPACT_WINDOW: "200000"1030 CLAUDE_CODE_AUTO_COMPACT_WINDOW: "200000"
1026```1031```
1027 1032
1028Claude Code는 개발자에게 승인 대화 상자를 표시하지 않고 이 변수를 적용합니다. 이 변수는 `[1m]`으로 끝나는 모델 ID를 포함한 모든 모델에 적용됩니다.1033Claude Code는 이 변수를 개발자에게 승인 대화상자를 표시하지 않고 적용합니다. 이 변수는 `[1m]`으로 끝나는 모델 ID를 포함한 모든 모델에 적용됩니다.
1029 1034
1030대신 1M 컨텍스트를 끄려면 같은 `env` 블록에 [`CLAUDE_CODE_DISABLE_1M_CONTEXT: "1"`](https://code.claude.com/docs/ko/model-config#extended-context)을 설정하십시오. 그러면 Claude Code는 모든 모델을 200K 윈도우로 취급합니다. 대화형 세션에서는 이 변수가 적용되기 전에 각 개발자가 [승인 대화 상자](#what-goes-in-cli)에서 이를 승인합니다.1035대신 1M 컨텍스트를 끄려면 같은 `env` 블록에서 [`CLAUDE_CODE_DISABLE_1M_CONTEXT: "1"`](https://code.claude.com/docs/ko/model-config#extended-context)을 설정하십시오. 그러면 Claude Code는 모든 모델을 200K 윈도우로 취급합니다. 대화형 세션에서는 이 변수가 적용되기 전에 각 개발자가 [승인 대화상자](#what-goes-in-cli)에서 승인해야 합니다.
1031 1036
1032#### 1시간 프롬프트 캐시1037#### 1시간 프롬프트 캐시
1033 1038
1034기본값인 5분 대신 1시간 [프롬프트 캐시 TTL](https://code.claude.com/docs/ko/prompt-caching.md#cache-lifetime)을 요청하려면 정책의 기존 [`code`, `cli` 또는 `settings` 블록](#choose-cli-or-code)에 다음 키를 추가하고 게이트웨이를 다시 시작하십시오. 이 키에는 게이트웨이 서버와 클라이언트 모두에 Claude Code v2.1.242 이상이 필요합니다.1039기본 5분 대신 1시간 [프롬프트 캐시 TTL](https://code.claude.com/docs/ko/prompt-caching.md#cache-lifetime)을 요청하려면 정책의 기존 [`code`, `cli` 또는 `settings` 블록](#choose-cli-or-code)에 다음 키를 추가하고 게이트웨이를 다시 시작하십시오. 이 키에는 게이트웨이 서버와 클라이언트 모두에 Claude Code v2.1.242 이상이 필요합니다.
1035 1040
1036`promptCacheTtl`은 메인 대화에 적용됩니다. `subagentPromptCacheTtl`은 선택 사항이며 서브에이전트, 워크플로, 백그라운드 요청에 적용됩니다. 이 예시는 `cli` 키를 사용하는 `match: {}` 정책에 두 키를 모두 추가합니다.1041`promptCacheTtl`은 메인 대화를 다룹니다. `subagentPromptCacheTtl`은 선택 사항이며 서브에이전트, 워크플로, 백그라운드 요청을 다룹니다. 다음 예시는 `cli` 키를 사용하는 `match: {}` 정책에 두 키를 모두 추가합니다.
1037 1042
1038```yaml theme={null}1043```yaml theme={null}
1039managed:1044managed:
1046 1051
1047> [!WARNING]1052> [!WARNING]
1048>1053>
1049> 업스트림이 게이트웨이가 제공하는 모든 모델에 대해 1시간 TTL을 제공하는 경우에만 이 키를 설정하십시오. 업스트림이 TTL을 거부하면 요청이 실패하며, 게이트웨이와 Claude Code 모두 5분 TTL로 재시도하지 않습니다. Amazon Bedrock의 경우 [지원되는 모델, 리전 및 한도](https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html#prompt-caching-models)를 확인하십시오.1054> 업스트림이 게이트웨이가 제공하는 모든 모델에 대해 1시간 TTL을 지원하는 경우에만 이 키를 설정하십시오. 업스트림이 TTL을 거부하면 요청이 실패하며, 게이트웨이와 Claude Code 모두 5분 TTL로 재시도하지 않습니다. Amazon Bedrock의 경우 [지원되는 모델, 리전 및 제한](https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html#prompt-caching-models)을 확인하십시오.
1050 1055
1051`promptCacheTtl`을 확인하려면 정책에 매칭되는 사용자로 게이트웨이에 로그인하고 [캐시 쓰기에 사용된 TTL을 확인](https://code.claude.com/docs/ko/prompt-caching.md#choose-the-ttl-yourself)하십시오. 게이트웨이가 제공하는 각 모델에 대해 확인을 반복하려면 `--model`을 전달하십시오.1056`promptCacheTtl`을 확인하려면 정책과 매칭되는 사용자로 게이트웨이에 로그인하여 [캐시 쓰기에 사용된 TTL을 확인](https://code.claude.com/docs/ko/prompt-caching.md#choose-the-ttl-yourself)하십시오. 게이트웨이가 제공하는 각 모델에 대해 확인을 반복하려면 `--model`을 전달하십시오.
1052 1057
10531시간 캐시 쓰기는 5분 쓰기보다 [비용이 더 듭니다](https://code.claude.com/docs/ko/prompt-caching.md#cache-lifetime). [지출 한도](https://code.claude.com/docs/ko/claude-apps-gateway-spend-limits.md#how-requests-are-priced)가 이 더 높은 요금을 집계하려면 게이트웨이 서버에 v2.1.286 이상이 필요합니다.10581시간 캐시 쓰기는 5분 쓰기보다 [비용이 더 높습니다](https://code.claude.com/docs/ko/prompt-caching.md#cache-lifetime). [지출 한도](https://code.claude.com/docs/ko/claude-apps-gateway-spend-limits.md#how-requests-are-priced)가 이 더 높은 요금을 계산하려면 게이트웨이 서버에 v2.1.286 이상이 필요합니다.
1054 1059
1055#### 정책의 MCP 서버1060#### 정책의 MCP 서버
1056 1061
1057정책에 매칭되는 Claude Code 클라이언트에 MCP 서버를 제공하려면 해당 정책의 `cli` 블록에 [`managedMcpServers`](https://code.claude.com/docs/ko/managed-mcp#provide-servers-through-managed-settings)를 설정하십시오. 게이트웨이 서버와 클라이언트 모두에 Claude Code v2.1.259 이상이 필요합니다.1062정책과 매칭되는 Claude Code 클라이언트에 MCP 서버를 제공하려면 해당 정책의 `cli` 블록에서 [`managedMcpServers`](https://code.claude.com/docs/ko/managed-mcp#provide-servers-through-managed-settings)를 설정하십시오. 게이트웨이 서버와 클라이언트 모두에 Claude Code v2.1.259 이상이 필요합니다.
1058 1063
1059게이트웨이는 부팅 시 [Claude Code가 클라이언트에서 적용하는 것과 동일한 규칙](https://code.claude.com/docs/ko/managed-mcp.md#what-an-entry-can-contain)으로 각 항목을 검사하며, 항목이 검사에 실패하면 시작을 거부하고 해당 항목을 명시합니다.1064게이트웨이는 부팅 시 [Claude Code가 클라이언트에서 적용하는 것과 동일한 규칙](https://code.claude.com/docs/ko/managed-mcp.md#what-an-entry-can-contain)으로 각 항목을 검사하며, 항목이 검사에 실패하면 시작을 거부하고 해당 항목을 명시합니다.
1060 1065
1061`gateway.yaml`에 `${VAR}` 참조를 작성하면, 게이트웨이는 항목 검사를 실행하기 전에 부팅 시 [시크릿 확장](#secret-expansion)을 통해 자신의 환경에서 이를 해석하므로, 매칭되는 모든 클라이언트가 리터럴 값을 받아 읽을 수 있습니다. [제공되는 서버의 헤더 지침](https://code.claude.com/docs/ko/managed-mcp.md#provide-servers-through-managed-settings)은 확장된 값에 적용됩니다.1066`gateway.yaml`에 `${VAR}` 참조를 작성하면, 게이트웨이는 항목 검사를 실행하기 전에 부팅 시 [시크릿 확장](#secret-expansion)을 통해 자신의 환경에서 이를 해석하므로, 매칭되는 모든 클라이언트가 리터럴 값을 받고 읽을 수 있습니다. [제공되는 서버에 대한 헤더 지침](https://code.claude.com/docs/ko/managed-mcp.md#provide-servers-through-managed-settings)은 확장된 값에 적용됩니다.
1062 1067
1063게이트웨이는 `cli` 블록에서 `.mcp.json` 표기인 `mcpServers`를 거부하며, 부팅 오류에서 사용할 키로 `managedMcpServers`를 안내합니다. v2.1.259 이전에는 게이트웨이가 `cli` 블록의 모든 MCP 서버 정의를 거부했습니다.1068게이트웨이는 `cli` 블록에서 `.mcp.json` 표기인 `mcpServers`를 거부하며, 부팅 오류에서 사용할 키로 `managedMcpServers`를 명시합니다. v2.1.259 이전에는 게이트웨이가 `cli` 블록의 모든 MCP 서버 정의를 거부했습니다.
1064 1069
1065#### Claude Desktop 오버레이1070#### Claude Desktop 오버레이
1066 1071
1067조직에서 [Claude Desktop](https://code.claude.com/docs/ko/desktop.md)도 배포하는 경우 동일한 게이트웨이가 두 클라이언트를 모두 제공합니다. Claude Desktop의 [관리형 구성](https://claude.com/docs/third-party/claude-desktop/configuration)에서 `bootstrapUrl`을 `<listen.public_url>/user/bootstrap`으로 지정하십시오. Claude Desktop은 해당 URL에서 OAuth 발급자를 도출하고, 이 게이트웨이를 대상으로 동일한 디바이스 코드 로그인을 실행하며, 응답에서 구성을 가져옵니다.1072조직에서 [Claude Desktop](https://code.claude.com/docs/ko/desktop.md)도 배포하는 경우, 동일한 게이트웨이가 두 클라이언트를 모두 지원합니다. Claude Desktop의 [관리형 구성](https://claude.com/docs/third-party/claude-desktop/configuration)에서 `bootstrapUrl`을 `<listen.public_url>/user/bootstrap`으로 지정하십시오. Claude Desktop은 이 URL에서 OAuth 발급자를 도출하고, 이 게이트웨이를 대상으로 동일한 디바이스 코드 로그인을 실행하며, 응답에서 구성을 가져옵니다.
1068 1073
1069> [!NOTE]1074> [!NOTE]
1070>1075>
1071> 게이트웨이 서버에 Claude Code v2.1.203 이상이 필요하며, 명시적인 옵트인이 필요합니다. 사용자에게 매칭되는 정책에 `desktop` 키가 없으면 `/user/bootstrap`은 404를 반환합니다. 빈 `desktop: {}`로도 정책을 옵트인할 수 있으며, `match: {}` 기본 레이어의 `desktop` 키는 이를 상속하는 모든 정책을 옵트인합니다. 감사 로그는 각 요청을 `desktop_bootstrap.serve` 또는 `desktop_bootstrap.denied`로 기록합니다.1076> 게이트웨이 서버에 Claude Code v2.1.203 이상과 명시적인 옵트인이 필요합니다. 사용자와 매칭되는 정책에 `desktop` 키가 없으면 `/user/bootstrap`은 404를 반환합니다. 빈 `desktop: {}`로 정책을 옵트인할 수 있으며, `match: {}` 기본 계층의 `desktop` 키는 이를 상속하는 모든 정책을 옵트인합니다. 감사 로그는 각 요청을 `desktop_bootstrap.serve` 또는 `desktop_bootstrap.denied`로 기록합니다.
1072 1077
1073Claude Desktop을 배포하지 않는 경우 정책에서 `desktop`을 완전히 제외하십시오. 그러면 게이트웨이는 모든 사용자에 대해 `/user/bootstrap`에서 404를 반환합니다.1078Claude Desktop을 배포하지 않는 경우 정책에서 `desktop`을 완전히 제외하십시오. 그러면 게이트웨이는 모든 사용자에 대해 `/user/bootstrap`에서 404를 반환합니다.
1074 1079
1076 1081
1077게이트웨이는 부트스트랩 응답의 상당 부분을 매칭된 정책의 `cli` 또는 `code` 블록과 최상위 게이트웨이 구성에서 도출합니다.1082게이트웨이는 부트스트랩 응답의 상당 부분을 매칭된 정책의 `cli` 또는 `code` 블록과 최상위 게이트웨이 구성에서 도출합니다.
1078 1083
1079* 모델 목록: `availableModels`에서 도출합니다. 이 목록에서는 정책이 [`deniedModels` 또는 `availableModelsMatch: exact`](#what-goes-in-cli)로 차단한 모델이 제외됩니다. 이 필터에는 게이트웨이 서버에 Claude Code v2.1.299 이상이 필요합니다. 각 모델의 1M 컨텍스트 옵션은 [Claude Desktop의 확장 컨텍스트](#extended-context-in-claude-desktop)에서 다룹니다1084* 모델 목록: `availableModels`에서 도출합니다. 목록에서는 정책이 [`deniedModels` 또는 `availableModelsMatch: exact`](#what-goes-in-cli)로 차단하는 모델이 제외됩니다. 이 필터에는 게이트웨이 서버에 Claude Code v2.1.299 이상이 필요합니다. 각 모델의 1M 컨텍스트 옵션은 [Claude Desktop의 확장 컨텍스트](#extended-context-in-claude-desktop)에서 다룹니다
1080* 비활성화된 도구: 도구 이름만 있는 `permissions.deny` 항목에서 도출합니다. 정책의 `desktop` 블록에 `disabledBuiltinTools`를 설정하면 게이트웨이는 해당 값과 도출된 목록의 합집합을 제공하므로, 이 방법으로 더 많은 도구를 비활성화할 수는 있지만 `permissions.deny`로 비활성화한 도구를 다시 활성화할 수는 없습니다1085* 비활성화된 도구: 도구 이름만 있는 `permissions.deny` 항목에서 도출합니다. 정책의 `desktop` 블록에서 `disabledBuiltinTools`를 설정하면 게이트웨이는 설정한 값과 도출된 목록의 합집합을 제공하므로, 이 방식으로 더 많은 도구를 비활성화할 수는 있지만 `permissions.deny`로 비활성화한 도구를 다시 활성화할 수는 없습니다
1081* 이그레스 허용 목록: `sandbox.network.allowedDomains`에서 도출합니다. 정책의 `desktop` 블록에 `coworkEgressAllowedHosts`를 설정하면 게이트웨이는 도출된 목록 대신 해당 값을 사용합니다. 게이트웨이가 제공하는 허용 목록에 `*`가 포함되어 있고 게이트웨이가 Claude Desktop의 [`allowedWorkspaceFolders`](https://claude.com/docs/third-party/claude-desktop/code#applied-as-managed-policy)도 제공하지 않으면, Claude Desktop은 Code 탭에서 [Bash 샌드박스](https://code.claude.com/docs/ko/sandboxing.md)를 켜지 않습니다1086* 이그레스 허용 목록: `sandbox.network.allowedDomains`에서 도출합니다. 정책의 `desktop` 블록에서 `coworkEgressAllowedHosts`를 설정하면 게이트웨이는 도출된 목록 대신 해당 값을 사용합니다. 게이트웨이가 제공하는 허용 목록에 `*`가 포함되어 있고 게이트웨이가 Claude Desktop의 [`allowedWorkspaceFolders`](https://claude.com/docs/third-party/claude-desktop/code#applied-as-managed-policy)도 함께 제공하지 않으면, Claude Desktop은 Code 탭에서 [Bash 샌드박스](https://code.claude.com/docs/ko/sandboxing.md)를 켜지 않습니다
1082* 게이트웨이 자체를 가리키는 OTLP 엔드포인트와 로그인한 사용자의 ID 속성. 게이트웨이는 해당 엔드포인트에서 받은 내보내기 데이터를 `forward_to` 대상으로 중계합니다. [`telemetry.forward_to`](#telemetry)와 `listen.public_url`을 모두 설정한 경우 엔드포인트와 속성이 포함됩니다.1087* 게이트웨이 자신을 가리키는 OTLP 엔드포인트와 로그인한 사용자의 ID 속성. 게이트웨이는 해당 엔드포인트에서 받은 내보내기 데이터를 `forward_to` 대상으로 중계합니다. [`telemetry.forward_to`](#telemetry)와 `listen.public_url`을 모두 설정하면 엔드포인트와 속성이 포함됩니다.
1083 1088
1084 Claude Desktop은 모든 신호를 하나의 인코딩으로 내보냅니다. 기본은 `http/protobuf`이며, 정책의 `env`에서 `OTEL_EXPORTER_OTLP_PROTOCOL` 또는 신호별 변형 중 하나를 `http/json`으로 설정하면 `http/json`입니다. 게이트웨이 서버의 Claude Code v2.1.261 이전에는 응답이 항상 `http/json`으로 설정되었으므로, protobuf만 허용하는 컬렉터는 Claude Desktop의 내보내기를 거부했습니다1089 Claude Desktop은 모든 신호를 하나의 인코딩으로 내보냅니다. 기본은 `http/protobuf`이며, 정책의 `env`에서 `OTEL_EXPORTER_OTLP_PROTOCOL` 또는 신호별 변형 중 하나를 `http/json`으로 설정하면 `http/json`을 사용합니다. 게이트웨이 서버의 Claude Code v2.1.261 이전에는 응답이 항상 `http/json`을 설정했으므로, protobuf만 받는 수집기는 Claude Desktop의 내보내기를 거부했습니다
1085 1090
1086정책의 `desktop` 블록에서 `disabledBuiltinTools`, `coworkEgressAllowedHosts` 또는 Claude Desktop 자체의 `managedMcpServers` 설정을 지정하려면 게이트웨이 서버에 Claude Code v2.1.232 이상이 필요합니다. Claude Desktop의 `managedMcpServers`는 객체가 아닌 배열 값을 받습니다.1091정책의 `desktop` 블록에서 `disabledBuiltinTools`, `coworkEgressAllowedHosts` 또는 Claude Desktop 자체의 `managedMcpServers` 설정을 지정하려면 게이트웨이 서버에 Claude Code v2.1.232 이상이 필요합니다. Claude Desktop의 `managedMcpServers`는 객체가 아닌 배열 값을 받습니다.
1087 1092
1088게이트웨이는 `hooks`나 `Bash(npm *)` 같은 범위 지정 권한 규칙처럼 Claude Desktop에 대응 항목이 없는 키를 부트스트랩 응답에서 생략합니다.1093게이트웨이는 `hooks` 및 `Bash(npm *)` 같은 범위 지정 권한 규칙처럼 Claude Desktop에 대응하는 항목이 없는 키를 부트스트랩 응답에서 생략합니다.
1089 1094
1090##### Code 탭에 `code` 설정 적용1095##### Code 탭에 `code` 설정 적용
1091 1096
1094* 정책에 `desktop` 키도 있어야 하며, 빈 `desktop: {}`도 해당됩니다1099* 정책에 `desktop` 키도 있어야 하며, 빈 `desktop: {}`도 해당됩니다
1095* Claude Desktop이 버전 2.9939.2 이상이어야 합니다1100* Claude Desktop이 버전 2.9939.2 이상이어야 합니다
1096* 머신의 Claude Code 관리형 설정이 [이 게이트웨이를 지정](#client-side-managed-settings)해야 합니다1101* 머신의 Claude Code 관리형 설정이 [이 게이트웨이를 지정](#client-side-managed-settings)해야 합니다
1097* 해당 머신이 사설 네트워크에서 HTTPS로 게이트웨이에 접근해야 합니다1102* 해당 머신이 사설 네트워크에서 HTTPS로 게이트웨이에 연결되어야 합니다
1098 1103
1099마지막 두 조건은 세션에서 Claude Code를 실행하는 머신에 적용됩니다. 로컬 세션의 경우 사용자 본인의 컴퓨터이고, SSH를 통한 Code 탭 세션의 경우 원격 호스트입니다.1104마지막 두 조건은 세션에서 Claude Code를 실행하는 머신에 적용됩니다. 로컬 세션의 경우 사용자 자신의 컴퓨터이고, SSH를 통한 Code 탭 세션의 경우 원격 호스트입니다.
1100 1105
1101`cli`를 `code`로 이름을 바꾸기 전에 해당 머신에 [클라이언트 측 관리형 설정](#client-side-managed-settings)을 배포하십시오. 처음 두 조건은 충족되지만 마지막 두 조건 중 하나가 충족되지 않으면, 정책에 매칭되는 사용자는 다음 결과 중 하나를 얻습니다.1106`cli`를 `code`로 이름을 바꾸기 전에 해당 머신에 [클라이언트 측 관리형 설정](#client-side-managed-settings)을 배포하십시오. 처음 두 조건이 충족되고 마지막 두 조건 중 하나가 충족되지 않으면, 정책과 매칭되는 사용자는 다음 결과 중 하나를 얻습니다.
1102 1107
1103* **HTTPS 사용, Claude Desktop에 Claude Code v2.1.296 이상이 번들된 경우**: Code 탭이 시작되지 않으며, 사용자의 프롬프트에 대한 응답에 그 이유가 표시됩니다1108* **HTTPS 연결, Claude Desktop이 Claude Code v2.1.296 이상을 번들하는 경우**: Code 탭이 시작되지 않으며, 사용자의 프롬프트에 대한 응답에서 그 이유를 알려 줍니다
1104* **HTTPS 사용, Claude Desktop에 이전 버전이 번들된 경우**: Code 탭이 `code` 설정 없이 시작되며, 세션에서 이를 알리는 내용은 없습니다1109* **HTTPS 연결, Claude Desktop이 이전 버전을 번들하는 경우**: Code 탭이 `code` 설정 없이 시작되며, 세션에서 이를 알리지 않습니다
1105* **일반 HTTP 사용**: Claude Desktop에 번들된 버전과 관계없이 Code 탭이 `code` 설정 없이 시작됩니다1110* **일반 HTTP 연결**: Claude Desktop이 번들하는 버전과 관계없이 Code 탭이 `code` 설정 없이 시작됩니다
1106 1111
1107게이트웨이 앞의 프록시가 `/managed/settings`에 자체 404로 응답하는 경우에도, 네 가지 조건을 모두 충족하는 머신을 포함하여 Code 탭이 `code` 설정 없이 시작됩니다.1112게이트웨이 앞단의 프록시가 `/managed/settings`에 자체 404로 응답하는 경우에도, 네 가지 조건을 모두 충족하는 머신을 포함하여 Code 탭이 `code` 설정 없이 시작됩니다.
1108 1113
1109`desktop` 키가 있는 정책에서 설정이 담긴 `code` 블록은 Cowork, Chat, Code 탭의 WebSearch 도구를 끕니다. MCP 서버에 대해서는 [`managedMcpServers`가 적용되는 위치](https://code.claude.com/docs/ko/managed-mcp#where-managedmcpservers-applies)를 참조하십시오.1114`desktop` 키가 있는 정책에서 설정을 포함하는 `code` 블록은 Cowork, Chat, Code 탭에서 WebSearch 도구를 끕니다. MCP 서버에 대해서는 [`managedMcpServers`가 적용되는 위치](https://code.claude.com/docs/ko/managed-mcp#where-managedmcpservers-applies)를 참조하십시오.
1110 1115
1111##### Claude Desktop 설정 직접 지정1116##### Claude Desktop 설정 직접 지정
1112 1117
1113Claude Desktop 설정을 직접 지정하려면 `cli` 옆에 선택적 `desktop` 블록을 추가하십시오. Claude Desktop의 [관리형 구성 레퍼런스](https://claude.com/docs/third-party/claude-desktop/configuration)에 있는 설정을 평면 키 이름으로 작성하십시오. `bootstrapUrl`처럼 Claude Desktop이 MDM이나 로컬 파일에서만 읽는 키는 제외하십시오. 게이트웨이는 부팅 시 이를 거부합니다.1118Claude Desktop 설정을 직접 지정하려면 `cli`와 함께 선택적 `desktop` 블록을 추가하십시오. Claude Desktop의 [관리형 구성 참조](https://claude.com/docs/third-party/claude-desktop/configuration)에 있는 설정을 평면 키 이름으로 작성하십시오. `bootstrapUrl`처럼 Claude Desktop이 MDM이나 로컬 파일에서만 읽는 키는 제외하십시오. 게이트웨이는 부팅 시 이를 거부합니다.
1114 1119
1115이 예시는 `eng-contractors` 그룹에 대해 `cli` 설정과 함께 세 가지 Claude Desktop 키를 설정합니다.1120다음 예시는 `eng-contractors` 그룹에 대해 `cli` 설정과 함께 세 가지 Claude Desktop 키를 설정합니다.
1116 1121
1117```yaml theme={null}1122```yaml theme={null}
1118managed:1123managed:
1127 banner: { text: "Contractor build: internal use only" }1132 banner: { text: "Contractor build: internal use only" }
1128```1133```
1129 1134
1130모든 키는 선택 사항이며, 생략한 키에는 Claude Desktop이 자체 기본값을 적용합니다.1135모든 키는 선택 사항이며, 생략한 키에는 Claude Desktop 자체 기본값이 적용됩니다.
1131 1136
1132##### 게이트웨이가 부팅 시 거부하는 항목1137##### 게이트웨이가 부팅 시 거부하는 항목
1133 1138
1134게이트웨이는 부팅 시 각 `desktop` 블록을 Claude Desktop 자체가 사용하는 구성 스키마에 대해 검증하므로, 실수가 연결된 모든 데스크톱에 도달하는 대신 게이트웨이 시작 시 해당 키를 명시하는 오류로 드러납니다. 블록에 다음이 포함되면 게이트웨이는 부팅에 실패합니다.1139게이트웨이는 부팅 시 Claude Desktop 자체가 사용하는 구성 스키마로 각 `desktop` 블록을 검증하므로, 실수가 연결된 모든 데스크톱에 도달하는 대신 게이트웨이 시작 시 해당 키를 명시하는 오류로 드러납니다. 블록에 다음이 포함되면 게이트웨이는 부팅에 실패합니다.
1135 1140
1136* 알 수 없는 키1141* 알 수 없는 키
1137* 빈 값이나 중첩 항목 내부의 철자가 틀린 하위 키처럼 Claude Desktop이 거부하거나 조용히 삭제할 값을 가진 인식된 키. v2.1.260 이전에는 게이트웨이가 `managedMcpServers` 또는 `orgPluginSettings` 항목의 중첩 객체 내부에 있는 철자가 틀린 필드를 부팅 실패 대신 조용히 삭제했습니다.1142* 빈 값이나 중첩 항목 안의 철자가 틀린 하위 키처럼 Claude Desktop이 거부하거나 조용히 무시할 값을 가진 인식된 키. v2.1.260 이전에는 게이트웨이가 `managedMcpServers` 또는 `orgPluginSettings` 항목의 중첩 객체 안에 있는 철자가 틀린 필드를 부팅 실패 대신 조용히 무시했습니다.
1138* 게이트웨이가 직접 계산하는 키: 추론 연결, 모델 목록, OTLP 릴레이. 이들은 [`upstreams`](#upstreams), [`models`](#models), [`telemetry`](#telemetry) 섹션의 `forward_to`를 통해 구성하십시오.1143* 게이트웨이가 직접 계산하는 키: 추론 연결, 모델 목록, OTLP 중계. 이는 [`upstreams`](#upstreams), [`models`](#models), [`telemetry`](#telemetry) 섹션의 `forward_to`를 통해 구성하십시오.
1139* 현재 키의 레거시 별칭. 부팅 오류에서 게이트웨이는 작성해야 할 정식 키를 안내합니다.1144* 현재 키의 레거시 별칭. 부팅 오류에서 게이트웨이는 작성해야 할 표준 키를 명시합니다.
1140 1145
1141`transport`가 없는 `managedMcpServers` 항목처럼 deprecated 값이나 항목 형태를 사용하면, 게이트웨이는 시작하되 대체 항목을 안내하는 경고를 로그에 기록합니다.1146`transport`가 없는 `managedMcpServers` 항목처럼 deprecated 값이나 항목 형태를 사용하면, 게이트웨이는 시작되고 대체 항목을 명시하는 경고를 로그에 기록합니다.
1142 1147
1143v2.1.232 이전에는 게이트웨이가 `chatTabEnabled` 및 `disableAutoUpdates` 같은 11개의 기능 게이트 키로 이루어진 고정 목록만 허용하고 그 밖의 모든 키를 부팅 시 거부했습니다. v2.1.227 이전에는 게이트웨이가 부팅 시 `chatTabEnabled`와 `chatAdvancedFileAnalysisEnabled`도 거부했습니다.1148v2.1.232 이전에는 게이트웨이가 `chatTabEnabled` 및 `disableAutoUpdates` 같은 11개의 고정된 기능 게이트 키 목록만 허용하고 다른 모든 키를 부팅 시 거부했습니다. v2.1.227 이전에는 게이트웨이가 `chatTabEnabled`와 `chatAdvancedFileAnalysisEnabled`도 부팅 시 거부했습니다.
1144 1149
1145##### 이후 버전의 게이트웨이 또는 Claude Desktop이 필요한 키1150##### 이후 버전의 게이트웨이 또는 Claude Desktop이 필요한 키
1146 1151
1147게이트웨이는 `cli` 블록과 마찬가지로 `desktop` 블록을 설치된 버전에 번들된 스키마에 대해 검증합니다. 최신 Claude Desktop 릴리스에서 도입된 설정을 전달하려면 먼저 게이트웨이를 업그레이드하십시오. 예를 들어 `userPluginMarketplacesEnabled`와 `userPluginUploadsEnabled`에는 게이트웨이 서버에 Claude Code v2.1.260 이상, 구성원 머신에 Claude Desktop 1.37937.0 이상이 필요합니다.1152게이트웨이는 `cli` 블록과 마찬가지로, 설치된 버전에 번들된 스키마로 `desktop` 블록을 검증합니다. 최신 Claude Desktop 릴리스에서 도입된 설정을 전달하려면 먼저 게이트웨이를 업그레이드하십시오. 예를 들어 `userPluginMarketplacesEnabled`와 `userPluginUploadsEnabled`에는 게이트웨이 서버에 Claude Code v2.1.260 이상, 구성원 머신에 Claude Desktop 1.37937.0 이상이 필요합니다.
1153
1154`blockReadsOutsideWorkingDirectories`, `disableBypassPermissionsMode`, `configRecheckIntervalMinutes`, `sshClientPath`에는 게이트웨이 서버에 Claude Code v2.1.281 이상이 필요합니다. `microsoftAuthBroker`의 `required` 값과 Microsoft 365 `managedMcpServers` 항목의 `continuousAccessEvaluation` 필드도 마찬가지입니다. `required` 값보다 이전의 Claude Desktop 릴리스는 이를 `disabled`로 읽으므로, 모든 구성원의 Claude Desktop이 이를 지원한 후에만 `required`를 설정하십시오. Claude Desktop의 [관리형 구성 참조](https://claude.com/docs/third-party/claude-desktop/configuration)에 각 키를 처음 읽는 릴리스가 나열되어 있습니다.
1148 1155
1149`blockReadsOutsideWorkingDirectories`, `disableBypassPermissionsMode`, `configRecheckIntervalMinutes`, `sshClientPath`에는 게이트웨이 서버에 Claude Code v2.1.281 이상이 필요합니다. `microsoftAuthBroker`의 `required` 값과 Microsoft 365 `managedMcpServers` 항목의 `continuousAccessEvaluation` 필드도 마찬가지입니다. `required` 값보다 이전의 Claude Desktop 릴리스는 이를 `disabled`로 읽으므로, 모든 구성원의 Claude Desktop이 이를 지원한 후에만 `required`를 설정하십시오. Claude Desktop의 [관리형 구성 레퍼런스](https://claude.com/docs/third-party/claude-desktop/configuration)에 각 키를 처음 읽는 릴리스가 나열되어 있습니다.1156> [!NOTE]
1157>
1158> [`sshTransport`](https://claude.com/docs/third-party/claude-desktop/configuration#sshtransport)에는 게이트웨이 서버에 Claude Code v2.1.293 이상이 필요합니다.
1150 1159
1151정책의 `desktop` 블록에 `orgPluginSettings`를 설정하면, 게이트웨이는 Claude Desktop 1.15200.0 이상이 읽는 배열 형식으로 이를 제공합니다. 이전 데스크톱은 배열을 무시하고 플러그인 도구 정책을 적용하지 않으므로, 이에 의존하기 전에 구성원을 1.15200.0 이상으로 업데이트하십시오.1160정책의 `desktop` 블록에서 `orgPluginSettings`를 설정하면, 게이트웨이는 Claude Desktop 1.15200.0 이상이 읽는 배열 형식으로 이를 제공합니다. 이전 데스크톱은 배열을 무시하고 플러그인 도구 정책을 적용하지 않으므로, 이에 의존하기 전에 구성원을 1.15200.0 이상으로 업데이트하십시오.
1152 1161
1153##### 역할 정책이 기반 `desktop` 블록을 상속하는 방식1162##### 역할 정책이 기본 `desktop` 블록을 상속하는 방식
1154 1163
1155게이트웨이는 정책의 `cli` 블록을 기반에서 채우는 것과 같은 방식으로, 정책의 `desktop` 블록이 설정하지 않은 키를 `match: {}` 캐치올의 `desktop` 블록에서 채웁니다. 기반과 역할 정책 모두에 `disabledBuiltinTools` 또는 `builtinToolPolicy`를 설정하면, 게이트웨이는 기반의 제한을 유지합니다.1164게이트웨이는 정책의 `cli` 블록을 기본 정책에서 채우는 것과 같은 방식으로, 정책의 `desktop` 블록이 설정하지 않은 키를 `match: {}` 캐치올의 `desktop` 블록에서 채웁니다. 기본 정책과 역할 정책 모두에서 `disabledBuiltinTools` 또는 `builtinToolPolicy`를 설정하면 게이트웨이는 기본 정책의 제한을 유지합니다.
1156 1165
1157* `disabledBuiltinTools`: 게이트웨이는 기반 목록과 정책 목록의 합집합을 사용합니다1166* `disabledBuiltinTools`: 게이트웨이는 기본 정책의 목록과 정책의 목록의 합집합을 사용합니다
1158* `builtinToolPolicy`: 기반에서 도구를 `allow` 이외의 값으로 설정하면, 역할 정책에서 같은 도구를 `allow`로 설정하더라도 게이트웨이는 해당 값을 유지합니다1167* `builtinToolPolicy`: 기본 정책에서 도구를 `allow` 이외의 값으로 설정하면, 역할 정책에서 같은 도구에 `allow`를 설정하더라도 게이트웨이는 그 값을 유지합니다
1159 1168
1160그 밖의 모든 키는 역할 정책에서 설정하면 게이트웨이가 역할 정책의 값을 사용합니다. 게이트웨이는 배열이나 `banner` 같은 중첩 객체를 통째로 대체하므로, 역할 정책에서 `banner.text`를 설정하면 게이트웨이는 기반의 `banner.backgroundColor`를 삭제합니다.1169다른 모든 키의 경우, 역할 정책에서 설정하면 게이트웨이는 역할 정책의 값을 사용합니다. 게이트웨이는 배열이나 `banner` 같은 중첩 객체를 통째로 대체하므로, 역할 정책에서 `banner.text`를 설정하면 게이트웨이는 기본 정책의 `banner.backgroundColor`를 제거합니다.
1161 1170
1162##### 정책 변경이 Claude Desktop에 도달하는 시점1171##### 정책 변경이 Claude Desktop에 반영되는 시점
1163 1172
1164변경된 정책으로 게이트웨이를 재배포한 후, Claude Desktop은 대부분의 설정을 다음 시작 시에만 적용합니다.1173변경된 정책으로 게이트웨이를 재배포한 후, Claude Desktop은 대부분의 설정을 다음 시작 시에만 적용합니다.
1165 1174
1166* **닫혀 있는 경우**: Claude Desktop은 시작할 때 부트스트랩 응답을 가져오므로, 변경 사항은 다음 시작부터 적용됩니다1175* **닫혀 있는 경우**: Claude Desktop은 시작할 때 부트스트랩 응답을 가져오므로, 변경 사항은 다음 시작부터 적용됩니다
1167* **열려 있는 경우**: Claude Desktop은 기본적으로 10분마다 변경된 응답을 확인하며, 일부 설정은 재시작 없이 적용합니다. [`skillCreationEnabled`](https://claude.com/docs/third-party/claude-desktop/configuration#skillcreationenabled) 같은 나머지 설정의 경우, 사용자는 사이드바에서 **Relaunch Claude Desktop** 카드를 보게 되며 앱을 재시작할 때까지 이전 구성을 유지합니다. 기본적으로 24시간 후 Claude Desktop은 재시작 대화 상자를 표시하고, 2분간 활동이 없으면 자동으로 재시작합니다1176* **열려 있는 경우**: Claude Desktop은 기본적으로 10분마다 응답 변경 여부를 확인하며, 일부 설정은 재시작 없이 적용합니다. [`skillCreationEnabled`](https://claude.com/docs/third-party/claude-desktop/configuration#skillcreationenabled) 같은 나머지 설정의 경우, 사용자는 사이드바에서 **Relaunch Claude Desktop** 카드를 보게 되며 앱을 재시작할 때까지 이전 구성을 유지합니다. 기본적으로 24시간이 지나면 Claude Desktop은 재시작 대화상자를 표시하고 2분간 활동이 없으면 자동으로 재시작합니다
1168 1177
116924시간을 단축하려면 정책의 `desktop` 블록에 [`relaunchEnforcementHours`](https://claude.com/docs/third-party/claude-desktop/configuration#relaunchenforcementhours)를 설정하십시오. 게이트웨이 서버에 Claude Code v2.1.260 이상, 구성원 머신에 Claude Desktop 1.40609.0 이상이 필요합니다. `0`으로 설정하면 Claude Desktop이 변경 사항을 발견하는 즉시 대화 상자가 나타납니다.117824시간을 단축하려면 정책의 `desktop` 블록에서 [`relaunchEnforcementHours`](https://claude.com/docs/third-party/claude-desktop/configuration#relaunchenforcementhours)를 설정하십시오. 게이트웨이 서버에 Claude Code v2.1.260 이상, 구성원 머신에 Claude Desktop 1.40609.0 이상이 필요합니다. `0`으로 설정하면 Claude Desktop이 변경 사항을 발견하는 즉시 대화상자가 나타납니다.
1170 1179
1171#### Claude Desktop의 확장 컨텍스트1180#### Claude Desktop의 확장 컨텍스트
1172 1181
1173게이트웨이에서 [Claude Desktop](#claude-desktop-overlay)을 제공하는 경우, 모델 선택기는 1M 컨텍스트 윈도우로 실행할 수 있는 나열된 각 모델에 대해 1M 컨텍스트 옵션을 제공합니다. 여기에는 Claude Opus 4.6 이상, Claude Sonnet 4.6 이상, Fable 모델이 포함됩니다. 이 옵션은 [확장 컨텍스트](https://code.claude.com/docs/ko/model-config.md#extended-context)에서 설명하는 모델의 `[1m]` 변형입니다. 게이트웨이 서버에 Claude Code v2.1.284 이상이 필요합니다.1182게이트웨이에서 [Claude Desktop](#claude-desktop-overlay)을 제공하는 경우, 모델 선택기는 1M 컨텍스트 윈도우로 실행할 수 있는 각 나열 모델에 대해 1M 컨텍스트 옵션을 제공합니다. 여기에는 Claude Opus 4.6 이상, Claude Sonnet 4.6 이상, Fable 모델이 포함됩니다. 이 옵션은 [확장 컨텍스트](https://code.claude.com/docs/ko/model-config.md#extended-context)에서 설명하는 모델의 `[1m]` 변형입니다. 게이트웨이 서버에 Claude Code v2.1.284 이상이 필요합니다.
1174 1183
1175다음의 경우 [`models`](#models) 항목에는 1M 옵션이 제공되지 않습니다.1184[`models`](#models) 항목은 다음과 같은 경우 1M 옵션을 받지 않습니다.
1176 1185
1177* 항목을 처리할 수 있는 업스트림이 이를 1M을 지원하지 않는 모델에 매핑하는 경우(게이트웨이가 장애 조치 시에만 접근하는 업스트림 포함)1186* 해당 항목을 처리할 수 있는 업스트림이 1M을 지원하지 않는 모델에 매핑하는 경우. 게이트웨이가 장애 조치 시에만 연결하는 업스트림도 포함됩니다
1178* `id`와 `upstream_model` 값 중 어느 것도 Claude 모델을 지정하지 않는 경우(예: 애플리케이션 추론 프로필 ARN으로 라우팅되는 사용자 지정 별칭)1187* `id`와 `upstream_model` 값 중 어느 것도 Claude 모델을 지정하지 않는 경우. 예를 들어 애플리케이션 추론 프로필 ARN으로 라우팅되는 사용자 지정 별칭이 해당됩니다
1179 1188
1180선택기에 표시되는 옵션을 변경하려면 다음 중 하나를 사용하십시오.1189선택기가 제공하는 항목을 변경하려면 다음 중 하나를 사용하십시오.
1181 1190
1182* **사용자를 1M 옵션으로 시작**: 정책의 `desktop` 블록에 `modelPrefer1mContext: true`를 설정하십시오. 아직 모델을 선택하지 않은 사용자는 나열된 첫 번째 모델에 1M 옵션이 있으면 해당 옵션으로 시작합니다. 이미 모델을 선택한 사용자는 선택을 유지합니다.1191* **사용자를 1M 옵션으로 시작**: 정책의 `desktop` 블록에서 `modelPrefer1mContext: true`를 설정하십시오. 아직 모델을 선택하지 않은 사용자는 첫 번째 나열 모델에 1M 옵션이 있을 때 1M 옵션으로 시작합니다. 이미 모델을 선택한 사용자는 선택을 유지합니다.
1183* **수동으로 옵션 제공**: 게이트웨이 서버가 v2.1.284보다 이전 버전을 실행하거나, 항목이 Claude 모델을 지정하지 않는 경우 이 방법을 사용하십시오. `models`에 모델을 두 번 나열하되, 한 번은 일반 ID로, 한 번은 `[1m]`을 덧붙여 나열하고 둘 다 같은 `upstream_model` 맵을 사용하십시오. Claude Desktop은 이 쌍을 1M 옵션이 있는 하나의 모델로 표시합니다. 게이트웨이는 `[1m]` 항목을 검사 없이 제공하므로, 업스트림이 1M으로 제공하는 모델에 대해서만 추가하십시오.1192* **옵션을 수동으로 제공**: 게이트웨이 서버가 v2.1.284보다 오래된 버전을 실행하거나 항목이 Claude 모델을 지정하지 않는 경우 이 방법을 사용하십시오. `models`에 모델을 두 번 나열하되, 한 번은 일반 ID로, 한 번은 `[1m]`을 덧붙여 나열하고 둘 다 동일한 `upstream_model` 맵을 사용하십시오. Claude Desktop은 이 쌍을 1M 옵션이 있는 하나의 모델로 표시합니다. 게이트웨이는 `[1m]` 항목을 검사하지 않고 제공하므로, 업스트림이 1M으로 제공하는 모델에 대해서만 추가하십시오.
1184 1193
1185이 예시는 애플리케이션 추론 프로필로 라우팅되는 사용자 지정 별칭에 대해 수동으로 옵션을 제공하고, 새 사용자를 해당 옵션으로 시작합니다.1194다음 예시는 애플리케이션 추론 프로필로 라우팅되는 사용자 지정 별칭에 대해 옵션을 수동으로 제공하고 새 사용자를 해당 옵션으로 시작합니다.
1186 1195
1187```yaml theme={null}1196```yaml theme={null}
1188models:1197models:
1202 1211
1203##### 1M 옵션 제거1212##### 1M 옵션 제거
1204 1213
1205선택기에서 옵션을 제거하려면 정책의 `cli` 키 아래 `env` 블록에 `CLAUDE_CODE_DISABLE_1M_CONTEXT: "1"`을 설정하십시오. `id`가 `[1m]`으로 끝나는 항목도 나열했다면 게이트웨이가 여전히 이를 제공하므로, 해당 항목도 삭제하십시오.1214선택기에서 옵션을 제거하려면 정책의 `cli` 키 아래 `env` 블록에서 `CLAUDE_CODE_DISABLE_1M_CONTEXT: "1"`을 설정하십시오. `id`가 `[1m]`으로 끝나는 항목도 나열했다면 게이트웨이가 여전히 이를 제공하므로 해당 항목도 삭제하십시오.
1206 1215
1207이 변수는 정책에 매칭되는 개발자의 터미널 세션에도 전달됩니다. 그곳에서 변경되는 내용은 [확장 컨텍스트](https://code.claude.com/docs/ko/model-config.md#extended-context)를 참조하십시오.1216이 변수는 정책과 매칭되는 개발자의 터미널 세션에도 적용됩니다. 그곳에서 무엇이 바뀌는지는 [확장 컨텍스트](https://code.claude.com/docs/ko/model-config.md#extended-context)를 참조하십시오.
1208 1217
1209#### 다른 관리형 소스와의 우선순위1218#### 다른 관리형 소스와의 우선순위
1210 1219
1211디바이스에 MDM으로 전달된 정책이나 로컬 `managed-settings.json`도 있는 경우, 게이트웨이가 전달한 설정이 가장 높은 순위를 가집니다. 관리형 설정 페이지의 [관리형 계층 내 우선순위](https://code.claude.com/docs/ko/managed-settings.md#precedence-within-the-managed-tier)에서 로컬 소스가 적용되는 시점을 설명하며, 샌드박스 잠금 키, `forceRemoteSettingsRefresh`, 변수별 `env` 병합처럼 어떤 소스를 선택했는지와 관계없이 [Claude Code가 모든 관리자 소스에서 읽는 키](https://code.claude.com/docs/ko/managed-settings.md#keys-read-from-every-admin-source)도 안내합니다. MDM 프로필이나 관리형 설정 파일에 구성된 [`policyHelper`](https://code.claude.com/docs/ko/settings-reference#policyhelper)는 게이트웨이가 설정을 전달하지 않을 때만 실행되며, 해당 항목에서 그 출력이 무엇을 대체하는지 설명합니다.1220디바이스에 MDM으로 전달된 정책이나 로컬 `managed-settings.json`도 있는 경우, 게이트웨이가 전달한 설정이 가장 우선합니다. 관리형 설정 페이지의 [관리형 계층 내 우선순위](https://code.claude.com/docs/ko/managed-settings.md#precedence-within-the-managed-tier)에서 로컬 소스가 적용되는 시점을 설명하며, 샌드박스 잠금 키, `forceRemoteSettingsRefresh`, 변수별 `env` 병합처럼 어떤 소스가 선택되든 관계없이 [Claude Code가 모든 관리자 소스에서 읽는 키](https://code.claude.com/docs/ko/managed-settings.md#keys-read-from-every-admin-source)도 나와 있습니다. MDM 프로필이나 관리형 설정 파일에 구성된 [`policyHelper`](https://code.claude.com/docs/ko/settings-reference#policyhelper)는 게이트웨이가 설정을 전달하지 않을 때만 실행되며, 해당 항목에서 그 출력이 무엇을 대체하는지 설명합니다.
1212 1221
1213[Claude Desktop](https://code.claude.com/docs/ko/desktop.md) 같은 임베딩 호스트는 SDK `managedSettings` 옵션을 통해 정책을 제공할 수 있습니다. [임베딩 호스트의 상위 설정](https://code.claude.com/docs/ko/managed-settings.md#parent-settings-from-embedding-hosts)에서 Claude Code가 이를 적용하는 시점을 설명하며, [상위 설정 제한](https://code.claude.com/docs/ko/claude-apps-gateway#restrict-parent-settings)에는 `allowManaged*Only` 잠금 없이도 여전히 적용되는 허용 방향 설정이 나열되어 있습니다.1222[Claude Desktop](https://code.claude.com/docs/ko/desktop.md) 같은 임베딩 호스트는 SDK `managedSettings` 옵션을 통해 정책을 제공할 수 있습니다. [임베딩 호스트의 상위 설정](https://code.claude.com/docs/ko/managed-settings.md#parent-settings-from-embedding-hosts)에서 Claude Code가 이를 적용하는 시점을 설명하며, [상위 설정 제한](https://code.claude.com/docs/ko/claude-apps-gateway#restrict-parent-settings)에서 `allowManaged*Only` 잠금 없이도 여전히 적용되는 허용 방향 설정을 나열합니다.
1214 1223
1215게이트웨이 정책은 비대화형 `claude -p` 실행과 Agent SDK로 생성된 세션을 포함하여 머신의 모든 Claude Code 호출에 적용됩니다. 시작 시 게이트웨이에 연결할 수 없으면, 로그인한 세션은 정책 없이 실행되는 대신 오류와 함께 종료됩니다.1224게이트웨이 정책은 비대화형 `claude -p` 실행과 Agent SDK가 생성한 세션을 포함하여 머신의 모든 Claude Code 호출에 적용됩니다. 시작 시 게이트웨이에 연결할 수 없으면 로그인한 세션은 정책 없이 실행되는 대신 오류와 함께 종료됩니다.
1216 1225
1217### `telemetry`1226### `telemetry`
1218 1227
1219CLI는 메트릭, 로그, 그리고 활성화된 경우 트레이스를 게이트웨이로 보내며, 게이트웨이는 이를 구성된 각 대상으로 그대로 중계합니다. 내보내기에는 HTTP 기반 OpenTelemetry Protocol(OTLP)이 사용됩니다. 릴레이를 건너뛰고 세션이 컬렉터로 직접 내보내도록 하려면 [정책에 컬렉터를 지정](#export-directly-to-your-collector)하십시오. CLI가 내보내는 메트릭과 이벤트는 [사용량 모니터링](https://code.claude.com/docs/ko/monitoring-usage.md)을 참조하십시오.1228CLI는 메트릭, 로그, 그리고 활성화된 경우 트레이스를 게이트웨이로 보내며, 게이트웨이는 이를 구성된 각 대상으로 그대로 중계합니다. 내보내기는 HTTP를 통한 OpenTelemetry Protocol(OTLP)을 사용합니다. 중계를 건너뛰고 세션이 수집기로 직접 내보내도록 하려면 [정책에서 수집기를 지정](#export-directly-to-your-collector)하십시오. CLI가 내보내는 메트릭과 이벤트는 [사용량 모니터링](https://code.claude.com/docs/ko/monitoring-usage.md)을 참조하십시오.
1220 1229
1221`/login`으로 로그인한 세션에서 CLI는 게이트웨이가 발급한 JWT에서 읽은 인증된 사용자의 ID, 즉 `user.id`, `user.email`, `user.groups` 속성을 각 내보내기에 기록합니다. 따라서 개발자 측 구성 없이도 개발자별 비용 및 사용량 귀속이 작동합니다. 개발자가 로그인하기 전에 Claude Code가 기록하는 이벤트에는 [이 ID가 포함되지 않습니다](https://code.claude.com/docs/ko/monitoring-usage.md#standard-attributes). 개발자의 그룹 변경을 어떤 속성이 반영하는지는 [열린 세션 중 그룹 변경](#group-changes-during-an-open-session)을 참조하십시오.1230`/login`으로 로그인한 세션에서 CLI는 게이트웨이가 발급한 JWT에서 읽은 인증된 사용자의 ID, 즉 `user.id`, `user.email`, `user.groups` 속성을 각 내보내기에 기록합니다. 따라서 개발자 측 구성 없이도 개발자별 비용 및 사용량 귀속이 가능합니다. 개발자가 로그인하기 전에 Claude Code가 기록하는 이벤트는 [이 ID를 포함하지 않습니다](https://code.claude.com/docs/ko/monitoring-usage.md#standard-attributes). 개발자 그룹 변경 시 어떤 속성이 이를 따르는지 확인하려면 [열린 세션 중 그룹 변경](#group-changes-during-an-open-session)을 참조하십시오.
1222 1231
1223게이트웨이를 통해 로그인한 [Claude Desktop](#claude-desktop-overlay) 및 Cowork 세션은 `enduser.id`와 함께 `user.email` 및 `user.groups`를 텔레메트리에 기록하므로, `user.email` 또는 `user.groups`에 대한 하나의 쿼리로 터미널, Desktop, Cowork 사용량을 모두 다룰 수 있습니다. `user.groups`는 쉼표로 구분된 IdP 그룹 목록입니다.1232게이트웨이를 통해 로그인한 [Claude Desktop](#claude-desktop-overlay) 및 Cowork 세션은 `enduser.id`와 함께 `user.email`과 `user.groups`를 텔레메트리에 기록하므로, `user.email` 또는 `user.groups`에 대한 하나의 쿼리로 터미널, Desktop, Cowork 사용량을 모두 다룰 수 있습니다. `user.groups`는 쉼표로 구분된 IdP 그룹 목록입니다.
1224 1233
1225Desktop 및 Cowork 텔레메트리에는 ID 공급자가 사용자에게 발급하는 `sub` 클레임인 `enduser.sub`도 포함되며, 이 값은 사용자의 이메일이 변경되어도 동일하게 유지됩니다. 터미널 세션은 같은 값을 `user.id`에 기록하므로, `enduser.sub`를 터미널 `user.id`와 매칭하는 쿼리로 한 사용자의 터미널, Desktop, Cowork 사용량을 함께 다룰 수 있습니다. Desktop 및 Cowork 내보내기에서 `user.id`는 주체가 아닌 익명 식별자입니다.1234Desktop 및 Cowork 텔레메트리에는 ID 공급자가 사용자에 대해 발급하는 `sub` 클레임인 `enduser.sub`도 포함되며, 이는 사용자의 이메일이 변경되어도 동일하게 유지됩니다. 터미널 세션은 같은 값을 `user.id`에 기록하므로, `enduser.sub`를 터미널 `user.id`와 매칭하는 쿼리로 한 사용자의 터미널, Desktop, Cowork 사용량을 함께 다룰 수 있습니다. Desktop 및 Cowork 내보내기에서 `user.id`는 주체(subject)가 아닌 익명 식별자입니다.
1226 1235
1227Claude Code의 모든 OpenTelemetry 데이터와 마찬가지로, 이러한 속성은 조직이 구성한 대상으로만 전송되며 Anthropic으로는 전송되지 않습니다.1236Claude Code의 모든 OpenTelemetry 데이터와 마찬가지로, 이러한 속성은 조직이 구성한 대상으로만 전송되며 Anthropic에는 절대 전송되지 않습니다.
1228 1237
1229사용자의 그룹 목록이 퍼센트 인코딩 후 255자를 초과하거나 그룹 이름에 쉼표 또는 등호가 포함된 경우, 게이트웨이는 목록을 잘라내는 대신 해당 사용자의 Desktop 및 Cowork 텔레메트리에서 `user.groups`를 제외합니다. 해당 사용자의 터미널 세션에는 여전히 전체 목록이 포함됩니다.1238사용자의 그룹 목록이 퍼센트 인코딩 후 255자를 초과하거나 그룹 이름에 쉼표나 등호가 포함된 경우, 게이트웨이는 잘라내지 않고 해당 사용자의 Desktop 및 Cowork 텔레메트리에서 `user.groups`를 제외합니다. 해당 사용자의 터미널 세션은 여전히 전체 목록을 포함합니다.
1230 1239
1231주체가 퍼센트 인코딩 후 255자를 초과하거나, 공백, 출력 가능한 ASCII 범위 밖의 문자, 또는 `,` `;` `=` `\` `"` `%` 중 하나를 포함하는 경우 게이트웨이는 `enduser.sub`를 제외합니다. 해당 사용자의 Desktop 및 Cowork 텔레메트리는 다른 속성을 유지합니다.1240게이트웨이는 주체가 퍼센트 인코딩 후 255자를 초과하거나, 공백, 인쇄 가능한 ASCII 범위를 벗어난 문자, 또는 `,` `;` `=` `\` `"` `%` 중 하나를 포함하는 경우 `enduser.sub`를 제외합니다. 해당 사용자의 Desktop 및 Cowork 텔레메트리는 다른 속성을 유지합니다.
1232 1241
1233Desktop 및 Cowork 텔레메트리의 `user.email`과 `user.groups`에는 게이트웨이 서버에 Claude Code v2.1.265 이상이 필요하며, `user.groups`에는 각 개발자 머신에 Claude Desktop 1.24012 이상이 필요합니다.1242Desktop 및 Cowork 텔레메트리의 `user.email` 및 `user.groups`에는 게이트웨이 서버에 Claude Code v2.1.265 이상이 필요하며, `user.groups`에는 각 개발자 머신에 Claude Desktop 1.24012 이상이 필요합니다.
1234 1243
1235`enduser.sub`에는 게이트웨이 서버에 Claude Code v2.1.274 이상이 필요합니다.1244`enduser.sub`에는 게이트웨이 서버에 Claude Code v2.1.274 이상이 필요합니다.
1236 1245
1254> 각 대상은 `metrics`, `logs`, `traces`를 독립적으로 옵트인하며, 기본값은 메트릭만입니다. 신호마다 민감도가 다릅니다.1263> 각 대상은 `metrics`, `logs`, `traces`를 독립적으로 옵트인하며, 기본값은 메트릭만입니다. 신호마다 민감도가 다릅니다.
1255>1264>
1256> * **메트릭**: 토큰 수, 요청 수, 지연 시간 같은 집계 카운터1265> * **메트릭**: 토큰 수, 요청 수, 지연 시간 같은 집계 카운터
1257> * **로그 및 트레이스**: 전체 Bash 명령, 도구 입력, 파일 경로를 포함할 수 있으며, 개발자 머신에서 Claude Code가 수행하는 모든 작업을 포괄합니다1266> * **로그 및 트레이스**: 전체 Bash 명령, 도구 입력, 파일 경로를 포함할 수 있어 Claude Code가 개발자 머신에서 수행하는 모든 작업을 다룹니다
1258>1267>
1259> 로그와 트레이스는 해당 데이터에 걸맞은 접근 제어와 보존 정책을 갖춘 대상에서만 활성화하십시오.1268> 해당 데이터에 걸맞은 액세스 제어와 보존 정책이 있는 대상에서만 로그와 트레이스를 활성화하십시오.
1260 1269
1261각 `forward_to` URL은 `https://`를 사용해야 하며, 게이트웨이 자체의 루프백 인터페이스에 있는 컬렉터에 대해서만 예외가 있습니다.1270각 `forward_to` URL은 `https://`를 사용해야 하며, 게이트웨이 자체 루프백 인터페이스의 수집기에 대해서만 예외가 있습니다.
1262 1271
1263* `http://localhost:<port>`는 구성 검증을 통과하지만, 게이트웨이 환경에 `CLAUDE_GATEWAY_ALLOW_LOOPBACK=1`을 설정하지 않으면 [SSRF 가드](https://code.claude.com/docs/ko/claude-apps-gateway-deploy.md#threat-model-summary)가 `ECONNREFUSED_SSRF`로 모든 내보내기를 차단합니다1272* `http://localhost:<port>`는 구성 검증을 통과하지만, 게이트웨이 환경에 `CLAUDE_GATEWAY_ALLOW_LOOPBACK=1`을 설정하지 않으면 [SSRF 가드](https://code.claude.com/docs/ko/claude-apps-gateway-deploy.md#threat-model-summary)가 모든 내보내기를 `ECONNREFUSED_SSRF`로 차단합니다
1264* `http://127.0.0.1:<port>` 또는 `http://[::1]:<port>`는 해당 변수가 설정되지 않으면 부팅에 실패합니다1273* `http://127.0.0.1:<port>` 또는 `http://[::1]:<port>`는 해당 변수를 설정하지 않으면 부팅에 실패합니다
1265 1274
1266클러스터 내 컬렉터의 경우 자체 내부 주소에서 HTTPS로 노출하거나, 변수를 설정한 사이드카로 실행하십시오.1275클러스터 내 수집기의 경우 자체 내부 주소에서 HTTPS로 노출하거나, 변수를 설정한 사이드카로 실행하십시오.
1267 1276
1268`HTTPS_PROXY`가 설정되어 있으면 게이트웨이는 해당 프록시를 통해 내보내기를 전송합니다.1277`HTTPS_PROXY`가 설정되어 있으면 게이트웨이는 해당 프록시를 통해 내보내기를 전송합니다.
1269 1278
1270내부 컬렉터에 직접 접근하려면 호스트 이름이나 `.internal.example.com`처럼 선행 점이 있는 도메인으로 `NO_PROXY`에 추가하십시오. 이를 위해서는 게이트웨이 서버에 Claude Code v2.1.277 이상이 필요합니다. 게이트웨이가 프록시 없이 컬렉터에 접근할 수 있는지 확인하십시오. 선행 점이 없는 항목은 그 아래의 이름이 아닌 정확히 해당 이름만 매칭합니다. CIDR 범위는 매칭되지 않습니다.1279내부 수집기에 직접 연결하려면 호스트 이름이나 `.internal.example.com`처럼 앞에 점이 붙은 도메인으로 `NO_PROXY`에 추가하십시오. 이를 위해서는 게이트웨이 서버에 Claude Code v2.1.277 이상이 필요합니다. 게이트웨이가 프록시 없이 수집기에 연결할 수 있는지 확인하십시오. 앞에 점이 없는 항목은 해당 이름과 정확히 일치하는 경우에만 매칭되며 그 하위 이름과는 매칭되지 않습니다. CIDR 범위는 매칭되지 않습니다.
1271 1280
1272[프록시 전용 이그레스](#proxy-only-egress)를 켠 경우에는 `NO_PROXY` 항목이 하나라도 있으면 프록시 전용 이그레스가 꺼지므로, 대신 프록시에서 컬렉터를 허용하십시오.1281[프록시 전용 이그레스](#proxy-only-egress)가 켜져 있으면 `NO_PROXY` 항목이 하나라도 있으면 프록시 전용 이그레스가 꺼지므로, 대신 프록시에서 수집기를 허용하십시오.
1273 1282
1274CLI에서 텔레메트리는 기본적으로 꺼져 있습니다. `telemetry.forward_to`와 `listen.public_url`을 모두 설정하면, 게이트웨이는 `/managed/settings`를 통해 6개의 환경 변수를 푸시하여 연결된 클라이언트에서 이를 켭니다.1283CLI에서 텔레메트리는 기본적으로 꺼져 있습니다. `telemetry.forward_to`와 `listen.public_url`을 모두 설정하면, 게이트웨이는 `/managed/settings`를 통해 여섯 개의 환경 변수를 푸시하여 연결된 클라이언트에서 텔레메트리를 켭니다.
1275 1284
1276* `CLAUDE_CODE_ENABLE_TELEMETRY=1`1285* `CLAUDE_CODE_ENABLE_TELEMETRY=1`
1277* `OTEL_METRICS_EXPORTER`, `OTEL_LOGS_EXPORTER`, `OTEL_TRACES_EXPORTER`: 하나 이상의 `forward_to` 대상이 해당 신호를 활성화하면 각각 `otlp`로, 그렇지 않으면 `none`으로 설정됩니다1286* `OTEL_METRICS_EXPORTER`, `OTEL_LOGS_EXPORTER`, `OTEL_TRACES_EXPORTER`: 각각 하나 이상의 `forward_to` 대상이 해당 신호를 활성화하면 `otlp`로, 그렇지 않으면 `none`으로 설정됩니다
1278* `OTEL_EXPORTER_OTLP_ENDPOINT=<public_url>`1287* `OTEL_EXPORTER_OTLP_ENDPOINT=<public_url>`
1279* `OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf`1288* `OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf`
1280 1289
1281[자체 레이블을 추가](#add-your-own-labels)하면 게이트웨이는 `OTEL_RESOURCE_ATTRIBUTES`도 푸시합니다.1290[자체 레이블을 추가](#add-your-own-labels)하면 게이트웨이는 `OTEL_RESOURCE_ATTRIBUTES`도 푸시합니다.
1282 1291
1283게이트웨이 서버의 Claude Code v2.1.265 이전에는 게이트웨이가 어떤 대상도 옵트인하지 않은 신호를 포함하여 세 가지 익스포터 선택자를 모두 `otlp`로 푸시했습니다.1292게이트웨이 서버의 Claude Code v2.1.265 이전에는 어떤 대상도 옵트인하지 않은 신호를 포함하여 세 가지 내보내기 선택자를 모두 `otlp`로 푸시했습니다.
1284 1293
1285푸시되는 엔드포인트는 공개 URL로 구성되므로, 메트릭과 로그에는 개발자나 정책의 OTEL 구성이 필요하지 않습니다.1294푸시되는 엔드포인트는 공개 URL로 구성되므로, 메트릭과 로그에는 개발자나 정책의 OTEL 구성이 필요하지 않습니다.
1286 1295
1287`/login`으로 로그인한 개발자는 자체 OTEL 구성으로 내보내기를 리디렉션할 수 없습니다.1296`/login`으로 로그인한 개발자는 자신의 OTEL 구성으로 내보내기를 리디렉션할 수 없습니다.
1288 1297
1289* **로컬에서 설정한 변수**: Claude Code는 푸시된 변수를 관리형 계층에서 적용하므로, 각 변수는 개발자가 로컬에서 설정한 값을 재정의합니다.1298* **로컬에서 설정한 변수**: Claude Code는 푸시된 변수를 관리형 계층에서 적용하므로, 각 변수는 개발자가 로컬에서 설정한 값을 재정의합니다.
1290* **로컬에서 구성한 엔드포인트**: OTLP/HTTP 내보내기가 활성화된 경우, 게이트웨이가 텔레메트리 변수를 푸시했는지 여부와 관계없이 CLI는 로컬에서 구성한 엔드포인트를 무시합니다. 정책이 [컬렉터를 엔드포인트로 지정](#export-directly-to-your-collector)하지 않는 한 내보내기는 게이트웨이로 전송됩니다.1299* **로컬에서 구성한 엔드포인트**: OTLP/HTTP 내보내기가 활성화되어 있으면, 게이트웨이가 텔레메트리 변수를 푸시했는지와 관계없이 CLI는 로컬에서 구성한 엔드포인트를 무시합니다. 정책이 [수집기를 엔드포인트로 지정](#export-directly-to-your-collector)하지 않는 한 내보내기는 게이트웨이로 전송됩니다.
1291 1300
1292신호에 대한 `forward_to` 대상이 없으면 게이트웨이는 해당 신호를 받아서 폐기합니다. 개발자가 이미 Claude Code 텔레메트리를 조직의 컬렉터 중 하나로 내보내고 있다면, 해당 컬렉터를 `forward_to` 대상으로 추가하고(로그나 트레이스를 내보내고 있다면 해당 신호도 활성화) 개발자가 로그인한 후에도 데이터를 계속 받도록 하십시오. 대신 릴레이를 건너뛰려면 [정책에 컬렉터를 지정](#export-directly-to-your-collector)하십시오.1301신호에 대한 `forward_to` 대상이 없으면 게이트웨이는 이를 받아서 폐기합니다. 개발자가 이미 Claude Code 텔레메트리를 조직의 수집기 중 하나로 내보내고 있다면, 로그인 후에도 해당 수집기가 데이터를 계속 받도록 `forward_to` 대상으로 추가하고, 개발자가 로그나 트레이스를 내보내는 경우 이를 활성화하십시오. 대신 중계를 건너뛰려면 [정책에서 수집기를 지정](#export-directly-to-your-collector)하십시오.
1293 1302
1294[트레이스](https://code.claude.com/docs/ko/monitoring-usage.md#traces-beta)에는 각 클라이언트에 `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1`도 필요합니다. 게이트웨이는 이를 푸시하지 않으므로 관리형 정책의 `env` 블록에 설정하십시오. 개발자는 푸시된 엔드포인트가 이미 트리거하는 것과 동일한 [보안 승인 대화 상자](#managed)에서 이를 승인합니다.1303[트레이스](https://code.claude.com/docs/ko/monitoring-usage.md#traces-beta)에는 각 클라이언트에 `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1`도 필요합니다. 게이트웨이가 이를 푸시하지 않으므로 관리형 정책의 `env` 블록에서 설정하십시오. 개발자는 푸시된 엔드포인트가 이미 유발하는 동일한 [보안 승인 대화상자](#managed)에서 이를 승인합니다.
1295 1304
1296트레이스를 수집하려는 그룹의 정책에서만 `1`로 설정하십시오. 이를 설정하지 않은 정책은 [병합 규칙](#managed)에 따라, `match: {}` 캐치올 정책이 값을 설정한 경우 해당 값을 상속합니다. 개발자가 로컬에서 변수를 설정하더라도 특정 그룹의 클라이언트가 트레이스를 보내지 않도록 하려면 해당 그룹의 정책에서 `0`으로 설정하십시오.1305트레이스를 수집하려는 그룹의 정책에서만 `1`로 설정하십시오. 이를 설정하지 않은 정책은 [병합 규칙](#managed)에 따라 `match: {}` 캐치올 정책이 값을 설정한 경우 그 값을 상속합니다. 개발자가 로컬에서 변수를 설정하더라도 특정 그룹의 클라이언트가 트레이스를 보내지 않도록 하려면 해당 그룹의 정책에서 `0`으로 설정하십시오.
1297 1306
1298protobuf와 JSON OTLP 인코딩 모두 중계되며, OpenTelemetry 호환 백엔드라면 어떤 것이든 대상으로 사용할 수 있습니다.1307protobuf와 JSON OTLP 인코딩이 모두 중계되며, OpenTelemetry와 호환되는 모든 백엔드를 대상으로 사용할 수 있습니다.
1299 1308
1300#### 누적 메트릭 전송1309#### 누적 메트릭 전송
1301 1310
1302컬렉터가 누적 메트릭만 허용하는 경우 [`OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE`](https://code.claude.com/docs/ko/monitoring-usage#common-configuration-variables)를 `cumulative`로 설정하십시오. Claude Code는 기본적으로 델타 메트릭을 보내며, 게이트웨이는 이를 변환하지 않고 중계합니다. 세션 유형별로 변수를 읽는 위치에 설정하십시오.1311수집기가 누적 메트릭만 받는 경우 [`OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE`](https://code.claude.com/docs/ko/monitoring-usage#common-configuration-variables)를 `cumulative`로 설정하십시오. Claude Code는 기본적으로 델타 메트릭을 보내며, 게이트웨이는 변환 없이 이를 중계합니다. 각 세션 유형이 변수를 읽는 위치에 설정하십시오.
1303 1312
1304* **터미널 세션**: 정책의 [`cli` 또는 `code` 키](#choose-cli-or-code) 아래 `env` 블록1313* **터미널 세션**: 정책의 [`cli` 또는 `code` 키](#choose-cli-or-code) 아래 `env` 블록
1305* **[사용자 머신에서 실행되는](https://code.claude.com/docs/ko/managed-settings.md#where-and-when-a-policy-applies) Cowork 세션**: 해당 머신의 [클라이언트 측 관리형 설정](#client-side-managed-settings)의 `env` 블록1314* **[사용자 머신에서 실행되는](https://code.claude.com/docs/ko/managed-settings.md#where-and-when-a-policy-applies) Cowork 세션**: 해당 머신의 [클라이언트 측 관리형 설정](#client-side-managed-settings)의 `env` 블록
1306* **`code` 정책의 Code 탭 세션**: [`code` 설정이 적용되기 위한 조건](#apply-code-settings-in-the-code-tab)을 충족한 후 정책의 `env` 블록1315* **`code` 정책 아래의 Code 탭 세션**: [`code` 설정이 적용되는 조건](#apply-code-settings-in-the-code-tab)을 충족한 후 정책의 `env` 블록
1307* **`cli` 정책의 Code 탭 세션**: 세션을 실행하는 머신의 클라이언트 측 관리형 설정의 `env` 블록. SSH를 통한 경우 원격 호스트입니다.1316* **`cli` 정책 아래의 Code 탭 세션**: 세션을 실행하는 머신의 클라이언트 측 관리형 설정의 `env` 블록. SSH를 통한 경우에는 원격 호스트입니다.
1308 1317
1309머신의 관리형 설정에 변수를 추가하는 경우, 해당 머신의 최우선 소스에 [`parentSettingsBehavior: "merge"`](https://code.claude.com/docs/ko/claude-apps-gateway#set-the-opt-in)도 설정하십시오. 이 설정이 없으면 Cowork 세션과 `cli` 정책의 Code 탭 세션은 Claude Desktop이 상위 설정으로 전달하는 이그레스 허용 목록 및 기타 정책 없이 실행됩니다.1318머신의 관리형 설정에 변수를 추가하는 경우, 해당 머신에서 우선순위가 가장 높은 소스에 [`parentSettingsBehavior: "merge"`](https://code.claude.com/docs/ko/claude-apps-gateway#set-the-opt-in)도 설정하십시오. 이 설정이 없으면 Cowork 세션과 `cli` 정책 아래의 Code 탭 세션은 Claude Desktop이 상위 설정으로 전달하는 이그레스 허용 목록 및 기타 정책 없이 실행됩니다.
1310 1319
1311#### 자체 레이블 추가1320#### 자체 레이블 추가
1312 1321
1313게이트웨이를 통해 로그인한 세션의 텔레메트리에 `service.namespace`나 `deployment.environment.name` 같은 고정 레이블을 붙이려면 `telemetry.resource_attributes`를 설정하십시오. 각 레이블은 OpenTelemetry 리소스 속성이며, 모든 대상이 동일한 레이블을 받습니다.1322게이트웨이를 통해 로그인한 세션의 텔레메트리에 `service.namespace`나 `deployment.environment.name` 같은 고정 레이블을 붙이려면 `telemetry.resource_attributes`를 설정하십시오. 각 레이블은 OpenTelemetry 리소스 속성이며, 모든 대상이 동일한 레이블을 받습니다.
1314 1323
1315세션은 `telemetry.forward_to`와 `listen.public_url`도 설정한 경우에만 레이블을 받습니다. 이 예시는 두 개의 레이블을 추가합니다.1324세션은 `telemetry.forward_to`와 `listen.public_url`도 함께 설정한 경우에만 레이블을 받습니다. 다음 예시는 두 개의 레이블을 추가합니다.
1316 1325
1317```yaml theme={null}1326```yaml theme={null}
1318telemetry:1327telemetry:
1323 deployment.environment.name: prod1332 deployment.environment.name: prod
1324```1333```
1325 1334
1326레이블이 다음 규칙 중 하나를 위반하면 게이트웨이는 시작을 거부하며, 시작 오류에 해당 레이블이 표시됩니다.1335레이블이 다음 규칙 중 하나를 위반하면 게이트웨이는 시작을 거부하며, 시작 오류에서 해당 레이블을 명시합니다.
1327 1336
1328* 이름에는 문자, 숫자, `.`, `_`, `-`만 사용합니다1337* 이름에는 문자, 숫자, `.`, `_`, `-`만 사용합니다
1329* 이름은 예약되지 않아야 합니다. 대소문자에 관계없이 비교하며, 예약된 이름은 `user.`, `enduser.` 또는 `identity.`로 시작하는 모든 이름과 `service.name`, `service.version`, `claude.deployment_mode`, `host.arch`, `os.type`, `os.version`, `wsl.version`입니다1338* 이름은 예약된 이름이 아니어야 합니다. 대소문자 구분 없이 비교하며, 예약된 이름은 `user.`, `enduser.`, `identity.`로 시작하는 모든 이름과 `service.name`, `service.version`, `claude.deployment_mode`, `host.arch`, `os.type`, `os.version`, `wsl.version`입니다
1330* 값은 비어 있지 않은 출력 가능한 ASCII이며, 공백과 `, ; = \ " %`를 포함하지 않아야 합니다1339* 값은 공백이 없고 `, ; = \ " %` 중 어느 것도 포함하지 않는, 비어 있지 않은 인쇄 가능한 ASCII여야 합니다
1331* 값은 게이트웨이가 퍼센트 인코딩 후 계산하는 기준으로 최대 255자이므로, `/`, `:`, `@`는 각각 3자로 계산됩니다1340* 값은 게이트웨이가 퍼센트 인코딩 후 계산하는 기준으로 최대 255자이므로, `/`, `:`, `@`는 각각 3자로 계산됩니다
1332* 값은 텍스트이므로 숫자, `true`, `false`는 따옴표로 묶으십시오1341* 값은 텍스트이므로 숫자, `true`, `false`는 따옴표로 감싸십시오
1333 1342
1334`telemetry.resource_attributes`를 설정하려면 게이트웨이 서버에 Claude Code v2.1.281 이상이 필요합니다. 이전 게이트웨이는 이 키를 발견하면 시작을 거부합니다. 키를 추가하기 전에 모든 레플리카를 업그레이드하고, 이전 버전으로 롤백하기 전에 키를 제거하십시오.1343`telemetry.resource_attributes`를 설정하려면 게이트웨이 서버에 Claude Code v2.1.281 이상이 필요합니다. 이전 게이트웨이는 이 키를 발견하면 시작되지 않습니다. 키를 추가하기 전에 모든 레플리카를 업그레이드하고, 이전 버전으로 롤백하기 전에는 키를 제거하십시오.
1335 1344
1336`/login`으로 로그인한 터미널 세션은 다른 [텔레메트리 변수](#telemetry)와 함께 푸시된 `OTEL_RESOURCE_ATTRIBUTES`로 레이블을 받습니다. 정책의 `env` 블록에 `OTEL_RESOURCE_ATTRIBUTES`를 설정하면, 해당 정책에 매칭되는 터미널 세션은 레이블 대신 그 값을 받습니다. Claude Desktop은 `user.email` 및 기타 ID 속성과 함께 게이트웨이로부터 레이블을 받습니다.1345`/login`으로 로그인한 터미널 세션은 다른 [텔레메트리 변수](#telemetry)와 함께 푸시되는 `OTEL_RESOURCE_ATTRIBUTES`로 레이블을 받습니다. 정책의 `env` 블록에서 `OTEL_RESOURCE_ATTRIBUTES`를 설정하면, 해당 정책과 매칭되는 터미널 세션은 레이블 대신 그 값을 받습니다. Claude Desktop은 `user.email` 및 기타 ID 속성과 함께 게이트웨이로부터 레이블을 받습니다.
1337 1346
1338Claude Code는 각 레이블을 모든 메트릭 데이터 포인트에도 복사하므로, 리소스 속성을 인덱싱하지 않는 백엔드에서도 레이블로 메트릭을 필터링할 수 있습니다. 이 복사를 끄려면 [메트릭 카디널리티 제어](https://code.claude.com/docs/ko/monitoring-usage.md#metrics-cardinality-control)를 참조하십시오.1347Claude Code는 각 레이블을 모든 메트릭 데이터 포인트에도 복사하므로, 리소스 속성을 인덱싱하지 않는 백엔드에서도 이를 기준으로 메트릭을 필터링할 수 있습니다. 이 복사를 끄려면 [메트릭 카디널리티 제어](https://code.claude.com/docs/ko/monitoring-usage.md#metrics-cardinality-control)를 참조하십시오.
1339 1348
1340#### 열린 세션 중 그룹 변경1349#### 열린 세션 중 그룹 변경
1341 1350
1342터미널 세션은 `user.groups`를 OTLP 리소스에 넣고, 각 메트릭 데이터 포인트와 이벤트에도 다시 넣습니다. 세션이 열려 있는 동안 개발자의 그룹이 변경되면, 다음 [자동 갱신](#session) 이후 사용량에 대한 데이터 포인트와 이벤트에는 새 그룹이 포함됩니다. 리소스는 개발자가 Claude Code를 재시작할 때까지 이전 그룹을 유지하므로, 데이터 포인트나 이벤트의 속성을 기준으로 그룹화하십시오.1351터미널 세션은 `user.groups`를 OTLP 리소스에 넣고, 각 메트릭 데이터 포인트와 이벤트에도 다시 넣습니다. 세션이 열려 있는 동안 개발자의 그룹이 변경되면, 다음 [자동 갱신](#session) 이후 사용량에 대한 데이터 포인트와 이벤트는 새 그룹을 포함합니다. 리소스는 개발자가 Claude Code를 재시작할 때까지 이전 그룹을 유지하므로, 데이터 포인트나 이벤트의 속성을 기준으로 그룹화하십시오.
1343 1352
1344OpenTelemetry Collector의 Prometheus remote write 익스포터에서 `resource_to_telemetry_conversion`을 켜면, 익스포터가 각 데이터 포인트의 `user.groups`를 리소스의 값으로 대체하므로 모든 데이터 포인트에 이전 그룹이 표시됩니다. 데이터 포인트의 값을 유지하려면 해당 익스포터 앞에서 리소스의 `user.groups`를 삭제하십시오.1353OpenTelemetry Collector의 Prometheus remote write 내보내기 도구에서 `resource_to_telemetry_conversion`을 켜면, 내보내기 도구가 각 데이터 포인트의 `user.groups`를 리소스의 값으로 대체하므로 모든 데이터 포인트에 이전 그룹이 표시됩니다. 데이터 포인트의 값을 유지하려면 해당 내보내기 도구보다 앞에서 리소스의 `user.groups`를 삭제하십시오.
1345 1354
1346이 OpenTelemetry Collector `resource` 프로세서는 이를 나열하는 파이프라인에서 속성을 삭제합니다.1355다음 OpenTelemetry Collector `resource` 프로세서는 이를 나열한 파이프라인에서 속성을 삭제합니다.
1347 1356
1348```yaml theme={null}1357```yaml theme={null}
1349processors:1358processors:
1353 action: delete1362 action: delete
1354```1363```
1355 1364
1356메트릭 파이프라인의 `processors`에 `resource/drop-user-groups`를 추가하면, 각 시리즈는 자체 데이터 포인트의 `user_groups` 레이블을 갖게 됩니다.1365메트릭 파이프라인의 `processors`에 `resource/drop-user-groups`를 추가하면, 각 시계열은 자체 데이터 포인트의 `user_groups` 레이블을 포함합니다.
1357 1366
1358#### 수집기로 직접 내보내기1367#### 수집기로 직접 내보내기
1359 1368
1360`/login`을 통해 로그인한 세션이 릴레이를 거치지 않고 텔레메트리를 수집기로 직접 보내도록 하려면, [관리형 정책](#managed)의 `env` 블록에서 `OTEL_EXPORTER_OTLP_ENDPOINT`를 수집기의 `https://` 기본 URL로 설정합니다. Claude Code는 `https://otel-collector.example.com:4318`과 같이 설정한 URL에 `/v1/metrics`, `/v1/logs` 또는 `/v1/traces`를 덧붙이고, 각 신호를 OTLP/HTTP를 통해 해당 위치로 내보냅니다. 각 개발자 머신에 Claude Code v2.1.265 이상이 필요합니다. 이전 클라이언트는 릴레이를 통해 내보냅니다.1369`/login`을 통해 로그인한 세션이 릴레이를 거치지 않고 수집기로 텔레메트리를 직접 보내도록 하려면, [관리형 정책](#managed)의 `env` 블록에서 `OTEL_EXPORTER_OTLP_ENDPOINT`를 수집기의 `https://` 기본 URL로 설정합니다. Claude Code는 설정한 URL(예: `https://otel-collector.example.com:4318`)에 `/v1/metrics`, `/v1/logs` 또는 `/v1/traces`를 덧붙이고, 각 신호를 OTLP/HTTP를 통해 해당 위치로 내보냅니다. 각 개발자의 머신에 Claude Code v2.1.265 이상이 필요합니다. 이전 버전의 클라이언트는 릴레이를 통해 내보냅니다.
1361 1370
1362수집기에 인증하려면 같은 `env` 블록에서 `OTEL_EXPORTER_OTLP_HEADERS`를 설정합니다. 세션은 이런 방식으로 지정된 수집기에 개발자의 게이트웨이 세션 토큰을 절대 보내지 않습니다.1371수집기에 인증하려면 같은 `env` 블록에서 `OTEL_EXPORTER_OTLP_HEADERS`를 설정합니다. 세션은 이런 방식으로 지정된 수집기에 개발자의 게이트웨이 세션 토큰을 절대 보내지 않습니다.
1363 1372
1364정책에서 이 엔드포인트를 추가하거나 변경하면, Claude Code는 대화형 세션에 적용하기 전에 [보안 승인 대화 상자](#managed)에서 각 개발자에게 승인을 요청합니다.1373정책에서 이 엔드포인트를 추가하거나 변경하면, Claude Code는 대화형 세션에 적용하기 전에 각 개발자에게 [보안 승인 대화 상자](#managed)에서 승인하도록 요청합니다.
1365 1374
1366Claude Code는 신호를 직접 내보내기 전에 엔드포인트를 확인하며, 확인에 실패하면 해당 신호를 릴레이에 유지합니다. 확인 항목은 다음과 같습니다.1375Claude Code는 신호를 직접 내보내기 전에 엔드포인트를 확인하며, 확인에 실패하면 해당 신호를 릴레이에 유지합니다. 확인 항목은 다음과 같습니다.
1367 1376
1368* 엔드포인트가 게이트웨이 자체에서 제공됩니다. MDM 프로필이나 로컬 `managed-settings.json`에서 같은 변수를 설정하면 내보내기는 릴레이에 유지됩니다.1377* 엔드포인트가 게이트웨이 자체에서 제공됩니다. 같은 변수를 MDM 프로필이나 로컬 `managed-settings.json`에서 설정하면 내보내기는 릴레이에 유지됩니다.
1369* URL이 `https://`를 사용하거나, 루프백 주소에 대해 `http://`를 사용합니다1378* URL이 `https://`를 사용하거나, 루프백 주소에 대해 `http://`를 사용합니다
1370* URL이 쿼리나 프래그먼트 없이 `/v1/<signal>`로 끝나는 경로로 확인됩니다. Claude Code는 일반 변수로부터 해당 경로를 직접 만듭니다. `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT`와 같은 신호별 변수는 작성된 그대로 사용하므로, 그곳에는 전체 경로를 포함해야 합니다.1379* URL이 쿼리나 프래그먼트 없이 `/v1/<signal>`로 끝나는 경로로 확인됩니다. Claude Code는 일반 변수로부터 이 경로를 직접 만듭니다. `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT`와 같은 신호별 변수는 작성된 그대로 사용하므로, 여기에는 전체 경로를 포함해야 합니다.
1371* URL이 게이트웨이 자체 호스트가 아닙니다. 게이트웨이를 대상으로 하는 엔드포인트는 릴레이 경로와 해당 세션 토큰을 유지합니다.1380* URL이 게이트웨이 자체의 호스트가 아닙니다. 게이트웨이를 대상으로 하는 엔드포인트는 릴레이 경로와 세션 토큰을 유지합니다.
1372* 사용자와 개발자 모두 어떤 설정 소스에서도 [`otelHeadersHelper`](https://code.claude.com/docs/ko/settings-reference#otelheadershelper)를 구성하지 않았습니다. 헬퍼가 구성되어 있으면 모든 신호가 릴레이에 유지됩니다.1381* 관리자와 개발자 모두 어떤 설정 소스에서도 [`otelHeadersHelper`](https://code.claude.com/docs/ko/settings-reference#otelheadershelper)를 구성하지 않았습니다. 헬퍼가 구성되어 있으면 모든 신호가 릴레이에 유지됩니다.
1373 1382
1374지정한 엔드포인트는 내보내기 대상만 변경합니다. 어떤 신호를 내보낼지는 여전히 `OTEL_*_EXPORTER` 선택자로 선택합니다.1383지정한 엔드포인트는 내보내기 대상만 변경합니다. 어떤 신호를 내보낼지는 여전히 `OTEL_*_EXPORTER` 선택자로 선택합니다.
1375 1384
1376엔드포인트만으로는 내보내기가 켜지지 않으므로, 게이트웨이가 이미 푸시하지 않는 한 내보내기를 켜는 변수도 함께 설정합니다.1385엔드포인트만으로는 내보내기가 켜지지 않으므로, 게이트웨이가 이미 푸시하고 있지 않다면 내보내기를 켜는 변수도 함께 설정합니다.
1377 1386
1378* 게이트웨이가 이미 [텔레메트리 변수를 푸시](#telemetry)하는 경우, 해당 변수가 활성화, 선택자, 프로토콜을 처리하며, 명시적으로 지정한 엔드포인트가 푸시된 `<public_url>` 값을 재정의합니다. 어떤 `forward_to` 대상도 활성화하지 않는 신호에 대해서만 `OTEL_*_EXPORTER` 선택자를 직접 `otlp`로 설정합니다.1387* 게이트웨이가 이미 [텔레메트리 변수를 푸시](#telemetry)하고 있다면, 해당 변수가 활성화, 선택자, 프로토콜을 처리하며 명시적으로 지정한 엔드포인트가 푸시된 `<public_url>` 값을 재정의합니다. 어떤 `forward_to` 대상도 활성화하지 않는 신호에 대해서만 `OTEL_*_EXPORTER` 선택자를 직접 `otlp`로 설정합니다.
1379* 그렇지 않은 경우, `CLAUDE_CODE_ENABLE_TELEMETRY=1`, `OTEL_*_EXPORTER` 선택자, `OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf`도 설정합니다.1388* 그렇지 않다면 `CLAUDE_CODE_ENABLE_TELEMETRY=1`, `OTEL_*_EXPORTER` 선택자, `OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf`도 설정합니다.
1380 1389
1381개발자가 로그아웃하거나 다른 게이트웨이에 로그인하면 수집기로의 내보내기가 중지되며, Claude Code는 남은 각 배치를 전송하지 않고 삭제합니다.1390개발자가 로그아웃하거나 다른 게이트웨이에 로그인하면 수집기로의 내보내기가 중단되고, Claude Code는 남아 있는 각 배치를 전송하지 않고 삭제합니다.
1382 1391
1383#### 대상이 실패하는 경우1392#### 대상 전송이 실패하는 경우
1384 1393
1385게이트웨이는 텔레메트리를 버퍼링, 재시도 또는 저장하지 않으므로, 대상에 도달하지 못한 내보내기는 늦게 전달하지 않고 삭제합니다. 각 대상은 개별적으로 성공하거나 실패하며, 내보내는 클라이언트는 어느 경우든 성공 응답을 받으므로 실패한 전달은 게이트웨이의 로그에만 나타납니다.1394게이트웨이는 텔레메트리를 버퍼링하거나 재시도하거나 저장하지 않으므로, 대상에 도달하지 못한 내보내기는 나중에 전달하지 않고 삭제합니다. 각 대상은 개별적으로 성공하거나 실패하며, 내보내는 클라이언트는 어느 경우든 성공 응답을 받으므로 전송 실패는 게이트웨이의 로그에만 나타납니다.
1386 1395
1387한 대상으로의 전달이 연속 다섯 번 실패하면, 게이트웨이는 전달이 성공할 때까지 30초 단위로 해당 대상으로의 전달을 일시 중지하고 각 일시 중지를 로그에 기록합니다. 모든 오류 응답, 타임아웃 또는 연결 오류는 실패한 전달로 간주되지만, `400`, `413`, `415`, `422`, `431`은 예외입니다. 이 상태 코드들은 수집기가 해당 내보내기의 페이로드를 형식이 잘못되었거나 너무 크다는 이유로 거부했음을 의미합니다.1396한 대상으로의 전송이 연속으로 다섯 번 실패하면, 게이트웨이는 전송이 성공할 때까지 30초 단위로 해당 대상으로의 전달을 일시 중지하며 각 일시 중지를 로그에 기록합니다. 모든 오류 응답, 타임아웃, 연결 오류는 전송 실패로 간주되지만, `400`, `413`, `415`, `422`, `431`은 예외입니다. 이 코드들은 수집기가 해당 내보내기의 페이로드를 형식이 잘못되었거나 너무 크다는 이유로 거부했음을 의미합니다.
1388 1397
1389거부된 페이로드는 실패 횟수를 늘리거나 초기화하지 않습니다. 게이트웨이는 해당 대상으로 계속 전달하며, 대상의 첫 번째 거부와 이후 100번째 거부마다 대상과 상태를 명시한 경고를 로그에 기록합니다.1398거부된 페이로드는 실패 횟수를 늘리지도 초기화하지도 않습니다. 게이트웨이는 해당 대상으로 계속 전달하며, 대상의 첫 번째 거부와 이후 매 100번째 거부마다 대상과 상태를 명시한 경고를 로그에 기록합니다.
1390 1399
1391### HTTP 튜닝1400### HTTP 조정
1392 1401
1393선택 사항인 네 개의 최상위 블록 `access_control`, `limits`, `timeouts`, `rate_limits`로 HTTP 사용 환경을 튜닝합니다. 기본값은 대부분의 배포에 적합합니다.1402선택 사항인 네 가지 최상위 블록 `access_control`, `limits`, `timeouts`, `rate_limits`로 HTTP 사용 환경을 조정합니다. 대부분의 배포에는 기본값이 적합합니다.
1394 1403
1395| 블록 | 키 | 기본값 | 설명 |1404| 블록 | 키 | 기본값 | 설명 |
1396| - | - | - | - |1405| - | - | - | - |
1397| `access_control` | `allow_cidrs` / `deny_cidrs` | 비어 있음 | `trusted_proxies` 확인 후 클라이언트 주소를 기준으로 인바운드 IP를 허용/거부합니다. `deny_cidrs`가 먼저 확인되며, 여기에 일치하는 클라이언트는 `allow_cidrs`에도 일치하더라도 거부됩니다. `allow_cidrs`가 비어 있지 않으면 게이트웨이는 기본 거부 상태가 됩니다. `/healthz`와 `/readyz`는 `allow_cidrs`에서 제외됩니다. 신뢰할 수 있는 프록시가 IP 주소가 아닌 `X-Forwarded-For` 항목을 보내면 실제 클라이언트를 알 수 없으며, 게이트웨이는 확인할 사항을 명시한 경고를 한 번 로그에 기록합니다. 두 목록 중 하나라도 요청에 적용되는 경우, 게이트웨이는 `403`과 감사 사유 `xff_unparseable`로 요청을 거부합니다. 어느 목록도 적용되지 않는 경우, 요청을 처리하고 IP별 속도 제한과 감사에 프록시 자체의 주소를 클라이언트 IP로 사용합니다. |1406| `access_control` | `allow_cidrs` / `deny_cidrs` | 비어 있음 | `trusted_proxies` 확인 후 클라이언트 주소 기준으로 인바운드 IP를 허용/거부합니다. `deny_cidrs`를 먼저 확인하며, 여기에 일치하는 클라이언트는 `allow_cidrs`에도 일치하더라도 거부됩니다. `allow_cidrs`가 비어 있지 않으면 게이트웨이는 기본적으로 거부합니다. `/healthz`와 `/readyz`는 `allow_cidrs`에서 제외됩니다. 신뢰할 수 있는 프록시가 IP 주소가 아닌 `X-Forwarded-For` 항목을 보내면 실제 클라이언트를 알 수 없으며, 게이트웨이는 확인할 항목을 명시한 경고를 한 번 로그에 기록합니다. 두 목록 중 하나라도 요청에 적용되는 경우 `403`과 감사 사유 `xff_unparseable`로 요청을 거부합니다. 둘 다 적용되지 않는 경우 요청을 처리하며, IP별 속도 제한과 감사에 프록시 자체의 주소를 클라이언트 IP로 사용합니다. |
1398| `limits` | `max_request_bytes` | 32 MiB | 인바운드 요청 본문의 최대 크기입니다. 크기를 초과하는 요청은 본문이 버퍼링되기 전에 `413`을 받습니다. 대용량 파일이나 이미지 요청의 경우 값을 높이십시오. |1407| `limits` | `max_request_bytes` | 32 MiB | 인바운드 요청 본문의 최대 크기입니다. 크기를 초과하는 요청은 본문이 버퍼링되기 전에 `413`을 받습니다. 대용량 파일이나 이미지 요청에는 값을 늘립니다. |
1399| `limits` | `max_request_header_bytes` | 설정 안 됨 | 요청 전체 헤더에 대한 게이트웨이의 256 KiB 제한을 낮춥니다. 제한을 초과하는 요청은 `431`을 반환하며, 256 KiB를 초과하는 값은 효과가 없습니다. 개발자가 로그인 후 `431`을 받는 경우 [Request headers too large after sign-in](https://code.claude.com/docs/ko/claude-apps-gateway-deploy.md#request-headers-too-large-after-sign-in)을 참조하십시오. |1408| `limits` | `max_request_header_bytes` | 설정 안 됨 | 요청의 전체 헤더에 대한 게이트웨이의 256 KiB 제한을 낮춥니다. 제한을 초과하는 요청은 `431`을 반환하며, 256 KiB보다 큰 값은 효과가 없습니다. 개발자가 로그인 후 `431`을 받는 경우 [로그인 후 요청 헤더가 너무 큼](https://code.claude.com/docs/ko/claude-apps-gateway-deploy.md#request-headers-too-large-after-sign-in)을 참조하세요. |
1400| `limits` | `max_url_length` | 설정 안 됨 | 설정하면 지나치게 긴 URL은 `414`를 반환합니다 |1409| `limits` | `max_url_length` | 설정 안 됨 | 설정하면 너무 긴 URL은 `414`를 반환합니다 |
1401| `timeouts` | `upstream_ttfb_ms` | 120000 | 업스트림의 응답 헤더를 기다리는 최대 시간(첫 바이트까지의 시간)입니다. 이후 응답 본문은 경과 시간 제한 없이 스트리밍됩니다. 직접 Anthropic 업스트림 경로에 적용되며, 다른 모든 제공자의 경우 게이트웨이는 응답이 시작될 때까지 최대 1시간 기다립니다. |1410| `timeouts` | `upstream_ttfb_ms` | 120000 | 업스트림의 응답 헤더를 기다리는 최대 시간(첫 바이트까지의 시간)입니다. 이후 응답 본문은 실제 경과 시간 제한 없이 스트리밍됩니다. 키가 설정되지 않은 경우 기본값은 `provider: anthropic` 업스트림에 적용되며, 다른 모든 제공자에서는 게이트웨이가 응답이 시작될 때까지 최대 1시간 기다립니다. 이 대기 시간을 줄이려면 [여러 업스트림](#multiple-upstreams)을 참조하세요. |
1402| `rate_limits` | `device_authorization.max` / `.window_seconds` | 30 / 600 | 인증되지 않은 디바이스 인증 엔드포인트에 대한 IP별 속도 제한입니다. 공유 이그레스 IP나 NAT 뒤에 있는 대규모 조직의 경우 값을 높이십시오. [대규모 롤아웃](https://code.claude.com/docs/ko/claude-apps-gateway-deploy.md#large-rollouts)에서 크기 산정 방법을 보여줍니다. 이 제한은 `/v1/messages` 추론이 아닌 디바이스 그랜트 로그인 흐름에만 적용됩니다. [사용자 코드 무차별 대입 방지](https://code.claude.com/docs/ko/claude-apps-gateway-deploy.md#user-code-brute-force-resistance)를 참조하십시오. |1411| `rate_limits` | `device_authorization.max` / `.window_seconds` | 30 / 600 | 인증되지 않은 디바이스 인증 엔드포인트에 대한 IP별 속도 제한입니다. 공유 이그레스 IP나 NAT 뒤에 있는 대규모 조직의 경우 값을 늘립니다. [대규모 롤아웃](https://code.claude.com/docs/ko/claude-apps-gateway-deploy.md#large-rollouts)에서 크기를 정하는 방법을 보여 줍니다. 이 제한은 디바이스 그랜트 로그인 흐름에만 적용되며 `/v1/messages` 추론에는 적용되지 않습니다. [사용자 코드 무차별 대입 방지](https://code.claude.com/docs/ko/claude-apps-gateway-deploy.md#user-code-brute-force-resistance)를 참조하세요. |
1403| `rate_limits` | `device_verify.max` / `.window_seconds` | 10 / 600 | `/device`에서의 `user_code` 제출에 대한 IP별 속도 제한입니다. 다른 개발자의 코드를 추측하는 것을 막는 역할을 합니다. [대규모 롤아웃](https://code.claude.com/docs/ko/claude-apps-gateway-deploy.md#large-rollouts)에서 얼마나 높일지 보여줍니다. |1412| `rate_limits` | `device_verify.max` / `.window_seconds` | 10 / 600 | `/device`에서의 `user_code` 제출에 대한 IP별 속도 제한입니다. 다른 사람이 다른 개발자의 코드를 추측하지 못하도록 막는 역할을 합니다. [대규모 롤아웃](https://code.claude.com/docs/ko/claude-apps-gateway-deploy.md#large-rollouts)에서 얼마나 늘려야 하는지 보여 줍니다. |
1404 1413
1405두 `access_control` 목록을 기본값대로 모두 비워 두면, 게이트웨이는 모든 클라이언트 주소를 처리하므로 네트워크만이 접근할 수 있는 대상을 제한합니다. 게이트웨이는 개발자 머신에서 명령을 실행하는 [관리형 설정](#managed)을 푸시할 수 있으므로 이 점이 중요합니다.1414기본값대로 두 `access_control` 목록을 모두 비워 두면 게이트웨이는 모든 클라이언트 주소에 응답하므로, 게이트웨이에 접근할 수 있는 대상은 네트워크에 의해서만 제한됩니다. 게이트웨이는 개발자 머신에서 명령을 실행하는 [관리형 설정](#managed)을 푸시할 수 있으므로 이 점이 중요합니다.
1406 1415
1407`allow_cidrs`가 비어 있는 동안 게이트웨이는 요청에 응답하는 방식은 변경하지 않고 두 곳에서 경고합니다.1416`allow_cidrs`가 비어 있는 동안 게이트웨이는 요청에 응답하는 방식은 바꾸지 않고 두 곳에서 경고합니다.
1408 1417
1409* **부팅 시**: 운영 로그의 경고는 사설 범위 `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`을 모두 설정하지 않으면 경고가 나타나지 않습니다.1418* **부팅 시**: 운영 로그의 경고가 사설 범위 `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`을 모두 설정하지 않으면 경고가 나타나지 않습니다.
1410* **런타임 시**: 해당 사설 범위 밖의 주소에서 요청이 처음 도착하면, 게이트웨이는 경고를 로그에 기록하고 클라이언트 IP를 포함한 [`access.public_client` 감사 이벤트](https://code.claude.com/docs/ko/claude-apps-gateway-deploy#logs)를 생성합니다. 둘 다 프로세스당 한 번 발생합니다. 링크 로컬 주소 `169.254.0.0/16`과 `fe80::/10`은 공용으로 간주되지 않습니다. 게이트웨이는 이 확인이 실행되기 전에 `/healthz`와 `/readyz`에 응답하므로, 공용 범위에서 오는 헬스 프로브는 이를 트리거하지 않습니다.1419* **런타임 시**: 이러한 사설 범위 밖의 주소에서 처음으로 요청이 도착하면, 게이트웨이는 경고를 로그에 기록하고 클라이언트 IP를 포함한 [`access.public_client` 감사 이벤트](https://code.claude.com/docs/ko/claude-apps-gateway-deploy#logs)를 발생시킵니다. 둘 다 프로세스당 한 번 발생합니다. 링크 로컬 주소인 `169.254.0.0/16`과 `fe80::/10`은 공용으로 간주되지 않습니다. 게이트웨이는 이 확인이 실행되기 전에 `/healthz`와 `/readyz`에 응답하므로, 공용 범위에서 오는 상태 프로브는 이 확인을 트리거하지 않습니다.
1411 1420
1412두 신호 모두 게이트웨이가 확인한 클라이언트 주소를 사용합니다. 로드 밸런서, 포트 포워드 또는 터널이 트래픽을 중계하면서 `listen.trusted_proxies`에 나열되어 있지 않으면, 게이트웨이는 보통 사설 주소인 중계 장치의 주소를 보게 되므로, 런타임 경고와 사설 허용 목록 모두 해당 장치를 통해 중계된 트래픽을 잡아내지 못합니다.1421두 신호 모두 게이트웨이가 확인한 클라이언트 주소를 사용합니다. 로드 밸런서, 포트 포워드 또는 터널이 트래픽을 중계하면서 `listen.trusted_proxies`에 등록되어 있지 않으면, 게이트웨이는 일반적으로 사설 주소인 중계 장치의 주소를 보게 되므로 런타임 경고와 사설 허용 목록 모두 이를 통해 중계된 트래픽을 잡아내지 못합니다.
1413 1422
1414이러한 프런트 엔드 뒤에서는 먼저 [`listen.trusted_proxies`](#listen)를 설정하여 게이트웨이가 실제 클라이언트 주소를 보도록 하고, 그와 관계없이 게이트웨이와 그 앞에 있는 모든 것을 공용 인터넷에서 접근할 수 없도록 유지하십시오.1423이러한 프런트 엔드 뒤에서는 게이트웨이가 실제 클라이언트 주소를 볼 수 있도록 먼저 [`listen.trusted_proxies`](#listen)를 설정하고, 어떤 경우에도 게이트웨이와 그 앞에 있는 모든 것이 공용 인터넷에서 접근할 수 없도록 유지합니다.
1415 1424
1416### `load_test_mode`1425### `load_test_mode`
1417 1426
1418`load_test_mode` 블록을 사용하면 모델 제공자를 호출하지 않고 게이트웨이를 부하 테스트할 수 있습니다. 이 모드가 켜져 있는 동안 게이트웨이는 평소처럼 각 제공자 요청을 빌드하고 서명한 뒤, 전송하지 않고 폐기하며, 일반 응답 경로를 통해 미리 준비된 응답을 스트리밍합니다. 응답은 미리 준비된 응답임을 알리는 문장으로 시작하는 채움 텍스트입니다.1427`load_test_mode` 블록을 사용하면 모델 제공자를 호출하지 않고 게이트웨이의 부하 테스트를 수행할 수 있습니다. 이 모드가 켜져 있는 동안 게이트웨이는 평소처럼 각 제공자 요청을 빌드하고 서명한 다음, 전송하는 대신 폐기하고 일반 응답 경로를 통해 미리 준비된 응답을 스트리밍합니다. 응답은 미리 준비된 응답임을 알리는 문장으로 시작하는 채우기 텍스트입니다.
1419 1428
1420게이트웨이 서버에 Claude Code v2.1.282 이상이 필요합니다. 이전 버전의 게이트웨이는 이 키를 발견하면 시작을 거부합니다. 블록을 추가하기 전에 모든 레플리카를 업그레이드하고, 롤백하기 전에 블록을 제거하십시오.1429게이트웨이 서버에 Claude Code v2.1.282 이상이 필요합니다. 이전 버전의 게이트웨이는 이 키를 발견하면 시작을 거부합니다. 블록을 추가하기 전에 모든 복제본을 업그레이드하고, 롤백하기 전에 블록을 제거하세요.
1421 1430
1422아래 예시는 기본값으로 모드를 켜며, 약 750 토큰 분량의 텍스트 응답을 약 10초에 걸쳐 스트리밍합니다.1431아래 예시는 기본값으로 모드를 켜며, 약 750 토큰 분량의 텍스트 응답을 약 10초에 걸쳐 스트리밍합니다.
1423 1432
1430 1439
1431| 필드 | 필수 | 설명 |1440| 필드 | 필수 | 설명 |
1432| - | - | - |1441| - | - | - |
1433| `enabled` | 예 | `true`는 모드를 켭니다. `false`는 모드를 끈 상태로 파일에 수치를 유지합니다. 이 필드 없이 블록이 있으면 게이트웨이는 시작을 거부합니다. |1442| `enabled` | 예 | `true`는 모드를 켭니다. `false`는 모드를 끈 상태로 파일에 값을 유지합니다. 이 필드 없이 블록이 있으면 게이트웨이는 시작을 거부합니다. |
1434| `reply_tokens` | 아니요 | 기본값 `750`. 미리 준비된 각 응답이 담는 대략적인 텍스트 토큰 수로, 1부터 100000까지의 정수입니다. |1443| `reply_tokens` | 아니요 | 기본값 `750`. 각 미리 준비된 응답에 포함되는 텍스트의 대략적인 토큰 수로, 1에서 100000 사이의 정수입니다. |
1435| `reply_seconds` | 아니요 | 기본값 `9.5`. 스트리밍 응답에 걸리는 시간으로, 0부터 600까지입니다. `0`은 전체 응답을 한 번에 보냅니다. 스트리밍이 아닌 요청에 대한 응답은 항상 한 번에 반환됩니다. |1444| `reply_seconds` | 아니요 | 기본값 `9.5`. 스트리밍 응답에 걸리는 시간으로, 0에서 600 사이입니다. `0`은 전체 응답을 한 번에 보냅니다. 스트리밍이 아닌 요청에 대한 응답은 항상 한 번에 반환됩니다. |
1436 1445
1437이 모드의 부하 테스트는 게이트웨이, Postgres, 그리고 게이트웨이 앞에 있는 모든 것을 다룹니다. 제공자의 제한, 속도 또는 네트워크 경로는 다루지 않습니다.1446이 모드의 부하 테스트는 게이트웨이, Postgres, 게이트웨이 앞에 있는 모든 것을 대상으로 합니다. 제공자의 제한, 속도, 네트워크 경로는 대상으로 하지 않습니다.
1438 1447
1439제공자에게 모델 요청이 전송되지 않으므로, 레플리카의 요청당 CPU는 추정치이며 제공자로 가는 트래픽도 암호화하는 프로덕션 환경보다 낮게 나타납니다. 실제 제공자를 대상으로 한 소규모 파일럿으로 레플리카 수를 확인하십시오. v2.1.283 이전에는 추정치가 훨씬 낮게 나타납니다.1448모델 요청이 제공자에게 전송되지 않으므로 복제본의 요청당 CPU는 추정치이며, 제공자로의 트래픽도 암호화하는 프로덕션 환경보다 낮게 측정됩니다. 실제 제공자를 대상으로 소규모 파일럿을 실행하여 복제본 수를 확인하세요. v2.1.283 이전에는 추정치가 훨씬 낮게 측정됩니다.
1440 1449
1441모드가 켜져 있는 동안 요청은 최대 일곱 자리 정수를 담은 `x-load-test-user` 헤더를 포함할 수 있습니다. 게이트웨이는 각 숫자를 별도의 개발자로 계산하며, 요청과 함께 온 토큰의 개발자 이메일과 그룹을 사용합니다.1450모드가 켜져 있는 동안 요청에 최대 일곱 자리 정수를 담은 `x-load-test-user` 헤더를 포함할 수 있습니다. 게이트웨이는 각 숫자를 별도의 개발자로 간주하며, 요청과 함께 전달된 토큰의 개발자 이메일과 그룹을 사용합니다.
1442 1451
1443부하 테스트 배포에는 별도의 빈 데이터베이스를 제공하십시오. 게이트웨이는 이미 어떤 개발자라도 사용량이 발생한 데이터베이스에서는 모드가 켜진 상태로 시작하기를 거부하기 때문입니다.1452부하 테스트 배포에는 전용의 빈 데이터베이스를 제공하세요. 이미 어떤 개발자라도 사용량이 발생한 데이터베이스에서는 게이트웨이가 이 모드를 켠 상태로 시작을 거부하기 때문입니다.
1444 1453
1445> [!WARNING]1454> [!WARNING]
1446>1455>
1447> 개발자가 사용하는 게이트웨이에서는 절대 이 모드를 켜지 마십시오. 모든 요청이 미리 준비된 응답을 받으며 어떤 모델도 호출되지 않습니다. 게이트웨이는 모드가 켜져 있는 동안 부팅 시 `load_test_mode is on` 경고를 로그에 기록하고 각 `inference` [감사 이벤트](https://code.claude.com/docs/ko/claude-apps-gateway-deploy.md#logs)에 `load_test: true`를 표시합니다.1456> 개발자가 사용하는 게이트웨이에서는 절대 이 모드를 켜지 마세요. 모든 요청이 미리 준비된 응답을 받고 모델은 호출되지 않습니다. 모드가 켜져 있는 동안 게이트웨이는 부팅 시 `load_test_mode is on` 경고를 로그에 기록하고, 각 `inference` [감사 이벤트](https://code.claude.com/docs/ko/claude-apps-gateway-deploy.md#logs)에 `load_test: true`를 표시합니다.
1448 1457
1449## 완전한 예제1458## 완전한 예제
1450 1459
