01｜Claude Code를 Crazyrouter에 연동하는 빠른 시작 및 설정 가이드

01｜Claude Code를 Crazyrouter에 연결하는 빠른 시작과 설정#

이 글은 Crazyrouter Claude Code 시리즈의 01편입니다. 이번 글에서는 “Claude Code를 Crazyrouter에 연결하는 빠른 시작과 설정”을 중심으로, Claude Code의 기본 사용법과 설정 방법을 집중적으로 다룹니다.

통합 접속 기준: Claude Code / Anthropic 네이티브 클라이언트는 ANTHROPIC_BASE_URL=https://cn.crazyrouter.com을 사용하고, OpenAI 호환 SDK, HTTP 요청, 프런트엔드/백엔드 애플리케이션은 base_url=https://cn.crazyrouter.com/v1을 사용합니다.

이 글에서 다루는 내용#

• 대상 독자: Claude Code를 사용 중이거나, 중국산 모델을 연동하려고 준비 중이거나, 팀의 모델 호출 경로를 Crazyrouter로 통합하려는 개발자.
• 배울 내용: Crazyrouter 문서에 맞춰 환경 변수를 설정하고 워크플로를 구성하는 방법, 그리고 Base URL을 잘못 입력해 /v1/v1/... 문제가 생기는 것을 피하는 방법.
• 준비 사항: 먼저 Crazyrouter 콘솔에서 별도의 API Token을 만든 뒤, Claude Code 연동 문서를 참고해 기본 설정을 완료하는 것을 권장합니다.

Claude Code 빠른 시작과 설정#

Claude Code 설치#

시스템은 다음 최소 요구 사항을 충족해야 합니다.

운영체제: Linux(Ubuntu 18.04+, CentOS 7+) macOS 10.15+, Windows 10+

네트워크 연결: 안정적인 인터넷 연결

저장 공간: 최소 500MB 이상의 사용 가능한 디스크 공간

Node.js 설치#

설치를 시작하기 전에 먼저 Node.js와 npm 버전을 확인하세요.

node --version
npm --version

로컬 환경에 Node.js가 아직 없다면 Node.js 18 LTS 이상 버전을 설치하는 것을 권장합니다.

• 다운로드: Node.js 공식 사이트
• 설치 문서: Node.js 공식 문서

Git 설치#

설치를 시작하기 전에 먼저 Git 버전을 확인하세요.

git --version

로컬 환경에 Git이 아직 없다면 사용하는 시스템에 맞는 설치 방법을 선택하면 됩니다.

• 다운로드: Git 공식 사이트
• 설치 문서: Git 공식 문서

Linux /macOS 설치#

# Claude Code 전역 설치
sudo npm install -g @anthropic-ai/claude-code

# 설치 확인
claude --version

Windows 설치#

# 관리자 권한으로 Powershell 또는 명령 프롬프트 열기

# 전역 설치
npm install -g @anthropic-ai/claude-code

# 설치 확인
claude --version

Crazyrouter API Key 설정#

Claude Code를 Crazyrouter에 연결할 때는 ANTHROPIC_BASE_URL과 ANTHROPIC_API_KEY를 우선 설정합니다. 일반적으로 글 안에 빈 프록시 주소를 적을 필요는 없습니다.

Windows PowerShell:

[Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "https://cn.crazyrouter.com", "User")
[Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "YOUR_CRAZYROUTER_API_KEY", "User")

macOS / Linux:

export ANTHROPIC_BASE_URL=https://cn.crazyrouter.com
export ANTHROPIC_API_KEY=YOUR_CRAZYROUTER_API_KEY

스크립트로 Git, Node.js, Claude Code 설치 여부를 자동 확인하고 싶다면 Crazyrouter Claude Code 원클릭 설정 스크립트를 바로 사용할 수 있습니다.

콘솔에서 claude code 실행#

터미널에 claude를 입력합니다. 이후 claude에 로그인하고 Crazyrouter Token으로 인증을 완료해야 합니다.

1. 기본 작업: 명령어와 설정이 출발점#

도움말 명령어를 제대로 익혀 모든 가능성 열기#

빠르게 시작하고 싶다면 claude --help부터 실행해 보세요. 이 명령어는 사용 가능한 모든 파라미터와 명령어를 보여줍니다. 예를 들어 비대화형 출력에 쓰는 -p, 최근 대화를 이어가는 -c, 모델을 지정하는 --model 등이 있습니다. 자주 쓰는 파라미터를 기억해 두면 작업 효율이 크게 올라갑니다. 예를 들어 claude -r로 이전 세션을 복원하거나, --output-format json으로 구조화된 결과를 내보낼 수 있습니다.

IDE와 매끄럽게 연동해 창 전환 없이 코딩하기#

VS Code, Cursor 등의 IDE에서 Claude Code를 사용하는 방법은 두 단계면 충분합니다.#

• 플러그인 설치: “Claude Code”를 검색한 뒤 Anthropic 공식 버전을 확인하고 설치하면 됩니다.

