Claude Code 설치와 안전한 첫 실행

설치 전 준비물

터미널, 수정해도 되는 작은 Git 프로젝트, 가능하면 깨끗한 git status가 필요합니다. 공식 login에는 지원되는 Claude 또는 Console account가 필요하고 gateway는 별도 provider 경로입니다. Key를 source, screenshot, shell history에 넣지 마세요.

macOS, Linux, WSL의 Native Install

Anthropic 권장 Native Install입니다.

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

이 단계는 client만 설치하며 browser login이나 provider 설정은 하지 않습니다. 오래된 npm 안내 대신 최신 Docs에서 다른 설치 방법과 dependencies를 확인하세요.

Windows PowerShell, CMD, WSL 차이

PowerShell:

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

CMD:

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

네이티브 Windows에서는 Claude Code가 Bash를 쓰도록 Git for Windows를 권장합니다. WSL에서는 필요하지 않으며 Linux client를 WSL에 설치하고 가능하면 프로젝트도 WSL filesystem에 둡니다.

client와 auth status 확인

새 terminal에서 실행합니다.

claude --version
claude auth status

그 다음 claude를 시작해 공식 browser login을 완료합니다. account를 바꿀 때는 session의 /login을 사용합니다. API Key를 일반 prompt나 repository에 저장하지 마세요.

third-party gateway 설정

gateway에는 API Key, 지원 Model ID, 정확한 Base URL이 필요합니다. BetterToken은 최신 가이드를 따르고 Anthropic-compatible Base URL로 https://bettertoken.ai를 사용합니다. 이는 raw Messages HTTP URL이 아니며 client가 protocol path를 추가합니다. Key, model, URL을 동시에 바꾸지 말고 작은 request로 확인합니다.

읽기 전용 첫 project

cd path/to/test-project
git status
claude --permission-mode plan

“구조, entry point, 시작 command를 설명하고 file 변경이나 network command는 하지 마세요”라고 요청합니다. Plan mode는 읽고 탐색하지만 source를 편집하지 않습니다.

되돌릴 수 있는 첫 수정

README.md에 로컬 개발의 짧은 절을 추가하세요. README.md만 수정하고 dependencies를 설치하지 말고 network를 사용하지 말며 commit하지 마세요.

허용할 action을 확인한 뒤 실행합니다.

git diff -- README.md

대상 file, 내용, secrets, 예상 밖 configuration/dependency 변경을 확인합니다.

permission mode와 안전 경계

default는 읽기를 허용하고 edit와 command 전에 묻습니다. plan은 source 수정 없이 조사합니다. acceptEdits는 edit와 일반 filesystem 작업을 자동 허용하며 auto는 background safety check가 있는 research preview입니다. bypassPermissions는 격리 container나 VM 전용입니다. 처음에는 default 또는 plan을 사용하세요.

성공 신호와 API 검증

올바른 working folder, 성공한 login 또는 provider request, 허용한 한 file만의 변경, 이해 가능한 diff가 성공 신호입니다. BetterToken에서는 Dashboard와 Usage History의 model, status, input/output/cache token도 확인합니다. 이는 API 경로 확인이며 Chat/Cowork entitlement가 아닙니다.

계층별 문제 해결

claude를 찾지 못하면 terminal을 다시 열고 오래된 npm command가 아닌 공식 installation help를 따릅니다. login 문제는 Claude login, Console/API, gateway를 분리합니다. provider error는 Key, Base URL, Model ID 순서로 확인합니다. 수정이 너무 넓으면 거절하고 Plan mode로 돌아가 한 file, network 금지, commit 금지를 지정합니다.

다음 단계와 공식 소스

README diff가 깨끗하면 test 하나나 작은 fix로 진행합니다. scope와 autonomy는 한 번에 하나씩 넓힙니다. deployment, API, remote system은 local file처럼 되돌릴 수 없습니다.

Sources

• Claude Code installation
• Claude Code quickstart
• Claude Code permission modes
• Claude Code CLI reference
• BetterToken Claude Code