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

# OpenClaw

> OpenClaw 오픈소스 로컬 AI 어시스턴트 연동 가이드 (GravitexAI)

## 1. 개요

**OpenClaw**는 자체 머신에서 실행되는 오픈소스(MIT 라이선스) 로컬 AI 어시스턴트입니다. Telegram, WhatsApp, Discord, Slack, iMessage 등 메시징 플랫폼을 통해 상호작용하며 **파일 작업, 터미널 명령, 브라우저 제어, 예약 작업** 등 실제 자동화를 수행합니다.

**GravitexAI**(OpenAI 호환 API)와 함께 하나의 API 키로 GPT, Claude, Gemini, DeepSeek 등 400개 이상의 선도 모델에 OpenClaw가 접근할 수 있습니다.

<CardGroup cols={2}>
  <Card title="로컬 & 프라이버시" icon="shield">
    모든 데이터가 사용자 머신에 유지됩니다
  </Card>

  <Card title="멀티 플랫폼" icon="message-circle">
    Telegram / WhatsApp / Discord / Slack / iMessage
  </Card>

  <Card title="자율 실행" icon="wand-magic-sparkles">
    채팅을 넘어 실제로 컴퓨터를 조작합니다
  </Card>

  <Card title="확장 가능" icon="puzzle-piece">
    커스텀 skill 및 플러그인
  </Card>
</CardGroup>

<Info>
  Website: `openclaw.ai` ｜ Repo: `github.com/openclaw/openclaw` ｜ License: MIT
</Info>

## 2. 사전 요구사항

