Ubuntu下OpenClaw部署实战：从零安装到配置模型与技能

最近在Linux圈子里，OpenClaw这个名字出现的频率越来越高。简单来说，它是一个开源的AI代理框架，可以把大模型的能力接到真实的工作流里——比如让它读微信消息、操作浏览器、执行命令行、调用各种API。前几天我在一台Ubuntu 22.04的机器上从零到一部署了一份，整个过程踩了不少坑，也积累了一些经验。这篇文章不是官方文档的复读，而是把我实际跑通的步骤、配置方法、以及遇到问题时的排查思路整理出来，给想在Ubuntu下安装OpenClaw的朋友一个可以直接照着做的参考。

我一直觉得，这类Agent框架最大的门槛不是运行环境，而是“你以为它是个聊天机器人，实际上它是个可以操控系统的数字员工”。所以下面第一部分，我会先花点时间把OpenClaw的架构位置讲清楚，然后再进入环境准备、安装、配置这条完整链路。如果你已经对OpenClaw很熟了，可以直接跳到第3节看实操。

1. 安装前先搞清楚：OpenClaw到底是什么，装它能做什么

1.1 核心是一个Agent框架，不是一个聊天框

很多人第一次看到OpenClaw，容易把它理解成又一个ChatGPT套壳。实际上它的定位更接近一个Agent运行时：你给它配置大模型作为“大脑”，再通过Gateway接入各种消息渠道，通过Skill扩展各种工具能力，它就能自主完成一系列任务。比如你让它“每天早上九点去某个网页抓取天气并推送到微信”，在传统聊天框里做不到，但在OpenClaw里可以通过定时任务、浏览器技能和微信渠道组合实现。

从架构上看，OpenClaw大致由几个部分组成：Agent运行时负责理解任务、编排步骤；Gateway负责和外部渠道通信，也就是消息进出的门面；Model Provider层负责对接各种大模型，只要支持OpenAI协议的服务都可以接进来；Skill则是插件系统，给Agent补充工具调用能力。理解这层结构很重要，因为后面对配置、排查问题时，你才能快速定位是哪一层出了问题。

1.2 为什么我建议你在Ubuntu上部署

OpenClaw的官方支持里其实有Windows整合包，网上也有一些离线整合包可以下载，想快速体验的话门槛并不高。但如果你打算长期使用，或者准备部署到云服务器上，Ubuntu几乎是更合理的选择。

原因很直接：一是资源占用可控，Ubuntu Server版没有图形界面，可以把大部分内存留给OpenClaw和模型API调用；二是后台运行方案成熟，systemd、screen、tmux、Docker都能很好地管理进程；三是整个AI生态的工具链在Linux上最顺——Git、Node.js、Python、Docker、浏览器自动化这些组件，在Ubuntu上安装几乎没有多余的折腾。另外，现在很多开发者习惯在Windows上装WSL来获得Ubuntu环境，写代码时再配一款接近macOS体验的字体，本质上也是冲着Linux生态来的。所以与其在Windows里绕一圈，不如直接面对Ubuntu，把底层跑顺。

1.3 安装前需要准备哪些东西

在敲命令之前，建议先花几分钟把下面这些东西准备好，不然装到一半发现少这个少那个，来回打断体验很不好。

• 一台Ubuntu机器，版本推荐22.04 LTS或24.04 LTS。物理机、VMware虚拟机、云服务器都可以，部署流程差别不大。
• 能够正常访问GitHub的网络环境。安装脚本和源码都在GitHub上，网络不稳定会导致拉取失败，这个问题后面我专门讲。
• Node.js环境。OpenClaw基于Node.js生态，我建议用nvm来安装和管理版本。
• Git。无论你用安装脚本还是源码方式部署，都绕不开Git。
• 一个大模型API的Key。OpenClaw本身不内置模型，它需要调用外部模型服务。硅基流动这类平台提供OpenAI兼容接口，可以先用它来跑通流程。
• 一个可用的浏览器环境（可选）。如果你想用OpenClaw做网页操作类任务，需要准备Chrome或Chromium。

这些准备项里，模型API Key是最容易被忽视的，很多人装完OpenClaw启动时才发现没有配置模型，导致第一印象很差。其实提前注册一个开放平台，拿到Key填进配置里就行。

