Skip to main content
Tilnote
달의이성
달의이성
공개 노트

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

Views 493약 11분생성형 AI 활용

Python·Windows 초보자도 따라 하는 10분 설치 튜토리얼
확인 기준: 2026년 8월 22일

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

완성 후에는 터미널이라는 명령 입력 창에서 다음 한 줄을 실행합니다. Windows 사용자는 이 글에서 기본적으로 Windows PowerShell을 사용합니다.

python ox_alpha.py

그러면 프로그램이 Ox Alpha에 질문을 보내고 최종 답변을 출력합니다. “터미널이 무엇인지”, “CMD와 PowerShell 중 무엇을 열어야 하는지”를 모르더라도 괜찮습니다. 바로 아래의 ox_alpha.py 파일 만들기부터 화면을 보듯이 따라가면 됩니다.

가장 먼저 할 일: ox_alpha.py 파일부터 만들기

현재 PowerShell 화면이 다음처럼 보인다고 가정하겠습니다.

PS C:Userssound>

아직 python ox_alpha.py를 실행하면 안 됩니다. 먼저 프로그램 본체인 ox_alpha.py 파일을 실제로 만들어야 합니다. 다음 과정은 Windows PowerShell에서 그대로 따라 하는 가장 짧은 완성 경로입니다.

1. 프로그램을 보관할 폴더 만들기

PowerShell에 다음 세 줄을 한 줄씩 입력합니다.

cd $HOME
New-Item -ItemType Directory -Path "openrouter-ox-alpha" -Force | Out-Null
cd .openrouter-ox-alpha

현재 위치를 확인합니다.

Get-Location

다음과 비슷하게 표시되면 맞습니다.

Path
----
C:Userssoundopenrouter-ox-alpha

2. ox_alpha.py 만들기

다음 명령을 입력합니다.

notepad .ox_alpha.py

“새 파일을 만드시겠습니까?”가 나오면 예를 누릅니다. 메모장이 열리면 아래 Python 코드를 처음부터 끝까지 복사해 붙여넣으십시오.

import os

from dotenv import load_dotenv
from openai import OpenAI

# 현재 폴더의 .env 파일에서 API 키를 읽습니다.
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,
        }
    },
)

print("n[Ox Alpha의 최종 답변]")
print(response.choices[0].message.content)

메모장에서 Ctrl + S를 눌러 저장하고 창을 닫습니다.

PowerShell로 돌아와 파일이 만들어졌는지 확인합니다.

Get-ChildItem .ox_alpha.py

ox_alpha.py가 표시되면 성공입니다. 만약 ox_alpha.py.txt로 저장되었다면 다음 명령으로 고칩니다.

Rename-Item .ox_alpha.py.txt ox_alpha.py

3. API 키를 넣을 .env 파일 만들기

다음 명령을 입력합니다.

notepad ..env

아직 API 키가 없다면 OpenRouter API Keys 페이지에서 먼저 발급받습니다. 메모장에 다음 한 줄을 넣되, 오른쪽 부분은 발급받은 본인의 실제 키로 바꿉니다.

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

Ctrl + S로 저장하고 메모장을 닫습니다. 실제 API 키를 채팅, 블로그, 캡처 화면, GitHub에 공개하면 안 됩니다.

4. 이 프로그램에 필요한 패키지 설치하기

PowerShell에 다음 세 줄을 한 줄씩 입력합니다.

python -m venv .venv
..venvScriptspython.exe -m pip install --upgrade pip
..venvScriptspython.exe -m pip install openai python-dotenv

여기서는 가상환경 활성화 명령을 일부러 사용하지 않았습니다. 가상환경 안의 Python을 직접 지정하므로 PowerShell 실행 정책 오류를 피할 수 있습니다.

5. Ox Alpha 프로그램 실행하기

이제 다음 명령을 입력합니다.

..venvScriptspython.exe .ox_alpha.py

정상이라면 다음과 비슷한 결과가 나옵니다.

