OpenRouter의 Ox Alpha를 내 컴퓨터에서 실행하는 가장 쉬운 방법

OpenRouter는 여러 회사의 AI 모델을 하나의 API 형식으로 호출할 수 있게 해 주는 중계 서비스입니다. 이 글에서는 OpenAI 호환 API를 이용해 stealth/ox-alpha 모델에 질문하고, 답변을 받아 화면에 출력하는 작은 프로그램을 만듭니다.

완성 후에는 터미널에서 다음처럼 실행할 수 있습니다.

python ox_alpha.py

그러면 프로그램이 Ox Alpha에 질문을 보내고 최종 답변을 출력합니다.

현재 OpenRouter 모델 페이지는 Ox Alpha를 무료 프리뷰 모델, 100만 토큰 문맥 길이를 가진 추론 모델로 소개하고 있습니다. 다만 프리뷰 모델은 가격·사용 한도·제공 여부가 바뀔 수 있으므로 실제 사용 전에는 Ox Alpha 모델 페이지를 다시 확인하십시오.

먼저 알아둘 핵심 세 가지

1. OpenRouter 계정과 API 키가 필요합니다. API 키는 AI 서비스를 호출할 때 사용하는 비밀번호와 같습니다.
2. API 키를 코드에 직접 적지 않습니다. 별도의 .env 파일에 저장하고, 이 파일은 GitHub에 올리지 않습니다.
3. 민감한 정보를 입력하지 않습니다. Ox Alpha는 익명의 제3자 제공자가 운영하는 스텔스 프리뷰 모델입니다. OpenRouter의 현재 안내에 따르면 이 모델의 프롬프트와 응답은 제공자에게 보관됩니다. 학생 이름, 전화번호, 상담 기록, 성적표, 미공개 시험지, 주민등록번호 같은 개인정보·기밀자료는 보내지 마십시오.

전체 과정 한눈에 보기

OpenRouter 가입 → API 키 발급 → Python 프로젝트 생성 → 패키지 설치 → .env에 키 저장 → Ox Alpha 호출 → 답변 확인 순서입니다.

python --version

py --version

python3 --version

mkdir openrouter-ox-alpha
cd openrouter-ox-alpha

mkdir openrouter-ox-alpha
cd openrouter-ox-alpha

openrouter-ox-alpha/
├── .env
├── .gitignore
└── ox_alpha.py

code .

python -m venv .venv
.\.venv\Scripts\Activate.ps1

py -m venv .venv
.\.venv\Scripts\Activate.ps1

.venv\Scripts\activate.bat

python3 -m venv .venv
source .venv/bin/activate

python -m pip install --upgrade pip
python -m pip install openai python-dotenv

OPENROUTER_API_KEY=sk-or-v1-여기에_본인의_실제_키를_붙여넣으세요

.env
.venv/
__pycache__/

import os
from dotenv import load_dotenv
from openai import OpenAI

# 같은 폴더의 .env 파일을 읽습니다.
load_dotenv()

api_key = os.getenv("OPENROUTER_API_KEY")
if not api_key:
    raise RuntimeError(
        "OPENROUTER_API_KEY를 찾지 못했습니다. .env 파일명과 내용을 확인하세요."
    )

# OpenAI SDK가 OpenRouter 주소로 요청을 보내도록 설정합니다.
client = OpenAI(
    base_url="https://openrouter.ai/api/v1",
    api_key=api_key,
)

response = client.chat.completions.create(
    model="stealth/ox-alpha",
    messages=[
        {
            "role": "system",
            "content": "당신은 초보자에게 친절하게 설명하는 한국어 튜터입니다.",
        },
        {
            "role": "user",
            "content": "영어 단어 strawberry에는 r이 몇 개 있나요? 글자를 하나씩 세어 설명해 주세요.",
        },
    ],
    max_tokens=500,
    extra_body={
        "reasoning": {
            "enabled": True,
        }
    },
)

message = response.choices[0].message

# 모델·제공자에 따라 reasoning 또는 reasoning_details가 없거나,
# 요약·암호화된 형태로만 반환될 수 있습니다.
reasoning_details = getattr(message, "reasoning_details", None)
reasoning_text = getattr(message, "reasoning", None)

if reasoning_details:
    print("\n[추론 정보]")
    print(reasoning_details)
elif reasoning_text:
    print("\n[추론 정보]")
    print(reasoning_text)

print("\n[최종 답변]")
print(message.content)

python ox_alpha.py

python3 ox_alpha.py

import os
from dotenv import load_dotenv
from openai import OpenAI

load_dotenv()

api_key = os.getenv("OPENROUTER_API_KEY")
if not api_key:
    raise RuntimeError(".env에서 OPENROUTER_API_KEY를 찾지 못했습니다.")

