OpenClaw本地部署实战：Docker接入DeepSeek等国内大模型全攻略

OpenClaw最近的讨论热度一直在线，尤其是“本地部署”和“接国内大模型”这两个方向，大家问得最多。我自己把OpenClaw用Docker跑起来，再把DeepSeek这类国内模型接进去，前后折腾了一整天，踩了不少坑，也把整个链路摸透了。这篇东西不整虚的，直接把完整过程拆给你看：Docker环境怎么准备、OpenClaw容器怎么起、Control UI怎么打开、国内大模型（DeepSeek、通义、硅基流动等）怎么配置进去，以及最让人头疼的unknown model: deepsee这类报错到底怎么解决。

先说明一下，这篇内容面向两种人：一种是想把OpenClaw作为个人AI助手跑起来、但又不想把数据交给境外服务的同学；另一种是已经在用OpenClaw、却卡在“自定义模型配置”这一步的开发者。无论你是哪种，读完应该都能把整套系统跑通，并且理解里面的配置逻辑，而不是只会抄命令。

1. OpenClaw到底是什么，以及为什么我推荐用Docker装

1.1 它的核心定位：消息网关与Agent运行时的结合体

OpenClaw本质上是一个AI Agent运行时，它做的事情可以概括为：把各种即时通讯渠道（微信、Telegram、Discord、Slack这些）收到的消息，交给大模型处理，然后让模型调用工具去完成具体任务，比如查资料、执行命令、操作浏览器、读取文件等等。换句话说，它更像是一个“带爪子的AI”——不只是聊天，而是能真正动手干活。

这里有一个关键点：OpenClaw本身不内置大模型。它只是定义了一套“模型怎么接入”、“工具怎么调用”、“消息怎么分发”的框架。模型是你自己选的，你可以接Claude、GPT，也可以接DeepSeek、通义千问这些国内模型，甚至本地跑一个Ollama也行。这也是它和那些绑死某家云服务的AI产品最大的区别。

那Docker部署的优势在哪里？隔离和可复现。OpenClaw依赖Node.js运行环境、一堆npm包、还可能涉及浏览器自动化组件，如果直接装在宿主机上，很容易和现有的Node版本冲突，或者因为某个系统库缺失导致装到一半失败。Docker把这些依赖全部打进容器，你只需要一个运行环境（Docker本身），其他都不用手动处理。换机器、升级版本、出问题回滚，都非常省事。

1.2 Docker方式和本机直接安装的本质区别

本机直接安装的思路是：clone代码 -> 装Node -> npm install -> 配置环境变量 -> 启动进程。这套流程在系统干净的时候没问题，但往往有个隐性问题：OpenClaw不同版本对Node版本要求不一致，而且它依赖的某些原生模块需要本地编译工具链。我见过不少人在macOS上用homebrew的Node装到一半报python依赖错误，在Windows上则容易卡在node-gyp这一步。

Docker方案则是：拉取官方镜像 -> 写compose文件 -> docker compose up -d -> 完成。所有系统级依赖都封装在镜像里，不会污染宿主机。而且OpenClaw的配置通常是持久化存储在某个目录下的，Docker挂载卷（volume）的方式可以保证容器删了重建、配置和数据还在。

如果只是体验一下，本机装当然也行。但如果你打算长期使用，还频繁升级版本，我强烈建议一开始就用Docker。你后面会感谢这个选择。

1.3 部署前需要认清的几个边界

开始之前有两件事必须说清楚：

第一，OpenClaw是开源项目，官方仓库和文档都在GitHub上，不存在什么“腾讯官网”。检索的时候注意识别，不要被一些挂着“OpenClaw官网”名字的第三方站点误导。这类站点往往为了引流，提供所谓“一键部署工具”“终身会员特惠”，实际上就是打包了别人开源代码再收你钱。哪怕不退钱，他从你机器上拿走什么配置、API Key、聊天记录，你完全没有掌控。开源项目不需要买会员，这一点务必记得。

第二，OpenClaw默认配置里接的模型通常是境外服务（比如Claude），如果你直接用默认配置，很可能因为网络和账号的问题跑不通。这也是“自定义配置国内大模型”这个需求最核心的出发点——把模型供应商改成DeepSeek这些国内可直接访问的服务，网络稳定、付费方便、而且中文效果也不错。

2. 部署前必须准备的Docker环境：先把地基打牢

2.1 Windows、macOS、Linux三个平台的差异