2. Ubuntu环境准备：把地基打好再动工

2.1 系统基础依赖安装

我这次部署用的是Ubuntu 22.04 LTS，整体过程在24.04上同样适用。开箱第一件事就是更新软件源和系统包，这一步能避免后面很多依赖版本过旧造成的坑。

bash复制sudo apt update && sudo apt upgrade -y

然后安装基础编译工具。虽然OpenClaw本身是JavaScript项目，但它的部分依赖在安装过程中需要编译原生模块，所以build-essential、curl、wget、git这些一个都不能少。

bash复制sudo apt install -y curl wget git build-essential

这里多说一句，build-essential里包含gcc、g++、make等编译工具。如果你的机器是精简版系统，没装这套工具，后面npm install阶段很可能因为编译失败而报错，所以一次性装齐最省事。

2.2 用nvm安装Node.js，别直接用apt

OpenClaw对Node.js版本有要求，太老或太新的版本都有可能在安装依赖时出问题。我建议用nvm来安装Node.js，版本选择20 LTS，这是一个比较稳妥的选择。

nvm的安装方式很简单：

bash复制curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

安装完成后，重新打开终端，或者执行source ~/.bashrc让nvm命令生效。然后安装并切换Node版本：

bash复制nvm install 20
nvm use 20
node -v
npm -v

为什么不直接用apt安装nodejs？因为apt源里的Node版本往往偏旧，而且切换版本很麻烦。用nvm可以随时在多个Node版本之间切换，以后OpenClaw官方升级要求新版本时，你只需要nvm install新版本再切过去就行，不用重装系统。

2.3 Git配置与拉取准备

OpenClaw的安装脚本方式是从GitHub拉取仓库，手动部署方式也是通过git clone，所以Git的可用性和稳定性很关键。

先做基本配置：

bash复制git config --global user.name "你的名字"
git config --global user.email "你的邮箱"

如果你习惯用SSH方式拉取代码，可以生成密钥并配置到GitHub账户里：

bash复制ssh-keygen -t ed25519 -C "你的邮箱"
cat ~/.ssh/id_ed25519.pub

把输出的公钥内容添加到GitHub的SSH Keys设置页面即可。

如果你所在的网络环境访问GitHub不稳定，git clone时经常卡住，可以尝试调整Git的超时容忍度：

bash复制git config --global http.lowSpeedLimit 1000
git config --global http.lowSpeedTime 60

这个配置的意思是，如果连接速度低于1000字节/秒并持续60秒，Git才判定超时。默认情况下，Git对低速网络的容忍度很低，稍微慢一点就中断，调大这两个参数能减少拉取失败的概率。另外也可以选择在网络比较空闲的时段拉取，实测成功率会高很多。

3. 安装OpenClaw的完整实操流程

3.1 官方安装脚本方式：一行命令起步

OpenClaw官方提供了安装脚本，这是最快的方式。脚本会自动检测你的系统环境，检查缺失的依赖，然后从GitHub的main分支检出源码，完成依赖安装并生成初始配置。这个安装脚本本身是可配置的，我记得官方文档里提到，可以通过安装脚本指定git安装方式，比如从GitHub的main分支检出源码。具体命令以官方仓库README为准，一般形式类似：

bash复制curl -fsSL 官方安装脚本地址 | bash

如果你想显式指定用git方式从main分支安装，可以在脚本后面追加参数，形式大概是：

bash复制bash <(curl -fsSL 官方安装脚本地址) --git

我自己的体验是，安装脚本适合第一次接触OpenClaw、想快速看到效果的朋友。它会帮你省掉手动克隆、安装依赖、初始化配置这些步骤。但需要注意的是，脚本执行过程中如果网络波动，很容易中断，而且中断后留下的半成品状态比较难处理。所以我个人更推荐下面这种手动部署方式，虽然多敲几条命令，但每一步都看得清楚，出问题也好排查。

3.2 手动部署：从源码把OpenClaw拉起来

手动部署的本质就三步：克隆源码、安装依赖、配置启动。首先从官方仓库克隆代码到本地：

bash复制git clone 官方仓库地址 openclaw
cd openclaw

