環境構成 #

インストール手順 #

1. パッケージ更新と必要ツールのインストール #

   sudo apt update && sudo apt upgrade -y
   sudo apt install -y curl git

   Copy to Clipboard

2. OpenClaw をインストール #

   公式インストーラを実行します。Node.js のセットアップも含めて自動で処理されます。

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

   Copy to Clipboard

   インストーラが以下を自動で行います。

   • 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

   Copy to Clipboard

リモートアクセス時のデバイスペアリング承認 #

別端末からダッシュボードにアクセスすると pairing required エラーが表示されます。
これは OpenClaw のセキュリティ機能で、初回アクセス時に管理者の承認が必要です。
一度承認すれば以降は不要です。

1. ブラウザでダッシュボードにアクセス #

   トークン付き URL をブラウザで開きます。サーバー側で確認します。

   openclaw dashboard
   # 表示された URL（#token=...）をブラウザで開く

   Copy to Clipboard

   ブラウザに pairing required と表示された状態のまま次へ進みます。

2. Pending リストを確認して承認 #

   # ペアリング待ちのデバイスを一覧表示
   openclaw devices list
   
   # 表示された Request ID をすべて承認
   openclaw devices approve <Request ID>

   Copy to Clipboard

   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 の設定を行うことで、
会話開始直後のコンテキストオーバーフローを防げます。