오픈라우터 설정

1. 문서 범위

이 문서는 아래 도구에서 OpenRouter를 바로 쓰기 위한 설정 가이드입니다.

사용 가능

• Codex
• Claude CLI
• Cursor
• OpenCode
• Careti

사용 불가능 (지금은 OpenRouter에 바로 연결할 수 없는 도구)

• Gemini CLI
• Windsurf
• Antigravity

2. 도구 공통 입력값

도구마다 설정 UI 이름은 다르지만, 아래 3가지는 공통으로 필요합니다.

• API Key: 발급받은 OpenRouter Key
• Base URL: 기본 https://openrouter.ai/api/v1 (Claude Code는 https://openrouter.ai/api)
• Model ID: 사용 가능한 모델 목록은 OpenRouter Models에서 확인

3. 도구별 설정 가이드

3.1 Codex

1) codex-cli (@openai/codex)

지원 형태

• 가능: Codex CLI는 config.toml에서 커스텀 provider를 정의해 프록시/라우터(OpenRouter 포함)로 보낼 수 있습니다.
• 또한 OPENAI_BASE_URL로 기본 OpenAI provider의 엔드포인트를 프록시로 오버라이드할 수도 있습니다.

설정 위치

• 유저 설정: ~/.codex/config.toml (기본 CODEX_HOME=~/.codex)
• 프로젝트 설정(선택): .codex/config.toml (repo 내부)

방법 A: 커스텀 provider로 OpenRouter 추가 (권장)

1. 환경변수에 키 저장

Copyexport OPENROUTER_API_KEY="<your-openrouter-api-key>"

2. ~/.codex/config.toml에 provider 추가

Copymodel = "openai/gpt-5.2"
model_provider = "openrouter"
 
[model_providers.openrouter]
name = "OpenRouter"
base_url = "https://openrouter.ai/api/v1"
env_key = "OPENROUTER_API_KEY"
 
# 필요 시 wire_api(도구/버전에 따라) 설정 가능
# wire_api = "chat"

• Codex가 provider를 "base URL + wire API + optional headers"로 정의한다는 구조가 핵심입니다.

방법 B: 기본 OpenAI provider를 OpenRouter로 "URL만" 교체

Copyexport OPENAI_BASE_URL="https://openrouter.ai/api/v1"
export OPENAI_API_KEY="<your-openrouter-api-key>"
codex

• OPENAI_BASE_URL로 기본 엔드포인트를 바꿀 수 있습니다.

3.2 Claude Code

지원 형태

• 가능: Claude Code는 환경변수 기반으로 OpenRouter 연결을 구성할 수 있습니다.
• 또한 settings.json의 env 필드에 같은 값을 넣는 파일 기반 설정도 지원합니다.
• OpenRouter 연결 시 충돌 방지를 위해 ANTHROPIC_API_KEY를 반드시 ""로 명시해야 합니다.

OpenRouter 연결 설정 (필수 환경변수 4개)

OpenRouter 문서 기준 핵심 조건은 아래 3가지입니다.

1. Base URL: https://openrouter.ai/api
2. Auth token: OpenRouter API Key를 ANTHROPIC_AUTH_TOKEN으로 설정
3. 충돌 방지: ANTHROPIC_API_KEY를 명시적으로 빈 문자열("")로 설정

권장 변수 세트:

Copyexport OPENROUTER_API_KEY="<your-openrouter-api-key>"
export ANTHROPIC_BASE_URL="https://openrouter.ai/api"
export ANTHROPIC_AUTH_TOKEN="$OPENROUTER_API_KEY"
export ANTHROPIC_API_KEY="" # 중요: 반드시 빈 문자열

• OpenRouter 문서 기준으로 설치기는 표준 .env 파일을 읽지 않으므로, 셸 프로필 또는 설정 파일을 사용합니다.

방법 A: 셸 프로필에 영구 적용 (가장 단순)

zsh (macOS 기본)

1. 프로필 편집

Copynano ~/.zshrc

2. 아래 변수 추가

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

3. 적용

Copysource ~/.zshrc

bash

Copynano ~/.bashrc   # 또는 ~/.bash_profile (환경에 따라)

• 변수 추가/적용 절차는 zsh와 동일합니다.

fish

• 권장 위치: ~/.config/fish/config.fish

Copyset -x OPENROUTER_API_KEY "<your-openrouter-api-key>"
set -x ANTHROPIC_BASE_URL "https://openrouter.ai/api"
set -x ANTHROPIC_AUTH_TOKEN $OPENROUTER_API_KEY
set -x ANTHROPIC_API_KEY ""

방법 B: Claude Code 설정 파일(settings.json)에 env 구성 (파일 기반)

Claude Code는 settings.json의 env 필드로 세션별 환경변수를 주입할 수 있습니다.

설정 스코프:

• 사용자 전역: ~/.claude/settings.json
• 프로젝트 공유(커밋됨): .claude/settings.json
• 프로젝트 로컬(개인용, gitignored): .claude/settings.local.json

키를 커밋하지 않으려면 보통 ~/.claude/settings.json 또는 .claude/settings.local.json을 사용합니다.

예시: ~/.claude/settings.json

Copy{
  "env": {
    "OPENROUTER_API_KEY": "<your-openrouter-api-key>",
    "ANTHROPIC_BASE_URL": "https://openrouter.ai/api",
    "ANTHROPIC_AUTH_TOKEN": "<your-openrouter-api-key>",
    "ANTHROPIC_API_KEY": ""
  }
}

