OpenClaw

OpenClaw는 오픈 소스 에이전트입니다. 내장된 설정 마법사나 명령으로 HiAPI를 모델 공급자로 추가한 뒤, Dashboard(브라우저의 콘솔)나 TUI(터미널의 채팅 인터페이스)에서 채팅할 수 있습니다. 아래 단계는 claude-opus-5-5를 예로 사용하며, HiAPI는 OpenAI Chat Completions 프로토콜을 사용합니다. 이 튜토리얼은 OpenClaw 2026.10.7에서 검증했습니다.

1. OpenClaw 설치

공식 설치 스크립트를 권장합니다. 필요한 Node.js 환경을 확인하고 준비해 줍니다. Mac / Linux / WSL2에서는 실행하세요:

curl -fsSL https://openclaw.ai/install.sh | bash

Windows에서는 PowerShell을 사용하세요:

iwr -useb https://openclaw.ai/install.ps1 | iex

설치한 뒤 터미널을 다시 열고 openclaw --version을 실행하세요. 버전 번호가 보이면 충분합니다.

2. OpenClaw 초기화 및 열기

먼저 HiAPI API 키를 준비하세요. 다른 모델을 사용하려면 텍스트 모델 목록에서 이름을 찾아 입력하세요.

처음 사용할 때 터미널에서 실행하세요:

openclaw onboard --install-daemon

안내에 따라 기본 설정을 완료하세요. 현재 버전은 브라우저에서 모델 설정 페이지를 엽니다. 클래식 터미널 마법사가 나타나면 QuickStart를 선택하고, 기본 에이전트로 main을 유지하며, 모델, 채널, 검색, 선택적 Skills는 Skip for now를 선택한 뒤 아래와 같이 HiAPI를 연결하세요. 이미 초기화했다면 Dashboard를 바로 여세요:

openclaw dashboard

OpenClaw는 백그라운드 Gateway 서비스로 실행됩니다. Gateway가 아직 실행 중이 아니라면 한 터미널에서 openclaw gateway run을 실행해 창을 열어 두고, 다른 터미널에서 openclaw dashboard를 실행하세요. 백그라운드 서비스를 설치했다면 openclaw gateway restart로 다시 시작할 수도 있습니다.

아래 스크린샷은 2026년 10월 28일 OpenClaw 2026.10.7의 독립 데모 인스턴스에서 찍은 것입니다. 포트는 사용하는 컴퓨터와 다를 수 있으므로 openclaw dashboard가 여는 주소를 사용하세요.

3. OpenClaw에 HiAPI 추가

Model settings 페이지에 처음 들어가면 Custom OpenAI/Anthropic-compatible endpoint를 찾아 Set up endpoint를 클릭합니다. 이미 초기화했다면 Settings → Models → Connect provider → On this Gateway로 이동해 같은 진입점을 열 수 있습니다.

3.1 API 주소 입력

API Base URL을 /chat/completions 없이 https://api.hiapi.ai/v1로 설정하고 Submit을 클릭합니다.

3.2 API 키 입력

How do you want to provide this API key? 단계에서 Paste API key now를 선택하고 HiAPI API 키를 붙여 넣은 뒤 Submit을 클릭합니다.

3.3 프로토콜 선택

Endpoint compatibility에서 OpenAI-compatible — Uses /chat/completions (즉 OpenAI Chat Completions 프로토콜)를 선택하세요. 모델이 Claude여도 이 프로토콜을 사용합니다.

3.4 모델 및 공급자 이름 입력

Model ID를 claude-opus-5-5로 설정하고 Submit을 클릭합니다.

Endpoint ID를 hiapi로 설정하고 Submit을 클릭합니다. 그러면 OpenClaw의 전체 모델 참조는 hiapi/claude-opus-5-5가 됩니다.

**Model alias (optional)**는 선택적 별칭이므로 비워 두고 제출해도 됩니다. 검증이 끝나면 최초 설정에 “Inference is ready”와 “Verified model: hiapi/claude-opus-5-5”가 표시됩니다.