先说Windows。最常用的是Docker Desktop，它会依托WSL2或Hyper-V来运行Linux容器。安装Docker Desktop之前，先去BIOS里确认虚拟化技术已开启。很多人的Docker Desktop装完启动失败，提示“virtualisation support wasn't detected”，十有八九就是虚拟化被关了，或者WSL2内核没更新。解决办法是：开启硬件虚拟化，然后到控制面板的“启用或关闭Windows功能”里勾选“适用于Linux的Windows子系统”和“虚拟机平台”，重启后再安装WSL2内核更新包。

macOS上简单一些，Docker Desktop基于Apple虚拟化框架，只要系统版本不是太老，装完就能用。Intel芯片和Apple Silicon芯片的安装包不同，注意选对。

Linux服务器最小，不需要Docker Desktop，直接装Docker Engine就行。Ubuntu/Debian用官方apt源安装，CentOS/RHEL用yum。装完之后务必把当前用户加入docker组，否则每次执行docker命令都要sudo，很烦。

sudo usermod -aG docker $USER newgrp docker

2.2 国内拉取镜像的加速配置

OpenClaw的镜像托管在GitHub Container Registry（ghcr.io）上，国内直连速度通常很慢，甚至超时失败。这里我们需要给Docker配置registry mirror，也就是镜像加速器。

在Docker Desktop的Settings -> Docker Engine里，或Linux下在/etc/docker/daemon.json中，添加如下配置：

{ "registry-mirrors": [ "https://docker.m.daocloud.io", "https://dockerproxy.net" ] }

注意，加速器地址随时可能失效，如果某个地址拉不动，搜一下当前可用的镜像加速站替换即可。配置完成后重启Docker服务，再去拉镜像，速度会有质的提升。镜像层有缓存，第一次拉取需要完整下载，后续更新版本只需要拉取增量层，所以别因为第一次慢就放弃。

2.3 部署前的目录和端口规划

在动手之前，先规划好两样东西：挂载目录和端口。

OpenClaw运行时会把配置、日志、消息历史这些数据写到工作目录里。我建议在宿主机上创建一个独立目录，比如~/openclaw，下面再建data子目录，用来挂载到容器内部。这样万一容器坏了，删除重建，配置和数据都还在。这也是Docker部署OpenClaw最核心的一条经验：所有持久化数据都通过挂载卷放到宿主机，容器本身可以随时丢掉重来。

端口方面，OpenClaw的Control UI默认监听33281，这个端口就是浏览器访问管理界面的入口。如果33281被占用，compose文件里可以改映射，但注意容器内部端口最好保持不变，只改宿主机侧端口。

确认好这两个问题，Docker这层地基就算打牢了。

3. 用docker compose把OpenClaw跑起来：完整部署链

3.1 为什么选docker compose而不是docker run

你可能会搜到基于docker run的一行命令部署方式。docker run适合快速验证，但有个明显问题：启动参数一多，命令就会变得又长又乱，而且每次启动都要复制一长串。docker compose可以把服务定义、端口映射、环境变量、挂载卷全部固化在一个YAML文件里，之后一个docker compose up -d就是完整启动，一个docker compose down就是完整清理。

所以我的建议是：一开始就用compose，别走弯路。官方仓库的README里一般会给一个compose示例，下面是一个典型的配置结构，请根据你的实际版本调整镜像名和端口（以官方文档为准）：

services: openclaw: image: ghcr.io/openclaw/openclaw:latest container_name: openclaw restart: unless-stopped ports: - "33281:33281" environment: - TZ=Asia/Shanghai - OPENCLAW_CONTROL_AUTH_TOKEN=请改成你自己的长随机字符串 volumes: - ./data:/root/.openclaw extra_hosts: - "host.docker.internal:host-gateway"

这里面有几个细节值得说一下。

restart: unless-stopped的作用是：服务器重启后容器能自动启动，OpenClaw作为常驻服务，这个必须加。

OPENCLAW_CONTROL_AUTH_TOKEN是Control UI的认证令牌。OpenClaw的Web管理界面默认不允许无令牌访问，这个字段就是你浏览器登录时要输入的密码。一定设一个足够长的随机字符串，不要用默认值，也不要嫌麻烦不设。

extra_hosts里加了host.docker.internal的映射，这是为了容器内部访问宿主机服务准备的。如果你后面要接本地模型（比如宿主机上的Ollama或NVIDIA NIM），这个映射几乎是必须的。

