OpenClaw本地部署指南：Docker接入Qwen模型与Skill扩展实战-代码聚汇网

OpenClaw本地部署指南：Docker接入Qwen模型与Skill扩展实战

眠子子子·2026-08-30·阅读 22 GEO检测（免费）

OpenClawQwenDocker

|难度：普通|阅读约 46 分钟

最近 AI 圈子里 OpenClaw 这个名字出现得越来越频繁，不少朋友问我这玩意儿到底能干嘛、怎么在自己的机器上跑起来，还想接上千问（Qwen）当后端模型。我花了几天时间把整套流程从零到一捋了一遍，包括环境准备、容器部署、模型接入、Skill 编写以及几个高频报错的排查，今天这篇就把完整过程和踩过的坑一次性写清楚。这篇文章适合有一定命令行基础、想在自己电脑上跑一套私有 AI 助手的开发者，也适合想深度定制 agent 能力、把国内模型跟主流 agent 框架打通的同学参考。

1. 整体设计与部署思路拆解

1.1 OpenClaw 到底是什么，为什么值得本地部署

OpenClaw 是一个开源的个性化 AI 助手框架，核心定位是让普通开发者和爱好者能够在自己的设备上运行一个可控、可扩展、可私有化部署的 agent 系统。它跟常见的 OpenAI API 套壳不同，OpenClaw 更像一个完整的运行环境：你可以把微信、飞书、Telegram 等消息渠道接入进来，定义自己的 Skill（技能），选择后端模型，然后让这个 agent 自动处理消息、调用工具、执行任务，甚至通过扩展机制跟外部系统（比如 Milvus 向量库）联动。

很多朋友第一次接触 OpenClaw 可能是在 GitHub 上刷到的，或者看到腾讯开源的消息。这里有个容易混淆的点：腾讯开源过一个叫 OpenClaw 的项目，但社区里还有别的同名或类似命名的 agent 框架。实际部署时不要只盯着名字，而是要看仓库的活跃度、文档完整度、以及对 Qwen 等模型后端兼容性。我的选择是社区活跃度最高、issue 响应最快的那个主分支版本，因为后续踩坑时能搜到大量现成方案。

为什么要本地部署而不是直接用云端服务？核心原因有三个：一是隐私和可控性，你的对话记录、上传的文件、Skill 执行产生的中间数据都留在自己机器上，不会经过第三方平台；二是成本，对于高频调用、要长期跑的场景，自己部署后接入本地模型或国内 API 能省下不少 token 费用；三是可定制性，本地部署后你可以随意改配置、加 Skill、换模型，不受平台限制。说白了，就是“我的助手我做主”。

1.2 部署路径选型：Docker 还是裸机运行

OpenClaw 官方推荐 Docker 部署，同时也支持从源码直接运行。我实际对比了两条路线的体验，这里把结论放在前面：如果你是 Mac mini、Linux 服务器或 Windows 装了 WSL2 的环境，优先用 Docker Compose；如果你是开发调试、要频繁改代码，那就源码跑。

Docker 方案的好处是依赖隔离干净，OpenClaw 涉及 Node.js 运行时、Python 插件环境、配置目录、日志目录等多个组件，用容器可以一次性把环境固化下来，避免“在我机器上能跑”的尴尬。官方镜像会把主程序、控制面板、skill 沙箱等组件打包好，通过环境变量和 volumes 映射来做配置，升级也方便，直接拉新镜像重启就完事。

裸机运行的好处是调试直观，热重载速度快，适合二次开发。但代价是你得自己装 Node.js（版本有要求）、Python 3.10+、pnpm、git 等一堆依赖，还要处理系统级依赖冲突。我个人的建议是：先 Docker 跑通，理解配置项含义之后，再根据需要在开发机上切换到源码模式。下面整个教程的主线会以 Docker 部署为主，但我也会在相应位置说明源码模式下的差异。

1.3 整体架构和组件关系

在动手之前，先把 OpenClaw 的架构捋清楚，后面配置就不会懵。整个系统的核心组件可以分为这么几层：