client = OpenAI(
    base_url="https://openrouter.ai/api/v1",
    api_key=api_key,
)

stream = client.chat.completions.create(
    model="stealth/ox-alpha",
    messages=[
        {
            "role": "user",
            "content": "회상 연습이 공부에 도움이 되는 이유를 중학생도 이해하게 설명해 주세요.",
        }
    ],
    max_tokens=800,
    stream=True,
    stream_options={"include_usage": True},
    extra_body={
        "reasoning": {
            "enabled": True,
        }
    },
)

print("\n[Ox Alpha 답변]\n")

for chunk in stream:
    if chunk.choices:
        content = chunk.choices[0].delta.content
        if content:
            print(content, end="", flush=True)

    # 사용량 정보가 포함된 마지막 청크가 오면 요약해서 보여 줍니다.
    if chunk.usage:
        print("\n\n[사용량]")
        print(chunk.usage.model_dump())

print()

python ox_alpha_stream.py

설치 없이 API 연결만 1분 만에 확인하기

Python 프로젝트를 만들기 전에 API 키와 모델이 작동하는지만 확인하고 싶다면 터미널에서 직접 요청할 수 있습니다.

macOS·Linux

현재 터미널 세션에 키를 등록합니다.

export OPENROUTER_API_KEY="sk-or-v1-본인의_실제_키"

그다음 요청합니다.

curl -N https://openrouter.ai/api/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -d '{
    "model": "stealth/ox-alpha",
    "stream": true,
    "messages": [
      {"role": "user", "content": "안녕하세요. 한 문장으로 자기소개해 주세요."}
    ]
  }'

Windows PowerShell

$env:OPENROUTER_API_KEY="sk-or-v1-본인의_실제_키"

PowerShell에서는 다음 명령으로 요청합니다.

$headers = @{
    "Authorization" = "Bearer $env:OPENROUTER_API_KEY"
    "Content-Type"  = "application/json"
}

$body = @{
    model = "stealth/ox-alpha"
    messages = @(
        @{
            role = "user"
            content = "안녕하세요. 한 문장으로 자기소개해 주세요."
        }
    )
} | ConvertTo-Json -Depth 5

$response = Invoke-RestMethod `
    -Uri "https://openrouter.ai/api/v1/chat/completions" `
    -Method Post `
    -Headers $headers `
    -Body $body

$response.choices[0].message.content

PowerShell 예제는 이해하기 쉽게 비스트리밍 방식으로 작성했습니다.

TypeScript로 실행하고 싶은 경우

Python 대신 Node.js를 사용한다면 Node.js 공식 사이트에서 Node.js를 설치한 뒤 다음 순서로 진행합니다.

1. 프로젝트 만들기

mkdir openrouter-ox-alpha-ts
cd openrouter-ox-alpha-ts
npm init -y
npm install @openrouter/sdk dotenv

2. .env 만들기

OPENROUTER_API_KEY=sk-or-v1-여기에_본인의_실제_키를_붙여넣으세요

3. index.mjs 만들기

import "dotenv/config";
import { OpenRouter } from "@openrouter/sdk";

const apiKey = process.env.OPENROUTER_API_KEY;

if (!apiKey) {
  throw new Error(".env에서 OPENROUTER_API_KEY를 찾지 못했습니다.");
}

const openrouter = new OpenRouter({ apiKey });

const stream = await openrouter.chat.send({
  model: "stealth/ox-alpha",
  messages: [
    {
      role: "user",
      content: "영어 단어 strawberry에는 r이 몇 개 있나요?",
    },
  ],
  reasoning: {
    enabled: true,
  },
  stream: true,
});

for await (const chunk of stream) {
  const content = chunk.choices[0]?.delta?.content;
  if (content) {
    process.stdout.write(content);
  }

  if (chunk.usage) {
    console.log("\n\nUsage:", chunk.usage);
  }
}

4. 실행하기

node index.mjs

현재 공식 OpenRouter SDK 문서는 chat.send({ model, messages, ... }) 형식을 사용합니다. 모델 페이지의 자동 생성 예제에서 chat.send({ chatRequest: { ... } })처럼 보일 때는 설치된 SDK 버전과 문서 버전이 다른지 먼저 확인하십시오. 이 글의 예제는 2026년 8월 22일 기준 공식 Client SDK 문서의 형식에 맞췄습니다.

reasoning과 reasoning_details를 정확히 이해하기

reasoning을 활성화했다고 해서 모든 모델이 완전한 내부 사고 과정을 그대로 공개하는 것은 아닙니다.

• 모델·제공자에 따라 추론 텍스트가 반환될 수 있습니다.
• 추론 요약만 반환될 수 있습니다.
• 암호화된 블록이 반환될 수 있습니다.
• 추론 정보가 전혀 반환되지 않을 수도 있습니다.