• 빠른 실행: 단축키 Cmd+Escape(사용자 지정 가능)로 호출하거나 IDE 화면의 Claude Code 아이콘을 클릭하면 오른쪽에 작업 영역이 바로 표시됩니다. 선택한 코드를 자동으로 컨텍스트에 전달하고, diff로 코드 변경 사항을 비교할 수 있으며, Alt+Cmd+K로 선택한 내용을 프롬프트 입력창에 한 번에 보낼 수도 있습니다.

2. 핵심 모드: 상황에 맞춰 전환해 효율 극대화#

자동 편집 모드: 확인 없이 일괄 작업#

매번 확인할 필요가 없는 파일 생성이나 수정 작업에 적합합니다. Shift+Tab을 한 번 누르면 활성화되며, 이때 Claude는 편집 작업을 자동으로 실행하므로 수동 확인이 필요 없습니다. 예를 들어 “멋진 todolist 앱을 만들어 줘”라고 입력하면 파일을 바로 생성하고 수정해, 반복 확인에 쓰는 시간을 줄일 수 있습니다.

Plan 모드: 초반 설계에 유용한 도구#

프로젝트를 구성하거나 복잡한 문제를 다룰 때는 Shift+Tab을 두 번 눌러 Plan 모드를 켭니다. 이 모드는 먼저 해결 방안의 큰 틀을 정리합니다. 예를 들어 “픽셀 스타일의 모바일 todolist”를 만들려고 하면 기술 스택, 페이지 구조, 적응형 처리 방안 등을 자동으로 계획한 뒤 확인을 받은 다음 작업을 시작합니다. 마음에 들지 않으면 “다시 계획해 줘”라고 말하면 되고, 원하는 수준이 될 때까지 조정할 수 있습니다.

Yolo 모드: 전체 권한으로 맡기기#

코드 리팩터링, 새 프로젝트 시작, 복잡한 bug 수정처럼 더 많은 권한이 필요한 경우 claude --dangerously-skip-permissions로 Yolo 모드에 진입합니다. 이때 Claude는 더 높은 권한을 갖고 더 많은 작업을 직접 실행할 수 있습니다. 단, 보안에 유의해야 하며 샌드박스 환경에서 사용하는 것을 권장합니다. 진입한 뒤에도 Shift+Tab으로 모드를 조정해 권한 수준을 유연하게 전환할 수 있습니다.

claude --dangerously-skip-permissions

3. CLAUDE.md: 전역 메모리의 핵심#

채팅봇과 대화할 때 “시스템 프롬프트”가 중요하고, AI의 동작에 지속적으로 영향을 준다는 점은 잘 알려져 있습니다. CC에서도 CLAUDE.md가 비슷한 역할을 합니다. 일반적인 워크플로는 다음과 같습니다.

초기 CLAUDE.md 작성 → 대화가 길어져 한계에 가까워질 때까지 진행하고 /compact로 수명 연장 → 마일스톤에 도달하면 CC에게 진행 상황을 바탕으로 CLAUDE.md를 업데이트하도록 요청 → 끝날 때까지 반복

즉 CLAUDE.md는 계속 영향을 미치는 전역 변수에 가깝습니다. 게다가 CC가 여기에 내용을 쓸 때는 보통 충분히 요약해서 정리하므로 가독성도 좋습니다.

CLAUDE.md 주의사항

• 파일은 너무 길게 만들지 마세요. 어차피 CC가 기본적으로 이 파일을 읽어 들입니다.
• 대화 중에는 편하게 claude.md라고 말해도 CC가 알아듣습니다.
• 파일에는 리마인더를 넣어두기 좋습니다. 예를 들어 “CC가 성공했다고 말할 때마다 반드시 증거 파일 링크를 함께 제시할 것”, “프록시 서비스 포트는 9890” 같은 내용을 적어둘 수 있습니다. 이후 대화에서 CC에게 “claude.md 관련 부분을 확인해줘”라고 요청하면 됩니다.
• 공식 문서의 #로 문서에 넣는 방식은 GPT에 따르면 불안정한 버그가 있다고 합니다.

4. 세션 관리: 통제력을 잃지 않고 효율적으로 진행하기#

언제든지 일시정지와 롤백#

• 작업 중 Esc를 누르면 현재 작업을 일시정지할 수 있습니다. 예를 들어 Claude가 의존성 설치에서 타임아웃이 나거나, 방향이 어긋난다고 느껴질 때 즉시 중단하면 불필요한 작업을 줄일 수 있습니다.
• Esc를 두 번 누르면 이전 대화 기록 노드로 되돌아갈 수 있습니다. 단, redo 기능은 없으므로 되돌리기 전에 꼭 확인하세요.
• 코드가 마음에 들지 않나요? “이전 코드로 롤백해줘”라고 바로 말하면 Claude가 이전 버전으로 자동 복구합니다.

히스토리 초과에 대응하기#

세션에 “Context left until auto-compact: 3%”라는 안내가 뜨면 히스토리가 거의 찼다는 뜻입니다. 이때 자동 압축이 트리거되며 약 150초가 걸립니다. 필요하면 /compact 명령으로 수동 압축해 대화를 이어갈 수도 있어, 대화가 끊기는 상황을 피할 수 있습니다.#