[Ox Alpha의 최종 답변]
strawberry에는 r이 3개 있습니다.

다음 날 PowerShell을 새로 열었을 때는 아래 두 줄만 입력하면 다시 실행할 수 있습니다.

cd "$HOMEopenrouter-ox-alpha"
..venvScriptspython.exe .ox_alpha.py

가장 중요한 원칙: python ox_alpha.py는 파일을 자동으로 만들어 주는 명령이 아닙니다. 이미 만들어진 ox_alpha.py를 실행하는 명령입니다. 따라서 파일 생성과 저장이 반드시 먼저입니다.

현재 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 호출 → 답변 확인 순서입니다.

0단계: 터미널이 무엇인지부터 알아보기

터미널이란?

터미널은 마우스로 버튼을 누르는 대신, 컴퓨터에 글자로 명령을 입력하는 창입니다. Python 설치 확인, 폴더 만들기, 패키지 설치, 프로그램 실행을 모두 이 창에서 합니다.

이 글에서 말하는 터미널은 운영체제에 따라 다음 프로그램을 뜻합니다.

image

Windows에서는 CMD와 PowerShell 중 무엇을 열어야 하나요?

이 튜토리얼에서는 PowerShell을 권장합니다.

  • PowerShell을 열면 줄 앞부분이 보통 PS C:Users사용자이름>처럼 보입니다.

  • CMD를 열면 보통 C:Users사용자이름>처럼 보입니다.

  • 두 프로그램은 비슷하지만 가상환경을 켜는 명령 등이 조금 다릅니다.

  • 이 글에서 제목이 Windows PowerShell인 코드 상자는 PowerShell에 입력하십시오.

  • 제목이 Windows 명령 프롬프트(CMD)인 코드 상자만 CMD에 입력하십시오.

처음이라면 두 창을 번갈아 쓰지 말고 PowerShell 하나로 끝까지 진행하는 것이 가장 쉽습니다.

Windows PowerShell 여는 방법

  1. 키보드에서 Windows 키를 누릅니다.

  2. PowerShell이라고 입력합니다.

  3. 검색 결과에서 Windows PowerShell을 클릭합니다.

  4. 파란색 또는 검은색 창이 열리고 다음과 비슷한 글자가 보이면 성공입니다.

Windows PowerShell
PS C:Usersminhee>

관리자 권한으로 실행할 필요는 없습니다. 일반 PowerShell 창이면 충분합니다.

Windows 11에서 Windows Terminal이 열려도 괜찮습니다. 탭 제목이 PowerShell이고 줄 앞에 PS가 보이면 같은 방식으로 사용할 수 있습니다.

명령은 어떻게 입력하나요?

이 글의 코드 상자 안에 있는 명령만 복사해 깜빡이는 커서 뒤에 붙여넣고 Enter를 누릅니다.

예를 들어 화면이 다음처럼 보인다면:

PS C:Usersminhee>

python --version만 입력해 다음처럼 만듭니다.

PS C:Usersminhee> python --version

다음 항목은 입력하지 않습니다.

  • PS C:Usersminhee>처럼 컴퓨터가 이미 보여 주는 부분

  • 코드 상자 위의 powershell, bash, python 같은 언어 이름

  • 코드 상자를 감싸는 세 개의 백틱 기호

명령이 두 줄이면 첫 줄을 입력하고 Enter, 두 번째 줄을 입력하고 다시 Enter를 누르면 됩니다.

이 글의 Windows 기본 규칙: 별도의 안내가 없다면 모든 설치 명령은 방금 연 PowerShell 창에 입력합니다.

1단계: OpenRouter API 키 만들기

  1. OpenRouter API Keys 페이지에 로그인합니다.

  2. Create Key를 누릅니다.

  3. 알아보기 쉬운 이름을 입력합니다. 예: ox-alpha-tutorial

  4. 필요하면 사용 한도를 설정합니다.

  5. 생성된 sk-or-v1-... 형태의 키를 복사합니다.

