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

# OpenClaw 수동 설치 - 스마트 모델 라우팅

> OpenClaw Gateway를 수동으로 설치하고 구성하기 (스마트 모델 라우팅 지원)

## 개요

OpenClaw는 채팅 애플리케이션과 AI 에이전트 간의 브리지 역할을 하는 오픈 소스 AI 에이전트 Gateway입니다. 중앙 집중식 Gateway 프로세스를 통해 Telegram, WhatsApp, Discord, Feishu와 같은 채팅 플랫폼을 AI 프로그래밍 에이전트에 연결할 수 있습니다.

이 문서는 OpenClaw를 수동으로 설치하고 **EvoLink API**를 모델 제공자로 구성하는 방법을 설명합니다. 이 문서를 완료한 후 특정 채팅 채널(예: Telegram 또는 Feishu)을 계속 구성할 수 있습니다.

**이 가이드의 내용:**

* OpenClaw Gateway 설치 및 구성
* EvoLink API를 사용자 정의 모델 제공자로 구성
* 설치 확인

## 시스템 환경 확인 (선택 사항)

설치를 시작하기 전에 환경 확인 도구를 실행하여 시스템이 OpenClaw의 요구 사항을 충족하는지 확인하는 것이 좋습니다.

### 확인 도구 다운로드