消息渠道层：负责接入微信、飞书、Telegram、Discord 等 IM 平台，把用户消息统一转换成内部事件。
Agent 核心层：负责理解意图、维护会话状态、调度 Skill 执行，是“大脑”。
模型后端层：可以是 OpenAI 兼容 API、Ollama 本地模型、国内大模型 API（比如 Qwen 的 DashScope）等，负责生成回复。
Skill 扩展层：一组预定义或用户自定义的工具函数，比如查天气、发邮件、读写文件、调用外部 API 等，agent 根据需求调用这些 skill。
外部服务层：可选组件，比如向量数据库 Milvus、知识库、数据库、对象存储等，通过 skill 或 API 集成。

配置的核心是 openclaw.config.json 或环境变量，模型后端、渠道 token、skill 开关全在这里控制。理解了这层关系之后，你在写配置时就不会把“模型 API key”误填到“渠道 webhook”里了。我见过不少新手在配置阶段卡住，八成是把这几个层级的配置项搞混了。

需要模型API调用？免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。

2. 本地部署 OpenClaw 环境准备

2.1 硬件和系统要求

OpenClaw 本身并不重，真正吃资源的是你接入的模型。如果你用 Qwen 系列模型通过 Ollama 本地跑 7B 或 14B 量化版，建议内存 16GB 起步，32GB 更舒服；如果只接入 DashScope 云端 API，那么本地只要 8GB 内存、双核 CPU 就够了。磁盘方面，镜像加依赖大概占 2GB 左右，日志和模型缓存另算。

系统上，Linux 和 macOS 是最顺利的，Windows 用户需要装 WSL2 + Docker Desktop。这里特别提醒一下 WSL2 的内存配置，默认可能只分配宿主机内存的 50%，跑模型容易出现 OOM。建议在 .wslconfig 里手动设一下内存上限，比如 memory=24GB，再加 swap=8GB，能省掉很多麻烦。

还要确认 Docker 版本，建议 24.0 以上。太老的版本对 Compose V2 支持不好，会导致 docker compose 命令走 V1 语法，部分配置项不生效。检查方式很简单，Docker Desktop 的 “About” 页面或命令行 docker version 都能看到。

2.2 安装 Docker 与 Docker Compose

Linux 上安装 Docker 已经很成熟了，官方脚本一行搞定：

bash复制curl -fsSL https://get.docker.com | sh
systemctl enable --now docker

装完后验证一下：

bash复制docker version
docker compose version

macOS 用户直接装 Docker Desktop，安装完确认右上角小鲸鱼图标在运行。Windows 用户装 WSL2 后同样用 Docker Desktop，需要在 Settings -> Resources -> WSL Integration 里把对应的发行版开关打开，否则容器会跑在 Hyper-V 上，网络模式不一样，后面访问宿主机服务时 IP 会不同。

这里有个实操细节：OpenClaw 容器内要访问宿主机的 Ollama 服务（本地跑 Qwen 模型时），Docker Desktop for Mac 下你直接可以用 host.docker.internal 来访问宿主机；Linux 下 Docker 默认的 bridge 网络里没有自动加这个域名，需要在 compose 文件里加 extra_hosts: - "host.docker.internal:host-gateway"。这个坑我后面反复踩了两次，提前写在这里。

2.3 准备目录结构和配置文件

在部署前先规划好目录结构，我习惯把所有数据放在一个总目录下，方便备份和迁移：

bash复制mkdir -p ~/openclaw/{config,data,logs,skills}
cd ~/openclaw

config/ 存放 openclaw.config.json 和渠道配置文件
data/ 存放 agent 的持久化数据，比如会话记录、知识库索引
logs/ 挂载容器日志，出问题直接看文件
skills/ 放自定义 skill 源码，容器启动时热加载

把配置和数据跟容器分离是部署阶段最值得养成的习惯，否则每次重建容器设置全丢，心态容易崩。

3. 通过 Docker 部署 OpenClaw 详细步骤

3.1 拉取镜像并准备 Compose 文件

OpenClaw 官方镜像发布在 GitHub Container Registry 上，直接用 docker pull 拉最新稳定版：

bash复制docker pull ghcr.io/openclaw/openclaw:latest