API 키는 생성 직후 안전한 곳에 보관하십시오. 화면 공유, 블로그 캡처, GitHub 코드, 카카오톡 메시지에 실제 키가 노출되지 않도록 주의합니다. 노출되었다면 즉시 해당 키를 폐기하고 새로 발급하십시오.

2단계: Python 설치 확인하기

Windows

0단계에서 연 PowerShell 창에 다음 명령을 입력하고 Enter를 누릅니다.

python --version

명령이 작동하지 않으면 다음도 시도합니다.

py --version

버전 번호가 나오지 않으면 Python 공식 다운로드 페이지에서 Python 3.10 이상을 설치하십시오. Windows 설치 화면에서는 Add Python to PATH를 반드시 체크하는 것이 좋습니다.

macOS·Linux

0단계에서 연 터미널 창에 다음 명령을 입력합니다.

python3 --version

Python 3.10 이상의 버전 번호가 나오면 다음 단계로 이동합니다.

3단계: 프로젝트 폴더 만들기

Windows PowerShell

0단계에서 연 PowerShell 창을 그대로 사용합니다. 다음 두 명령을 한 줄씩 입력하고, 매번 Enter를 누릅니다.

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

첫 번째 명령은 openrouter-ox-alpha 폴더를 만들고, 두 번째 명령은 그 폴더 안으로 이동합니다. 현재 위치를 확인하려면 다음 명령을 입력합니다.

Get-Location

Windows 파일 탐색기에서 지금 폴더를 보고 싶다면 다음 명령을 입력합니다.

explorer .

마지막의 점 .은 “현재 폴더”라는 뜻입니다.

macOS·Linux

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

이제 이 폴더 안에 다음 세 파일을 만들게 됩니다.

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

VS Code를 사용한다면 이 폴더에서 다음 명령을 실행해 편집기를 열 수 있습니다.

code .

code 명령이 없어도 메모장이나 다른 텍스트 편집기를 사용하면 됩니다.

4단계: 가상환경 만들기

가상환경은 이 프로젝트에 필요한 Python 패키지만 따로 보관하는 작은 상자입니다. 다른 프로젝트와 패키지가 뒤섞이는 것을 막아 줍니다.

Windows PowerShell

python 명령을 사용할 수 있다면:

python -m venv .venv
..venvScriptsActivate.ps1

py 명령만 작동한다면:

py -m venv .venv
..venvScriptsActivate.ps1

실행 정책 오류가 나타나면 PowerShell 대신 명령 프롬프트를 열어 다음 명령을 사용해도 됩니다.

.venvScriptsactivate.bat

macOS·Linux

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

성공하면 터미널 줄 앞에 (.venv)가 표시됩니다.

5단계: 필요한 패키지 설치하기

가상환경이 활성화된 상태에서 설치합니다. 터미널 줄 앞에 (.venv)가 보이는지 먼저 확인하십시오.

Windows PowerShell

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

macOS·Linux

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

설치하는 패키지는 두 개입니다.

  • openai: OpenAI 호환 형식으로 OpenRouter API를 호출합니다.

  • python-dotenv: .env 파일에 보관한 API 키를 안전하게 불러옵니다.

6단계: API 키를 .env에 저장하기

프로젝트 폴더에 이름이 정확히 .env인 파일을 만들고 다음 한 줄을 입력합니다.

Windows에서 .env 파일 여는 가장 쉬운 방법

프로젝트 폴더에 들어와 있는 PowerShell 창에서 다음 명령을 입력합니다.

notepad .env

“새 파일을 만드시겠습니까?”라는 질문이 나오면 예를 누릅니다. 열린 메모장에 아래 한 줄을 붙여넣고 Ctrl + S로 저장합니다. Word나 한글 워드프로세서는 사용하지 마십시오.

macOS·Linux에서 .env 파일 만들기

터미널에서 다음 명령을 입력합니다.

nano .env

