여러분은 사람들이 Claude Code에 대해 극찬하는 것을 들어보셨을 것입니다. 아마도 OpenRouter가 같은 맥락에서 언급되는 것도 들어보셨을 텐데, 대개 환경 변수(environment variables)의 조합과 터미널 스크린샷이 뒤따르곤 합니다. 만약 이 모든 것이 처음이라면, 마치 모든 사람이 단계를 건너뛰고 바로 전문 용어로 뛰어든 것처럼 느껴질 수 있습니다.

이 가이드는 그 빠진 단계입니다. 중요한 부분에서는 천천히 진행하고, 혼란스러운 부분들을 설명할 것이며, 마지막에는 단순히 명령어를 복사해서 붙여넣고 요행을 바라는 대신 실제로 어떤 일이 일어나고 있는지 이해하게 될 것입니다.

두 가지 요소, 빠르게 살펴보기

**Claude Code**는 Anthropic의 터미널 코딩 에이전트 (terminal coding agent)입니다. 파일 내용을 읽고, 코드를 수정하며, 명령어를 실행합니다. 기본적으로 Anthropic의 서버와 직접 통신합니다.

**OpenRouter**는 교환기 (switchboard)입니다. AI 모델들을 위한 교환기입니다. 모든 앱이 각 AI 제공업체와 개별적인 연결을 가질 필요 없이, OpenRouter가 중간에 위치하여 하나의 계정, 하나의 대시보드, 그리고 하나의 지출 관리 창구를 통해 다양한 모델로 요청을 라우팅(route)할 수 있게 해줍니다. (심지어 무료 및 오픈 소스 모델도 가능합니다!)

OpenRouter에서 제공하는 모든 모델은 여기에서 확인할 수 있습니다.

중요한 정직한 확인 사항: OpenRouter의 자체 문서에 따르면, 이 조합은 Anthropic의 자체 모델에서만 원활하게 작동하는 것이 보장됩니다. 여기서 여러분은 Claude의 두뇌를 실제로 교체하는 것이 아니라, 주로 그것이 통신하는 통로를 재라우팅(rerouting)하는 것입니다.

빠른 어휘 확인: "OpenAI 호환 (OpenAI compatible)"

Claude Code는 Anthropic의 형식으로 요청을 보냅니다. 어떤 서버들은 대신 OpenAI의 형식만을 이해합니다. 실수로 Claude Code를 그런 서버 중 하나로 지정하면, 스페인어만 읽을 수 있는 사람에게 프랑스어 편지를 보내는 것처럼 엉망이 된 에러를 받게 됩니다.

OpenRouter는 Anthropic의 형식을 네이티브하게 지원하는 엔드포인트 (endpoint)를 가지고 있어, 별도의 번역 단계나 별도의 프록시 (proxy)가 필요하지 않습니다.

잠깐, zsh를 써야 하나요 bash를 써야 하나요? 제가 그걸 어떻게 알죠?

이 질문은 이 가이드에서 그 어떤 것보다 더 많은 초보자들을 멈칫하게 만듭니다. 그리고 이는 충분히 합리적인 질문입니다. 10초 만에 확인하는 방법은 다음과 같습니다.

터미널을 열고 다음을 입력한 뒤 엔터를 누르세요:

echo $SHELL

다음 중 하나가 출력될 것입니다:

• /bin/zsh와 같이 /zsh로 끝나는 결과가 나온다면, zsh를 사용 중이라는 의미입니다. 이는 최신 Mac의 기본값입니다.
• /bin/bash와 같이 /bash로 끝나는 결과가 나온다면, bash를 사용 중이라는 의미입니다. 이는 구형 Mac, 많은 Linux 설정, 그리고 Windows Subsystem for Linux (WSL)에서 흔히 볼 수 있습니다.

그게 전부입니다. 화면에 나타나는 것에 따라 나중에 편집해야 할 파일이 결정됩니다:

• zsh 사용자는 ~/.zshrc를 편집합니다.
• bash 사용자는 ~/.bashrc를 편집합니다.

설정 (Setup)

1. Claude Code 설치

curl -fsSL https://claude.ai/install.sh | bash

2. OpenRouter API 키 확보
openrouter.ai에서 API 키를 가져오고, 약간의 크레딧을 충전하세요.

3. 쉘 파일에 추가 (위에서 찾은 파일)
내용을 추가한 뒤 터미널을 재시작하세요:

export OPENROUTER_API_KEY="your-openrouter-api-key"
export ANTHROPIC_BASE_URL="https://openrouter.ai/api"
export ANTHROPIC_AUTH_TOKEN="$OPENROUTER_API_KEY"
...

마지막 줄은 오타가 아니라 의도된 것입니다. 해당 위치에 오래된 값이 있으면 혼란스러운 인증 (auth) 에러가 발생할 수 있습니다. 또한, 이 줄들을 파일의 끝부분 근처에 배치하세요. 그렇지 않으면 나중에 OPENROUTER_API_KEY가 재정의될 경우, 토큰이 조용히 빈 값으로 처리될 수 있습니다.

프로젝트별로 유지하는 것을 선호하시나요? 대신 설정 (settings) 파일을 사용하세요:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://openrouter.ai/api",
...

4. 이전 로그인 정보 삭제

/logout

그 다음 Claude Code를 완전히 재시작하세요.

5. 실행

cd /path/to/your/project
claude

6. 작동 확인

/status

ANTHROPIC_AUTH_TOKEN과 OpenRouter의 베이스 URL (base URL)이 표시되어야 합니다. 활동 대시보드 (activity dashboard)도 확인해 보세요. 요청이 나타나는 것을 보는 것은 묘하게 만족감을 줍니다.

이제 시작할 준비가 되었습니다. 다양한 모델 라인업이 차례를 기다리고 있는 Claude Code와 함께 말이죠!

요약 (Bottom line)

Claude Code를 설치하고, OpenRouter 키를 발급받은 뒤, 적절한 파일에 네 가지 환경 변수 (env vars)를 설정하세요. 그 다음 /logout을 입력하고 다시 실행한 뒤, /status로 확인하면 끝입니다. 10분이면 충분합니다. 우선은 Claude 모델들을 중심으로 사용해 보고, 무엇이