./data:/root/.openclaw这个挂载卷是持久化数据的核心，OpenClaw会把配置文件和运行时数据写到容器内的~/.openclaw目录，映射到宿主机后，你的模型配置、渠道配置、日志都在宿主机上可见，方便备份和排查。

3.2 初次启动的完整命令与验证方式

把上面的compose内容保存为docker-compose.yml，放到~/openclaw目录下，然后执行：

cd ~/openclaw docker compose up -d

第一次启动会拉取镜像，耐心等待。完成后执行docker compose ps查看容器状态，正常应该是running。

接着验证Control UI是否正常。浏览器访问http://localhost:33281，第一次打开会让你输入上面设置的控制台令牌。能进到管理界面，说明OpenClaw的容器主体已经跑通了。

注意：如果你用的服务器在远端，访问Control UI需要用公网IP或做端口转发，同时注意防火墙规则。开发环境调试阶段建议不要直接暴露到公网，避免被扫描爆破。

3.3 Control UI没起来怎么排查

很多人会在这里卡住，打开http://localhost:33281提示连接不上。常见原因有三个：

第一，容器启动后马上就退出了。用docker compose logs -f看日志，如果是端口被占用、或者启动配置有问题，日志里会有明确报错。OpenClaw启动时如果检测到配置文件的JSON格式错误，会直接退出，这种问题日志里通常会有parse error之类的关键词。

第二，Control UI和核心服务是两个独立进程。如果核心服务起来了但UI没起来，日志里可能有“Control UI did not start”这样的提示。这种情况一般是端口被容器内的其他进程占用了，或者Control UI的依赖组件没启动成功。先重启容器试试，docker compose restart，大部分情况下能恢复。

第三，防火墙拦截。确保宿主机的33281端口是开放的。Linux下如果开了firewalld或ufw，需要手动放行。Windows下如果开启了防火墙，Docker Desktop一般会自动放行映射端口，但偶尔也会出问题。

装好容器、能看到Control UI，这只是第一步。接下来才是整个项目最关键的部分：把模型接进来。

4. 把国内大模型配置进OpenClaw：核心思路与操作细节

4.1 理解OpenAI兼容接口：这一步通了，所有模型都能接

先搞懂一个概念：OpenClaw对接模型供应商，走的是OpenAI兼容协议。所谓OpenAI兼容，简单理解就是：模型服务商提供一个API地址，这个地址的请求格式和响应格式跟OpenAI官方一致。你只需要告诉OpenClaw四个信息——API地址（base URL）、API密钥（API Key）、模型名称（model ID）、以及这个模型是做什么用的（比如是通用对话模型还是推理模型）。

只要服务商支持OpenAI兼容格式，不管它是DeepSeek、通义千问、智谱，还是硅基流动这类聚合平台，都能用同一套方式接进OpenClaw。这也是“自定义配置国内大模型”这件事最底层的原理。

这里我用一个生活化的类比：OpenAI兼容协议就像是一个通用的电源插座标准。OpenClaw是电器，它只认这个标准插座。国内各家大模型提供的API，虽然不是OpenAI官方，但只要你把它们的插头做成标准插座的样子，OpenClaw就能直接用。我们要做的，就是把每家模型的“插头”信息（API地址、密钥、模型ID）填到OpenClaw的配置里。

4.2 在Control UI或配置文件中添加模型供应商

模型的配置有两个入口：图形化的Control UI，以及OpenClaw的配置文件。推荐先用Control UI操作，直观且不容易出错。

在Control UI里找到模型供应商（Model Provider）配置页面，点击添加，填以下几个字段：

注意到没有，不同平台的Model ID差别很大。DeepSeek官方叫deepseek-chat和deepseek-reasoner，硅基流动要带前缀deepseek-ai/，阿里云百炼则是qwen-plus这种叫法。后面所有的报错，十有八九都出在这个Model ID上。

添加完成后保存，在界面里测试一下连接，如果返回正常，说明模型已经接入了。

如果你是那种更喜欢直接用配置文件的人，也可以找到~/.openclaw目录下的配置文件，在模型（models）相关段落里手动添加类似的配置项。配置文件改完需要重启容器才能生效：

docker compose restart

4.3 unexpected的unknown model：根因到底是什么

如果你在热词里搜过“OpenClaw unknown model deepsee”，说明你已经撞上了这个经典报错：

agent failed before reply: unknown model: deepsee

