환경 구성 #

설치 절차 #

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
     
   • Max Tokens: 4096(기본값 유지)
     

   
   
   

   
   

   방법②: 명령줄에서 설정 #

   # 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

   Copy to Clipboard
   UI에서 설정하는 것이 더 확실합니다
   대시보드에서 설정하면 변경 사항이 즉시 반영되며 설정 오류도 방지할 수 있습니다.
   CLI 설정 후에는 반드시 openclaw gateway restart가 필요합니다.

5. Gateway 시작 확인 #

   openclaw gateway status
   systemctl --user is-enabled openclaw-gateway.service

   Copy to Clipboard

   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"

   Copy to Clipboard

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

   Copy to Clipboard

3. OpenClaw 설정 변경 #

   # localhost가 아닌 곳에서의 연결 허용
   openclaw config set gateway.controlUi.allowInsecureAuth true
   
   # 접속 출처 오리진 허용
   openclaw config set gateway.controlUi.allowedOrigins '["*"]'
   
   openclaw gateway restart

   Copy to Clipboard

4. 방화벽 포트 열기 #

   sudo ufw allow 443/tcp
   sudo ufw allow 80/tcp

   클립보드에 복사

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

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

1. 브라우저에서 대시보드에 접속 #

   토큰이 포함된 URL을 브라우저에서 엽니다. 서버 측에서 확인합니다.

   openclaw dashboard
   # 표시된 URL(#token=...)을 브라우저에서 열기

   클립보드에 복사

   브라우저에 pairing required가 표시된 상태 그대로 다음으로 진행합니다.

2. Pending 목록을 확인하고 승인 #

   # 페어링 대기 중인 디바이스 목록 표시
   openclaw devices list
   
   # 표시된 Request ID를 모두 승인
   openclaw devices approve <Request ID>

   클립보드에 복사

   Pending에 여러 요청이 있는 경우 모두 승인합니다.

3. 브라우저에서 재접속 #

   승인 후, 브라우저의 “연결” 버튼을 누르면 대시보드가 열립니다.

GPUStack 측 설정 #

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

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

Windows 환경과의 비교 #

작동 확인 체크리스트 #

• 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 설정을 수행함으로써,
대화 시작 직후의 컨텍스트 오버플로를 방지할 수 있습니다.