注意，国内网络拉 GitHub 镜像可能较慢，建议配置 Docker Registry 镜像加速器（具体加速地址因服务商而异，我这里不列具体公共地址了）。也可以直接用 docker run 先跑个临时容器验证镜像完整性，但我更推荐直接用 Compose 文件一步到位。

创建 docker-compose.yml：

yaml复制version: "3.8"

services:
  openclaw:
    image: ghcr.io/openclaw/openclaw:latest
    container_name: openclaw
    restart: unless-stopped
    ports:
      - "3000:3000"
      - "8080:8080"
    environment:
      - TZ=Asia/Shanghai
      - LOG_LEVEL=info
      - OPENCLAW_CONFIG_DIR=/app/config
      # model backend type: ollama / openai / dashscope
      - OPENCLAW_MODEL_BACKEND=dashscope
    volumes:
      - ./config:/app/config
      - ./data:/app/data
      - ./logs:/app/logs
      - ./skills:/app/skills
    extra_hosts:
      - "host.docker.internal:host-gateway"

这里解释两个端口：3000 是 OpenClaw 的 Control UI（管理面板），8080 是 API 服务端口。如果你要接飞书或微信 webhook，回调地址里就用宿主机映射的 8080 端口。

OPENCLAW_MODEL_BACKEND 这个环境变量决定走哪种模型后端，可选值一般有 ollama、openai、dashscope、anthropic 等，具体以官方文档为准。

3.2 初始化配置并验证容器状态

启动前先创建一个最小可用的配置文件 config/openclaw.config.json，否则容器首次启动可能出现 “failed to load config” 一类的问题：

json复制{
  "model": {
    "provider": "dashscope",
    "modelName": "qwen-plus",
    "apiKey": "sk-xxxxxx",
    "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1"
  },
  "agent": {
    "name": "my-assistant",
    "systemPrompt": "你是一个乐于助人的中文AI助手。"
  },
  "servers": {
    "api": {
      "enabled": true,
      "port": 8080
    }
  },
  "skill": {
    "directories": ["/app/skills"]
  }
}

启动容器：

bash复制docker compose up -d
docker compose logs -f

正常情况下会看到类似 “Server listening on 0.0.0.0:8080” 和 “Control UI is running” 的日志。打开浏览器访问 http://localhost:3000 应该能看到控制面板登录页。如果 Control UI 没起来，常见原因要么是端口映射写错了，要么是持久化卷权限不够，这个后面问题排查部分细说。

3.3 源码方式部署的补充说明

如果你想用源码方式跑，官方仓库克隆下来后需要安装 pnpm，然后执行 pnpm install 和 pnpm dev。启动前同样把配置文件放到指定的配置目录，然后通过命令参数指定环境。

源码模式最大的坑在于 Node.js 版本。OpenClaw 要求 Node 18 以上，且对某些大版本有 pnpm lockfile 兼容问题。我建议直接用项目仓库里的 .nvmrc 指定的版本，用 nvm use 切过去，可以少踩很多编译报错的坑。如果你本机版本不对，pnpm install 时经常会出现一堆 gyp 相关的编译错误，根本原因就是 Node 版本和原生模块不匹配。

4. 接入千问（Qwen）模型后端

4.1 千问接入的两种主流方式

OpenClaw 接入 Qwen 目前有两条路线：一条是走阿里云百炼（DashScope）的 OpenAI 兼容接口，直接调用 qwen-plus、qwen-max 等云端模型；另一条是通过 Ollama 本地跑 Qwen 系列开源模型（比如 qwen2.5:14b、qwen2.5:32b 的量化版），实现完全离线推理。

两条路线各有适用场景。云 API 的优势是模型能力强、响应快、不需要高端显卡，适合日常聊天、复杂任务处理；本地模型的优势是零 API 费用、数据不出机器、离线可用，但需要足够内存和显存，且 7B 级别的模型在复杂推理上明显弱于云端大模型。我的选择是“混合”配置：OpenClaw 支持多个模型 profile 切换，日常简单任务用本地小模型，复杂任务切到云端 qwen-max。

4.2 方案一：通过 Ollama 接入本地 Qwen