克隆完成后，先看下目录里有没有.env.example这样的模板文件，这是配置的起点。把它复制一份为.env：

bash复制cp .env.example .env

然后安装依赖。OpenClaw的依赖比较多，安装过程可能持续几分钟，需要耐心等：

bash复制npm install

如果项目使用pnpm，也可以看下package.json里的包管理器约定，按项目要求来。依赖安装完成后，先别急着启动，打开.env文件，把模型服务的配置填进去。这一步是最关键的，我放到第4节详细说。

手动部署的一个好处是，你能清楚知道OpenClaw装在了哪里、依赖装到了哪里。以后要升级，只需要git pull拉取最新代码，再重新npm install一次即可。而且如果你有二次开发的打算，直接在源码目录里改东西也比改容器里的文件方便得多。

3.3 用Docker容器方式部署（可选）

如果你不太想在宿主机上装一堆Node依赖，或者怕OpenClaw的依赖污染系统环境，可以考虑Docker方式。Ubuntu下安装Docker很简单：

bash复制sudo apt install -y docker.io
sudo systemctl enable --now docker
sudo usermod -aG docker $USER

重新登录终端后，就可以用docker命令了。OpenClaw官方也提供了镜像和docker-compose配置，你需要准备一个docker-compose.yml文件，里面定义OpenClaw主服务，并挂载配置目录、数据目录，如果有浏览器自动化需求，还要在容器里安装Chromium或映射宿主机的Chrome。

Docker方式比较适合一种特殊场景：用容器控制Chrome。因为浏览器自动化在容器里跑，可以把Chrome进程、用户数据目录都隔离起来，不会跟宿主机上的日常浏览器冲突。如果你的OpenClaw任务涉及大量网页操作，Docker方案会省心很多。但代价是容器调试相对麻烦，查看日志、进入容器都要多打几条命令，初次使用还是建议先手动部署跑通流程再说。

3.4 安装完成后的目录结构与验证

安装完成后，OpenClaw的目录结构大致是：根目录下会有src或dist这样的核心代码目录，一个config目录存放配置文件，一个skills目录存放技能插件，还有logs目录记录运行日志。你可以先看看这几个目录是否存在：

bash复制ls -la
cat package.json | head -20

接下来可以尝试启动OpenClaw，验证安装是否完整。启动命令通常是npm start，或者项目里定义了对应的npm script。启动成功后，终端会输出监听端口、Gateway地址等信息。第一次启动还会引导你初始化管理员账号，或者输出一个用于Web端登录的二维码图片。看到这些输出，基本就说明安装环节已经通过，后面就是配置和体验的问题了。

4. 配置模型、网关和技能，让OpenClaw真正跑起来

4.1 接入模型供应商，以硅基流动为例

OpenClaw本身不包含大模型，它需要对接一个模型服务。现在国内很多平台都提供OpenAI兼容的API接口，硅基流动就是其中之一。用这类平台的好处是门槛低、按量计费、不需要自己折腾显卡，而且它家提供不少开源模型可以选。

在 .env里，核心配置大概是下面这样的：

bash复制OPENAI_API_KEY=你的API密钥
OPENAI_BASE_URL=https://api.siliconflow.cn/v1
OPENAI_MODEL=Qwen/Qwen2.5-7B-Instruct

注意，具体字段名要以你拉取的版本里的.env.example为准，不同版本可能会有细微差异。但核心思路是一致的：API Key负责鉴权，Base URL告诉OpenClaw该把请求发到哪个地址，Model指定默认使用哪个模型。

配置保存后，需要重启OpenClaw让配置生效。这一步经常有人忘记——改了配置不重启，然后发现模型没切换过来，误以为是配置格式写错了。重启后再发一条测试消息，如果模型开始正常回复，就说明接入成功。

4.2 Gateway：理解消息网关的作用

配置模型的时候，很多人会看到一个词：Gateway。这是OpenClaw里相当核心的组件，你可以把它理解成“消息路由器”——微信、Web面板、命令行这些渠道的消息，都是先经过Gateway，再由Gateway转给Agent核心处理；Agent回复的消息，也是通过Gateway分发回原渠道。

