OpenClaw（龙虾）部署配置完整教程 + 实操问题汇总文档

一、OpenClaw（龙虾）完整部署配置详细流程

1. 前置环境准备

1. 操作系统：Windows 10/11
2. 已安装 Node.js 环境（保障命令行可识别 openclaw 指令）
3. 提前准备阿里云通义千问 DashScope API Key（sk- 开头密钥）

2. OpenClaw 安装

1. 打开 Windows PowerShell / 终端
2. 执行全局安装命令：

powershell

npm install -g openclaw

1. 输入 openclaw -v 能输出版本号，代表安装成功。

3. 初始化对接大模型（通义千问）

1. 终端执行配置向导命令：

openclaw onboard --mode local

1. 配置流程分步选择：

• 选择服务商：Custom Provider（自定义兼容接口）
• 输入 Base URL：

https://dashscope.aliyuncs.com/compatible-mode/v1

• 选择：Paste API key now
• 粘贴阿里云通义千问 API Key（sk-xxx）
• 模型 ID 填写：qwen-turbo
• 后续所有步骤默认回车，选择 Yes 确认个人使用模式
• 出现 Verification successful 代表 API 校验配置成功。

4. 关键配置文件修改（必改，解决后续所有报错）

1. 打开配置目录：文件管理器地址栏输入

%USERPROFILE%\.openclaw\

1. 用记事本打开 config.json
2. 新增 / 修改以下三项核心配置：

（1）提升上下文缓存阈值，避免会话重置

"agents": {
  "defaults": {
    "compaction": {
      "reserveTokensFloor": 20000
    }
  }
}

（2）适配 qwen-turbo 大上下文窗口

找到模型配置项，修改：

"contextWindow": 128000

（3）放行桌面 / 下载 / 文档目录权限，允许读写本地文件图片

"tools": {
  "filesystem": {
    "allowedPaths": [
      "C:\\Users\\DKL\\Desktop",
      "C:\\Users\\DKL\\Downloads",
      "C:\\Users\\DKL\\Documents"
    ]
  }
}

1. 保存 config.json 文件。

5. 启动服务 & 访问控制台

1. PowerShell 启动龙虾网关服务：

openclaw gateway

1. 日志出现 Browser control listening 代表启动成功
2. 浏览器访问 Web 控制台：

http://127.0.0.1:18789/

1. 新建对话会话，即可正常下发指令控制电脑。

6. 日常启停命令

• 停止服务：终端按 Ctrl + C
• 正常启动：openclaw gateway
• 停止后台服务：openclaw gateway stop

---

二、本次实操遇到的所有问题汇总 + 原因 + 解决方案

问题 1：模型输入长度限制报错

报错原文：Range of input length should be [1, 3072]

现象：发送任意消息直接报错，无法对话

原因：原模型 qwen2.5-math-7b-instruct 上下文仅 3072tokens，OpenClaw 系统提示词过长直接溢出

解决：重新配置把模型替换为 qwen-turbo（128k 超大上下文）

问题 2：401 Unauthorized 认证失败

报错原文：401 Unauthorized

现象：配置完模型后请求直接鉴权失败

原因：BaseURL 错误、API Key 输错 / 过期、Key 无调用 qwen-turbo 权限

解决：重新走 onboard 配置，核对标准 BaseURL + 重新粘贴有效 API Key

问题 3：上下文超限自动重置会话

报错原文：Context limit exceeded. I've reset our conversation to start fresh

提示建议：把 reserveTokensFloor 设为 20000 以上

现象：聊着天突然清空会话，提示重置

原因：默认缓存阈值太低，对话上下文累积超标

解决：修改 config.json，将 reserveTokensFloor 改为 20000

问题 4：性能延迟警告

日志警告：liveness warning: event_loop_delay cpu interval=35s

现象：终端刷出大量延时日志，模型响应变慢

原因：电脑 CPU 占用过高、事件循环阻塞，后台任务排队积压

解决：①关闭后台多余软件减负 ②Ctrl+C 重启网关服务 ③等待 1 分钟自动调度恢复

问题 5：本地图片生成 / 保存权限报错

报错原文：Local media path is not under an allowed directory: C:\Users\DKL\Desktop\smile.png

现象：让龙虾画图、保存到桌面直接失败

原因：OpenClaw 默认禁止访问桌面等目录，无读写权限

解决：在 config.json 中手动添加 allowedPaths 放行桌面、下载、文档目录

问题 6：模型只给操作步骤，不自动执行电脑操作

现象：下发控制指令，AI 只文字教步骤，不自动点击 / 打开软件

原因：指令为询问句式，被当成教程提问，未识别为执行命令

解决：用命令式短句，加约束：直接执行、不要解释步骤

---

三、整体部署总结

1. 核心关键：必须用 Custom Provider 自定义接口 对接通义千问，模型固定换成 qwen-turbo 规避上下文太小问题；
2. 必改配置三项：缓存阈值、128k 上下文窗口、本地目录权限放行，缺一后续必报错；
3. 大部分报错根源：模型上下文不足、API 鉴权错误、文件夹权限限制、配置参数默认值过低；
4. 日常使用原则：报错优先重启服务、新建会话；永久解决直接修改 config.json 配置文件即可。