环境配置 #

安装步骤 #

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 继续
   • 设置模式：QuickStart
   • 模型提供商：Custom Provider
   • Base URL：http://<GPUStack IP>/v1
   • API 密钥提供方式：Paste API key now
   • 接口兼容性：OpenAI-compatible
   • 模型 ID：在 GPUStack 上运行的模型名称
   • 消息渠道：Skip for now
   • 技能依赖：Skip for now
   • 网络搜索：SearXNG Search → 输入 URL
   • Hooks：仅启用 session-memory

   引导完成后，系统会自动安装并启动 systemd 服务。

4. 修正上下文限制与模型配置（重要） #

   如果在引导完成后立即开始聊天，可能会出现 Context limit exceeded 错误。
   安装完成后立即进行以下设置即可避免该问题。

   方法①：从仪表盘 UI 配置（推荐） #

   仪表盘左侧菜单 “AI and Agents” →
   “Models” 标签页 → 打开相应模型的 “Compat” 部分，
   设置以下数值后点击 “Save”。

   • Context Tokens：65536
   • Context Window：65536
     
   • Max Tokens：4096（保持默认）
     

   
   
   

   
   

   方法②：从命令行配置 #

   # Increase compaction buffer
   openclaw config set agents.defaults.compaction.reserveTokensFloor 20000
   
   # Manually fix contextWindow (change provider name to match your environment)
   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("Update complete")
   EOF
   
   openclaw gateway restart

   复制到剪贴板
   通过 UI 配置更可靠
   在仪表盘中设置会立即生效，可避免配置错误。
   通过 CLI 配置后，必须始终执行 openclaw gateway restart。

5. 验证网关启动状态 #

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

   复制到剪贴板

   如果显示 enabled，则网关会在系统启动时自动运行。

远程访问配置（nginx + 自签名证书） #

如果想从网络上的其他计算机访问仪表盘，需要将 nginx 配置为反向代理。
由于使用了 WebSocket，nginx 配置中需要转发 Upgrade 头。

1. 安装 nginx 并生成自签名证书 #

   sudo apt install -y nginx
   
   # Generate self-signed certificate (valid for 10 years)
   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 配置 #

   # Allow connections from non-localhost
   openclaw config set gateway.controlUi.allowInsecureAuth true
   
   # Allow origin of access source
   openclaw config set gateway.controlUi.allowedOrigins '["*"]'
   
   openclaw gateway restart

   复制到剪贴板

4. 开放防火墙 #

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

   复制到剪贴板

远程访问的设备配对审批 #

从其他计算机访问仪表盘时，会显示 pairing required 错误。
这是 OpenClaw 的安全功能，首次访问需要管理员批准。
批准后之后就不再需要了。

1. 从浏览器访问仪表盘 #

   在浏览器中打开包含 token 的 URL，并在服务器端进行确认。

   openclaw dashboard
   # Open the displayed URL (#token=...) in a browser

   复制到剪贴板

   浏览器会显示 pairing required，请在此状态下继续下一步。

2. 查看待批准列表并批准 #

   # List devices waiting for pairing
   openclaw devices list
   
   # Approve all displayed Request IDs
   openclaw devices approve <Request ID>

   复制到剪贴板

   如果有多个待批准的请求，请全部批准。

3. 在浏览器中重新连接 #

   批准后，在浏览器中点击“Connect”按钮即可打开仪表盘。

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://<server IP>
• 使用 openclaw devices approve 完成设备批准
• 在 main 会话中能返回聊天响应
• 会话界面 TOKENS 显示 xxxxx / 32768
• SearXNG 搜索功能正常

总结 #

在 Ubuntu 24.04 上安装 OpenClaw，比 Windows 环境要简单得多。
只需运行安装脚本，即可完成从 Node.js 配置到服务注册的全部工作。

唯一的坑是远程仪表盘访问所需的设备配对。
请注意使用 openclaw devices，而不是（用于渠道的）openclaw pairing。
此外，安装完成后立即配置 contextWindow 与 compaction 设置，
可以避免开始对话后立刻出现上下文溢出。