내용을 붙여넣은 뒤 Ctrl + O, Enter, Ctrl + X 순서로 눌러 저장하고 종료합니다.

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

주의할 점은 다음과 같습니다.

  • OPENROUTER_API_KEY 앞뒤에 공백을 넣지 않습니다.

  • 실제 키를 따옴표로 감쌀 필요는 없습니다.

  • 이 예시의 가짜 키를 그대로 사용하면 인증되지 않습니다.

  • Windows 메모장에서 저장할 때 파일명이 .env.txt가 되지 않았는지 확인합니다.

.gitignore 만들기

같은 폴더에 .gitignore 파일을 만들고 다음 내용을 입력합니다.

Windows PowerShell에서는 다음 명령으로 메모장을 엽니다.

notepad .gitignore

macOS·Linux에서는 다음 명령을 사용합니다.

nano .gitignore
.env
.venv/
__pycache__/

이 파일은 Git이 API 키와 가상환경 폴더를 추적하지 않도록 막아 줍니다.

7단계: 첫 번째 요청 보내기

ox_alpha.py 파일을 만들고 다음 코드를 그대로 붙여넣습니다.

Windows PowerShell에서는 다음 명령으로 메모장을 엽니다.

notepad ox_alpha.py

macOS·Linux에서는 다음 명령을 사용합니다.

nano ox_alpha.py

코드를 붙여넣고 저장하십시오. Windows 메모장에서는 Ctrl + S, nano에서는 Ctrl + O, Enter, Ctrl + X 순서입니다.

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)

코드가 하는 일

  • base_url을 OpenRouter 주소로 바꿉니다.

  • model="stealth/ox-alpha"로 사용할 모델을 지정합니다.

  • messages에 시스템 지침과 사용자의 질문을 넣습니다.

  • reasoning.enabled로 지원되는 범위 안에서 추론 기능을 활성화합니다.

  • 모델이 반환한 추론 정보가 있을 때만 출력하고, 마지막에 최종 답변을 출력합니다.

OpenRouter는 Chat Completions 요청 본문에 model, messages, stream, max_tokens, temperature, tools, response_format 등의 값을 받을 수 있습니다. 자세한 형식은 OpenRouter API Reference에서 확인할 수 있습니다.

8단계: 실행하기

Windows PowerShell에서 실행하기

앞 단계에서 사용하던 PowerShell 창이 그대로 열려 있고, 줄 앞에 (.venv)가 보인다면 다음 명령 한 줄만 입력합니다.

python .ox_alpha.py

PowerShell을 닫았다가 다시 열었다면 먼저 프로젝트 폴더로 이동하고 가상환경을 다시 켠 뒤 실행해야 합니다.

cd "$HOMEopenrouter-ox-alpha"
..venvScriptsActivate.ps1
python .ox_alpha.py

명령을 입력한 위치가 맞는지 모르겠다면 다음 명령으로 파일 목록을 확인합니다.

Get-ChildItem

목록에 ox_alpha.py, .env, .gitignore가 보이면 올바른 폴더입니다.

Windows 명령 프롬프트(CMD)를 사용하는 경우

PowerShell의 실행 정책 문제 때문에 CMD를 선택했다면 다음 세 줄을 사용합니다.

cd %USERPROFILE%openrouter-ox-alpha
.venvScriptsactivate.bat
python ox_alpha.py

CMD에서는 $HOME이나 Activate.ps1을 사용하지 않습니다.

macOS·Linux 터미널에서 실행하기

앞 단계의 터미널이 그대로 열려 있다면 다음처럼 실행합니다.

python3 ox_alpha.py

터미널을 닫았다가 다시 열었다면 다음 순서로 실행합니다.

cd "$HOME/openrouter-ox-alpha"
source .venv/bin/activate
python3 ox_alpha.py

정상이라면 strawberry에 들어 있는 r의 개수를 설명하는 답변이 표시됩니다. strawberry의 글자는 s-t-r-a-w-b-e-r-r-y이므로 r은 세 개입니다.

