---
title: Ubuntu 24.04에 OpenClaw를 설치해 보았다
description: "인프라 / 자체 호스팅 AI 에이전트 # Ubuntu 24.04에 OpenClaw 설치해보기 Windows Server 2019 및 Windows 11에 이어 이번에는 Ubuntu 24.04에 OpenClaw 설치를 검증했습니다. Linux 네이티브 환경은 공식 지원 대상이며, Windows 환경에 비해 훨씬 간단합니다. 다만 **원격 대시보드 액세스에는 디바이스…"
url: "https://bestnetllc.co.jp/ko/docs/ubuntu-24-04%ec%97%90-openclaw%eb%a5%bc-%ec%84%a4%ec%b9%98%ed%95%b4-%eb%b3%b4%ec%95%98%eb%8b%a4/"
updated: "2026-10-19"
category: Tech Blog
---

# Ubuntu 24.04에 OpenClaw를 설치해 보았다

인프라 / 자체 호스팅 AI 에이전트

# Ubuntu 24.04에 OpenClaw 설치해보기

Windows Server 2019 및 Windows 11에 이어 이번에는 Ubuntu 24.04에 OpenClaw 설치를 검증했습니다.
Linux 네이티브 환경은 공식 지원 대상이며, Windows 환경에 비해 훨씬 간단합니다.
다만 **원격 대시보드 액세스에는 디바이스 페어링 승인이 필요**하다는 함정이 있었습니다.
해당 절차를 포함하여 전체 기록을 공개합니다.

OpenClaw
Ubuntu 24.04
Linux
nginx
HTTPS
GPUStack**이전 글과의 관계**
본 글은 “Windows Server 2019” 및 “Windows 11”에 OpenClaw 설치 기록의 후속편입니다.
Windows 환경에서 고생했던 PATH 문제, npm 버그, NODE_OPTIONS 문제는 Ubuntu에서는 전혀 발생하지 않았습니다.

## 환경 구성

OpenClaw 호스트

- Ubuntu 24.04 LTS
- OpenClaw v2026.4.10 (npm 설치)
- Node.js v22.22.2 (설치 프로그램이 자동 설정)
- nginx 리버스 프록시 (443/HTTPS)
- Gateway 포트: 18789 (loopback)

모델 및 검색 백엔드

- GPUStack + vLLM 0.17.1
- Qwen2.5-14B-Instruct
- SearXNG (온프레미스)
- Custom Provider (OpenAI 호환)

**Windows와의 큰 차이점**
Ubuntu에서는 공식 설치 프로그램(`install.sh`) 하나로 Node.js 설정부터 OpenClaw 설치 및 온보딩까지 완료됩니다.
systemd를 사용할 수 있기 때문에 Gateway의 서비스화도 자동으로 이루어집니다.

## 설치 절차

1. ### 패키지 업데이트 및 필요한 도구 설치
   ```
   sudo apt update && sudo apt upgrade -y
   sudo apt install -y curl git
   ```
2. ### OpenClaw 설치
   공식 설치 프로그램을 실행합니다. Node.js 설정도 포함하여 자동으로 처리됩니다.
   ```
   curl -fsSL https://openclaw.ai/install.sh | bash
   ```
   설치 프로그램이 다음을 자동으로 수행합니다.
   - Node.js v22 설치 (NodeSource 경유)
   - 빌드 도구 (make / g++ / cmake) 설치
   - OpenClaw npm 패키지 설치
   - 온보딩 마법사 시작
   **Windows와의 차이점**
   Ubuntu에서는 npm 설치 시 MODULE_NOT_FOUND가 발생하지 않았습니다.
   pnpm으로 전환할 필요도 없습니다. 공식 설치 프로그램이 그대로 작동합니다.
3. ### 온보딩
   설치 완료 후 자동으로 마법사가 시작됩니다. 설정 항목은 다음과 같습니다.
   - 보안 경고: `Yes`로 계속
   - Setup mode: `QuickStart`
   - 모델 프로바이더: **Custom Provider**
   - Base URL: `http://<GPUStack의 IP>/v1`
   - API Key 제공 방법: **Paste API key now**
   - Endpoint compatibility: `OpenAI-compatible`
   - Model ID: GPUStack에서 실행 중인 모델 이름
   - 채널: **Skip for now**
   - 스킬 종속성: **Skip for now**
   - Web 검색: **SearXNG Search** → URL 입력
   - Hooks: `session-memory`만 활성화
   온보딩 완료 후, **systemd 서비스가 자동으로 설치 및 시작**됩니다.