[GitHub Releases](https://github.com/suuuuuu-1/openclaw-env-checker/releases)에서 플랫폼에 맞는 확인 도구를 다운로드하세요:

| 플랫폼                   | 파일명                            |
| --------------------- | ------------------------------ |
| Windows               | `openclaw-checker-win-x64.exe` |
| macOS (Intel)         | `openclaw-checker-macos-x64`   |
| macOS (Apple Silicon) | `openclaw-checker-macos-arm64` |
| Linux                 | `openclaw-checker-linux-x64`   |

### 확인 항목

도구는 다음을 자동으로 확인합니다:

* ✅ Node.js 버전 (>= 22.12.0 필요)
* ✅ npm 사용 가능
* ✅ Git 사용 가능
* ✅ 네트워크 연결 (github.com, npmjs.org, evolink.ai)

<img src="https://mintcdn.com/muyutechnology/nIFIx0gxdF53THw8/images/OpenClaw-Checker/check-success.png?fit=max&auto=format&n=nIFIx0gxdF53THw8&q=85&s=46f1fdbec3263845e35158b104fa5091" alt="확인 성공 예시" width="1778" height="1742" data-path="images/OpenClaw-Checker/check-success.png" />

확인이 실패하면 도구가 구체적인 수정 제안을 제공합니다.

## 사전 요구 사항

구성을 시작하기 전에 다음을 완료했는지 확인하세요:

### 1. Node.js 설치

OpenClaw는 npm을 통해 설치되며 Node.js 22 이상이 필요합니다.

<Tabs>
  <Tab title="Windows">
    [Node.js 공식 웹사이트](https://nodejs.org/ko/download)를 방문하여 Windows 설치 프로그램(.msi 파일)을 다운로드하고 실행합니다.

    설치 후 PowerShell에서 확인합니다:

    ```bash theme={null}
    node --version
    npm --version
    ```

    <Note>
      설치 중 권한 문제를 피하기 위해 PowerShell을 관리자 권한으로 실행하는 것이 좋습니다.
    </Note>
  </Tab>

  <Tab title="macOS">
    **방법 1: 설치 프로그램 사용**

    [Node.js 공식 웹사이트](https://nodejs.org/ko/download)를 방문하여 macOS 설치 프로그램(.pkg 파일)을 다운로드하고 실행합니다.

    **방법 2: Homebrew 사용**

    ```bash theme={null}
    brew install node
    ```

    설치 후 터미널에서 확인합니다:

    ```bash theme={null}
    node --version
    npm --version
    ```

    <Note>
      설치 중 권한 문제가 발생하면 명령 앞에 `sudo`를 추가해야 할 수 있습니다.
    </Note>
  </Tab>
</Tabs>

### 2. EvoLink API 키 받기

* [EvoLink 콘솔](https://evolink.ai/dashboard)에 로그인합니다
* 콘솔에서 API Keys를 찾아 "새 키 만들기"를 클릭하고 생성된 키를 복사합니다
* API 키는 일반적으로 `sk-`로 시작합니다. 안전하게 보관하세요

## 1단계: OpenClaw 설치

터미널에서 실행합니다:

```bash theme={null}
npm install -g openclaw@latest
```

설치 후 확인합니다:

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

## 2단계: 초기 설정

온보딩 명령을 실행합니다. OpenClaw가 초기 구성을 안내하고 데몬 서비스를 설치합니다:

```bash theme={null}
openclaw onboard --install-daemon
```

### 1. 설치 확인

시스템이 설치 주의 사항을 표시합니다. 확인하고 계속합니다:

<img src="https://mintcdn.com/muyutechnology/9zwrwFbHVtE0nZ-d/images/OpenClaw-Telegram/ScreenShot_2026-02-08_011629_241.png?fit=max&auto=format&n=9zwrwFbHVtE0nZ-d&q=85&s=fce0ba49fe04129dc943e6f63353595e" alt="설치 확인" width="1488" height="1420" data-path="images/OpenClaw-Telegram/ScreenShot_2026-02-08_011629_241.png" />

### 2. 설치 모드 선택

시스템이 설치 모드 선택을 요청합니다. **Quickstart**를 선택합니다:

<img src="https://mintcdn.com/muyutechnology/9zwrwFbHVtE0nZ-d/images/OpenClaw-Telegram/ScreenShot_2026-02-08_011705_241.png?fit=max&auto=format&n=9zwrwFbHVtE0nZ-d&q=85&s=24fbf84b590649d1fc1d515d2ee50609" alt="Quickstart 선택" width="1738" height="1540" data-path="images/OpenClaw-Telegram/ScreenShot_2026-02-08_011705_241.png" />

### 3. 제공자 선택

시스템이 모델 제공자 선택을 요청합니다. 여기서는 **Skip**을 선택합니다. 나중에 EvoLink를 사용자 정의 제공자로 수동 구성합니다:

<img src="https://mintcdn.com/muyutechnology/9zwrwFbHVtE0nZ-d/images/OpenClaw-Telegram/ScreenShot_2026-02-08_011742_033.png?fit=max&auto=format&n=9zwrwFbHVtE0nZ-d&q=85&s=a4f74b3bb72312ba426ea37179232576" alt="제공자 선택 건너뛰기" width="1398" height="1272" data-path="images/OpenClaw-Telegram/ScreenShot_2026-02-08_011742_033.png" />

### 4. 모델 선택

시스템이 활성화할 모델 선택을 요청합니다. **All**을 선택합니다:

<img src="https://mintcdn.com/muyutechnology/9zwrwFbHVtE0nZ-d/images/OpenClaw-Telegram/ScreenShot_2026-02-08_011808_857.png?fit=max&auto=format&n=9zwrwFbHVtE0nZ-d&q=85&s=701f58ca7164b7830cef3bfb713d911b" alt="모든 모델 선택" width="1380" height="1528" data-path="images/OpenClaw-Telegram/ScreenShot_2026-02-08_011808_857.png" />

### 5. 기본 모델 선택

시스템이 기본 모델 선택을 요청합니다. **Keep current**를 선택합니다:

<img src="https://mintcdn.com/muyutechnology/9zwrwFbHVtE0nZ-d/images/OpenClaw-Telegram/ScreenShot_2026-02-08_011825_375.png?fit=max&auto=format&n=9zwrwFbHVtE0nZ-d&q=85&s=5ded0a9c44fd991865dbe84195862563" alt="현재 모델 유지" width="1334" height="1792" data-path="images/OpenClaw-Telegram/ScreenShot_2026-02-08_011825_375.png" />

### 6. 채널 선택

시스템이 채팅 채널 선택을 요청합니다. \*\*Skip for now(지금은 건너뛰기)\*\*를 선택하는 것이 좋습니다. 나중에 채널을 추가할 수 있습니다:

<img src="https://mintcdn.com/muyutechnology/NlmbcWype-ERs65V/images/OpenClaw-Telegram/%E9%80%89%E6%8B%A9%E6%B8%A0%E9%81%93.png?fit=max&auto=format&n=NlmbcWype-ERs65V&q=85&s=15c688d8a70b5f8ae165dd2cd86882c7" alt="채널 선택" width="1328" height="700" data-path="images/OpenClaw-Telegram/选择渠道.png" />

### 7. Skills 구성

시스템이 Skills 구성 여부를 묻습니다. **No**를 선택하는 것이 좋습니다. 나중에 추가할 수 있습니다:

<img src="https://mintcdn.com/muyutechnology/NlmbcWype-ERs65V/images/OpenClaw-Telegram/%E9%85%8D%E7%BD%AESkills.png?fit=max&auto=format&n=NlmbcWype-ERs65V&q=85&s=5edf42414955f53d15cee1be85331183" alt="Skills 구성" width="672" height="355" data-path="images/OpenClaw-Telegram/配置Skills.png" />

### 8. Hooks 활성화

시스템이 Hooks 활성화 여부를 묻습니다. **session-memory**를 선택하는 것이 좋습니다:

<img src="https://mintcdn.com/muyutechnology/JJmr3OHsJ7C2UIEk/images/OpenClaw-Telegram/%E5%90%AF%E5%8A%A8%E6%9C%BA%E5%99%A8%E4%BA%BA.png?fit=max&auto=format&n=JJmr3OHsJ7C2UIEk&q=85&s=c7cd5c913d22a3ac5a7985055d6d60dd" alt="Hooks 활성화" width="1325" height="534" data-path="images/OpenClaw-Telegram/启动机器人.png" />

### 9. Gateway 서비스 재시작

시스템이 Gateway 서비스가 이미 설치되어 있음을 알립니다. \*\*Restart(재시작)\*\*를 선택합니다:

<img src="https://mintcdn.com/muyutechnology/NlmbcWype-ERs65V/images/OpenClaw-Telegram/%E9%87%8D%E5%90%AF%E7%BD%91%E5%85%B3.png?fit=max&auto=format&n=NlmbcWype-ERs65V&q=85&s=42712c7e9dbe454441e005d2275e8d3d" alt="Gateway 재시작" width="1129" height="327" data-path="images/OpenClaw-Telegram/重启网关.png" />

### 10. 봇 시작

시스템이 봇 시작 방법을 묻습니다. \*\*Do this later(나중에 하기)\*\*를 선택하는 것이 좋습니다:

<img src="https://mintcdn.com/muyutechnology/JJmr3OHsJ7C2UIEk/images/OpenClaw-Telegram/%E5%90%AF%E7%94%A8Hooks.png?fit=max&auto=format&n=JJmr3OHsJ7C2UIEk&q=85&s=91d5235d050ce3ef829d16de768237a4" alt="봇 시작" width="1227" height="459" data-path="images/OpenClaw-Telegram/启用Hooks.png" />

## 3단계: EvoLink API 및 모델 전환 구성

### 1. 두 개의 구성 파일 찾기 (중요)

OpenClaw 모델 구성에는 일반적으로 두 개의 파일이 관련됩니다:

<Tabs>
  <Tab title="Windows">
    * `openclaw.json`: `%USERPROFILE%\.openclaw\openclaw.json`
    * `models.json`: `%USERPROFILE%\.openclaw\agents\main\agent\models.json`
  </Tab>

  <Tab title="macOS">
    * `openclaw.json`: `~/.openclaw/openclaw.json`
    * `models.json`: `~/.openclaw/agents/main/agent/models.json`

    직접 열기:

    ```bash theme={null}
    open ~/.openclaw/openclaw.json
    open ~/.openclaw/agents/main/agent/models.json
    ```
  </Tab>
</Tabs>

<Warning>
  `models.json`의 제공자 `apiKey` / `baseUrl`이 비어 있지 않으면 `openclaw.json`의 해당 값을 재정의합니다. 둘 다 일관되게 유지하는 것이 좋습니다.
</Warning>

### 2. 모델 제공자 구성

`openclaw.json`에서 다음 제공자를 구성하는 것이 좋습니다 (`models.json`과 동기화):

```json theme={null}
"models": {
  "providers": {
    "evolink-anthropic": {
      "api": "anthropic-messages",
      "baseUrl": "https://direct.evolink.ai",
      "apiKey": "귀하의 EvoLink API 키",
      "models": [
        { "id": "evolink/auto", "name": "EvoLink Auto" },
        { "id": "claude-fable-5", "name": "Claude Fable 5" },
        { "id": "claude-opus-4-8", "name": "Claude Opus 4.8" },
        { "id": "claude-opus-4-7", "name": "Claude Opus 4.7" },
        { "id": "claude-opus-4-6", "name": "Claude Opus 4.6" },
        { "id": "claude-sonnet-4-6", "name": "Claude Sonnet 4.6" },
        { "id": "claude-sonnet-5", "name": "Claude Sonnet 5" },
        { "id": "claude-opus-4-5-20251101", "name": "Claude Opus 4.5" },
        { "id": "claude-sonnet-4-5-20250929", "name": "Claude Sonnet 4.5" },
        { "id": "claude-haiku-4-5-20251001", "name": "Claude Haiku 4.5" }
      ]
    },
    "evolink-google": {
      "api": "google-generative-ai",
      "baseUrl": "https://direct.evolink.ai/v1beta",
      "apiKey": "귀하의 EvoLink API 키",
      "models": [
        { "id": "evolink/auto", "name": "EvoLink Auto" },
        { "id": "gemini-3.1-flash-lite-preview", "name": "Gemini 3.1 Flash Lite" },
        { "id": "gemini-3.1-pro-preview", "name": "Gemini 3.1 Pro" },
        { "id": "gemini-2.5-pro", "name": "Gemini 2.5 Pro" },
        { "id": "gemini-2.5-flash", "name": "Gemini 2.5 Flash" },
        { "id": "gemini-3-pro-preview", "name": "Gemini 3.0 Pro" },
        { "id": "gemini-3-flash-preview", "name": "Gemini 3.0 Flash" }
      ]
    },
    "evolink-openai": {
      "api": "openai-completions",
      "baseUrl": "https://direct.evolink.ai/v1",
      "apiKey": "귀하의 EvoLink API 키",
      "models": [
        { "id": "gpt-5.4", "name": "GPT-5.4" },
        { "id": "gpt-5.2", "name": "GPT-5.2" },
        { "id": "gpt-5.1", "name": "GPT-5.1" },
        { "id": "gpt-5.1-chat", "name": "GPT-5.1 Chat" },
        { "id": "gpt-5.1-thinking", "name": "GPT-5.1 Thinking" },
        { "id": "gemini-2.5-pro", "name": "Gemini 2.5 Pro (OpenAI SDK)" },
        { "id": "gemini-2.5-flash", "name": "Gemini 2.5 Flash (OpenAI SDK)" },
        { "id": "gemini-3-pro-preview", "name": "Gemini 3.0 Pro (OpenAI SDK)" },
        { "id": "gemini-3-flash-preview", "name": "Gemini 3.0 Flash (OpenAI SDK)" },
        { "id": "doubao-seed-2.0-pro", "name": "Doubao Seed 2.0 Pro" },
        { "id": "doubao-seed-2.0-lite", "name": "Doubao Seed 2.0 Lite" },
        { "id": "doubao-seed-2.0-mini", "name": "Doubao Seed 2.0 Mini" },
        { "id": "doubao-seed-2.0-code", "name": "Doubao Seed 2.0 Code" },
        { "id": "kimi-k2-thinking", "name": "Kimi K2 Thinking" },
        { "id": "kimi-k2-thinking-turbo", "name": "Kimi K2 Thinking Turbo" }
      ]
    }
  }
}
```

<Note>
  위의 모델 ID는 예시입니다. EvoLink 계정에서 실제로 사용 가능한 모델을 사용하세요.
</Note>

<Warning>
  Gemini 시나리오의 경우 `evolink-google.baseUrl`에 `/v1beta`가 포함되어야 합니다. 즉, `https://direct.evolink.ai/v1beta`입니다. 이 접미사가 없으면 `Forbidden (403)` 오류가 발생할 수 있습니다.
</Warning>

### 3. 기본 모델 구성 (빠른 전환 지원)

`agents.defaults`에서 기본 모델을 설정합니다. 스마트 모델 라우팅 `evolink/auto` 사용을 권장합니다. 요청에 따라 자동으로 적합한 모델이 선택됩니다:

```json theme={null}
"agents": {
  "defaults": {
    "model": {
      "primary": "evolink-anthropic/evolink/auto"
    }
  }
}
```

<Tip>
  **스마트 모델 라우팅 (EvoLink Auto)**: 모델 ID로 `evolink/auto`를 사용하면 요청의 복잡도, 길이, 유형에 따라 모델 풀에서 적합한 모델이 자동으로 선택됩니다. 수동 전환이 필요 없으며 대부분의 범용 시나리오에 적합합니다. 자세한 내용은 [EvoLink Auto 문서](/ko/api-manual/language-series/evolink-auto/evolink-auto-quickstart)를 참조하세요.
</Tip>

특정 모델을 지정하려면 수동으로 전환할 수도 있습니다:

* 스마트 라우팅: `evolink-anthropic/evolink/auto` (권장)
* Claude: `evolink-anthropic/claude-opus-4-6`
* GPT: `evolink-openai/gpt-5.2`
* Gemini: `evolink-google/gemini-3.1-pro-preview`
* Doubao: `evolink-openai/doubao-seed-2.0-mini`

### 4. EvoLink 모델로 빠른 전환 (권장)

제공자 구성을 완료한 후 JSON을 수동으로 편집하는 대신 CLI 명령을 사용하여 모델을 전환하는 것이 좋습니다:

```bash theme={null}
# 구성된 EvoLink OpenAI 호환 모델 보기
openclaw models list --provider evolink-openai --plain

# 기본 모델 전환 (예: gpt-5.4)
openclaw models set evolink-openai/gpt-5.4

# 현재 활성 모델 보기
openclaw models status --plain
```

<Note>
  `models list --provider evolink-openai`가 예상 모델을 표시하지 않으면 `openclaw.json`과 `models.json` 모두에 해당 제공자가 구성되어 있는지 확인하세요.
</Note>

### 5. 재시작 및 확인

구성 후 게이트웨이를 재시작합니다:

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

상태 확인:

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

테스트 메시지를 보내 모델이 작동하는지 확인합니다:

```bash theme={null}
openclaw agent --agent main -m "hi" --json
```

## 일반 명령

| 명령                         | 설명              |
| -------------------------- | --------------- |
| `openclaw gateway status`  | 게이트웨이 실행 상태 확인  |
| `openclaw gateway restart` | 게이트웨이 서비스 재시작   |
| `openclaw gateway stop`    | 게이트웨이 서비스 중지    |
| `openclaw gateway start`   | 게이트웨이 서비스 시작    |
| `openclaw logs --follow`   | 게이트웨이 로그 실시간 보기 |
| `openclaw plugins list`    | 설치된 플러그인 보기     |

## 문제 해결

| 문제                           | 해결 방법                                                                                                |
| ---------------------------- | ---------------------------------------------------------------------------------------------------- |
| npm 설치 실패                    | Windows: PowerShell을 관리자 권한으로 실행; macOS: 명령 앞에 `sudo` 추가                                             |
| 구성 파일을 찾을 수 없음               | 온보딩 프로세스가 완료되었는지 확인하고 `~/.openclaw/` 디렉토리가 존재하는지 확인                                                  |
| 게이트웨이가 시작되지 않음               | 포트가 사용 중인지 확인하고 `openclaw gateway status`를 사용하여 자세한 오류 확인                                            |
| 잘못된 API 키                    | API 키가 올바르게 복사되었는지 확인하고 추가 공백이나 따옴표가 없는지 확인                                                          |
| 모델 구성이 적용되지 않음               | `openclaw.json`과 `models.json`의 일관성 확인 (`models.json`이 재정의할 수 있음)                                    |
| Gemini가 `Forbidden (403)` 반환 | `models.providers.evolink-google.baseUrl`이 `https://direct.evolink.ai/v1beta`인지 확인 (`/v1beta` 포함 필요) |
| 전환 후에도 이전 모델 사용              | `openclaw models status --plain`을 실행하여 현재 모델을 확인하고 필요시 `openclaw gateway restart`로 재시작               |

## 다음 단계

OpenClaw 설치 및 EvoLink API 구성이 완료되었습니다. 다음을 수행할 수 있습니다:

* **Telegram 채널 구성**: [OpenClaw + Telegram](/ko/integration-guide/openclaw-telegram) 문서 참조
* **Feishu 채널 구성**: [OpenClaw + Feishu](/ko/integration-guide/openclaw-feishu) 문서 참조
* **자동 설치 도구 사용**: [OpenClaw 자동 설치](/ko/integration-guide/openclaw-auto) 문서 참조