> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Code 터미널 (CLI) 사용 튜토리얼

> Claude Code 集成指南 - Ace Data Cloud

Claude Code는 Anthropic이 출시한 **Agentic Coding** 도구로, 세계에서 가장 강력한 프로그래밍 에이전트 중 하나로 알려져 있습니다. 터미널 CLI는 Claude Code의 핵심 경험으로, 어떤 터미널에서든 `claude` 명령어를 실행하여 자연어로 AI와 프로그래밍 협업을 할 수 있습니다.

이 문서는 AceData Cloud의 프록시 서비스를 통해 터미널에서 Claude Code CLI를 설치, 구성 및 사용하는 방법을 주로 설명합니다.

## 신청 절차

Claude Code를 사용하려면 먼저 [Claude Messages 서비스 페이지](https://platform.acedata.cloud/documents/claude-messages)에서 "Acquire" 버튼을 클릭하여 요청에 필요한 자격 증명을 얻을 수 있습니다:

![](https://cdn.acedata.cloud/nyq0xz.png)

로그인 또는 등록이 되어 있지 않으면 자동으로 로그인 페이지로 리디렉션되어 등록 및 로그인을 초대합니다. 로그인 후에는 자동으로 현재 페이지로 돌아옵니다.

첫 신청 시 무료 크레딧이 제공되어 Claude Code 서비스를 무료로 체험할 수 있습니다.

## Claude Code 설치

### 시스템 요구 사항

* macOS, Linux 또는 Windows(WSL 포함)
* Node.js는 필수가 아니며, 네이티브 설치 방식이 자동으로 종속성을 처리합니다.

### 설치 방법

Claude Code는 여러 가지 설치 방법을 지원합니다:

**방법 1: 네이티브 설치(추천)**

macOS / Linux / WSL:

```bash theme={null}
curl -fsSL https://claude.ai/install.sh | bash
```

Windows PowerShell:

```powershell theme={null}
irm https://claude.ai/install.ps1 | iex
```

Windows CMD:

```cmd theme={null}
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
```

**방법 2: Homebrew(macOS / Linux)**

```bash theme={null}
brew install claude-code
```

**방법 3: WinGet(Windows)**

```cmd theme={null}
winget install Claude.ClaudeCode
```

네이티브 설치는 백그라운드에서 자동으로 업데이트되어 항상 최신 버전을 유지합니다.

## AceData Cloud API 구성

설치가 완료되면 기본적으로 Anthropic 공식 계정에 로그인하라는 요청이 있습니다. 우리는 환경 변수를 구성하여 AceData Cloud의 프록시 API를 사용할 수 있으며, **공식 구독이 필요 없습니다**.

### 환경 변수 구성

환경 변수를 구성하는 방법은 두 가지가 있으며, 원하는 방법을 선택하면 됩니다.

**방법 1: Shell 구성 파일에 설정(추천)**

다음 내용을 당신의 Shell 구성 파일(`~/.zshrc`, `~/.bashrc` 또는 `~/.bash_profile`)에 추가하고, `{token}`을 AceData Cloud 콘솔에서 얻은 API 토큰으로 교체합니다:

```bash theme={null}
# AceData Cloud - Claude Code 프록시 구성
export ANTHROPIC_AUTH_TOKEN="{token}"
export ANTHROPIC_BASE_URL="https://api.acedata.cloud"
```

수정 후 다음 명령어를 실행하여 구성을 적용합니다:

```bash theme={null}
source ~/.zshrc  # 또는 source ~/.bashrc
```

**방법 2: Claude Code settings.json에 설정**

`~/.claude/settings.json`을 편집하고(존재하지 않으면 생성) `env` 구성을 추가합니다:

```json theme={null}
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "{token}",
    "ANTHROPIC_BASE_URL": "https://api.acedata.cloud"
  }
}
```

이 방법의 장점은 환경 변수가 Claude Code에만 적용되어 다른 프로그램에 영향을 미치지 않는 것입니다.

> **팁**: API 토큰은 [AceData Cloud 콘솔](https://platform.acedata.cloud/console)에서 확인할 수 있습니다. `ANTHROPIC_AUTH_TOKEN`의 값은 자동으로 `Bearer` 접두사가 추가되어 서버로 전송됩니다.

## 사용 시작하기

### 대화 모드 시작

터미널을 열고 프로젝트 디렉토리로 이동한 후 다음을 실행합니다:

```bash theme={null}
cd /path/to/your/project
claude
```

Claude Code의 환영 화면이 표시되며, 자연어를 입력하여 상호작용을 시작할 수 있습니다.

### 자주 사용하는 명령어

| 명령어              | 설명                | 예시                    |
| ---------------- | ----------------- | --------------------- |
| `claude`         | 대화 모드 시작          | `claude`              |
| `claude "작업"`    | 일회성 작업 실행         | `claude "빌드 오류 수정"`   |
| `claude -p "질문"` | 질문 후 종료           | `claude -p "이 함수 설명"` |
| `claude -c`      | 현재 디렉토리의 최근 대화 계속 | `claude -c`           |
| `claude -r`      | 이전 대화 복원          | `claude -r`           |
| `claude commit`  | Git 커밋 생성         | `claude commit`       |

### 대화 모드 명령어

대화 모드에서 사용할 수 있는 내장 명령어는 다음과 같습니다:

| 명령어                | 기능         |
| ------------------ | ---------- |
| `/help`            | 도움말 표시     |
| `/clear`           | 대화 기록 지우기  |
| `/config`          | 설정 패널 열기   |
| `/model`           | 모델 전환      |
| `/mcp`             | MCP 서비스 관리 |
| `/compact`         | 컨텍스트 압축    |
| `/memory`          | 기억 관리      |
| `/login`           | 계정 전환      |
| `exit` 또는 `Ctrl+C` | 종료         |

### 대화 상호작용 예시

```bash theme={null}
# 프로젝트 분석
> 이 프로젝트는 무엇을 하나요?

# 버그 수정
> 사용자가 빈 양식을 제출할 수 있는 버그가 있습니다 - 수정해 주세요

# 테스트 작성
> 계산기 함수에 대한 단위 테스트를 작성해 주세요

# 코드 리팩토링
> 인증 모듈을 async/await를 사용하도록 리팩토링해 주세요

# Git 작업
> 변경 사항을 설명하는 메시지로 커밋해 주세요
> 이 기능에 대한 PR을 생성해 주세요
```

## 고급 사용법

### 파이프 및 스크립트화

Claude Code는 Unix 철학을 따르며, 파이프 및 스크립트화 작업을 지원합니다:

```bash theme={null}
# 로그 모니터링 및 자동 알림
tail -f app.log | claude -p "이상 발견 시 나에게 알림"

# 새 텍스트 자동 번역
claude -p "새로운 텍스트 문자열이 있으면 프랑스어로 번역하고 PR을 생성해 주세요"

# 코드 리뷰
git diff main | claude -p "이 변경 사항을 검토해 주세요"
```

### 환경 변수 참조

다음은 Claude Code가 지원하는 일반적인 환경 변수입니다:

| 변수                           | 설명                                             |
| ---------------------------- | ---------------------------------------------- |
| `ANTHROPIC_AUTH_TOKEN`       | 사용자 정의 Authorization 헤더의 값(자동으로 Bearer 접두사 추가) |
| `ANTHROPIC_API_KEY`          | API 키( X-Api-Key 헤더로 전송됨)                      |
| `ANTHROPIC_BASE_URL`         | API 기본 URL                                     |
| `ANTHROPIC_MODEL`            | 기본 모델 덮어쓰기                                     |
| `ANTHROPIC_SMALL_FAST_MODEL` | Haiku 수준 모델(백그라운드 작업용)                         |
| `MAX_THINKING_TOKENS`        | 생각 Token 예산 설정(0으로 설정 시 생각 모드 비활성화)            |
| `DISABLE_COST_WARNINGS`      | 1로 설정 시 비용 알림 비활성화                             |

### CLAUDE.md 프로젝트 기억

프로젝트 루트 디렉토리에 `CLAUDE.md` 파일을 생성하면 Claude Code에 프로젝트 특정 지침 및 컨텍스트를 제공할 수 있습니다. Claude는 시작 시 이 파일을 자동으로 로드합니다.

```markdown theme={null}
# 프로젝트 설명
이것은 Django + Vue.js의 풀스택 프로젝트입니다.

## 코딩 규칙
- Python 3.12 사용
- PEP 8 코드 스타일 준수
- 모든 API는 단위 테스트를 작성해야 합니다.
```

## 자주 묻는 질문

### 연결 실패 시 어떻게 하나요?

1. `~/.claude/config.json` 파일이 올바르게 생성되었는지 확인하고, 내용은 `{"primaryApiKey": "self"}`입니다.
2. 환경 변수가 올바르게 설정되었는지 확인하십시오:
   ```bash theme={null}
   echo $ANTHROPIC_AUTH_TOKEN
   echo $ANTHROPIC_BASE_URL
   ```
3. API 토큰이 유효한지 확인하십시오( [콘솔](https://platform.acedata.cloud/console)에서 확인 가능).
4. 터미널을 다시 시작해 보십시오.

### command not found: claude

설치 후 `command not found` 메시지가 표시되면 다음을 시도하십시오:

1. 터미널을 닫고 다시 엽니다.
2. PATH를 확인하십시오: `echo $PATH`
3. 재설치: `curl -fsSL https://claude.ai/install.sh | bash`

### 잔여 한도를 확인하는 방법은?

[AceData Cloud 콘솔](https://platform.acedata.cloud/console)에 로그인하면 현재 계정의 잔여 한도와 사용 현황을 확인할 수 있습니다.

## 더 알아보기

* 📖 [Claude Code CLI 공식 문서](https://code.claude.com/docs/en/quickstart)
* 📋 [CLI 명령 참조](https://code.claude.com/docs/en/cli-reference)
* 🔧 [AceData Cloud Claude Code 서비스](https://platform.acedata.cloud/documents/claude-messages)
* 💬 질문이 있으시면 플랫폼 고객 서비스에 문의해 주십시오.