* [GravitexAI 콘솔](https://maas.gravitex.ai/#/keys)에서 API 키 생성
* Node.js 22 이상
* macOS / Linux / Windows

## 3. OpenClaw 설치

### 3.1 Node.js 설치

<CodeGroup>
  ```bash macOS (Homebrew) theme={null}
  brew install node@22
  ```

  ```bash Linux (nvm) theme={null}
  curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
  nvm install 22
  nvm use 22
  ```

  ```powershell Windows (fnm) theme={null}
  winget install Schniz.fnm
  fnm install 22
  fnm use 22
  ```
</CodeGroup>

### 3.2 OpenClaw 설치

<CodeGroup>
  ```bash npm (recommended) theme={null}
  npm install -g openclaw
  ```

  ```bash One-line (macOS/Linux) theme={null}
  curl -fsSL https://openclaw.ai/install.sh | bash
  ```

  ```powershell Windows PowerShell theme={null}
  irm https://openclaw.ai/install.ps1 | iex
  ```
</CodeGroup>

### 3.3 확인

```bash theme={null}
openclaw --version
openclaw doctor
```

`openclaw doctor`에서 문제가 보고되면 `openclaw doctor --fix`를 실행하세요.

## 4. GravitexAI 설정

OpenClaw 설정은 `~/.openclaw/openclaw.json`에 저장됩니다.

### 옵션 A — JSON 파일 편집 (권장)

```json theme={null}
{
  "agents": {
    "defaults": {
      "model": { "primary": "gravitex/claude-sonnet-4-6" }
    }
  },
  "models": {
    "providers": {
      "gravitex": {
        "baseUrl": "https://api.gravitex.ai/v1",
        "apiKey": "sk-your-gravitexai-key",
        "api": "openai-completions",
        "models": [
          { "id": "claude-sonnet-4-6", "name": "Claude Sonnet 4.6" },
          { "id": "gpt-5.4", "name": "GPT-5.4" },
          { "id": "deepseek-v3-2-251201", "name": "DeepSeek V3.2" },
          { "id": "gemini-3.1-pro-preview", "name": "Gemini 3.1 Pro" }
        ]
      }
    }
  }
}
```

<Tip>
  * `baseUrl`은 반드시 `/v1`로 끝나야 합니다
  * OpenAI 호환 모드는 `openai-completions`, 네이티브 Claude API는 `anthropic-messages` 사용
</Tip>

### 옵션 B — CLI 마법사

```bash theme={null}
openclaw onboard
```

| Field         | Value                            |
| ------------- | -------------------------------- |
| Provider name | `gravitex`                       |
| API type      | `openai-completions`             |
| Base URL      | `https://api.gravitex.ai/v1`     |
| API key       | GravitexAI 키                     |
| Default model | `claude-sonnet-4-6` 또는 `gpt-5.4` |

### 옵션 C — Anthropic 네이티브 모드

최상의 Claude tool-calling 경험을 위해:

```json theme={null}
{
  "agents": {
    "defaults": {
      "model": { "primary": "gravitex/claude-sonnet-4-6" }
    }
  },
  "models": {
    "providers": {
      "gravitex": {
        "baseUrl": "https://api.gravitex.ai",
        "apiKey": "sk-your-gravitexai-key",
        "api": "anthropic-messages",
        "models": [
          { "id": "claude-sonnet-4-6", "name": "Claude Sonnet 4.6" },
          { "id": "claude-haiku-4-5-20251001", "name": "Claude Haiku 4.5" }
        ]
      }
    }
  }
}
```

편집 후 gateway를 재시작하세요:

```bash theme={null}
openclaw gateway restart
```

## 5. 실행

### Web UI (권장)

```bash theme={null}
openclaw dashboard
```

브라우저에서 `http://127.0.0.1:18789/`를 엽니다.

### Telegram Bot

1. Telegram에서 `@BotFather`와 대화하고 `/newbot`을 전송합니다
2. Bot Token을 복사하여 `openclaw onboard`에 입력합니다
3. 방화벽 뒤에 있다면 먼저 프록시를 설정하세요:

```bash theme={null}
export https_proxy=http://127.0.0.1:PORT
export http_proxy=http://127.0.0.1:PORT
openclaw gateway restart
```

### 기타 채널

WhatsApp (QR), Discord, Slack, Signal, iMessage, Microsoft Teams 등.

## 6. 추천 모델

| Use case | Model ID                    | Notes                 |
| -------- | --------------------------- | --------------------- |
| 복잡한 작업   | `claude-sonnet-4-6`         | 최고의 tool calling 및 추론 |
| 일상 채팅    | `gpt-5.5`                   | 자연스럽고 범용적             |
| 코딩       | `deepseek-v3-2-251201`      | 강력한 코드, 우수한 가성비       |
| 긴 컨텍스트   | `gemini-3.1-pro-preview`    | 대용량 컨텍스트 윈도우          |
| 빠르고 저렴   | `claude-haiku-4-5-20251001` | 지연 시간 최적화             |
| 심층 추론    | `claude-opus-4-7`           | 복잡한 추론, 알고리즘 / 논리     |

전체 목록은 [GravitexAI 모델 마켓플레이스](https://maas.gravitex.ai/#/models)에서 확인하세요.

## 7. 내장 Skills

### 파일 & 시스템

| Skill                              | Purpose                |
| ---------------------------------- | ---------------------- |
| `fs.read` / `fs.write` / `fs.edit` | 파일 읽기 / 쓰기 / 편집        |
| `shell.exec`                       | 터미널 명령 실행              |
| `shell.process`                    | 실행 중인 프로세스 관리          |
| `browser.*`                        | 브라우저 제어 (열기, 클릭, 스크린샷) |

### 지능

| Skill                          | Purpose         |
| ------------------------------ | --------------- |
| `web_search` / `web_fetch`     | 웹 검색 및 페이지 가져오기 |
| `memory_search` / `memory_get` | 장기 메모리          |
| `cron.*`                       | 알림 및 예약 작업      |
| `tts`                          | 텍스트 음성 변환       |

## 8. 명령어

### 터미널

| Command                               | Purpose      |
| ------------------------------------- | ------------ |
| `openclaw onboard`                    | 설정 마법사       |
| `openclaw gateway start/stop/restart` | gateway 제어   |
| `openclaw status`                     | 실행 상태 표시     |
| `openclaw doctor [--fix]`             | 진단 / 자동 수정   |
| `openclaw dashboard`                  | Web UI 열기    |
| `openclaw logs --follow`              | 로그 tail      |
| `openclaw configure`                  | 설정 편집        |
| `openclaw update`                     | 최신 버전으로 업데이트 |

### 채팅

| Command           | Purpose       |
| ----------------- | ------------- |
| `/help`           | 도움말 표시        |
| `/new` / `/reset` | 새 대화 / 대화 초기화 |
| `/stop`           | 현재 작업 취소      |
| `/model <name>`   | 모델 전환         |
| `/think <level>`  | 추론 깊이         |
| `/verbose on/off` | 상세 모드 전환      |
| `/skills`         | skill 목록      |

## 9. 예시

```text theme={null}
> Create test.txt on my Desktop with the text "hello GravitexAI"
> List every file on my Desktop
> Open maas.gravitex.ai in the browser and screenshot the page
> Remind me to drink water every day at 9:00
> Write a Python script that batch-renames every image in ~/Pictures
```

## 10. 문제 해결

<AccordionGroup>
  <Accordion title="401 / invalid API key">
    * [GravitexAI 콘솔](https://maas.gravitex.ai/#/keys)에서 키를 다시 복사하세요, 불필요한 공백에 주의
    * JSON 파일의 `apiKey`에 따옴표나 전각 문자가 없는지 확인
  </Accordion>

  <Accordion title="404 / wrong endpoint">
    * `openai-completions` 모드: `baseUrl`은 반드시 `/v1`로 끝나야 함
    * `anthropic-messages` 모드: `baseUrl`은 `https://api.gravitex.ai` (`/v1` 없음)
  </Accordion>

  <Accordion title="Model not found">
    * [모델 마켓플레이스](https://maas.gravitex.ai/#/models)에서 모델 ID 확인
  </Accordion>

  <Accordion title="설정 변경이 반영되지 않음">
    * 파일 편집 후 `openclaw gateway restart`로 재시작
    * `openclaw doctor`로 활성 설정 확인
  </Accordion>
</AccordionGroup>