• JSON 내부에서는 변수 참조를 직접 쓰기 어렵기 때문에 ANTHROPIC_AUTH_TOKEN에 키를 다시 명시하는 구성을 권장합니다.
• 핵심은 ANTHROPIC_API_KEY를 ""로 명시적으로 비우는 것입니다.

Windows에서 설정 (PowerShell)

A) 현재 PowerShell 세션에서만 적용

Copy$env:OPENROUTER_API_KEY = "<your-openrouter-api-key>"
$env:ANTHROPIC_BASE_URL = "https://openrouter.ai/api"
$env:ANTHROPIC_AUTH_TOKEN = $env:OPENROUTER_API_KEY
$env:ANTHROPIC_API_KEY = ""

B) 영구 적용

• System Properties -> Advanced -> Environment Variables로 이동합니다.
• User variables에 4개 변수를 추가합니다.
• 터미널을 재시작해 변경을 반영합니다.

Claude Code 실행

Copycd /path/to/your/project
claude

연결 검증 (중요)

Claude Code 내에서 아래 명령으로 연결 상태를 확인합니다.

Copy/status

정상 연결 시 확인 포인트:

• Auth token: ANTHROPIC_AUTH_TOKEN
• Anthropic base URL: https://openrouter.ai/api
• OpenRouter Activity Dashboard에 요청 로그가 기록되는지 확인

자주 나는 문제 / 해결

1. Anthropic 기본 경로로 붙거나 인증 오류가 나는 경우
   • ANTHROPIC_API_KEY가 unset이면 기본 동작으로 돌아갈 수 있으므로 ANTHROPIC_API_KEY=""를 명시합니다.
   • 이전 Anthropic 로그인 상태가 남아 있으면 /logout 후 다시 시도합니다.
2. 환경변수가 적용되지 않는 경우
   • 셸 프로필 수정 후 터미널 재시작이 필요할 수 있습니다.
   • 값 확인: macOS/Linux는 echo $ANTHROPIC_API_KEY, PowerShell은 echo $env:ANTHROPIC_API_KEY.
3. Claude.ai 구독이 있어도 API 과금이 발생하는 경우
   • Claude Code는 환경변수 API 키가 있으면 구독 로그인보다 우선하므로 OpenRouter 연결 목적에서는 정상 동작입니다.

3.3 Cursor

지원 형태

• 가능: Cursor는 OpenAI API Key + Base URL override 방식으로 OpenRouter를 연결할 수 있습니다.

설정 방법(OpenRouter 안내)

Cursor에서 아래 순서로 진행합니다.

1. Settings -> Cursor Settings -> Models
2. API Keys 섹션에서 아래 항목을 설정합니다.
   • OpenAI API Key 활성화
   • OpenRouter 키 입력
   • Override OpenAI Base URL 활성화
   • Base URL을 https://openrouter.ai/api/v1로 설정
3. 모델 추가에서 OpenRouter 모델을 선택해 사용합니다.
   • 예시: OpenRouter Cursor 안내

3.4 OpenCode

지원 형태

• 가능: OpenCode는 /connect 명령으로 OpenRouter provider를 연결할 수 있습니다.
• 또한 /models로 기본 모델을 선택하고, opencode.json으로 모델 목록/라우팅 옵션을 확장할 수 있습니다.

설정 방법(OpenCode 안내)

1. OpenCode에서 /connect를 실행합니다.

Copy/connect

2. provider 목록에서 OpenRouter를 검색해 선택합니다.
3. API Key 입력 화면에서 OpenRouter 키를 입력합니다.

Copy┌ API key
│
│
└ enter

4. 연결 후 /models를 실행해 원하는 모델을 선택합니다.

Copy/models

opencode.json으로 모델 추가

필요한 모델이 기본 목록에 없으면 opencode.json으로 추가할 수 있습니다.

Copy{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "openrouter": {
      "models": {
        "somecoolnewmodel": {}
      }
    }
  }
}

opencode.json으로 provider 라우팅 옵션 지정

모델별 provider 우선순위(order)와 fallback 허용 여부도 설정할 수 있습니다.

Copy{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "openrouter": {
      "models": {
        "moonshotai/kimi-k2": {
          "options": {
            "provider": {
              "order": ["baseten"],
              "allow_fallbacks": false
            }
          }
        }
      }
    }
  }
}

3.5 Careti

Careti 설정의 모델/프로바이더 영역에서 아래를 입력합니다.

• API Key: OpenRouter Key
• Base URL: https://openrouter.ai/api/v1
• Model: 사용할 OpenRouter 모델 ID

Careti 모델 선택 관련 상세 문서: Careti 모델 선택 가이드 문서 보기

3.6 현재 지원 불가능한 도구

• Gemini CLI: OpenRouter API Key를 직접 입력해 연결하는 방식은 현재 지원하지 않습니다.
• Windsurf: OpenRouter API Key를 직접 입력해 연결하는 방식은 현재 지원하지 않습니다.
• Antigravity: OpenRouter API Key를 직접 입력해 연결하는 방식은 현재 지원하지 않습니다.

4. 연결 확인 체크리스트

• 도구에서 간단한 프롬프트(예: "연결 테스트")를 실행해 정상 응답을 확인합니다.
• 401 오류가 나면 API Key 오입력 여부를 확인합니다.
• 404/모델 오류가 나면 Model ID와 Base URL을 다시 확인합니다.

5. 보안 및 운영 주의사항

• 키는 반드시 환경변수 또는 비밀 저장소로만 관리합니다.
• 키를 공유해야 할 경우 새 키를 재발급하고 기존 키는 즉시 폐기합니다.
• 비용 관리를 위해 기본 모델은 경량 모델로 시작하는 것을 권장합니다.