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

개요

OpenClaw는 채팅 애플리케이션과 AI 에이전트 간의 브리지 역할을 하는 오픈 소스 AI 에이전트 Gateway입니다. 중앙 집중식 Gateway 프로세스를 통해 Telegram, WhatsApp, Discord, Feishu와 같은 채팅 플랫폼을 AI 프로그래밍 에이전트에 연결할 수 있습니다. 이 문서는 OpenClaw를 수동으로 설치하고 EvoLink API를 모델 제공자로 구성하는 방법을 설명합니다. 이 문서를 완료한 후 특정 채팅 채널(예: Telegram 또는 Feishu)을 계속 구성할 수 있습니다. 이 가이드의 내용:

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

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

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

확인 도구 다운로드

GitHub 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)

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

사전 요구 사항

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

1. Node.js 설치

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

Windows
macOS

Node.js 공식 웹사이트를 방문하여 Windows 설치 프로그램(.msi 파일)을 다운로드하고 실행합니다.설치 후 PowerShell에서 확인합니다:

node --version
npm --version

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

방법 1: 설치 프로그램 사용Node.js 공식 웹사이트를 방문하여 macOS 설치 프로그램(.pkg 파일)을 다운로드하고 실행합니다.방법 2: Homebrew 사용

brew install node

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

node --version
npm --version

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

2. EvoLink API 키 받기

EvoLink 콘솔에 로그인합니다
콘솔에서 API Keys를 찾아 “새 키 만들기”를 클릭하고 생성된 키를 복사합니다
API 키는 일반적으로 sk-로 시작합니다. 안전하게 보관하세요

1단계: OpenClaw 설치

터미널에서 실행합니다:

npm install -g openclaw@latest

설치 후 확인합니다:

openclaw --version

2단계: 초기 설정

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

openclaw onboard --install-daemon

1. 설치 확인

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

2. 설치 모드 선택

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

3. 제공자 선택

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

4. 모델 선택

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

5. 기본 모델 선택

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

6. 채널 선택

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

7. Skills 구성

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

8. Hooks 활성화

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

9. Gateway 서비스 재시작

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

10. 봇 시작

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

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

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

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

Windows
macOS

openclaw.json: %USERPROFILE%\.openclaw\openclaw.json
models.json: %USERPROFILE%\.openclaw\agents\main\agent\models.json

openclaw.json: ~/.openclaw/openclaw.json
models.json: ~/.openclaw/agents/main/agent/models.json

직접 열기:

open ~/.openclaw/openclaw.json
open ~/.openclaw/agents/main/agent/models.json

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

2. 모델 제공자 구성

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

"models": {
  "providers": {
    "evolink-anthropic": {
      "api": "anthropic-messages",
      "baseUrl": "https://direct.evolink.ai",
      "apiKey": "귀하의 EvoLink API 키",
      "models": [
        { "id": "evolink/auto", "name": "EvoLink Auto" },
        { "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-opus-4-5-20251101", "name": "Claude Opus 4.5" },
        { "id": "claude-opus-4-1-20250805", "name": "Claude Opus 4.1" },
        { "id": "claude-sonnet-4-5-20250929", "name": "Claude Sonnet 4.5" },
        { "id": "claude-sonnet-4-20250514", "name": "Claude Sonnet 4" },
        { "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" }
      ]
    }
  }
}

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

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

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

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

"agents": {
  "defaults": {
    "model": {
      "primary": "evolink-anthropic/evolink/auto"
    }
  }
}

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

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

스마트 라우팅: 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 명령을 사용하여 모델을 전환하는 것이 좋습니다:

# 구성된 EvoLink OpenAI 호환 모델 보기
openclaw models list --provider evolink-openai --plain

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

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

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

5. 재시작 및 확인

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

openclaw gateway restart

상태 확인:

openclaw gateway status

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

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 문서 참조
Feishu 채널 구성: OpenClaw + Feishu 문서 참조
자동 설치 도구 사용: OpenClaw 자동 설치 문서 참조

AI 코딩 도구

Documentation Index

​개요

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

​확인 도구 다운로드

​확인 항목

​사전 요구 사항

​1. Node.js 설치

​2. EvoLink API 키 받기

​1단계: OpenClaw 설치

​2단계: 초기 설정

​1. 설치 확인

​2. 설치 모드 선택

​3. 제공자 선택

​4. 모델 선택

​5. 기본 모델 선택

​6. 채널 선택

​7. Skills 구성

​8. Hooks 활성화

​9. Gateway 서비스 재시작

​10. 봇 시작

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

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

​2. 모델 제공자 구성

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

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

​5. 재시작 및 확인

​일반 명령

​문제 해결

​다음 단계

개요

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

확인 도구 다운로드

확인 항목

사전 요구 사항

1. Node.js 설치

2. EvoLink API 키 받기

1단계: OpenClaw 설치

2단계: 초기 설정

1. 설치 확인

2. 설치 모드 선택

3. 제공자 선택

4. 모델 선택

5. 기본 모델 선택

6. 채널 선택

7. Skills 구성

8. Hooks 활성화

9. Gateway 서비스 재시작

10. 봇 시작

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

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

2. 모델 제공자 구성

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

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

5. 재시작 및 확인

일반 명령

문제 해결

다음 단계