추론 토큰은 일반적으로 출력 토큰 사용량에 포함됩니다. 유료 모델에서는 비용에 영향을 줄 수 있습니다.

따라서 사용자 화면에는 최종 답변을 기본으로 보여 주고, reasoning 데이터는 디버깅이나 고급 에이전트 구현에 필요한 경우에만 다루는 편이 안전합니다. 자세한 형식은 OpenRouter Reasoning Tokens 문서를 참고하십시오.

대화를 이어 갈 때

도구 호출을 포함한 고급 다중 턴 대화에서 모델이 reasoning_details를 반환했다면 다음 요청에 순서와 내용을 바꾸지 않고 그대로 포함해야 추론 문맥을 보존할 수 있습니다. 내용을 편집하거나 일부만 골라 넣으면 안 됩니다.

일반적인 단일 질문·답변 프로그램에서는 처음부터 이 기능을 구현할 필요가 없습니다.

세 가지 API 엔드포인트는 언제 쓰나

OpenRouter가 여러 호환 형식을 제공하더라도 한 요청에서 형식을 섞으면 안 됩니다.

처음 시작한다면 https://openrouter.ai/api/v1/chat/completions 하나만 익히면 충분합니다.

선택 사항: 앱 이름을 OpenRouter에 표시하기

다음 헤더는 인증에 필수는 아닙니다.

• HTTP-Referer: 앱이나 사이트 주소
• X-OpenRouter-Title: 앱 이름

OpenAI Python SDK에서 사용하려면 클라이언트를 다음처럼 만들 수 있습니다.

client = OpenAI(
    base_url="https://openrouter.ai/api/v1",
    api_key=api_key,
    default_headers={
        "HTTP-Referer": "https://example.com",
        "X-OpenRouter-Title": "My Ox Alpha App",
    },
)

개인 연습이라면 두 헤더를 생략해도 됩니다.

자주 발생하는 오류와 해결법

OpenRouter의 현재 오류 코드 설명은 Errors and Debugging 문서에서 확인할 수 있습니다.

.env를 찾지 못할 때

다음을 확인하십시오.

• 터미널의 현재 위치가 프로젝트 폴더인지 확인합니다.
• 파일명이 .env.txt가 아닌 .env인지 확인합니다.
• 변수명이 정확히 OPENROUTER_API_KEY인지 확인합니다.
• python-dotenv가 설치되어 있는지 확인합니다.

현재 폴더를 확인하는 명령은 다음과 같습니다.

pwd

Windows PowerShell에서는 다음 명령도 사용할 수 있습니다.

Get-Location

PowerShell에서 가상환경이 활성화되지 않을 때

가장 쉬운 우회 방법은 명령 프롬프트에서 다음을 실행하는 것입니다.

.venv\Scripts\activate.bat

가상환경을 활성화하지 않고도 해당 가상환경의 Python을 직접 지정할 수 있습니다.

.\.venv\Scripts\python.exe ox_alpha.py

운영에 사용하기 전 체크리스트

• API 키를 코드에 직접 적지 않았다.
• .env를 .gitignore에 추가했다.
• 키별 사용 한도 또는 예산을 설정했다.
• 학생·학부모 개인정보를 프롬프트에 넣지 않는다.
• 모델 가격과 제공 여부를 다시 확인한다.
• 429와 5xx 오류에 재시도·대체 모델 전략을 마련한다.
• AI 답변을 사실 검증 없이 자동 공개하지 않는다.
• 프리뷰 모델을 중요한 운영 시스템의 유일한 모델로 의존하지 않는다.

핵심 매개변수 빠른 설명

temperature, top_p, top_k를 동시에 과도하게 조정하면 결과를 이해하기 어려워집니다. 처음에는 기본값으로 시작하고 하나씩 바꾸는 것이 좋습니다.

다음 단계

첫 요청이 성공했다면 다음 순서로 확장해 보십시오.

1. input()으로 사용자의 질문을 받는 터미널 챗봇 만들기
2. 대화 내용을 messages 배열에 누적해 다중 턴 대화 만들기
3. response_format으로 JSON 출력 받기
4. 함수 호출용 tools 추가하기
5. Streamlit·Gradio·웹 앱에 연결하기
6. 시간 초과, 재시도, 로깅, 사용량 제한 추가하기

가장 중요한 출발점은 단순합니다. 키를 안전하게 보관하고, 하나의 요청을 성공시킨 뒤, 기능을 하나씩 늘리십시오.

공식 자료

• OpenRouter Quickstart
• Ox Alpha 모델 페이지
• API 키 생성
• OpenRouter Client SDKs
• Reasoning Tokens
• API Reference
• Errors and Debugging