히스토리 복구와 확인#

• claude -c로 바로 이전 대화에 진입할 수 있습니다.
• claude -r로 히스토리 세션을 선택해 복구할 수 있습니다. 중간에 종료한 뒤 이어서 작업할 때 유용합니다.

5. 리소스 모니터링과 배치 작업: 속도를 제어하고 낭비 줄이기#

token 사용량 실시간 모니터링#

하루 또는 시간당 리소스를 얼마나 쓰는지 알고 싶다면 npx ccusage@latest를 실행해 일별 사용량을 확인하세요. 또는 npx ccusage blocks --live로 소비 속도를 실시간 모니터링할 수 있습니다. 속도가 너무 빠르면 git commit처럼 token을 많이 쓰는 작업은 직접 처리해 초과 사용을 피하는 것이 좋습니다.

npx ccusage@latest

배치 작업 효율적으로 처리하기#

수십 개의 반복 작업을 실행해야 한다면, 예를 들어 문서 챕터를 일괄 생성하는 경우에는 스크립트 방식으로 처리할 수 있습니다.

1. 작업을 줄 단위로 TASK.md에 작성합니다. 한 줄에 작업 하나씩 넣습니다.
2. 다음 명령을 실행합니다.

cat TASK.md | while IFS= read -r line; do echo $line; claude -p "$line" --debug; done

timeout을 추가해 단일 작업이 멈춰버리는 것을 방지할 수 있고, --allowedTools "Edit"로 권한을 제한해 의도치 않은 작업을 피할 수도 있습니다. 단, 병렬 실행은 하지 마세요. 제한에 걸려 차단될 수 있습니다.

6. 함정 피하기와 고급 활용: Claude를 더 “말 잘 듣게” 만들기#

충분한 자유를 주되, 보호 장치도 마련하기#

• auto-accept edits를 켜면(Shift+Tab으로 전환) Claude가 파일을 자동으로 편집합니다. git 버전 관리와 함께 쓰면 실수해도 부담이 적습니다.
• Bash 명령을 실행할 때는 Docker로 환경을 격리하거나, btrfs 파일 시스템으로 스냅샷을 만들어두세요. 권한은 열어주면서도 빠르게 롤백할 수 있습니다.
• 세션 디렉터리에 ssh key 같은 민감 정보를 두지 마세요. 다른 머신으로 넘어가는 작업에서 위험이 생길 수 있습니다.

“가짜 성과” 철저히 막기#

Claude는 가끔 “허풍”을 칩니다. 예를 들어 테스트를 끝내지도 않았는데 성공했다고 말할 수 있습니다. CLAUDE.md에 “성공했다고 주장할 때마다 반드시 증거 파일 링크를 첨부할 것”이라는 규칙을 넣고, 주기적으로 “정말 완료했어? 증거가 있어?”라고 되물어보세요. 문제가 발견되면 즉시 수정하게 하면 됩니다.

이런 팁을 익히면 Claude Code를 단순한 “도구”가 아니라 “효율적인 파트너”로 활용할 수 있습니다. 일상적인 코딩, 프로젝트 관리, 배치 처리 모두에서 생산성을 크게 높일 수 있습니다. 핵심은 필요한 시점에 모드를 전환하고, 전역 메모리를 잘 활용하며, 적절한 모니터링과 보호 장치를 더하는 것입니다. 그러면 Claude Code의 가치를 최대한 끌어낼 수 있습니다.

관련 글#

• 다음 글: 제 02편
• 설정 문서: Claude Code에서 Crazyrouter 연동하기
• API 주소 설명: Base URL과 /v1 사용법
• 원클릭 설정 스크립트: Crazyrouter Claude Code 원클릭 설정 스크립트

Crazyrouter 연동 시작하기#

Claude Code, 중국산 모델 또는 자체 애플리케이션을 Crazyrouter에 통합해 사용하려는 경우에는 다음 순서로 진행하면 됩니다.

1. Crazyrouter 콘솔에서 전용 API Token을 만들고, 프로젝트 또는 팀 단위로 권한을 별도 관리합니다.
2. Claude Code는 루트 도메인 https://cn.crazyrouter.com을 사용합니다. OpenAI 호환 SDK는 https://cn.crazyrouter.com/v1을 사용합니다.
3. 환경을 자동으로 확인하거나 설정을 빠르게 작성해야 한다면 Crazyrouter Claude Code 원클릭 설정 스크립트를 사용하세요.
4. 디버깅에 실패하면 먼저 콘솔 로그를 확인한 뒤 API Endpoint 설명을 대조하세요. 특히 Base URL에 /v1을 중복해서 붙이지 않았는지 확인하는 것이 중요합니다.

모델 비용을 평가하거나 다른 모델을 선택해야 한다면 먼저 Crazyrouter 가격 및 모델 페이지를 확인한 다음, 자주 쓰는 모델을 Token 허용 목록에 추가하세요.