先安装 Ollama，官方脚本一行：

bash复制curl -fsSL https://ollama.com/install.sh | sh

然后拉取 Qwen 模型，这里以 qwen2.5:14b 为例：

bash复制ollama pull qwen2.5:14b

启动 Ollama 服务（默认监听 11434 端口）。修改 OpenClaw 配置文件，把 provider 换成 ollama：

json复制{
  "model": {
    "provider": "ollama",
    "modelName": "qwen2.5:14b",
    "baseUrl": "http://host.docker.internal:11434"
  }
}

改完配置重启容器：

bash复制docker compose restart openclaw

这里想强调一下 baseUrl 为什么不能写 localhost。OpenClaw 跑在容器里，容器内的 localhost 指向容器自身，根本访问不到宿主机的 Ollama。必须用 host.docker.internal（Docker Desktop 和加了 extra_hosts 的 Linux 环境都支持）或者你在 docker inspect 里查到的宿主机局域网 IP。

我第一次部署时就是漏了这层，容器一直报 connect ECONNREFUSED 127.0.0.1:11434，当时还以为是 Ollama 没启动，查了半天才发现是容器网络的问题。这是新手最容易踩的坑，没有之一。

4.3 方案二：通过百炼 DashScope API 接入云上 Qwen

如果你不打算本地跑模型，走 DashScope 的 OpenAI 兼容模式也很快。先去阿里云百炼控制台开通模型服务、拿到 API Key，然后修改配置：

json复制{
  "model": {
    "provider": "dashscope",
    "modelName": "qwen-plus",
    "apiKey": "sk-xxxxxxxxxxxxxxxxxxxx",
    "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1"
  }
}

注意这里 baseUrl 必须是完整路径，OpenAI 客户端会自动拼接 /chat/completions 后缀。如果你写成了 https://dashscope.aliyuncs.com，OpenClaw 会请求一个不存在的路径，报 404。

DashScope 的几种模型怎么选？简单说：qwen-max 最强，适合复杂任务；qwen-plus 性价比高，日常对话首选；qwen-turbo 快但能力弱，适合简单指令；qwen-long 支持超长上下文，适合处理长文档。我日常主力是 qwen-plus，需要长上下文理解时切 qwen-long。

4.4 验证模型连通性和基本对话

配置改完后，先在 Control UI 里发一条测试消息，或者直接调 API：

bash复制curl -X POST http://localhost:8080/api/v1/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "你好，你是谁"}'

如果你看到模型正常回复，说明接入成功。如果返回的是类似 agent failed before reply: unknown model: deepseek 这种错误，说明配置里的模型名和实际模型列表对不上，或者后端没正确加载。注意这个报错并不一定只跟 DeepSeek 有关，unknown model 的意思是“模型后端那边找不到你配置的这个名字”，比如你把 modelName 写成了 qwen2.5:14b，但 Ollama 里实际 pull 的是 qwen2.5:7b，就会出这个问题。

5. OpenClaw 核心能力扩展：Skill 编写与渠道接入

5.1 Skill 是什么，怎么用

Skill 是 OpenClaw 里最核心的扩展机制，本质上就是给 agent 预定义好的“工具函数”。当用户发来消息，agent 先判断要不要调用 skill，如果需要就执行技能代码，再把结果作为上下文交给模型生成最终回复。

Skill 的典型场景包括：查天气、查股票、读写文件、发 HTTP 请求、搜索数据库、调用外部 API、文档检索等。官方自带了一些常用 skill，但真正的威力在于你自己写 skill 接业务 API。

Skill 的文件结构一般长这样：

code复制skills/
  my_skill/
    SKILL.json
    script.py

SKILL.json 是技能描述文件，告诉 agent 这个技能什么时候该用、怎么调用。一个最小示例：

json复制{
  "name": "current_weather",
  "description": "获取一个城市的当前天气。当用户询问天气时使用此技能。",
  "parameters": {
    "type": "object",
    "properties": {
      "city": {
        "type": "string",
        "description": "城市名称"
      }
    },
    "required": ["city"]
  }
}

