Claude Code·Codex·Gemini CLI 설치
npm으로 Claude Code, Codex, Gemini CLI 중 필요한 도구를 설치하고 Code By AI에 연결한 뒤, 테스트 요청으로 설정을 확인하는 방법을 안내합니다. Node.js 확인부터 첫 호출까지 따라 해 보세요.
1. Node.js와 npm 확인하기
현재 Node.js LTS 버전을 사용하세요. 먼저 설치된 환경을 확인합니다.
1 node --version2 npm --version
명령 중 하나라도 없다면 Node.js를 먼저 설치하세요. npm은 Node.js에 포함되어 있습니다.
macOS(Homebrew)
1 brew install node
Ubuntu / Debian
1 sudo apt update2 sudo apt install nodejs npm
Windows
nodejs.org에서 현재 LTS 설치 프로그램을 다운로드하고, Node.js를 PATH에 추가하는 옵션을 켠 상태로 설치하세요. 설치 후 새 터미널을 열어 버전을 다시 확인하세요.
여러 Node.js 버전을 관리한다면 시스템 Node.js를 바꾸지 말고 기존 버전 관리 도구를 사용하세요.
2. 필요한 코딩 클라이언트 설치하기
실제로 사용할 도구만 설치하세요.
Claude Code
1 npm install -g @anthropic-ai/claude-code
Codex
1 npm install -g @openai/codex
Gemini CLI
1 npm install -g @google/gemini-cli
설치를 확인하고 CLI가 PATH에 있는지 확인합니다.
1 claude --version2 codex --version3 gemini --version
설치한 클라이언트만 확인하면 됩니다. 버전 번호가 보이면 패키지 설치는 성공한 것이지만, API 연결이 동작하는지는 별도로 확인해야 합니다.
3. Code By AI 설정하기
Code By AI 대시보드에서 키를 만든 뒤 클라이언트를 게이트웨이로 연결하세요. 키는 소스 관리에 넣지 말고, 가능하면 셸 기록에도 남기지 마세요.
Claude Code에는 엔드포인트와 토큰 두 가지 변수가 필요합니다.
macOS / Linux(Bash / Zsh)
1 export ANTHROPIC_BASE_URL="https://www.codebyai.net/api/agent"2 export ANTHROPIC_AUTH_TOKEN="sk-proj-xxxx"
Windows PowerShell
1 $env:ANTHROPIC_BASE_URL = "https://www.codebyai.net/api/agent"2 $env:ANTHROPIC_AUTH_TOKEN = "sk-proj-xxxx"
Windows CMD
1 set "ANTHROPIC_BASE_URL=https://www.codebyai.net/api/agent"2 set "ANTHROPIC_AUTH_TOKEN=sk-proj-xxxx"
사용하는 터미널에 맞는 명령을 선택하고 sk-proj-xxxx를 실제 키로 바꾸세요. 이 변수들은 현재 터미널에만 적용되므로 아래 스모크 테스트도 같은 창에서 실행하세요. 영구적으로 사용하려면 macOS / Linux에서는 export 줄을 ~/.zshrc 또는 ~/.bashrc에 추가하고, Windows에서는 Windows 설정 단계를 따르세요. ~/.claude/settings.json을 사용한다면 JSON 설정 예제에 따라 env 객체에 변수를 넣으세요. 셸 명령을 해당 파일에 그대로 붙여 넣으면 안 됩니다.
다른 클라이언트는 설정 파일과 변수 이름이 다릅니다.
어떤 변수를 어느 파일에 넣어야 할지 모르겠다면 환경 변수 레퍼런스를 확인하세요. 셸, settings.json, VS Code, TypeScript, Python, YAML, TOML, INI, .env 예제를 제공합니다.
4. 첫 요청 실행하기
Claude Code에서는 print 모드를 사용하면 응답 후 명령이 종료됩니다.
1 claude -p "Reply with exactly: setup ok"
setup ok가 반환되면 CLI 설치, 게이트웨이의 키 인증, 모델 응답이 모두 정상이라는 뜻입니다. 명령이 멈추거나 인증 오류가 반환되면 CLI를 다시 설치하기 전에 아래 항목을 확인하세요.
문제 해결
node: command not found 또는 npm: command not found. Node.js가 설치되지 않았거나 터미널이 PATH를 다시 읽지 않은 상태입니다. Node.js를 설치하고 터미널을 닫은 뒤 다시 시도하세요.
npm 전역 설치 후 claude: command not found. npm이 전역 실행 파일을 어디에 두었는지 확인하세요.
1 npm prefix -g
전역 실행 파일 디렉터리를 PATH에 추가하세요. 여기서 {prefix}는 npm prefix -g가 출력한 디렉터리를 뜻합니다.
- macOS / Linux:
{prefix}/bin을 추가하세요. - Windows:
{prefix}자체를 추가하고 뒤에bin을 붙이지 마세요.
PATH를 수정한 뒤 새 터미널을 열고 claude --version을 다시 실행하세요. macOS와 Linux에서는 sudo로 전역 패키지를 설치하는 것보다 nvm 같은 버전 관리 도구를 쓰는 편이 좋습니다.
npm install -g 중 EACCES 또는 권한 오류. 먼저 sudo를 쓰지 말고 Node.js 버전 관리 도구나 사용자가 쓸 수 있는 npm 전역 접두사를 사용하세요.
401, invalid api key 또는 인증 오류. ANTHROPIC_AUTH_TOKEN에 Code By AI 키가 들어 있는지, ANTHROPIC_API_KEY도 함께 설정되어 있지 않은지 확인하세요. 두 변수는 서로 다른 헤더를 사용하므로 하나만 설정해야 합니다.
Code By AI가 아니라 Anthropic으로 요청이 감. ANTHROPIC_BASE_URL이 https://www.codebyai.net/api/agent인지, CLI를 시작하는 환경에도 설정되어 있는지 확인하세요. VS Code 확장 패널에는 셸 export뿐 아니라 claudeCode.environmentVariables가 필요합니다.
긴 요청이 타임아웃됨. 실패 시점과 게이트웨이 로그를 확인하세요. Anthropic Messages 스트리밍은 시작 대기, 유휴 시간, 전체 시간에 별도 기한을 적용하며, 비스트리밍 요청의 전체 제한은 295초로 유지됩니다. API_TIMEOUT_MS를 늘려도 이 기한은 연장되지 않습니다. 즉시 실패한다면 엔드포인트와 API 키를 확인하세요.
설정 변경이 적용되지 않음. CLI를 재시작하거나 VS Code에서 Developer: Reload Window를 실행하세요. 환경 변수는 프로세스가 시작될 때 읽습니다.
다음 단계
- Claude Code 환경 변수 레퍼런스
- Claude Code 설정 가이드
- Codex 설정 가이드
- Gemini CLI 설정 가이드
- 모델 및 토큰 가격
- 직접 만든 스크립트나 SDK는 API 빠른 시작
스모크 테스트를 통과하면 Claude Code 가격을 비교하고 작업량에 맞는 모델을 선택하세요.