Claude Code에서 OneAster 사용하기

준비 사항

Claude Code는 Anthropic이 제공하는 커맨드라인 AI 프로그래밍 어시스턴트로, 터미널에서 직접 AI와 대화하고 코드를 생성하며 디버깅할 수 있습니다. OneAster를 연결하면 GPT, Claude, Gemini 등 다양한 모델을 Claude Code에서 사용할 수 있습니다. 시작하기 전에 다음을 확인하세요:

OneAster API 키 획득 완료 OneAster 콘솔에 로그인하여 API 키를 받으세요 (sk-로 시작)

팁: OneAster 계정이 없으시다면 먼저 OneAster에서 가입하고 API 키를 받으세요.

1단계: Claude Code 설치

다음 방법 중 하나를 선택하여 설치하세요:

macOS / Linux (권장)
Windows
NPM 설치

공식 스크립트로 설치:

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

Homebrew로도 설치 가능:

brew install --cask claude-code

권한 오류가 발생하면 명령어 앞에 sudo를 추가하세요.

PowerShell:

irm https://claude.ai/install.ps1 | iex

CMD:

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Node.js 18 이상이 설치되어 있다면 npm으로 설치할 수 있습니다:

npm install -g @anthropic-ai/claude-code

모든 운영체제에서 사용 가능합니다.

설치 확인

설치 후 다음 명령어로 확인합니다:

claude --version

버전 번호(예: 1.x.x)가 표시되면 설치 성공입니다.

2단계: OneAster API 설정

3가지 설정 방법을 제공합니다. 사용 습관에 맞게 선택하세요.

방법 1: settings.json 편집 (권장)

가장 안정적인 방법으로, 한 번 설정하면 영구적으로 유효합니다. 1. 설정 디렉토리 열기:

Windows: Win + R을 누르고 %userprofile%\.claude 입력
macOS: Command + Shift + G를 누르고 ~/.claude 입력
Linux: ~/.claude 디렉토리로 이동

디렉토리가 없으면 터미널에서 claude를 한 번 실행한 후 Ctrl + C로 종료하면 자동으로 생성됩니다.

2. settings.json 파일 생성 또는 편집:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.oneaster.ai",
    "ANTHROPIC_AUTH_TOKEN": "sk-xxxxxxxxxxxx",
    "ANTHROPIC_MODEL": "claude-opus-5",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  }
}

매개변수	설명
`ANTHROPIC_BASE_URL`	OneAster API 주소, `https://api.oneaster.ai` 고정
`ANTHROPIC_AUTH_TOKEN`	OneAster API 키 (`sk-`로 시작)
`ANTHROPIC_MODEL`	기본 사용 모델, 아래 모델 목록에서 선택
`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`	`1`로 설정하면 불필요한 네트워크 요청 감소

파일 저장 후 Claude Code를 재시작하면 적용됩니다.

방법 2: 영구 환경 변수

시스템 환경에 설정을 기록하여 모든 터미널 창에서 자동으로 로드됩니다.

macOS (zsh)
macOS / Linux (bash)
Windows

echo 'export ANTHROPIC_BASE_URL="https://api.oneaster.ai"' >> ~/.zshrc
echo 'export ANTHROPIC_API_KEY="sk-xxxxxxxxxxxx"' >> ~/.zshrc
echo 'export ANTHROPIC_MODEL="claude-opus-5"' >> ~/.zshrc
source ~/.zshrc

echo 'export ANTHROPIC_BASE_URL="https://api.oneaster.ai"' >> ~/.bashrc
echo 'export ANTHROPIC_API_KEY="sk-xxxxxxxxxxxx"' >> ~/.bashrc
echo 'export ANTHROPIC_MODEL="claude-opus-5"' >> ~/.bashrc
source ~/.bashrc

방법 A: GUI 설정

“내 PC” 우클릭 → “속성” → “고급 시스템 설정” → “환경 변수”
사용자 변수에 새로 추가:
- ANTHROPIC_BASE_URL = https://api.oneaster.ai
- ANTHROPIC_API_KEY = sk-xxxxxxxxxxxx
- ANTHROPIC_MODEL = claude-opus-5
터미널 재시작

방법 B: PowerShell 명령으로 설정

[System.Environment]::SetEnvironmentVariable('ANTHROPIC_BASE_URL', 'https://api.oneaster.ai', 'User')
[System.Environment]::SetEnvironmentVariable('ANTHROPIC_API_KEY', 'sk-xxxxxxxxxxxx', 'User')
[System.Environment]::SetEnvironmentVariable('ANTHROPIC_MODEL', 'claude-opus-5', 'User')

방법 3: 임시 환경 변수

테스트나 단기 사용에 적합합니다. 터미널을 닫으면 설정이 사라집니다.