4. ### 컨텍스트 상한 및 모델 설정 수정(중요)
   온보딩 직후 대화를 시작하면 `Context limit exceeded` 오류가 발생할 수 있습니다.
   **설치 직후 다음 설정을 수행하면 회피할 수 있습니다.**
   ### 방법①: 대시보드 UI에서 설정(권장)
   대시보드 왼쪽 메뉴의 **“AI 및 에이전트”** →
   **“Models”탭** → 해당 모델의 **“Compat”** 섹션을 열고,
   다음 값을 설정한 후 **“Save”**를 누릅니다.
   - **Context Tokens**: `65536`
   - **Context Window**: `65536`
     [![](https://bestnetllc.co.jp/wp-content/uploads/2026/04/annotated_image1.png)](https://bestnetllc.co.jp/wp-content/uploads/2026/04/annotated_image1.png)
   - **Max Tokens**: `4096`(기본값 유지)
     [![](https://bestnetllc.co.jp/wp-content/uploads/2026/04/annotated_image2.png)](https://bestnetllc.co.jp/wp-content/uploads/2026/04/annotated_image2.png)
   ### 방법②: 명령줄에서 설정
   ```
   # compaction 버퍼 증가
   openclaw config set agents.defaults.compaction.reserveTokensFloor 20000
   # contextWindow 수동 수정(프로바이더 이름은 환경에 맞게 변경)
   python3 - << 'EOF'
   import json, os
   path = os.path.expanduser("~/.openclaw/openclaw.json")
   with open(path) as f:
       c = json.load(f)
   for k, v in c["models"]["providers"].items():
       for m in v.get("models", []):
           m["contextWindow"] = 65536
           m["maxTokens"] = 4096
   with open(path, "w") as f:
       json.dump(c, f, indent=2, ensure_ascii=False)
   print("업데이트 완료")
   EOF
   openclaw gateway restart
   ```
   **UI에서 설정하는 것이 더 확실합니다**
   대시보드에서 설정하면 변경 사항이 즉시 반영되며 설정 오류도 방지할 수 있습니다.
   CLI 설정 후에는 반드시 `openclaw gateway restart`가 필요합니다.
5. ### Gateway 시작 확인
   ```
   openclaw gateway status
   systemctl --user is-enabled openclaw-gateway.service
   ```
   `enabled`로 표시되면 OS 부팅 시 자동으로 시작됩니다.

## 다른 단말기에서의 원격 액세스 설정(nginx + 자체 서명 인증서)

대시보드를 네트워크를 통해 다른 단말에서 사용하려면 nginx로 리버스 프록시를 구성합니다.
WebSocket도 사용하므로 nginx 설정에 Upgrade 헤더 전송이 필요합니다.

1. ### nginx와 자체 서명 인증서 설정
   ```
   sudo apt install -y nginx
   # 자체 서명 인증서 생성(유효기간 10년)
   sudo mkdir -p /etc/nginx/ssl
   sudo openssl req -x509 -nodes -days 3650 -newkey rsa:2048 
     -keyout /etc/nginx/ssl/openclaw.key 
     -out /etc/nginx/ssl/openclaw.crt 
     -subj "/CN=openclaw.local"
   ```
2. ### nginx 설정 파일 생성
   ```
   sudo tee /etc/nginx/sites-available/openclaw << 'EOF'
   server {
       listen 443 ssl;
       server_name _;
       ssl_certificate     /etc/nginx/ssl/openclaw.crt;
       ssl_certificate_key /etc/nginx/ssl/openclaw.key;
       location / {
           proxy_pass http://127.0.0.1:18789;
           proxy_http_version 1.1;
           proxy_set_header Upgrade $http_upgrade;
           proxy_set_header Connection "upgrade";
           proxy_set_header Host $host;
           proxy_set_header X-Real-IP $remote_addr;
           proxy_read_timeout 86400;
       }
   }
   server {
       listen 80;
       return 301 https://$host$request_uri;
   }
   EOF
   sudo ln -sf /etc/nginx/sites-available/openclaw /etc/nginx/sites-enabled/
   sudo rm -f /etc/nginx/sites-enabled/default
   sudo nginx -t && sudo systemctl restart nginx
   sudo systemctl enable nginx
   ```
3. ### OpenClaw 설정 변경
   ```
   # localhost가 아닌 곳에서의 연결 허용
   openclaw config set gateway.controlUi.allowInsecureAuth true
   # 접속 출처 오리진 허용
   openclaw config set gateway.controlUi.allowedOrigins '["*"]'
   openclaw gateway restart
   ```
4. ### 방화벽 포트 열기
   ```
   sudo ufw allow 443/tcp
   sudo ufw allow 80/tcp
   ```

## 원격 접속 시 디바이스 페어링 승인

다른 단말에서 대시보드에 접속하면 **pairing required** 오류가 표시됩니다.
이것은 OpenClaw의 보안 기능으로, 최초 접속 시 관리자의 승인이 필요합니다.
한 번 승인하면 이후에는 불필요합니다.

**흔한 실수**
채널(Telegram·Discord 등)의 페어링에 사용하는 `openclaw pairing` 명령은 **여기서는 사용하지 않습니다**.
대시보드의 디바이스 승인은 `openclaw devices` 명령을 사용합니다.

1. ### 브라우저에서 대시보드에 접속
   토큰이 포함된 URL을 브라우저에서 엽니다. 서버 측에서 확인합니다.
   ```
   openclaw dashboard
   # 표시된 URL(#token=...)을 브라우저에서 열기
   ```
   브라우저에 `pairing required`가 표시된 상태 그대로 다음으로 진행합니다.
2. ### Pending 목록을 확인하고 승인
   ```
   # 페어링 대기 중인 디바이스 목록 표시
   openclaw devices list
   # 표시된 Request ID를 모두 승인
   openclaw devices approve <Request ID>
   ```
   Pending에 여러 요청이 있는 경우 모두 승인합니다.
3. ### 브라우저에서 재접속
   승인 후, 브라우저의 “연결” 버튼을 누르면 대시보드가 열립니다.

**승인은 영구적입니다**
한 번 승인한 디바이스는 Gateway를 재시작해도 재승인이 불필요합니다.
브라우저의 캐시를 삭제하거나 다른 브라우저를 사용하면 새로운 디바이스로 간주되어 재승인이 필요합니다.

## GPUStack 측 설정

GPUStack 관리 화면에서 모델의 백엔드 파라미터에 다음을 추가하고 모델을 재시작합니다.

```
--max-model-len 32768
--generation-config vllm
--enable-auto-tool-choice
--tool-call-parser hermes
```

## Windows 환경과의 비교

Ubuntu에서 편리해진 점

- `install.sh` 하나로 Node.js부터 전부 자동 설정
- MODULE_NOT_FOUND가 발생하지 않음(pnpm 불필요)
- PATH 문제·NODE_OPTIONS 문제가 발생하지 않음
- systemd로 Gateway가 자동 서비스화됨
- nginx로 리버스 프록시를 간단히 구성할 수 있음

Ubuntu에서도 필요했던 작업

- contextWindow / compaction의 수동 설정
- GPUStack 백엔드 파라미터 설정

## 작동 확인 체크리스트

- `openclaw --version` 이 표시됨
- `systemctl --user is-enabled openclaw-gateway.service` 가 `enabled`
- `openclaw gateway status` 에서 `RPC probe: ok` 가 표시됨
- 다른 단말의 브라우저에서 `https://<서버IP>` 에 액세스 가능
- `openclaw devices approve` 로 디바이스 승인이 완료됨
- `main` 세션에서 채팅에 응답이 돌아옴
- 세션 화면의 TOKENS 가 `xxxxx / 32768` 로 표시됨
- SearXNG 검색이 작동함

## 정리

Ubuntu 24.04 에 OpenClaw 를 설치하는 것은 Windows 환경과 비교해 압도적으로 간단했습니다.
설치 프로그램을 실행하는 것만으로 Node.js 설정부터 서비스화까지 완료됩니다.

유일한 함정은**원격 대시보드 액세스 시 디바이스 페어링**입니다.
`openclaw pairing`(채널용)이 아닌 `openclaw devices` 를 사용하는 점에 주의하세요.
또한, **설치 직후 contextWindow 와 compaction 설정을 수행**함으로써,
대화 시작 직후의 컨텍스트 오버플로를 방지할 수 있습니다.

**3가지 환경의 종합 평가**
설치 난이도는 **Ubuntu 24.04 << Windows 11 < Windows Server 2019** 순입니다.
Linux 환경을 선택할 수 있다면 Ubuntu 를 단연 추천합니다.본 기사의 절차는 2026년 4월 시점의 OpenClaw v2026.4.10·vLLM 0.17.1·GPUStack 에 기반합니다.
버전이 변경되면 동작이 다를 수 있습니다.