这个报错翻译过来就是：OpenClaw找不到名为“deepsee”的模型定义。注意，报错里写的是deepsee，不是deepseek-chat。

这里要明白OpenClaw的模型解析机制：当你配置一个新模型时，OpenClaw会用一个模型标识（比如deepseek-chat）去它自己的模型定义表里查找。如果你填的模型名和它内置的模型ID对不上，或者这个模型ID没有被正确注册到对应的provider下，它就报unknown model。因此这个报错背后的原因基本可以锁定为三个方向：

1. 模型ID拼写错误或使用别名，比如把deepseek-chat写成了deepsee。
2. 模型ID正确，但模型供应商没有配置成功，导致模型ID没有绑定到可用的API地址。
3. 供应商配置成功，但OpenClaw版本较老，内置的模型列表里没有DeepSeek，需要手动注册。

大部分情况下是前两个原因。尤其是你在一个聚合平台上接模型的时候，平台展示的调用名称可能带仓库前缀（比如deepseek-ai/DeepSeek-V3），如果漏掉了前缀或者多加了前缀，都会报unknown model。

4.4 base_url和model id的匹配：一个案例讲透

我拿自己在硅基流动上接DeepSeek的经历举个例子。硅基流动的API地址是https://api.siliconflow.cn/v1，在这个平台上DeepSeek的模型ID是deepseek-ai/DeepSeek-V3。如果我在OpenClaw里只填了deepseek-chat，模型供应商指向硅基流动，那OpenClaw会把请求发到硅基流动的接口，要求调用deepseek-chat这个模型，硅基流动会返回“模型不存在”的错误。

反过来，如果用DeepSeek官方API（https://api.deepseek.com/v1），模型ID必须是deepseek-chat或deepseek-reasoner，如果你写了带前缀的deepseek-ai/DeepSeek-V3，DeepSeek官方也会报错。

所以在配置的时候，要记住一个原则：base_url和model id必须来自同一个服务商，不要混搭。官方API配官方模型名，聚合平台配聚合平台的调用名。

再补充一个细节：Model Type字段。DeepSeek的deepseek-reasoner是推理模型，类似于带思维链的模型，如果你在OpenClaw里把它配成普通chat类型，响应可能会异常。建议先配deepseek-chat这种通用对话模型测试，跑通了再尝试推理模型。

5. 从日志到跑通：模型配置的完整排错链路

5.1 先看日志，再看配置，别凭感觉猜

配置完模型后如果回复异常，我建议你按这个顺序排查：看容器日志 -> 看配置回显 -> 看网络连通性。而不是反复改配置重启，那是在碰运气。

查看日志的命令是：

docker compose logs -f openclaw

日志里会显示每次模型调用的细节。如果是HTTP状态码错误，比如401，就是API Key错了；404，就是模型ID不对或接口路径不对；超时，则是网络问题或模型响应太慢。日志明确指向了方向，你再去对应的组件里查原因，效率会高很多。

5.2 一个典型的“模型配置不生效”排查过程

我复盘一下自己当时接入DeepSeek的完整排错过程，相信很多人会经历类似的过程。

第一次配置，我在Control UI里添加了DeepSeek供应商，填了官方API的base_url和key，模型ID填了deepseek-chat。保存后测试连接，界面提示成功。但实际对话的时候，OpenClaw报unknown model: deepseek。

注意，这里报的是deepseek，不是deepseek-chat。这说明OpenClaw启动时读到的模型配置，和我界面上填的不一致。这种情况通常是因为：配置文件里存在两个模型定义，一个是启动时加载的默认模型，一个是界面新建的模型，而OpenClaw默认选择了旧的那一个。

解决办法是：在Control UI的模型设置里，确认默认模型（default model）指向新建的DeepSeek模型，或者直接在配置文件里把默认模型的名称改成deepseek-chat，然后重启容器。

第二次配置成功之后，我加了个deepseek-reasoner作为第二个模型，结果新的模型一直报model not found。后来发现是我把base_url填成了另一个服务商的地址，而该服务商并没有上架deepseek-reasoner。删掉重填，确认base_url和model id同源，问题就消失了。

5.3 各家国内大模型的接入参数对比

选型的时候，你可能想多接几个模型对比效果。我把几个主流平台的关键参数整理如下，供参考：

建议第一次先接DeepSeek官方，因为它接口模型名最直观、文档清晰、按量计费也便宜。跑通之后，再根据自己的需求去接其他平台。

5.4 密钥管理与安全小建议