4. 기본 모델 설정 및 채팅 확인

새 세션의 기본 모델을 설정한 뒤 구성을 확인하세요:

openclaw config set agents.defaults.model.primary hiapi/claude-opus-5-5
openclaw config validate
openclaw config get agents.defaults.model.primary

결과에 Config valid가 포함되고 마지막 명령이 hiapi/claude-opus-5-5를 출력하면 구성이 기록된 것입니다. 그래도 실제 메시지로 확인해야 합니다:

1. 아직 최초 설정 페이지에 있다면 Continue with the web app을 클릭한 뒤 Back to app을 클릭합니다.
2. 새 채팅을 시작하고 입력 상자 아래의 모델 이름을 클릭한 다음 Hiapi 그룹에서 방금 구성한 모델을 선택합니다. 기존 세션은 이전에 선택한 모델을 계속 사용할 수 있습니다.
3. “안녕하세요, 한 문장으로 자기소개를 해 주세요.”를 보내고 답을 기다립니다.

정상적으로 답하면 연결이 된 것입니다. 답변은 매번 다를 수 있으므로 현재 선택된 공급자, 요청 성공 여부, HiAPI 콘솔의 요청 로그를 기준으로 판단하세요.

터미널에서 채팅하려면 Gateway가 실행 중인 상태에서 실행하세요:

openclaw tui

5. 명령으로 구성 작성(선택 사항)

명령만으로도 모든 것을 할 수 있습니다: 초기화 → 구성 작성 → 확인. 위에서 웹 UI로 이미 구성했다면 이 섹션은 건너뛰세요. 먼저 명령의 YOUR_HIAPI_API_KEY를 자신의 HiAPI API 키로 바꾼 뒤 시스템에 맞는 명령을 실행하세요.

openclaw config patch --stdin <<'JSON'
{
  "agents": {
    "defaults": {
      "model": {
        "primary": "hiapi/claude-opus-5-5"
      }
    }
  },
  "models": {
    "mode": "merge",
    "providers": {
      "hiapi": {
        "baseUrl": "https://api.hiapi.ai/v1",
        "apiKey": "YOUR_HIAPI_API_KEY",
        "api": "openai-completions",
        "models": [
          {
            "id": "claude-opus-5-5",
            "name": "Claude Opus 5.5"
          }
        ]
      }
    }
  }
}
JSON

@'
{
  "agents": {
    "defaults": {
      "model": {
        "primary": "hiapi/claude-opus-5-5"
      }
    }
  },
  "models": {
    "mode": "merge",
    "providers": {
      "hiapi": {
        "baseUrl": "https://api.hiapi.ai/v1",
        "apiKey": "YOUR_HIAPI_API_KEY",
        "api": "openai-completions",
        "models": [
          {
            "id": "claude-opus-5-5",
            "name": "Claude Opus 5.5"
          }
        ]
      }
    }
  }
}
'@ | openclaw config patch --stdin

이 패치는 hiapi 공급자를 추가하고 기본 모델을 설정하며, 다른 공급자의 구성은 유지합니다. hiapi 공급자가 이미 있으면 패치가 그 구성을 갱신하고 모델 배열을 교체하므로, 기존 모델이 여러 개였다면 모두 배열에 먼저 적어 넣으세요.

Windows CMD에서는 위 JSON을 hiapi.patch.json으로 저장한 뒤 실행하세요:

openclaw config patch --file hiapi.patch.json

작성한 뒤에는 4단계와 같이 구성을 확인하고 새 채팅으로 검증하세요. Gateway를 재시작해야 한다고 나오면: 백그라운드 서비스를 설치했다면 openclaw gateway restart를 실행하고, 포그라운드로 실행 중이라면 그 창에서 Ctrl+C를 누른 뒤 openclaw gateway run을 다시 실행하세요.

6. 문제 해결

여기에는 OpenClaw에 특화된 문제만 정리했습니다. 401, 404, 429 같은 일반적인 오류는 자주 발생하는 오류를 참고하세요.