macOS / Linux
Windows (PowerShell)
Windows (CMD)

export ANTHROPIC_API_KEY="sk-xxxxxxxxxxxx"
export ANTHROPIC_MODEL="claude-opus-5"
export ANTHROPIC_BASE_URL="https://api.oneaster.ai"
claude

$env:ANTHROPIC_API_KEY="sk-xxxxxxxxxxxx"
$env:ANTHROPIC_MODEL="claude-opus-5"
$env:ANTHROPIC_BASE_URL="https://api.oneaster.ai"
claude

set ANTHROPIC_API_KEY=sk-xxxxxxxxxxxx
set ANTHROPIC_MODEL=claude-opus-5
set ANTHROPIC_BASE_URL=https://api.oneaster.ai
claude

임시 환경 변수는 현재 터미널 창에서만 유효합니다. 창을 전환하거나 닫으면 다시 설정해야 합니다.

3단계: 사용 시작

설정 확인

Claude Code를 실행하고 간단한 메시지를 보내 설정이 올바른지 확인합니다:

claude "안녕하세요"

AI 응답을 받으면 설정 성공입니다. 401, 403 등의 오류가 나타나면 아래 FAQ를 참고하세요.

사용 모드

Claude Code는 두 가지 상호작용 모드를 제공합니다:

대화 모드: claude를 실행하여 지속적인 대화 진행, 복잡한 작업에 적합
단일 명령: claude "질문"으로 한 번의 응답 후 종료, 빠른 질문에 적합

지원 모델

OneAster는 Claude 모델 시리즈를 완벽하게 지원합니다. 작업 요구에 따라 유연하게 전환할 수 있습니다:

모델명	특징	권장 용도
`claude-opus-5`	차세대 플래그십 모델	복잡한 아키텍처, 난해한 디버깅
`claude-opus-4-6`	강력한 종합 능력	복잡한 아키텍처, 난해한 디버깅
`claude-sonnet-4-6`	성능과 속도의 균형	일상 프로그래밍, 코드 생성
`claude-opus-4-5-20251101`	고급 추론 능력	복잡한 코드, 심층 분석
`claude-sonnet-4-5-20250929`	우수한 코드 능력	알고리즘 설계, 코드 최적화
`claude-haiku-4-5-20251001`	초고속 응답	빠른 Q&A, 코드 스니펫

위 모든 모델은 Thinking(확장 사고) 버전을 지원합니다. 모델 ID 뒤에 -thinking을 추가하면 활성화됩니다(예: claude-opus-4-6-thinking). 깊은 추론이 필요한 복잡한 작업에 적합합니다.

모델 선택 추천:

🚀 고성능: claude-opus-5 — 가장 복잡한 코드와 아키텍처 문제 처리
⚖️ 균형 잡힌 성능: claude-sonnet-4-6 — 일상 프로그래밍에 적합
⚡ 빠른 응답: claude-haiku-4-5-20251001 — 즉각적인 피드백이 필요할 때
🧠 심층 사고: claude-opus-5-thinking — 깊은 추론이 필요할 때

모델을 전환하려면 대화 모드에서 /model 명령을 사용하거나, 설정의 ANTHROPIC_MODEL 필드를 수정한 후 재시작하세요.

자주 사용하는 명령어

Claude Code에서 자주 사용하는 명령어와 단축키:

명령어	설명
`claude`	대화 모드 진입
`claude "질문"`	단일 질문
`claude --version`	버전 확인
`/model`	대화 모드에서 모델 전환
`/help`	도움말 보기
`Ctrl + C`	대화 모드 종료

자주 묻는 질문

Q1: 설정 후에도 로그인 선택 화면이 나타나나요?

시작 시 “Select login method”가 표시되면 설정이 적용되지 않은 것입니다. 확인 단계:

settings.json 방식: 파일 경로가 올바른지 확인
- Windows: C:\Users\<사용자명>\.claude\settings.json
- macOS / Linux: ~/.claude/settings.json
환경 변수 방식: 변수를 설정한 같은 터미널 창에서 Claude Code를 실행했는지 확인
JSON 형식 확인: 괄호, 쉼표, 따옴표가 모두 올바른지 확인

Q2: 401 / 403 오류가 발생하나요?

오류 코드	의미	해결 방법
`401 Unauthorized`	API 키 누락 또는 무효	키가 올바르고 `sk-`로 시작하는지 확인
`403 Forbidden`	권한 부족 또는 키 만료	콘솔에서 키 상태 확인

ANTHROPIC_BASE_URL이 https://api.oneaster.ai로 설정되어 있는지도 확인하세요 (Anthropic 공식 주소가 아닌).

Q3: “Unable to connect” 연결 실패?