API Key一定要妥善保管。OpenClaw的配置文件里会以明文存储API Key，所以~/openclaw目录不要随意共享给别人，也不要把config文件截图发到群里。

更安全的做法是：在compose文件里用环境变量注入API Key，例如DEEPSEEK_API_KEY=sk-xxxx，然后在OpenClaw的配置里引用这个环境变量。这样配置文件中不会出现明文密钥，即使代码仓库泄露，密钥也不会跟着暴露。用Docker部署的好处是环境变量的隔离很干净，升级容器版本时密钥仍然保留在compose里，不怕丢。

6. 接微信渠道与进阶本地模型玩法

6.1 把OpenClaw接到微信/Telegram等渠道

模型跑通之后，下一个高频需求是“让OpenClaw用我的微信跟我说话”。OpenClaw的渠道（channel）设计是为了对接不同的即时通讯工具。

以微信为例，一般有两种接法：一种是通过个人号协议接入，好处是体验自然，但个人号自动化存在账号风控风险，不建议在主号上尝试；另一种是通过企业微信/公众号的官方API接入，合规稳定，更适合长期使用。

在Control UI的Channels配置页面，选择微信分类下的渠道，根据提示填入凭证信息，比如企业微信的corpId、secret、agentId，保存后重启容器。启动日志里如果出现渠道连接成功的提示，说明已经完成了。之后你在微信里发消息给这个机器人，OpenClaw会通过配置好的大模型处理并回复。

这里提醒一句：接个人微信之前，想清楚自己的使用场景。个人号自动化协议本质上是在模拟真人操作，账号可能被限制。如果你只是想自己玩，用Telegram这类开放的IM平台作为测试渠道更安全。

6.2 本地模型（Companion/Ollama/NVIDIA NIM）的接入思路

除了云端的国内大模型，你还可以接本地模型，从根本上解决数据出域的问题，也摆脱API按量付费的困扰。OpenClaw社区里有个概念叫OpenClaw Companion，思路很直接：在本地起一个小模型，处理那些不需要强推理能力的简单任务，复杂任务再交给云端大模型。这样可以省token，也能离线工作。

本地模型最常见的运行方式有两种：Ollama和NVIDIA NIM。Ollama安装简单，支持在CPU上跑小模型，也可以通过GPU加速。NVIDIA NIM则是面向企业级场景的推理微服务，对GPU有要求。

接本地模型的关键是网络地址。OpenClaw运行在容器里，容器访问宿主机上的Ollama服务，不能用localhost，要用host.docker.internal这个宿主机别名（前面compose里的extra_hosts就是为这个准备的）。Ollama的API地址填：

http://host.docker.internal:11434/v1

模型ID填你本地拉取的模型名，比如qwen2.5:7b。只要Ollama的模型名字对得上，OpenClaw就能直接调用。本地模型的选型上，我建议优先选支持工具调用的模型（比如Qwen系列），否则OpenClaw的工具能力会大打折扣。

6.3 关于长期稳定运行的一些个人观察

跑了一个多月，我遇到的高频问题就三类：容器磁盘膨胀、模型API限流、版本升级导致的配置格式变化。

磁盘膨胀主要是因为日志和消息历史在不断增加。建议给docker容器加上日志轮转配置：

logging: driver: "json-file" options: max-size: "10m" max-file: "3"

模型API限流就比较烦了。OpenAI兼容接口一般都有每分钟调用次数限制，OpenClaw如果同时开了多个自动化任务，很容易触发429。可以在OpenClaw的配置里调低并发数，或者给不同任务用不同的API Key分摊限额。

版本升级之前，先备份~/openclaw/data目录。虽然正常升级不会丢数据，但OpenClaw迭代很快，偶尔有breaking change导致配置文件不兼容。备份一份只需要一条命令：

cp -r ~/openclaw/data ~/openclaw/data.bak.$(date +%Y%m%d)

升级后如果配置文件格式变了导致容器无法启动，把备份还原回去，再读一下官方升级文档，按说明修改配置即可。

我自己在踩过几次坑之后，现在部署OpenClaw的步骤基本固定：装好Docker、加上镜像加速、写好compose文件、配好模型供应商、测试渠道连接。整个过程熟练之后十分钟就能完成。上面这些内容如果对你有帮助，建议先把模型配置那一节吃透，因为大部分问题都集中在模型标识、API地址和密钥管理这三个环节上。之后再去折腾渠道和工具，基本就是水到渠成的事。