script.py 是实际执行逻辑，入参通过标准输入或环境变量传入，输出 JSON 到标准输出，agent 会读取输出结果继续生成回复。注意一点：Python skill 运行在沙箱环境里，默认没有联网和文件系统权限，需要你在 skill 配置里显式声明需要的权限，否则会报权限错误。

5.2 一个实际例子：编写 Skill 接入 Qwen Embedding 并存储 Milvus

这里正好可以展开热搜词里提到的 “Qwen Embedding 并存储 Milvus” 场景。这个场景的典型需求是：把文档切片后用 Qwen Embedding 接口做向量化，再把向量写入 Milvus 向量库，实现知识库问答。

首先需要在 Milvus 里创建 collection，用 pymilvus 客户端连接。Milvus 的安装方式我在后面会提。执行向量化的代码会调用 DashScope 的 embedding 接口。

写一个 add_doc.py 作为 skill 的脚本：

python复制#!/usr/bin/env python3
import json
import os
import sys

from pymilvus import MilvusClient, DataType
from openai import OpenAI

MODEL_NAME = "text-embedding-v3"
MILVUS_URI = os.getenv("MILVUS_URI", "http://localhost:19530")
COLLECTION_NAME = "doc_chunks"
DASHSCOPE_API_KEY = os.getenv("DASHSCOPE_API_KEY")
EMBEDDING_DIM = 1024

client = OpenAI(
    api_key=DASHSCOPE_API_KEY,
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1"
)
milvus_client = MilvusClient(uri=MILVUS_URI)

def ensure_collection():
    if milvus_client.has_collection(COLLECTION_NAME):
        return
    milvus_client.create_collection(
        collection_name=COLLECTION_NAME,
        dimension=EMBEDDING_DIM
    )

def add_document(text: str, doc_id: str):
    resp = client.embeddings.create(model=MODEL_NAME, input=text)
    vector = resp.data[0].embedding
    ensure_collection()
    milvus_client.insert(
        collection_name=COLLECTION_NAME,
        data=[{"id": doc_id, "text": text, "vector": vector}]
    )
    return json.dumps({"status": "ok", "doc_id": doc_id})

if __name__ == "__main__":
    param = json.load(sys.stdin)
    text = param.get("text", "")
    doc_id = param.get("doc_id", "")
    print(add_document(text, doc_id))

对应的 SKILL.json 则声明这个技能的名称和输入参数：

json复制{
  "name": "add_doc_to_kb",
  "description": "将一段文本进行向量化并存储到Milvus向量库，用于知识库检索。",
  "parameters": {
    "type": "object",
    "properties": {
      "text": {
        "type": "string",
        "description": "需要存储的文本内容"
      },
      "doc_id": {
        "type": "string",
        "description": "文档ID"
      }
    },
    "required": ["text", "doc_id"]
  }
}

把这两个文件放到 skills/add_doc_to_kb/ 目录，在 SKILL.json 里加上 "environment": [{"name": "DASHSCOPE_API_KEY", "value": "sk-xxx"}] 来注入环境变量，然后重启 OpenClaw 容器。这样 agent 在后续对话中如果被要求“记住这段内容”，就会自动调用这个 skill。

Java 侧的接入和 LangChain4j 也有类似方案，但那是另一套生态了，思路大同小异：通过 OpenAI 兼容客户端调用 Qwen Embedding，再通过 LangChain4j Milvus 模块做向量存储和检索。核心是理解协议层兼容，不绑定具体语言。

5.3 接入微信和飞书

接入微信是很多人的刚需。OpenClaw 对微信的支持一般通过个人微信 hook 或企业微信 API 实现，不同版本方案不同。一种常见做法是用 openclaw-channel-wechat 插件配合企业微信应用，通过 webhook 回调方式和 OpenClaw API 联动。个人微信方面，社区有通过 iPad 协议接入的方案，但稳定性取决于第三方库维护状态，这里不做详细推荐。

飞书接入相对规范，OpenClaw 提供了官方机器人支持。你需要去飞书开放平台创建应用、配置事件订阅，把请求地址指向 http://你的公网IP:8080/webhook/feishu，然后在配置里填上 App ID 和 App Secret。实测下来飞书机器人是最稳的渠道，事件回调签名验证也没出过幺蛾子。

