OpenClaw 部署与配置入门手册

本手册记录从环境准备、软件安装、本地大模型（LM Studio）接入、Telegram 渠道绑定到浏览器工具扩展的全流程。

一、 环境要求

OpenClaw 对 Node.js 版本有严格限制：

• Node.js: >=22.22.3 <23 或 >=24.15.0 <25 或 >=25.9.0
• 推荐版本: Node.js v24.20.0 (使用 NVM 管理)

1.1 更新 Node.js (基于 NVM)

# 安装并切换至 Node.js 24 稳定版
nvm install 24
nvm use 24
nvm alias default 24

二、 全局安装 OpenClaw

npm 的安全机制拦截了部分构建脚本，需要在安装时通过 --allow-scripts 显式授权。

# 全局安装并允许运行必要构建脚本
npm install -g --allow-scripts=openclaw,@google/genai,koffi,tree-sitter-bash,protobufjs openclaw

# 验证安装
openclaw --version

(可选) 避免后续更新再次拦截：

npm config set allow-scripts=openclaw,@google/genai,koffi,tree-sitter-bash,protobufjs --location=user

三、 清理与重新初始化配置

如需重置配置，删除旧目录后重新初始化：

# 1. 安全清理旧配置
rm -rf ~/.openclaw

# 2. 交互式初始化
openclaw onboard

四、 核心配置文件修改

编辑配置文件 ~/.openclaw/openclaw.json，完成 LM Studio 接口连接、模型指定及防回退设置。

4.1 配置文件样例 (~/.openclaw/openclaw.json)

{
  "wizard": {
    "securityAcknowledgedAt": "2026-09-03T06:20:23.354Z",
    "accessMode": "full"
  },
  "agents": {
    "defaults": {
      "model": "lmstudio/unsloth/qwen3.8-27b@lmstudio:setup-61de7abb-df50-4bdc-86dd-83faf733218e"
    },
    "entries": {
      "main": {
        "models": {
          "lmstudio/unsloth/qwen3.8-27b": {
            "agentRuntime": { "id": "openclaw" }
          }
        }
      }
    }
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "YOUR_TELEGRAM_BOT_TOKEN_HERE",
      "dmPolicy": "pairing"
    }
  },
  "models": {
    "providers": {
      "lmstudio": {
        "baseUrl": "http://100.103.59.20:1234/v1",
        "api": "openai-chat",
        "auth": "api-key",
        "apiKey": "lmstudio-local",
        "models": [
          {
            "id": "unsloth/qwen3.8-27b",
            "name": "Qwen3.8 27B UD",
            "reasoning": false,
            "compat": { "supportsTools": true },
            "contextWindow": 262144,
            "maxTokens": 8192
          }
        ]
      }
    }
  },
  "tools": {
    "profile": "coding",
    "entries": {
      "browser": {
        "enabled": true,
        "headless": true
      }
    }
  },
  "hooks": {
    "internal": {
      "entries": {
        "session-memory": {
          "enabled": true,
          "model": "lmstudio/unsloth/qwen3.8-27b"
        }
      }
    }
  }
}

注意：

1. models.providers.lmstudio.api 必须设为 "openai-chat"，否则无法支持工具调用（Function Calling）。
2. hooks.internal.entries.session-memory.model 需显式指定为你的 Qwen 模型，防止系统会话摘要回退到默认的 gemma 模型。

五、 后台服务托管与 Token 同步

修改配置文件后，必须强制刷入后台 Systemd 守护进程并重新加载。

# 1. 强制同步最新的配置 Token 到 Gateway 服务
openclaw gateway install --force

# 2. 重启后台 Systemd 服务
systemctl --user restart openclaw-gateway.service

# 3. 检查服务运行状态
systemctl --user status openclaw-gateway.service

六、 接入 Telegram 渠道

1. 在 Telegram 中联系 @BotFather，发送 /newbot 创建新 Bot，复制获取到的 HTTP API Token。
2. 将 Token 填入 ~/.openclaw/openclaw.json 的 channels.telegram.botToken 字段中。
3. 执行服务同步：

openclaw gateway install --force
systemctl --user restart openclaw-gateway.service

4. 在 Telegram 中打开你的 Bot 并点击 Start，Bot 会返回一段配对码（Pairing Code）。
5. 在 Linux 终端执行配对命令：

openclaw pairing approve telegram <YOUR_PAIRING_CODE>

七、 浏览器扩展配置 (Browser Tool)

开启浏览器后，OpenClaw 可自动执行网页抓取与解析。

# 1. 安装/配置 Playwright 浏览器依赖
openclaw tools setup browser

# 2. 确认 openclaw.json 中已开启 tools.entries.browser.enabled = true

# 3. 重启 Gateway 服务应用改动
openclaw gateway install --force
systemctl --user restart openclaw-gateway.service

# 4. 测试网页访问
openclaw "请访问 https://news.ycombinator.com 并总结前3条新闻"

八、 常见故障排查 (Troubleshooting)