热词里提到的“openclaw gateway改用模型”以及“openclaw ccswitch切换模型”，本质上都是在说Gateway的模型路由功能。OpenClaw允许你在Gateway里配置不同的模型，或者通过ccswitch命令在多个模型之间动态切换。比如日常闲聊用轻量模型省钱，写代码或深入分析时切换到更强的大模型，这就是很典型的用法。

切换模型时我建议注意一点：模型切换后，旧会话里的上下文如果还留着，新模型可能会延续旧模型的人设和风格，产生“串味”。如果你发现切换模型后回复风格不对，或者上下文理解混乱，最好的办法是新开一个会话，让新模型从干净的上下文开始工作。这一点在多媒体渠道上尤其明显，尤其当你接入了微信这类实时消息渠道，会话里积累了大量的历史消息，残留上下文会影响新模型的表现。

4.3 Skill技能插件与提示词设置

Skill是OpenClaw最有意思的部分。默认情况下，Agent只具备对话能力；装了Skill之后，它才真正具备“动手”能力。常见的Skill类型包括浏览器控制、网页搜索、代码执行、文件操作、定时任务、消息推送等。

Skill的安装方式一般是两种：一种是从Skill市场或社区一键安装，另一种是手动下载源码放到skills目录下。安装完成后，需要在配置里启用对应的技能，并针对该技能做必要的授权设置。比如浏览器控制类Skill，如果是容器化部署，要确保容器内有Chromium；如果是宿主机部署，要设置好Chrome的路径和用户数据目录。

社区里现在有大量现成的Skill，也有人做了“妙想skill”之类的中文合集，专门解决某些垂直场景。我的建议是，第一次使用不要贪多，先装两三个真正会用到的Skill，跑通一个完整任务，理解Skill在OpenClaw里是怎么被调用的，然后再逐步扩展。装太多Skill反而会让Agent在自主决策时无所适从，不知道优先调用哪一个。

提示词也是OpenClaw里容易被忽略的配置项。你可以在配置里给Agent设定一个系统提示词，约束它的身份、语气、行为边界和允许调用的技能范围。比如你可以告诉它“你是我的个人助理，回答尽量简洁，执行任务前先确认关键步骤”，这会让Agent的行为明显更符合你的预期。提示词不是一次性写死就完事的，用几天之后你要回头调整，让它更贴近实际使用习惯。

4.4 接入微信等消息渠道

OpenClaw支持接入微信，这也是很多人的刚需。接入方式大致是：启动OpenClaw后，在Web面板或Gateway里找到渠道绑定入口，生成一个二维码图片，然后用微信扫码完成绑定。扫码成功后，Agent就能在微信里收发消息了。

我的建议是，微信渠道适合个人助理场景，比如把Agent当备忘录、让它定时推送信息、让它查资料然后回复到微信。但如果你要让它自动群发消息或者高频回复，风险很大，一方面是容易被对话平台判定为异常行为，另一方面也会给真实好友带来困扰。我自己一直把OpenClaw的微信能力限制在单聊范围内，而且设置了消息频率上限，尽量让它像“一个偶尔帮忙的朋友”，而不是“一个话痨机器人”。

如果你是通过第三方IM接入服务把OpenClaw连到微信的，可能偶尔会遇到服务端风控或会话残留的情况。比如会话残留会造成Agent在回复时带上旧上下文，风控触发则可能导致消息发不出去。遇到这类问题，优先检查Gateway的会话缓存，重启Gateway清理一下，再适当降低消息发送频率。

5. 常见问题与排查技巧

5.1 安装阶段的经典报错

我在安装过程中遇到过几类高频问题，整理成了速查表：

安装阶段最常见的就是网络问题。我的经验是，npm install失败不要反复在同一条命令上死磕，先检查网络连通性，再考虑换镜像源。npm在国内使用可以临时指定镜像源：

bash复制npm install --registry=https://registry.npmmirror.com

这能明显提高依赖安装成功率。但要注意，有些OpenClaw依赖可能从GitHub直接拉取原生模块，这类依赖即使换了npm镜像源也可能慢，耐心多试几次就好。

5.2 启动与运行时的连接问题

