36 36
37`/status` 메뉴의 두 줄이 모두 올바르지만 Claude로의 메시지가 실패하면 [문제 해결 표](#troubleshoot-gateway-errors)를 참조하세요.37`/status` 메뉴의 두 줄이 모두 올바르지만 Claude로의 메시지가 실패하면 [문제 해결 표](#troubleshoot-gateway-errors)를 참조하세요.
38 38
39## Claude Code 직접 구성39## Claude Code 직접 구성하기
40 40
41게이트웨이에 대해 Claude Code를 직접 구성하려면 게이트웨이 팀에서 다음이 필요합니다:41게이트웨이용 Claude Code를 직접 구성하려면 게이트웨이 팀으로부터 다음 정보를 받아야 합니다.
42 42
43* 게이트웨이의 기본 URL43* 게이트웨이의 기본 URL
44* 자격 증명: 키 또는 토큰 문자열, 또는 하나를 가져오는 명령44* 자격 증명: 키 또는 토큰 문자열, 또는 이를 가져오는 명령
45 * 게이트웨이 팀이 어떤 종류의 자격 증명인지 말하지 않았다면, 아래의 [자격 증명 변수 섹션](#set-the-credential-variable)에서 시도할 것을 다룹니다.45 * 게이트웨이 팀이 자격 증명의 종류를 알려주지 않았다면, 아래의 [자격 증명 변수 섹션](#set-the-credential-variable)에서 시도해 볼 방법을 안내합니다
46 46
47아래 섹션은 순서대로 구성을 다룹니다:47아래 섹션에서는 구성을 순서대로 다룹니다.
48 48
49* [자격 증명 변수 설정](#set-the-credential-variable) 및 [기본 URL 설정](#set-the-base-url-and-credential): 모든 게이트웨이 연결에 필요한 두 변수49* [자격 증명 변수 설정](#set-the-credential-variable) 및 [기본 URL 설정](#set-the-base-url-and-credential): 모든 게이트웨이 연결에 필요한 두 가지 변수
50* [연결 확인](#verify-the-connection): 무엇이든 유지하기 전에 작동하는지 확인50* [연결 확인](#verify-the-connection): 값을 영구적으로 저장하기 전에 연결이 작동하는지 확인
51* [각 표면 구성](#configure-each-surface): Claude Code CLI 외에 VS Code와 같은 다른 표면을 사용하는 경우, 게이트웨이 자격 증명으로 구성하는 방법을 참조하세요.51* [각 사용 환경 구성](#configure-each-surface): VS Code 등 Claude Code CLI 이외의 사용 환경을 사용하는 경우, 게이트웨이 자격 증명으로 해당 환경을 구성하는 방법 확인
52* [추가 구성](#additional-configuration): 기본 URL과 자격 증명 외에 일부 게이트웨이가 필요로 하는 변수(예: 사용자 정의 헤더, 자격 증명 도우미, 모델 검색, 제공자 형식 기본 URL 또는 게이트웨이 경로 외부의 트래픽 끄기). 관리자가 명시한 경우에만 이를 설정하거나 네트워크가 송신을 제한합니다.52* [추가 구성](#additional-configuration): 일부 게이트웨이에서 기본 URL과 자격 증명 외에 필요로 하는 변수(사용자 지정 헤더, 자격 증명 헬퍼, 모델 검색, 제공자 형식 기본 URL, 게이트웨이 경로 외부 트래픽 비활성화 등). 관리자가 지정했거나 네트워크에서 외부 송신(egress)을 제한하는 경우에만 설정합니다
53 53
54### 자격 증명 변수 설정54### 자격 증명 변수 설정
55 55
56Claude Code를 게이트웨이에 인증하려면 환경 변수에 자격 증명을 설정합니다. 어떤 변수를 사용할지는 게이트웨이 팀이 말한 것에 따라 다릅니다:56Claude Code가 게이트웨이에 인증하도록 하려면 환경 변수에 자격 증명을 설정합니다. 어떤 변수를 사용할지는 게이트웨이 팀이 안내한 내용에 따라 다릅니다.
57 57
58| 자격 증명 설정 위치 | 사용 시기 |58| 자격 증명을 설정할 위치 | 사용하는 경우 |
59| :- | :- |59| :- | :- |
60| `ANTHROPIC_AUTH_TOKEN` | 게이트웨이 팀이 "bearer token" 또는 "Authorization header"라고 말했을 때 |60| `ANTHROPIC_AUTH_TOKEN` | 게이트웨이 팀이 "bearer token" 또는 "Authorization header"라고 안내한 경우 |
61| `ANTHROPIC_API_KEY` | 게이트웨이 팀이 "API key" 또는 "x-api-key"라고 말했을 때 |61| `ANTHROPIC_API_KEY` | 게이트웨이 팀이 "API key" 또는 "x-api-key"라고 안내한 경우 |
62| [`apiKeyHelper`](#rotate-credentials-with-apikeyhelper) | 자격 증명이 회전하거나 자격 증명 모음에서 나올 때 |62| [`apiKeyHelper`](#rotate-credentials-with-apikeyhelper) | 자격 증명이 교체(rotate)되거나 볼트(vault)에서 가져오는 경우 |
63 63
64어떤 종류인지 말하지 않았다면 `ANTHROPIC_AUTH_TOKEN`을 사용하세요. 아래의 [확인 요청](#verify-the-connection)은 전환이 필요한지 확인하는 방법을 보여줍니다.64종류를 안내받지 못했다면 `ANTHROPIC_AUTH_TOKEN`을 사용합니다. 아래의 [확인 요청](#verify-the-connection)에서 변수를 바꿔야 하는지 판단하는 방법을 설명합니다.
65 65
66### 기본 URL과 자격 증명 설정66### 기본 URL 및 자격 증명 설정
67 67
68게이트웨이의 기본 URL과 위에서 선택한 자격 증명 변수를 환경 변수로 설정합니다. 예제는 `ANTHROPIC_AUTH_TOKEN`을 사용합니다. [선택한 변수](#set-the-credential-variable)가 `ANTHROPIC_API_KEY`라면 이를 바꾸세요. [셸에서](#set-as-shell-environment-variables) 설정할 수 있으며, 이는 한 터미널 세션 동안 지속되거나, [Claude Code 설정 파일에서](#set-in-a-settings-file) 설정할 수 있으며, 이는 Claude Code가 실행되는 모든 곳에서 지속됩니다.68게이트웨이의 기본 URL과 위에서 선택한 자격 증명 변수를 환경 변수로 설정합니다. 예시에서는 `ANTHROPIC_AUTH_TOKEN`을 사용하며, [선택한 변수](#set-the-credential-variable)가 `ANTHROPIC_API_KEY`라면 해당 변수로 바꿔서 사용합니다. 하나의 터미널 세션 동안만 유지되는 [셸에서 설정](#set-as-shell-environment-variables)하거나, Claude Code가 실행되는 모든 곳에서 유지되는 [Claude Code 설정 파일에서 설정](#set-in-a-settings-file)할 수 있습니다.
69 69
70첫 번째 연결의 경우, 셸 내보내기로 시작하고 값을 설정 파일로 이동하기 전에 [확인 요청](#verify-the-connection)을 실행합니다.70처음 연결할 때는 셸 export로 시작하고, 값을 설정 파일로 옮기기 전에 [확인 요청](#verify-the-connection)을 실행합니다.
71 71
72#### 셸 환경 변수로 설정72#### 셸 환경 변수로 설정
73 73
74값을 게이트웨이 팀이 제공한 값으로 바꾸세요:74값을 게이트웨이 팀이 제공한 값으로 바꿉니다.
75 75
76> [tab] Bash 또는 Zsh76> [tab] Bash or Zsh
77>77>
78> ```bash theme={null}78> ```bash theme={null}
79> export ANTHROPIC_BASE_URL=https://llm-gateway.example.com79> export ANTHROPIC_BASE_URL=https://llm-gateway.example.com
87> $env:ANTHROPIC_AUTH_TOKEN = "sk-gateway-key"87> $env:ANTHROPIC_AUTH_TOKEN = "sk-gateway-key"
88> ```88> ```
89 89
90셸 내보내기는 해당 터미널 세션과 그로부터 시작된 프로그램에만 적용됩니다. 도크 또는 시작 메뉴에서 시작된 편집기는 이를 볼 수 없습니다. 새 터미널에서 지속되도록 하려면 `~/.zshrc`, `~/.bashrc` 또는 PowerShell `$PROFILE`과 같은 셸 프로필에 동일한 줄을 추가하세요.90셸 export는 해당 터미널 세션과 그 세션에서 시작된 프로그램에만 적용됩니다. Dock이나 시작 메뉴에서 실행한 편집기에서는 이 값을 인식하지 못합니다. 새 터미널에서도 값이 유지되도록 하려면 `~/.zshrc`, `~/.bashrc` 또는 PowerShell `$PROFILE`과 같은 셸 프로필에 같은 줄을 추가합니다.
91 91
92게이트웨이를 셸에서만 내보내면 [supervisor](https://code.claude.com/docs/ko/agent-view.md#how-background-sessions-are-hosted)에서 호스팅하는 백그라운드 에이전트에 안정적으로 도달하지 않습니다. [각 백그라운드 세션이 게이트웨이를 소싱하는 방식](https://code.claude.com/docs/ko/agent-view.md#llm-gateway)을 참조하세요. 백그라운드 에이전트가 항상 라우팅해야 하는 게이트웨이의 경우 설정 파일을 사용하세요.92게이트웨이를 셸에서만 export하면 [슈퍼바이저](https://code.claude.com/docs/ko/agent-view.md#how-background-sessions-are-hosted)가 호스팅하는 백그라운드 에이전트에 안정적으로 전달되지 않습니다. [각 백그라운드 세션이 게이트웨이를 가져오는 방식](https://code.claude.com/docs/ko/agent-view.md#llm-gateway)을 참조하세요. 백그라운드 에이전트가 항상 경유해야 하는 게이트웨이에는 설정 파일을 사용합니다.
93 93
94#### 설정 파일에서 설정94#### 설정 파일에서 설정
95 95
96Claude Code가 실행되는 모든 곳에서 구성이 적용되도록 하려면([백그라운드 에이전트](https://code.claude.com/docs/ko/agent-view.md#how-background-sessions-are-hosted) 포함), [설정 파일](https://code.claude.com/docs/ko/settings.md)의 `env` 블록에서 변수를 설정하세요. 설정 파일은 다양한 범위를 가집니다:96[백그라운드 에이전트](https://code.claude.com/docs/ko/agent-view.md#how-background-sessions-are-hosted)를 포함해 Claude Code가 실행되는 모든 곳에 구성을 적용하려면, 셸에 의존하는 대신 [설정 파일](https://code.claude.com/docs/ko/settings.md)의 `env` 블록에 변수를 설정합니다. 설정 파일마다 범위가 다릅니다.
97 97
98* `~/.claude/settings.json`은 모든 프로젝트에 적용됩니다. Windows에서 경로는 `%USERPROFILE%\.claude\settings.json`입니다.98* `~/.claude/settings.json`은 모든 프로젝트에 적용됩니다. Windows에서의 경로는 `%USERPROFILE%\.claude\settings.json`입니다
99* `.claude/settings.local.json`은 한 프로젝트에 적용됩니다. Claude Code는 파일을 생성할 때 이를 gitignore에 추가합니다. 직접 생성하는 경우, 자격 증명을 실수로 커밋하지 않도록 먼저 gitignore에 수동으로 추가합니다.99* `.claude/settings.local.json`은 하나의 프로젝트에 적용됩니다. Claude Code가 이 파일에 설정을 저장할 때 전역 gitignore에 이 파일을 추가합니다. 파일을 직접 만들거나 Claude에게 작성하도록 하는 경우에는 실수로 자격 증명을 커밋하지 않도록 먼저 직접 gitignore에 추가합니다
100 100
101> [!WARNING]101> [!WARNING]
102>102>
103> 프로젝트의 `.claude/settings.json`에 자격 증명을 넣지 마세요. 이 파일은 커밋되고 저장소를 복제하는 모든 사람과 공유됩니다.103> 프로젝트의 `.claude/settings.json`에 자격 증명을 넣지 마세요. 이 파일은 커밋되어 저장소를 클론하는 모든 사람과 공유됩니다.
104 104
105`env` 블록은 두 파일 모두에서 동일하게 보입니다:105`env` 블록은 두 파일 모두에서 동일한 형태입니다.
106 106
107```json theme={null}107```json theme={null}
108{108{
113}113}
114```114```
115 115
116셸 내보내기와 설정 파일 `env` 블록이 동일한 변수를 설정할 때, 설정 파일 값이 적용됩니다. `/status`를 실행하여 Claude Code가 사용 중인 기본 URL과 자격 증명 소스를 확인합니다.116셸 export와 설정 파일의 `env` 블록이 같은 변수를 설정하면 설정 파일의 값이 적용됩니다. `/status`를 실행하면 Claude Code가 사용 중인 기본 URL과 자격 증명 소스를 확인할 수 있습니다.
117 117
118### 연결 확인118### 연결 확인
119 119
120셸에서 변수를 내보낸 상태에서, 게이트웨이에 한 토큰 요청을 직접 전송합니다. 이는 Claude Code를 열기 전에 URL과 자격 증명이 작동하는지 확인하므로, 실패는 구성이 아닌 게이트웨이를 가리킵니다. 아래 명령은 셸 변수를 읽으므로, 설정 파일에도 값을 넣었더라도 [셸 내보내기](#set-as-shell-environment-variables)가 필요합니다.120셸에 변수를 export한 상태에서 게이트웨이에 직접 1토큰 요청을 보냅니다. 이렇게 하면 Claude Code를 열기 전에 URL과 자격 증명이 작동하는지 확인할 수 있으므로, 실패할 경우 구성이 아닌 게이트웨이 쪽 문제임을 알 수 있습니다. 아래 명령은 셸 변수를 읽으므로, 설정 파일에도 값을 넣었더라도 [셸 export](#set-as-shell-environment-variables)가 필요합니다.
121 121
122> [tab] Bash 또는 Zsh122> [tab] Bash or Zsh
123>123>
124> ```bash theme={null}124> ```bash theme={null}
125> curl -sS -w '\n%{http_code}\n' -X POST "$ANTHROPIC_BASE_URL/v1/messages" \125> curl -sS -w '\n%{http_code}\n' -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
138> -Body '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'138> -Body '{"model": "claude-sonnet-4-6", "max_tokens": 1, "messages": [{"role": "user", "content": "."}]}'
139> ```139> ```
140 140
141게이트웨이가 `x-api-key` 헤더의 키를 예상하면, Bash 명령에서 `Authorization` 헤더를 `x-api-key: $ANTHROPIC_API_KEY`로 바꾸거나, PowerShell 명령에서 `"Authorization"` 해시테이블 항목을 `"x-api-key" = "$env:ANTHROPIC_API_KEY"`로 바꾸세요.141게이트웨이가 `x-api-key` 헤더로 키를 받는 경우, Bash 명령에서는 `Authorization` 헤더를 `x-api-key: $ANTHROPIC_API_KEY`로, PowerShell 명령에서는 `"Authorization"` 해시테이블 항목을 `"x-api-key" = "$env:ANTHROPIC_API_KEY"`로 바꿉니다.
142 142
143`{"id":"msg_`로 시작하고 `"content":[...]` 필드를 포함하는 JSON 응답은 게이트웨이에 도달할 수 있고 자격 증명이 작동함을 의미합니다. 알 수 없는 모델을 명시하는 오류는 게이트웨이가 모델 이름을 거부하기 전에 요청을 인증했으므로 URL과 자격 증명이 작동함을 증명합니다. 게이트웨이가 제공하는 모델을 찾을 필요가 없습니다. `401`은 자격 증명이 거부되었음을 의미합니다. 변수를 추측했다면 다른 변수로 전환하고 다시 내보내세요.143`{"id":"msg_`로 시작하고 `"content":[...]` 필드를 포함하는 JSON 응답이 반환되면 게이트웨이에 연결할 수 있고 자격 증명이 작동한다는 의미입니다. 알 수 없는 모델이라는 오류가 반환되더라도 URL과 자격 증명이 작동한다는 것이 확인됩니다. 게이트웨이가 모델 이름을 거부하기 전에 요청을 인증했기 때문입니다. 이 테스트를 위해 게이트웨이가 제공하는 모델을 찾을 필요는 없습니다. `401`은 자격 증명이 거부되었다는 의미입니다. 변수를 추측해서 설정했다면 다른 변수로 바꾸고 다시 export합니다.
144 144
145#### Claude Code에서 확인145#### Claude Code에서 확인
146 146
147같은 셸에서 `claude`를 시작하여 내보내기를 상속받고, 메시지를 전송하고, `/status`를 실행합니다.147export가 상속되도록 같은 셸에서 `claude`를 시작하고, 메시지를 보낸 다음 `/status`를 실행합니다.
148 148
149**상태** 탭에서 `Anthropic base URL` 줄은 게이트웨이 주소를 표시해야 하며, 이는 요청이 그곳으로 라우팅되고 있음을 확인합니다. 줄이 없으면 변수가 세션에 도달하지 않았습니다. `Auth token` 또는 `API key` 줄이 설정한 변수를 명시하면 저장된 claude.ai 로그인이 아닌 게이트웨이 자격 증명이 활성화되어 있음을 확인합니다.149**Status** 탭의 `Anthropic base URL` 줄에 게이트웨이 주소가 표시되어야 하며, 이는 요청이 해당 게이트웨이로 라우팅되고 있음을 확인해 줍니다. 이 줄이 없다면 변수가 세션에 전달되지 않은 것입니다. 설정한 변수를 나타내는 `Auth token` 또는 `API key` 줄은 저장된 claude.ai 로그인이 아닌 게이트웨이 자격 증명이 활성화되어 있음을 확인해 줍니다.
150 150
151메시지가 실패하거나 `/status`가 게이트웨이 URL을 표시하지 않으면, 아래의 [문제 해결 표](#troubleshoot-gateway-errors)를 참조하세요.151메시지 전송이 실패하거나 `/status`에 게이트웨이 URL이 표시되지 않으면 아래의 [문제 해결 표](#troubleshoot-gateway-errors)를 참조하세요.
152 152
153### 자격 증명 변수가 헤더에 매핑되는 방식153### 자격 증명 변수와 헤더의 대응 관계
154 154
155각 변수는 자격 증명을 다른 HTTP 헤더로 전송합니다: `ANTHROPIC_AUTH_TOKEN`은 `Authorization: Bearer`로, `ANTHROPIC_API_KEY`는 `x-api-key`로, `apiKeyHelper`는 둘 다로 전송합니다. 잘못된 변수의 자격 증명은 게이트웨이가 읽지 않는 헤더에 도달하고, 요청은 `401`로 실패합니다. 확인 요청이 `401`을 반환했다면 다른 변수로 전환하고 다시 시도하세요.155각 변수는 서로 다른 HTTP 헤더로 자격 증명을 전송합니다. `ANTHROPIC_AUTH_TOKEN`은 `Authorization: Bearer`로, `ANTHROPIC_API_KEY`는 `x-api-key`로, `apiKeyHelper`는 두 헤더 모두로 전송합니다. 잘못된 변수에 넣은 자격 증명은 게이트웨이가 읽지 않는 헤더로 전달되므로 요청이 `401`로 실패합니다. 확인 요청이 `401`을 반환했다면 다른 변수로 바꿔서 다시 시도합니다.
156 156
157### 기존 로그인과의 충돌157### 기존 로그인과의 충돌
158 158
159게이트웨이 자격 증명 변수는 저장된 claude.ai 로그인 또는 Console 키보다 우선합니다. `ANTHROPIC_AUTH_TOKEN`을 사용하면 변수가 즉시 우선합니다. `ANTHROPIC_API_KEY`를 사용하면 대화형 모드에서 키가 인수하기 전에 한 번 승인하도록 요청받습니다.159요청에는 저장된 claude.ai 로그인이 아닌 게이트웨이 자격 증명 변수가 사용됩니다. `ANTHROPIC_AUTH_TOKEN`을 사용하면 변수가 즉시 우선 적용됩니다. `ANTHROPIC_API_KEY`를 사용하면 키가 적용되기 전에 대화형 모드에서 키를 승인하라는 메시지가 한 번 표시됩니다.
160 160
161`/status`를 실행하여 어떤 자격 증명 소스가 활성화되어 있는지 확인합니다. 시작 시 두 소스를 명시하는 인증 충돌 경고가 표시되면, [문제 해결 표](#troubleshoot-gateway-errors)의 첫 번째 행을 참조하여 어느 것을 제거할지 확인합니다. 저장된 로그인을 지워 게이트웨이 자격 증명만 남기려면 `/logout`을 실행합니다.161`/status`를 실행하여 어떤 자격 증명 소스가 활성화되어 있는지 확인합니다. 시작 시 두 소스를 명시하는 인증 충돌 경고가 표시되면 [문제 해결 표](#troubleshoot-gateway-errors)의 첫 번째 행에서 어느 쪽을 제거해야 하는지 확인하세요. 게이트웨이 자격 증명만 남도록 저장된 로그인을 지우려면 `/logout`을 실행합니다.
162 162
163## 각 표면 구성163## 각 표면 구성
164 164
506 506
507| 오류 | 원인 | 해결 방법 |507| 오류 | 원인 | 해결 방법 |
508| :- | :- | :- |508| :- | :- | :- |
509| 두 개의 자격 증명 출처를 명시하고 `auth may not work as expected`로 끝나는 시작 시 경고. 이전 버전에서는 대신 `Auth conflict: Both a token (SOURCE) and an API key (SOURCE) are set`가 표시됩니다. | 게이트웨이 자격 증명과 저장된 로그인이 모두 활성화되어 있습니다. 요청에는 변수가 사용되지만, 오래된 로그인으로 인해 예기치 않은 인증 동작이 발생할 수 있습니다 | 저장된 로그인을 사용하려면 변수를 해제하고, 게이트웨이 자격 증명을 사용하려면 `/logout`을 실행합니다 |509| 두 개의 자격 증명 출처를 명시하고 `auth may not work as expected`로 끝나는 시작 시 경고. 이전 버전에서는 대신 `Auth conflict: Both a token (SOURCE) and an API key (SOURCE) are set`가 표시됩니다. | 게이트웨이 자격 증명과 저장된 로그인이 모두 활성화되어 있습니다 | 저장된 로그인을 사용하려면 변수를 해제하고, 게이트웨이 자격 증명을 사용하려면 `/logout`을 실행합니다 |
510| 유효하지 않거나 인식되지 않는 토큰을 명시하는 `401` 오류 | 자격 증명이 게이트웨이에서 발급한 것이 아니거나, 게이트웨이가 읽지 않는 헤더에 들어 있습니다 | [자격 증명 표](#set-the-credential-variable)에서 변수가 자격 증명 종류와 일치하는지 확인하고, 키가 폐기된 경우 게이트웨이에서 키를 다시 생성합니다 |510| 유효하지 않거나 인식되지 않는 토큰을 명시하는 `401` 오류 | 자격 증명이 게이트웨이에서 발급한 것이 아니거나, 게이트웨이가 읽지 않는 헤더에 들어 있습니다 | [자격 증명 표](#set-the-credential-variable)에서 변수가 자격 증명 종류와 일치하는지 확인하고, 키가 폐기된 경우 게이트웨이에서 키를 다시 생성합니다 |
511| `Your apiKeyHelper script is failing`, 또는 비대화형 모드에서 stderr에 출력되는 `apiKeyHelper failed:` | [`apiKeyHelper`](https://code.claude.com/docs/ko/settings-reference#apikeyhelper) 설정의 명령이 사용 가능한 키를 생성하지 못해 요청에 자리 표시자 키가 담깁니다 | 명령을 직접 실행하여 실패 원인을 확인하고, 세션 만료가 보고되면 자격 증명 제공자에서 다시 인증합니다. [오류 참조](https://code.claude.com/docs/ko/errors.md#your-apikeyhelper-script-is-failing)를 참조하세요 |511| `Your apiKeyHelper script is failing`, 또는 비대화형 모드에서 stderr에 출력되는 `apiKeyHelper failed:` | [`apiKeyHelper`](https://code.claude.com/docs/ko/settings-reference#apikeyhelper) 설정의 명령이 사용 가능한 키를 생성하지 못해 요청에 자리 표시자 키가 담깁니다 | 명령을 직접 실행하여 실패 원인을 확인하고, 세션 만료가 보고되면 자격 증명 제공자에서 다시 인증합니다. [오류 참조](https://code.claude.com/docs/ko/errors.md#your-apikeyhelper-script-is-failing)를 참조하세요 |
512| 주소에서 아무것도 응답하지 않을 때의 `Connection refused — a firewall or proxy may be blocking it (ConnectionRefused)`, 또는 호스트 이름이 확인되지 않을 때의 `Can't reach the API server — check your internet or DNS (ENOTFOUND)`. Claude Code가 [백오프를 적용해 재시도](https://code.claude.com/docs/ko/errors.md#automatic-retries)하는 동안 아무 표시 없이 잠시 멈춘 후에 나타나는 경우가 많습니다. 괄호 안의 코드는 다를 수 있으며, [Unable to connect to API](https://code.claude.com/docs/ko/errors.md#unable-to-connect-to-api)에서 코드 표기와 이전 문구를 다룹니다 | 기본 URL에서 아무것도 응답하지 않았습니다. 주소가 잘못되었거나 VPN 또는 방화벽이 게이트웨이로 가는 경로를 차단하고 있습니다 | [위의 curl 테스트](#verify-the-connection)를 실행하면 같은 원인으로 즉시 실패합니다. 게이트웨이 팀과 함께 URL과 네트워크 경로를 확인합니다 |512| 주소에서 아무것도 응답하지 않을 때의 `Connection refused — a firewall or proxy may be blocking it (ConnectionRefused)`, 또는 호스트 이름이 확인되지 않을 때의 `Can't reach the API server — check your internet or DNS (ENOTFOUND)`. Claude Code가 [백오프를 적용해 재시도](https://code.claude.com/docs/ko/errors.md#automatic-retries)하는 동안 아무 표시 없이 잠시 멈춘 후에 나타나는 경우가 많습니다. 괄호 안의 코드는 다를 수 있으며, [Unable to connect to API](https://code.claude.com/docs/ko/errors.md#unable-to-connect-to-api)에서 코드 표기와 이전 문구를 다룹니다 | 기본 URL에서 아무것도 응답하지 않았습니다. 주소가 잘못되었거나 VPN 또는 방화벽이 게이트웨이로 가는 경로를 차단하고 있습니다 | [위의 curl 테스트](#verify-the-connection)를 실행하면 같은 원인으로 즉시 실패합니다. 게이트웨이 팀과 함께 URL과 네트워크 경로를 확인합니다 |
520| 추론 요청은 작동하는데 `/fast`가 `Fast mode unavailable due to network connectivity issues`를 보고함 | [빠른 모드](https://code.claude.com/docs/ko/fast-mode.md) 가용성 확인은 `api.anthropic.com`으로 직접 전송되며 `ANTHROPIC_BASE_URL`을 따르지 않으므로, 직접 송신이 차단되면 확인이 실패합니다 | 송신이 차단된 경우 `api.anthropic.com`을 허용 목록에 추가하거나 건너뛰기 변수를 설정합니다. [프록시 및 LLM 게이트웨이 뒤에서 빠른 모드 사용](https://code.claude.com/docs/ko/fast-mode.md#use-fast-mode-behind-proxies-and-llm-gateways)을 참조하세요 |520| 추론 요청은 작동하는데 `/fast`가 `Fast mode unavailable due to network connectivity issues`를 보고함 | [빠른 모드](https://code.claude.com/docs/ko/fast-mode.md) 가용성 확인은 `api.anthropic.com`으로 직접 전송되며 `ANTHROPIC_BASE_URL`을 따르지 않으므로, 직접 송신이 차단되면 확인이 실패합니다 | 송신이 차단된 경우 `api.anthropic.com`을 허용 목록에 추가하거나 건너뛰기 변수를 설정합니다. [프록시 및 LLM 게이트웨이 뒤에서 빠른 모드 사용](https://code.claude.com/docs/ko/fast-mode.md#use-fast-mode-behind-proxies-and-llm-gateways)을 참조하세요 |
521| `ANTHROPIC_API_KEY`에 게이트웨이 발급 키를 사용해 인증하는 세션에서 `/fast`가 `Fast mode is currently unavailable`를 보고함 | `ANTHROPIC_BASE_URL`이 게이트웨이를 가리키고 키가 Anthropic API 키 형식이 아닌 동안에는 Claude Code가 [빠른 모드](https://code.claude.com/docs/ko/fast-mode.md) 가용성 확인을 보내지 않습니다. 이전에 성공한 확인이 캐시되어 있지 않으면 Claude Code는 빠른 모드를 사용할 수 없는 것으로 간주합니다 | `CLAUDE_CODE_SKIP_FAST_MODE_NETWORK_ERRORS=1`을 설정합니다. [프록시 및 LLM 게이트웨이 뒤에서 빠른 모드 사용](https://code.claude.com/docs/ko/fast-mode.md#use-fast-mode-behind-proxies-and-llm-gateways)을 참조하세요 |521| `ANTHROPIC_API_KEY`에 게이트웨이 발급 키를 사용해 인증하는 세션에서 `/fast`가 `Fast mode is currently unavailable`를 보고함 | `ANTHROPIC_BASE_URL`이 게이트웨이를 가리키고 키가 Anthropic API 키 형식이 아닌 동안에는 Claude Code가 [빠른 모드](https://code.claude.com/docs/ko/fast-mode.md) 가용성 확인을 보내지 않습니다. 이전에 성공한 확인이 캐시되어 있지 않으면 Claude Code는 빠른 모드를 사용할 수 없는 것으로 간주합니다 | `CLAUDE_CODE_SKIP_FAST_MODE_NETWORK_ERRORS=1`을 설정합니다. [프록시 및 LLM 게이트웨이 뒤에서 빠른 모드 사용](https://code.claude.com/docs/ko/fast-mode.md#use-fast-mode-behind-proxies-and-llm-gateways)을 참조하세요 |
522| 조직에서 빠른 모드를 활성화했는데도 `ANTHROPIC_AUTH_TOKEN`으로 인증한 세션에서 `/fast`가 `Fast mode has been disabled by your organization`를 보고함 | 가용성 확인에는 claude.ai 로그인 또는 API 키가 필요합니다. bearer 토큰만 있으면 Claude Code는 확인을 보내지 않고 빠른 모드를 비활성화된 것으로 간주합니다 | `CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK=1`을 설정합니다. [프록시 및 LLM 게이트웨이 뒤에서 빠른 모드 사용](https://code.claude.com/docs/ko/fast-mode.md#use-fast-mode-behind-proxies-and-llm-gateways)을 참조하세요 |522| 조직에서 빠른 모드를 활성화했는데도 `ANTHROPIC_AUTH_TOKEN`으로 인증한 세션에서 `/fast`가 `Fast mode has been disabled by your organization`를 보고함 | 가용성 확인에는 claude.ai 로그인 또는 API 키가 필요합니다. bearer 토큰만 있으면 Claude Code는 확인을 보내지 않고 빠른 모드를 비활성화된 것으로 간주합니다 | `CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK=1`을 설정합니다. [프록시 및 LLM 게이트웨이 뒤에서 빠른 모드 사용](https://code.claude.com/docs/ko/fast-mode.md#use-fast-mode-behind-proxies-and-llm-gateways)을 참조하세요 |
523| `ANTHROPIC_BASE_URL`을 사용하는 세션에서 `/feedback`이 로컬 파일을 저장함 | 게이트웨이 뒤에서는 `ANTHROPIC_AUTH_TOKEN`과 Anthropic API 키 형식이 아닌 키가 Anthropic 자격 증명이 아닙니다. Anthropic 자격 증명이 없으면 Claude Code는 보고서를 전송하지 않고 `~/.claude/feedback-bundles/` 아래의 로컬 아카이브에 기록합니다 | 파일을 Anthropic 계정 담당자에게 보내거나 지원 요청에 첨부합니다. [텔레메트리 서비스](https://code.claude.com/docs/ko/data-usage.md#telemetry-services)를 참조하세요 |
523| [curl 테스트](#verify-the-connection)가 성공하는데도 Claude Code가 로그인을 요청함 | CLI에 자체 자격 증명이 없습니다. 접근 가능한 기본 URL은 자격 증명이 아니며, 대화형 세션에서 프로젝트의 `.claude/settings.json` 또는 `.claude/settings.local.json`에 있는 `env` 블록은 최초 실행 마법사와 [신뢰 프롬프트](https://code.claude.com/docs/ko/permissions.md#what-runs-before-you-trust-a-folder) 이후에만 적용됩니다 | 최초 실행 설정 전에 Claude Code가 읽는 위치에 `ANTHROPIC_AUTH_TOKEN`을 설정합니다. 셸 export, `~/.claude/settings.json`의 `env` 블록 또는 관리형 설정을 사용할 수 있습니다 |524| [curl 테스트](#verify-the-connection)가 성공하는데도 Claude Code가 로그인을 요청함 | CLI에 자체 자격 증명이 없습니다. 접근 가능한 기본 URL은 자격 증명이 아니며, 대화형 세션에서 프로젝트의 `.claude/settings.json` 또는 `.claude/settings.local.json`에 있는 `env` 블록은 최초 실행 마법사와 [신뢰 프롬프트](https://code.claude.com/docs/ko/permissions.md#what-runs-before-you-trust-a-folder) 이후에만 적용됩니다 | 최초 실행 설정 전에 Claude Code가 읽는 위치에 `ANTHROPIC_AUTH_TOKEN`을 설정합니다. 셸 export, `~/.claude/settings.json`의 `env` 블록 또는 관리형 설정을 사용할 수 있습니다 |
524| `ANTHROPIC_API_KEY`가 설정되어 있지만 확인 요청 없이 무시됨 | 대화형 세션에서는 키에 대한 일회성 승인이 필요하며, 이전에 거부한 키는 다시 묻지 않고 무시됩니다 | `/config`에서 `Use custom API key` 옵션으로 활성화합니다 |525| `ANTHROPIC_API_KEY`가 설정되어 있지만 확인 요청 없이 무시됨 | 대화형 세션에서는 키에 대한 일회성 승인이 필요하며, 이전에 거부한 키는 다시 묻지 않고 무시됩니다 | `/config`에서 `Use custom API key` 옵션으로 활성화합니다 |
525| `This machine's managed settings require a first-party login`, 또는 관리형 설정이 `forceLoginMethod`를 `"gateway"`로 설정하거나 `forceLoginGatewayUrl`도 설정한 경우의 [`Administrator policy requires a Cloud gateway sign-in`](https://code.claude.com/docs/ko/errors#administrator-policy-requires-a-cloud-gateway-sign-in) | 관리형 설정에 `forceLoginMethod` 또는 `forceLoginOrgUUID`가 포함되어 있으며, 이는 `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN` 또는 `apiKeyHelper`와 함께 사용할 수 없습니다 | 게이트웨이 자격 증명을 사용하려면 관리자가 관리형 설정에서 `forceLoginMethod`, `forceLoginOrgUUID`, `forceLoginGatewayUrl`을 제거해야 합니다. 또는 게이트웨이 자격 증명을 제거하고 관리형 설정이 요구하는 로그인을 사용합니다. 두 가지를 함께 사용할 수는 없습니다 |526| `This machine's managed settings require a first-party login`, 또는 관리형 설정이 `forceLoginMethod`를 `"gateway"`로 설정하거나 `forceLoginGatewayUrl`도 설정한 경우의 [`Administrator policy requires a Cloud gateway sign-in`](https://code.claude.com/docs/ko/errors#administrator-policy-requires-a-cloud-gateway-sign-in) | 관리형 설정에 `forceLoginMethod` 또는 `forceLoginOrgUUID`가 포함되어 있으며, 이는 `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN` 또는 `apiKeyHelper`와 함께 사용할 수 없습니다 | 게이트웨이 자격 증명을 사용하려면 관리자가 관리형 설정에서 `forceLoginMethod`, `forceLoginOrgUUID`, `forceLoginGatewayUrl`을 제거해야 합니다. 또는 게이트웨이 자격 증명을 제거하고 관리형 설정이 요구하는 로그인을 사용합니다. 두 가지를 함께 사용할 수는 없습니다 |