실행할 때 화면은 대략 이렇게 보입니다

(.venv) PS C:Usersminheeopenrouter-ox-alpha> python .ox_alpha.py

[최종 답변]
strawberry에는 r이 3개 있습니다. ...

여기서 (.venv)는 가상환경이 켜졌다는 뜻이고, PS는 PowerShell이라는 뜻입니다. 사용자의 Windows 계정 이름에 따라 minhee 부분은 다르게 표시되어도 정상입니다.

9단계: 답변을 실시간 스트리밍으로 받기

기본 요청은 답변 전체가 완성될 때까지 기다렸다가 한 번에 출력합니다. 긴 답변을 글자 단위로 바로 보고 싶다면 스트리밍을 사용합니다.

새 파일 ox_alpha_stream.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("nn[사용량]")
        print(chunk.usage.model_dump())

print()

Windows PowerShell에서는 다음 명령으로 실행합니다.

python .ox_alpha_stream.py

macOS·Linux 터미널에서는 다음 명령으로 실행합니다.

python3 ox_alpha_stream.py

stream=True를 넣으면 OpenRouter가 Server-Sent Events 방식으로 응답 조각을 차례로 보냅니다.

설치 없이 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. 프로젝트 만들기

다음 명령은 Windows PowerShell과 macOS·Linux 터미널에서 동일합니다. 자신이 앞에서 사용한 터미널 창에 한 줄씩 입력합니다.

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("nnUsage:", chunk.usage);
  }
}

4. 실행하기

Windows PowerShell이나 macOS·Linux 터미널에서 다음 명령을 입력합니다.

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가 여러 호환 형식을 제공하더라도 한 요청에서 형식을 섞으면 안 됩니다.

image

처음 시작한다면 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",
    },
)

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

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

image

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

.env를 찾지 못할 때

다음을 확인하십시오.

  1. 터미널의 현재 위치가 프로젝트 폴더인지 확인합니다.

  2. 파일명이 .env.txt가 아닌 .env인지 확인합니다.

  3. 변수명이 정확히 OPENROUTER_API_KEY인지 확인합니다.

  4. python-dotenv가 설치되어 있는지 확인합니다.

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

pwd

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

Get-Location

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

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

.venvScriptsactivate.bat

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

..venvScriptspython.exe ox_alpha.py

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

  • API 키를 코드에 직접 적지 않았다.

  • .env를 .gitignore에 추가했다.

  • 키별 사용 한도 또는 예산을 설정했다.

  • 학생·학부모 개인정보를 프롬프트에 넣지 않는다.

  • 모델 가격과 제공 여부를 다시 확인한다.

  • 429와 5xx 오류에 재시도·대체 모델 전략을 마련한다.

  • AI 답변을 사실 검증 없이 자동 공개하지 않는다.

  • 프리뷰 모델을 중요한 운영 시스템의 유일한 모델로 의존하지 않는다.

핵심 매개변수 빠른 설명

image

다음 단계

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

  1. input()으로 사용자의 질문을 받는 터미널 챗봇 만들기

  2. 대화 내용을 messages 배열에 누적해 다중 턴 대화 만들기

  3. response_format으로 JSON 출력 받기

  4. 함수 호출용 tools 추가하기

  5. Streamlit·Gradio·웹 앱에 연결하기

  6. 시간 초과, 재시도, 로깅, 사용량 제한 추가하기

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

공식 자료

이 노트는 보도·비평·교육·연구 목적으로 작성되었습니다. 저작권 문의가 있으시면 에서 알려주세요.

틸노트는 사용자가 AI를 활용해 노트를 쉽게 작성하거나 편집할 수 있는 서비스입니다.

회원 가입

AI 스퀘어 단톡방에 함께해요

AI 활용과 틸노트 사용 팁을 나누는 오픈채팅방입니다. 입장 비밀번호는 tilnote입니다.

참여하기
이용약관·개인정보처리방침