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