接入任何渠道之前建议先跑通 API 层，否则你分不清问题是出在 OpenClaw 还是平台回调。

5.4 二次开发和扩展思路

开源项目最大的好处就是可以改。OpenClaw 的代码结构相对清晰，核心服务用 Node.js 编写，skill 运行环境可以支持 Python 脚本，它内部会启动一个子进程来执行技能代码。如果你要新增能力，优先写 skill，而不是改核心代码，这样可维护性高得多。

我个人的经验是：把任何外部系统交互都封装成 skill，一个 skill 只干一件事，参数描述写得越清楚，agent 的调用准确率越高。比如“查询订单”和“创建订单”要分成两个 skill，不要混在一个脚本里用 action 字段区分，否则模型经常搞混。另外 skill 的 description 字段非常重要，它是模型判断什么时候调用这个技能的唯一依据，要写清“当用户在做什么时调用”，不要写成空泛的功能说明。

6. 常见问题与排查技巧实录

6.1 Control UI 无法启动

问题表现：docker compose up 后访问 http://localhost:3000 打不开，日志里有类似 openclaw control ui did not start 的报错。

排查步骤：

确认端口映射正常：docker compose ps 看端口状态。
看日志：docker logs openclaw | grep -i control。
如果日志提示前端静态资源找不到，基本是镜像版本和持久化卷冲突。解决方式是清掉旧的 data/ 卷重新初始化，或者更新镜像版本。

这个问题的根本原因通常是旧版本镜像升级后 UI 构建产物路径变了，而旧的持久化卷里还残留着旧配置。所以升级 OpenClaw 之前最好把 data/ 目录里的缓存文件清一遍，但要注意备份 config/ 下的配置。

6.2 模型调用报错：unknown model

agent failed before reply: unknown model: deepseek 这种报错在社区里高频出现。很多人的第一反应是 OpenClaw 不支持 DeepSeek，实际上这个报错的本质是模型后端返回了“找不到这个模型名”。

排查思路：

查看实际请求发到了哪个 baseUrl，日志里会打印。
用 curl 手动请求一次模型列表接口，对比 modelName 是否拼写一致。
如果你走 Ollama，运行 ollama list 确认模型标签完整（比如 qwen2.5:14b 而不是 qwen2.5）。
如果你走 OpenAI 兼容 API，确认所选的 provider 是否真的支持你填的模型名。

顺带一提，OpenClaw 默认配置里可能带了一些预置模型名，比如 deepseek、gpt-4o 等，如果你没有显式覆盖配置，就会拿默认名字去找模型，自然找不到。解决方式就是在配置文件里显式写清楚自己的模型名和 baseUrl。

6.3 容器内无法访问宿主机 Ollama

这个问题前面已经提到。在 Linux 上直接用 Docker Compose 部署时，host.docker.internal 默认不可用，必须在 compose 文件里加 extra_hosts。如果你不想改 compose，还有一个临时办法：docker run --network=host 让容器直接用宿主机网络，这样容器内 localhost:11434 就能访问到宿主机 Ollama 了。缺点是你不能再用端口映射的方式来访问 Control UI，需要直接访问 http://localhost:3000 来打开管理面板，这种方式灵活性更低。所以我倾向于推荐 extra_hosts 方案。

6.4 容器日志里出现权限不足

OpenClaw 的持久化卷映射到宿主机目录后，可能因为 UID 不匹配导致容器内写不进日志或数据。错误表现通常是启动时报 EACCES。解决方法是把宿主机目录的所有者改成容器的运行用户。找到容器内运行用户的 UID 后，直接 chown -R 1000:1000 ~/openclaw，然后再重启容器。很多官方文档不会提这一步，但在手动创建目录结构时非常容易踩到。

6.5 网络超时或连接被拒

如果你走 DashScope API 但报超时，先确认机器能否直连 dashscope.aliyuncs.com。某些网络环境下直连不稳定，可以考虑通过 HTTP 代理转发，OpenClaw 支持设置 HTTP_PROXY 环境变量。容器内设置代理时要注意，代理地址要写宿主机 IP 或局域网内代理服务器地址，不能写 localhost。

