Anthropic 공식 Claude Code 확장(2.0+)은 VS Code settings.json에서 릴레이 URL을 직접 설정할 수 있어 시스템 환경 변수에 의존하지 않아도 됩니다. Windows / macOS / Linux에서 사용법은 동일합니다.

Cursor와 Windsurf는 VS Code 기반이므로 설정 방법이 같습니다.

1. 확장 설치

확장 패널에서 Claude Code를 검색해 Anthropic이 게시한 항목을 설치합니다.

2. settings.json 열기

명령 팔레트로 여는 것이 가장 확실하고 빠릅니다.

명령 팔레트 열기:
- Windows / Linux: Ctrl + Shift + P
- macOS: Cmd + Shift + P (⇧⌘P)
Preferences: Open User Settings (JSON) 입력 후 Enter.

Ctrl/Cmd + Shift + P가 동작하지 않으면(입력기 등에 가로채지는 경우 흔함) Ctrl + P / Cmd + P로 Quick Open을 연 뒤, 입력창 첫 글자에 >를 넣어 명령 팔레트로 전환하고 같은 명령을 검색하세요.

3. 설정 추가

settings.json 최상위 객체에 claudeCode.environmentVariables를 추가합니다.

{
  "claudeCode.environmentVariables": [
    { "name": "ANTHROPIC_BASE_URL", "value": "https://relay.4aicode.com" },
    { "name": "ANTHROPIC_AUTH_TOKEN", "value": "sk-4ai-xxxxxxxxxxxxxxxx" }
  ]
}

다른 설정이 있으면 병합하세요. 다른 키 아래에 중첩하지 마세요.

Claude Code 패널에서 ChatGPT gpt-5.6-sol과 extra-high reasoning을 쓰려면 모델·reasoning 변수도 추가:

{
  "claudeCode.environmentVariables": [
    { "name": "ANTHROPIC_BASE_URL", "value": "https://relay.4aicode.com" },
    { "name": "ANTHROPIC_AUTH_TOKEN", "value": "sk-4ai-xxxxxxxxxxxxxxxx" },
    { "name": "ANTHROPIC_DEFAULT_OPUS_MODEL", "value": "gpt-5.6-sol" },
    { "name": "ANTHROPIC_DEFAULT_OPUS_MODEL_NAME", "value": "4AICode GPT 5.6 Sol" },
    {
      "name": "ANTHROPIC_DEFAULT_OPUS_MODEL_SUPPORTED_CAPABILITIES",
      "value": "effort,xhigh_effort,thinking,adaptive_thinking,interleaved_thinking"
    },
    { "name": "ANTHROPIC_MODEL", "value": "opus" },
    { "name": "ANTHROPIC_DEFAULT_HAIKU_MODEL", "value": "gpt-5.4-mini" },
    { "name": "CLAUDE_CODE_EFFORT_LEVEL", "value": "xhigh" }
  ]
}

ANTHROPIC_DEFAULT_OPUS_MODEL은 Claude Code opus 별칭을 gpt-5.6-sol에 매핑하고, CLAUDE_CODE_EFFORT_LEVEL=xhigh는 extra-high reasoning에 해당합니다.

GPT-6 Astra는 ANTHROPIC_DEFAULT_OPUS_MODEL을 gpt-6-astra로; 표시 이름은 4AICode GPT 6 Astra로 설정할 수 있습니다.

게이트웨이는 요청된 gpt-* 또는 claude-* 모델명으로 업스트림을 선택합니다. 현재 가용성은 콘솔에서 확인하세요.

4. VS Code 재시작

완전히 종료 후 다시 실행(창만 닫으면 부족; 프로세스 시작 시 변수를 한 번만 읽음):

Windows: File → Exit / Alt + F4, 시스템 트레이·작업 관리자에서 Code.exe가 모두 종료됐는지 확인.
macOS: Cmd + Q
Linux: File → Exit

Cursor / Windsurf도 동일.

5. 확인

왼쪽 Claude Code 패널(확장 설치 후 Anthropic 아이콘)을 열고 ping을 보냅니다. 응답이 오면 연결 성공입니다.

이어 대시보드 → 사용 기록에서 해당 요청을 확인하세요.

FAQ

Q: 여전히 "Welcome to Claude Code" 로그인 화면이 나옵니다

세 버튼(Claude.ai Subscription / Anthropic Console / Bedrock)을 누르지 마세요. 누르면 공식 OAuth가 시작됩니다. 이후 claude logout으로 로컬 로그인 상태를 지워야 4AICode로 돌아올 수 있습니다. 흔한 원인:

claudeCode.environmentVariables 오타 또는 다른 키 아래 중첩 — settings.json 확인.
VS Code 완전 재시작 안 함 — 트레이·작업 관리자에서 Code.exe 모두 종료 후 재실행.
ANTHROPIC_AUTH_TOKEN 대신 ANTHROPIC_API_KEY 사용 — 2.0 확장은 후자를 더 잘 인식.

Q: Cursor 자체 Chat / Agent와 충돌하나요?

아니요. Claude Code는 별도 패널입니다. Cursor 내장 Chat / Agent / Tab은 Cursor 백엔드를 쓰므로 서로 영향 없습니다.

Q: Workspace 설정 vs User 설정?

User 수준(Preferences: Open User Settings (JSON))을 권장해 모든 프로젝트에서 공유. 한 프로젝트만 적용하려면 **Preferences: Open Workspace Settings (JSON)**으로 .vscode/settings.json에 작성.

⚠️ Workspace 설정을 git에 커밋하지 마세요. 토큰이 노출될 수 있습니다.

VS Code / Cursor / Windsurf에서 4AICode 사용

1. 확장 설치

2. settings.json 열기

3. 설정 추가

4. VS Code 재시작

5. 확인

FAQ