OpenClaw启动后，你先检查日志确认Gateway是否正常监听。如果Web面板访问不了，先看进程是否存活，再看端口是否被监听：

bash复制ps aux | grep openclaw
ss -tlnp | grep 端口号

模型调用报401或403，基本就是Key填错了，或者Base URL格式不对。我建议在.env里改完配置后，先通过curl手动测试一次模型接口：

bash复制curl 模型服务地址 -H "Authorization: Bearer 你的Key" -d '{"model":"模型名","messages":[{"role":"user","content":"ping"}]}'

能通再启动OpenClaw，这样可以把问题范围缩小到“OpenClaw配置错误”还是“模型服务本身不可用”。

容器控制Chrome失败也是一个常见问题。如果你用Docker方式部署，容器内的Chrome或Chromium可能没装，或者缺少运行浏览器的系统库。解决办法是在Dockerfile里安装chromium-browser或google-chrome-stable，并把浏览器的可执行文件路径配置到OpenClaw的浏览器Skill里。如果是在宿主机上部署，则要确认Chrome的路径配置正确，且用户数据目录有读写权限。

5.3 消息渠道的风控与上下文残留

接入微信等实时对话渠道后，有两类问题需要特别注意。一类是第三方IM接入服务触发的服务端风控，表现为消息发送失败、被静默丢弃，甚至账号被短时限制。这类问题的主要原因往往是请求频率过高，或者消息内容触发了风控规则。解决思路是降低Agent的主动消息频率，增加随机延时，避免批量群发，以及不要在提示词里诱导Agent发送套路化广告内容。

另一类是会话残留。当Agent在多个渠道里共用一个核心上下文时，某个渠道的长对话可能会拖慢另一个渠道的响应速度，甚至导致回复内容出现混淆。遇到这种情况，我会定期重启Gateway清理会话缓存，或者在配置里按渠道隔离上下文。上下文隔离这一点，在OpenClaw里通常可以通过配置不同的会话策略来实现，具体字段名看版本文档，但思路是一致的：不同渠道尽量互不干扰。

从根上讲，接入微信这类平台，安全合规使用永远是第一位的。把Agent定位成一个对你有帮助的个人助理，而不是一个批量营销工具，既能稳定运行，也不会给自己惹麻烦。

5.4 升级与卸载的注意事项

OpenClaw迭代很快，官方经常会发布新版本。升级前一定要备份，至少把config目录、skills目录和里面所有数据文件copy一份。然后按你当初的部署方式操作。

如果是git方式部署，升级很简单：

bash复制git pull origin main
npm install

然后重启OpenClaw进程。如果版本跨度比较大，依赖变化较多，npm install报错时，可以先删掉node_modules再重新安装。如果是脚本方式部署，可以参考官方升级指引，或者直接重新跑安装脚本，脚本通常会自动检测已有配置并升级到最新版本。

卸载OpenClaw比较容易。先停掉正在运行的进程，然后删除整个OpenClaw目录，再清理一下可能存在的开机自启项。但如果你用OpenClaw有段时间了，真的建议先备份一下skills目录和.env配置文件，因为里面可能有你花心思写的提示词、调好的参数，这些东西一旦删了再重新调，非常耗时。

写在最后

部署OpenClaw这件事，坦白说难度不算高，真正花时间的是把它打磨成适合自己使用的工具。我自己的体会是，一开始不要试图把所有功能都装上，也不要同时接微信、浏览器、定时任务一大堆。先把最核心的模型接入跑通，再用一个Skill完成一个真实任务，比如“让它每天帮我整理某个网页的信息”，然后逐步增加渠道和技能。每加一个功能，就观察一阵，看它是不是真的提高了效率，还是只是增加了噪音。

最后分享一个实用小技巧：如果你希望OpenClaw在服务器上长期运行，不要只开一个终端窗口跑npm start，因为它会随着终端关闭而退出。简单点的方案是用tmux或者screen把进程挂到后台；更规范的方案是写一个systemd服务单元，把OpenClaw注册为开机自启服务。我一开始就是用tmux顶着用的，后来发现机器一次意外重启，OpenClaw没有跟着起来，才改成了systemd方案。配置好后，即使机器重启，OpenClaw也会自动恢复运行，省心很多。