另外，OpenClaw 容器内部还有个内置的验证服务和自动更新检查，首次启动时会尝试连接 GitHub API。如果访问不畅，启动时间会变得非常长。遇到这种情况可以看日志里是否有 github.com 连接超时的记录，然后设置 HTTPS_PROXY 来加速。

6.6 常见问题速查表

问题	现象	主要原因	解决方案
Control UI 无法启动	3000 端口无法访问	版本升级后缓存冲突	备份配置，清空 data 卷后重启
unknown model 报错	agent 回复失败	配置的模型名与后端不一致	核对 ollama list / API 模型列表
ECONNREFUSED 11434	无法调用 Ollama	容器内未正确访问宿主机	用 host.docker.internal 或 network=host
EACCES 权限错误	启动失败	卷目录 UID 不匹配	chown 宿主机目录
首次启动慢	启动卡在检查阶段	无法访问 GitHub	配置 HTTPS 代理或离线预下载
飞书回调签名失败	机器人无响应	App Secret 填错或回调地址错误	核对开放平台配置并检查接收地址

7. 性能调优和使用体验优化

7.1 本地模型推理参数调整

如果你用 Ollama 跑本地 Qwen，推理参数可以在模型配置里调整。比如设置 temperature 控制随机性，top_p 控制采样范围，max_tokens 控制回复长度。OpenClaw 支持在模型配置中透传这些参数，不同 provider 的具体字段名略有差别，但核心逻辑一致。

实测经验是：聊天场景用 temperature=0.7 比较自然，代码生成或信息抽取场景直接降到 0.1~0.3，能明显减少胡编乱造。千问系列中文能力好，但长上下文时容易忽略早期信息，如果对话太多，要么主动清上下文，要么换 qwen-long。

7.2 控制内存占用和日志增长

长期运行的 agent 最怕日志无限膨胀和内存缓慢增长。建议在 compose 文件里加上日志轮转配置：

yaml复制logging:
  driver: "json-file"
  options:
    max-size: "50m"
    max-file: "3"

数据目录里如果有大量会话记录，建议定期清理旧会话或者接数据库持久化。OpenClaw 的 data 目录会存放会话 JSON，量大后检索会越来越慢，定期归档是必要的。

7.3 用 NVLink/NIM 等方案加速推理

热搜里提到 “OpenClaw 配置 NVIDIA NIM”。NIM 是 NVIDIA 推出的模型推理微服务，如果你有 NVIDIA 显卡，可以让 NIM 扮演 OpenAI 兼容 API 的角色，OpenClaw 通过标准接口接入即可，这样既能在本地跑大模型又能利用 GPU 加速。具体配置上，把 OpenClaw 的 model provider 设为 openai，baseUrl 指向 NIM 服务的地址，模型名填 NIM 里部署的模型名即可。

这种做法适合有较强 GPU 的用户，效果接近云端 API 但完全本地化。没有 GPU 的话 NIM 方案可以不考虑，纯 CPU 跑 Qwen 7B 量化版虽然能出结果但速度偏慢。

8. 写在最后的实操体会

如果你问我本地部署 OpenClaw 这件事里最耗时间的环节是什么，我会说不是安装环境、不是配置文件、也不是写 skill，而是调试“模型后端连通”和“渠道回调”这两个环节。前者折腾网络地址，后者折腾密钥签名，都是看似简单、实际细节极多的东西。

我的建议是分阶段验证：先把模型跑通，再跑 API 测试，最后再接渠道。每一步都确认没问题再往下走，不要一股脑全配好再启动，否则报错的时候你根本不知道问题出在哪里。

还有一个真心建议：善用日志。OpenClaw 的日志信息量很大，虽然看起来有点吵，但几乎所有问题的答案都在里面。遇到问题先 docker logs 看十分钟，比自己瞎猜配置要高效得多。

这套环境搭好后，你就可以在这个基础上做很多事了：接知识库、自动写日报、做个人助理、搭团队机器人……后续我还会写一些关于 skill 开发和性能调优的深入内容，如果你在部署过程中碰到什么奇怪的报错，欢迎留言交流。