Claude Code가 API 서비스에 연결하지 못한 것입니다.

네트워크 연결이 정상인지 확인
ANTHROPIC_BASE_URL 설정이 올바른지 확인
프록시를 사용하는 경우 api.oneaster.ai 접근이 허용되었는지 확인

Q4: “Auth conflict” 인증 충돌 오류?

다음과 같은 메시지가 표시되는 경우:

Auth conflict: Both a token (claude.ai) and an API key (ANTHROPIC_API_KEY) are set.

claude.ai 계정 로그인과 API Key 설정이 동시에 존재하여 충돌이 발생한 것입니다. 해결 방법: Claude Code 대화 모드에서 /logout을 실행하여 claude.ai에서 로그아웃하세요. API Key 설정만 유지합니다.

Q5: 비 Claude 모델 사용 시 max_tokens 오류?

다음과 같은 오류가 표시되는 경우:

max_tokens is too large: 32000. This model supports at most 16384 completion tokens.

Claude Code는 기본적으로 Claude 모델의 매개변수(32000 tokens)로 요청을 보내기 때문에, 일부 비 Claude 모델(예: gpt-4o)에서는 토큰 제한을 초과합니다. 해결 방법: Claude 모델(예: claude-sonnet-4-6)로 전환하세요. Claude Code와 기본 호환되어 이 문제가 발생하지 않습니다.

Q6: 응답 속도가 느리나요?

더 빠른 모델로 전환 (예: claude-haiku-4-5-20251001 또는 claude-sonnet-4-6)
프롬프트를 줄여 컨텍스트 길이 감소
네트워크 상태 확인

Q7: 모델을 전환하려면?

두 가지 방법:

대화 모드에서: /model 명령어 입력
설정 변경: settings.json 또는 환경 변수의 ANTHROPIC_MODEL 필드를 변경한 후 Claude Code 재시작

Q8: Claude Code가 로컬 파일을 자동으로 읽나요?

아닙니다. Claude Code는 파일을 명시적으로 참조해야 하며, 민감한 작업 수행 전에 확인을 요청합니다. 전용 프로젝트 디렉토리에서 사용하는 것을 권장합니다.

Q9: 로컬 파일을 분석하려면?

대화 모드에서 다음 방법으로 파일을 참조할 수 있습니다:

파일 경로를 직접 입력
파일을 터미널 창에 드래그 앤 드롭
파일 내용 복사 붙여넣기

Q10: 사용량과 비용을 확인하려면?

OneAster 콘솔에 로그인하여 확인:

API 호출 통계
토큰 소비 상세
비용 통계 및 트렌드

지원

사용 중 문제가 발생하면:

OneAster 시작하기

지금 OneAster에 가입하고 API 키를 받아 Claude Code에서 멀티 모델 프로그래밍 어시스턴트를 경험하세요!

​준비 사항

​1단계: Claude Code 설치

​설치 확인

​2단계: OneAster API 설정

​방법 1: settings.json 편집 (권장)

​방법 2: 영구 환경 변수

​방법 3: 임시 환경 변수

​3단계: 사용 시작

​설정 확인

​사용 모드

​지원 모델

​자주 사용하는 명령어

​자주 묻는 질문

​Q1: 설정 후에도 로그인 선택 화면이 나타나나요?

​Q2: 401 / 403 오류가 발생하나요?

​Q3: “Unable to connect” 연결 실패?

​Q4: “Auth conflict” 인증 충돌 오류?

​Q5: 비 Claude 모델 사용 시 max_tokens 오류?

​Q6: 응답 속도가 느리나요?

​Q7: 모델을 전환하려면?

​Q8: Claude Code가 로컬 파일을 자동으로 읽나요?

​Q9: 로컬 파일을 분석하려면?

​Q10: 사용량과 비용을 확인하려면?

​지원

OneAster 시작하기

준비 사항

1단계: Claude Code 설치

설치 확인

2단계: OneAster API 설정

방법 1: settings.json 편집 (권장)

방법 2: 영구 환경 변수

방법 3: 임시 환경 변수

3단계: 사용 시작

설정 확인

사용 모드

지원 모델

자주 사용하는 명령어

자주 묻는 질문

Q1: 설정 후에도 로그인 선택 화면이 나타나나요?

Q2: 401 / 403 오류가 발생하나요?

Q3: “Unable to connect” 연결 실패?

Q4: “Auth conflict” 인증 충돌 오류?

Q5: 비 Claude 모델 사용 시 max_tokens 오류?

Q6: 응답 속도가 느리나요?

Q7: 모델을 전환하려면?

Q8: Claude Code가 로컬 파일을 자동으로 읽나요?

Q9: 로컬 파일을 분석하려면?

Q10: 사용량과 비용을 확인하려면?

지원