最近我把OpenClaw在Ubuntu上完整跑通了整个部署过程比想象中曲折一些但理清思路后其实就是几条主线系统环境准备、依赖安装、主程序部署、模型配置、验证启动。OpenClaw是一个把大模型变成真正“能干活的助手”的智能体运行环境它不再只是聊天窗口而是能读你文件、执行命令、调API、操作电脑桌面的Agent框架。这篇教程我就是按自己在Ubuntu 22.04/24.04上的实操记录来写的包含每一步为什么要这么做、做了什么、遇到问题怎么排查。不管你是想在物理机、VMware虚拟机还是云服务器上跑这套流程都能用Windows用户想在虚拟机里体验OpenClaw也适合照这篇来。1. 部署前先想清楚OpenClaw在Ubuntu上到底需要装什么1.1 OpenClaw解决什么问题很多人第一次看到OpenClaw会以为它又是一个聊天软件其实不是。它的定位是“模型工具执行策略”的组合体你可以把它理解成一个给AI装上手脚的终端环境模型负责理解和决策工具层负责实际执行比如操作文件系统、运行Shell命令、调用HTTP API、控制鼠标键盘。这意味着OpenClaw本身不产生模型能力真正负责“思考”的是背后接的大模型。所以在Ubuntu上部署OpenClaw核心其实是两件事把OpenClaw这个框架跑起来把它和某个模型服务云端API或本地模型对接好。就想通这一点后面看配置就不会乱。1.2 为什么推荐Ubuntu而不是Windows我一开始其实是在Windows上跑的后来换到Ubuntu才觉得舒服。原因很实际Linux的用户权限和进程管理更干净OpenClaw要执行Shell命令、读写文件在Linux下权限边界非常清晰不会动不动弹UAC。日志、配置、数据目录都有规范位置排查问题比Windows直观。Ubuntu对Docker的支持更好而Docker在后面接本地模型、跑插件沙箱时非常重要。如果你的OpenClaw要长期运行Ubuntu服务器可以通过SSH远程管理Windows桌面版在这方面就没那么顺手。当然Windows也不是不能装官方也提供Windows安装方式只是我体验下来Ubuntu这条路最顺。VMware里装Ubuntu的话我更推荐把网络模式设为桥接或NAT后面SSH连接、拉取依赖包都不容易踩坑。1.3 整体架构和安装路径在动手之前我先说清楚OpenClaw在Ubuntu上大概依赖哪些组件这样你不会在安装过程中一头雾水OpenClaw主程序官方提供安装脚本多数情况下装的是编译好的二进制部署在用户目录如~/.openclaw。Node.js部分辅助工具、扩展插件依赖Node生态建议提前装好版本20以上比较稳。PythonOpenClaw的很多工具链和内置脚本是Python写的建议系统Python 3.10。Docker不是启动OpenClaw的硬性条件但如果你要接NVIDIA NIM、跑隔离环境、部署本地模型Docker基本绕不开。有人会问为什么不能一条命令装完所有东西因为OpenClaw更像一个可扩展的平台真正常用的组件取决于你接什么模型、跑什么任务。先装核心再把需要的扩展补上这是我实际体验下来最不容易出错的顺序。2. 环境准备与依赖安装最容易翻车的环节2.1 系统基础检查和账号准备我在Ubuntu 24.04上部署成功过22.04 LTS也验证过没问题。先确认系统版本和架构lsb_release -a uname -m如果是x86_64或arm64架构就没问题OpenClaw对于常见的x86服务器支持最好。内存方面如果只接云端API4GB内存就够如果还要跑Ollama或NIM本地模型内存16GB起步显存则看模型规模。如果你是在VMware虚拟机里装Ubuntu我建议给虚拟机至少2核CPU、4GB内存、30G磁盘。官方Ubuntu镜像从官网iso直接下载就行桌面版和服务器版都可以但服务器版资源占用更少跑OpenClaw更干净。系统装好后第一步是确保当前用户有sudo权限。你可能会看到网上有人问“Ubuntu怎么切换超级管理员”就是那个意思。Ubuntu默认root没有密码日常操作用sudo -i可以临时切到root环境真想给root设密码就执行sudo passwd root但日常运行OpenClaw不推荐用root普通用户加sudo就够了。2.2 基础依赖curl、git、编译工具链这一步看似简单但很多安装脚本失败就是卡在基础工具缺失上。我先跑一遍sudo apt update sudo apt upgrade -y sudo apt install -y curl wget git ca-certificates build-essentialbuild-essential是编译工具链有些npm包或Python扩展需要本地编译没有它会报gcc找不到之类的错。装完顺手验证一下版本curl --version git --version gcc --version如果你的apt源是默认官方源在国内网络环境下可能很慢甚至超时。这时候可以先换国内镜像源再来执行apt update。换源本质就是把/etc/apt/sources.list或/etc/apt/sources.list.d/ubuntu.sources里的地址换掉。这一步不是必须的但实际体验差别非常大建议网络慢的先做。2.3 Node.js和Python版本选择OpenClaw主程序本身可能不强制要求本机装Node.js但它的很多子命令、插件、以及基于Node的工具链会在运行时用到。我实际踩过的坑是系统自带Node版本太旧装插件时直接报语法错误。推荐用NodeSource源的LTS版本curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt install -y nodejs或者你更习惯用nvm管理Node版本也可以curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash nvm install 20Python方面Ubuntu 22.04自带Python 3.1024.04自带3.12都够用。千万别手动去卸载系统自带Python很多系统工具依赖它删了会出大问题。2.4 安装Docker后面接本地模型和插件都要用“Ubuntu安装docker”这个词搜索量很高确实也是部署OpenClaw过程中很多人卡住的地方。Docker在OpenClaw体系里主要干两件事跑容器化插件做沙箱隔离跑本地模型服务比如NVIDIA NIM。安装Docker CE的推荐方式是用官方仓库sudo apt install -y ca-certificates curl gnupg lsb-release sudo install -m 0755 -d /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg sudo chmod ar /etc/apt/keyrings/docker.gpg echo \ deb [arch$(dpkg --print-architecture) signed-by/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \ $(. /etc/os-release echo $VERSION_CODENAME) stable | \ sudo tee /etc/apt/sources.list.d/docker.list /dev/null sudo apt update sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin安装完成后把当前用户加进docker组免得每次执行docker命令都要sudosudo usermod -aG docker $USER newgrp docker docker run hello-world注意一下usermod之后要重新登录或者用newgrp docker让组权限生效否则你会遇到“docker: permission denied”这个经典错误。我当初就是在这里卡了十分钟后来才发现没重连SSH。2.5 防火墙和SSH远程部署前先做好功课如果你是在云服务器或远程主机上部署SSH连不上就是第一道坎。热搜词里“ubuntu ssh无法连接”出现频率很高核心排查点有三个openssh-server是否安装、22端口是否被防火墙拦截、SSH服务是否在运行。sudo apt install -y openssh-server sudo systemctl enable --now ssh sudo ufw allow 22/tcp sudo ufw enable如果你用的是VMware NAT模式还要在虚拟机网络设置里把宿主机的某个端口映射到虚拟机的22端口否则从宿主机SSH进不去。3. 核心实操OpenClaw安装部署全流程3.1 下载安装主程序OpenClaw官方推荐用脚本安装在终端执行curl -fsSL https://openclaw.ai/install.sh | bash安装脚本会把主程序放到~/.openclaw目录下然后提示你添加PATH。这一步很多人会忽略结果安装完执行openclaw提示“command not found”以为装失败了。其实不是只是PATH没设置。脚本输出里一般会提示你执行类似下面这句或者自动写入~/.bashrcecho export PATH$HOME/.openclaw/bin:$PATH ~/.bashrc source ~/.bashrc然后验证版本openclaw --version如果你不想用官方安装脚本也可以去GitHub Releases手动下载对应的Linux二进制包解压到/usr/local/bin或你的自定义目录。但手动方式要自己管理依赖脚本方式省心很多我推荐先用脚本。3.2 初始化和目录结构安装完成后~/.openclaw目录会自动生成。我建议你先跑一下初始化命令openclaw init这个命令会生成本地配置文件。OpenClaw的配置目录结构大致是这样的以我实际部署后的目录为例~/.openclaw/ ├── bin/ ├── config/ │ └── openclaw.json ├── workspace/ ├── skills/ ├── logs/ └── exec-approvals.json这里每个目录都有讲究workspaceOpenClaw执行任务时的工作目录相当于它“干活的地方”。热搜词里出现过workspace: c:\users\administrator\.openclaw\workspace说明Windows版也有同样的目录设计。你可以把常用项目文件放这里让OpenClaw快速访问。skills技能目录放插件或自定义技能。logs运行日志后面排查问题全靠它。exec-approvals.json执行权限审批记录。OpenClaw在让模型执行有风险的操作前会先申请批准这个文件就是记录批准状态的。热词里那句“legacy exec approvals exist at /root/.openclaw/exec-approvals.json”指的就是这个文件。3.3 配置模型APIopenclaw本身不绑定特定模型你需要告诉它接哪个模型服务。以接Claude为例最常用的是通过环境变量注入API密钥export ANTHROPIC_API_KEY你的key如果用的是OpenAI兼容接口就要配置OPENAI_API_KEY和OPENAI_BASE_URL这地方要注意base_url一般要写到/v1结尾。你可以把环境变量写进~/.bashrc也可以直接改配置文件。打开~/.openclaw/config/openclaw.json典型配置长这样简化版{ model: { provider: anthropic, model: claude-3-5-sonnet-latest, apiKeyEnvVar: ANTHROPIC_API_KEY }, execution: { workspace: ~/.openclaw/workspace, requireApproval: true } }如果你是第一次使用我的建议是先用云端模型比如Claude跑通全流程不要一上来就折腾本地模型。等OpenClaw能正常干活了再切换本地模型也不迟。3.4 启动服务与验证配置完成后直接在终端执行openclaw就会进入OpenClaw的交互界面。你可以试着让它执行一个简单命令比如查看当前目录、读取某个文件。OpenClaw会向你展示它准备执行的操作并请求批准批准后它会在workspace里实际执行。配合--headless或服务模式可以让OpenClaw在后台常驻。如果是在服务器上我更推荐把它注册成systemd服务开机自启日志统一管理。systemd服务文件大概这么写[Unit] DescriptionOpenClaw Agent Afternetwork.target [Service] User你的用户名 EnvironmentANTHROPIC_API_KEY你的key ExecStart/home/你的用户名/.openclaw/bin/openclaw --headless Restarton-failure RestartSec5 [Install] WantedBymulti-user.target保存到/etc/systemd/system/openclaw.service然后sudo systemctl daemon-reload sudo systemctl enable --now openclaw sudo systemctl status openclaw这样OpenClaw就在后台跑起来了日志通过journalctl -u openclaw -f查看比挂着终端省心太多。4. 接入本地模型与扩展技巧4.1 为什么要接本地模型云端API模型能力强但数据都要发到外部且每次调用都有费用。本地模型的好处是数据不出机器、离线可用、没有按token计费的压力。很多人部署OpenClaw后就想接Ollama或NVIDIA NIM我也是这么折腾过来的。不过这里要先泼一盆冷水通用小模型在工具调用上经常犯迷糊比如看不懂该传什么参数或把文件名幻觉出来。我实测下来要接本地模型至少用7B~14B参数级别的指令微调模型且要选工具调用能力强的。太小或纯对话模型体验会很糟糕。4.2 配置Ollama本地模型Ollama是目前最简单的方式。先装Ollamacurl -fsSL https://ollama.com/install.sh | sh然后拉取模型比如qwen2.5系列的指令模型ollama pull qwen2.5:14b-instruct ollama serve默认情况下Ollama监听11434端口并且提供OpenAI兼容接口http://localhost:11434/v1。所以OpenClaw里只要把模型的provider或base_url指过去就行{ model: { provider: openai-compatible, baseUrl: http://localhost:11434/v1, model: qwen2.5:14b-instruct, apiKey: ollama } }注意apiKey字段Ollama默认不校验key可以随便填一个占位符。这个方案是社区里很成熟的做法适合没独显但内存比较大的机器。4.3 配置NVIDIA NIMNVIDIA NIM是另一个热词它把优化的推理服务打包成容器GPU利用率高效果也稳定。前提是你有NVIDIA显卡并且装好驱动和容器支持。先装好nvidia-container-toolkitsudo apt install -y nvidia-container-toolkit sudo nvidia-ctk runtime configure --runtimedocker sudo systemctl restart docker然后拉一个NIM容器。以Llama 3系列为例docker run -d --rm \ --name llama-nim \ --gpus all \ -p 8000:8000 \ -e NIM_HTTP_API_KEY你的key \ nvcr.io/nim/meta/llama3-70b-instruct:latest启动后NIM在localhost:8000提供OpenAI兼容接口OpenClaw这边配置{ model: { provider: openai-compatible, baseUrl: http://localhost:8000/v1, model: meta/llama3-70b-instruct, apiKey: 你的key } }NIM的镜像体积大、显存要求也高70B模型纯37B权重就有140G普通消费级卡根本跑不动。建议先查清楚你自己显卡型号再决定用哪个规格的NIM镜像。4.4 安装skill和扩展能力OpenClaw的魅力在于可扩展。“openclaw使用本地ollama如何安装skill”这类问题就是关于扩展的。Skill相当于给OpenClaw的“技能手册”让它知道在什么场景下调什么工具、按什么流程完成任务。skill一般是目录结构放在~/.openclaw/skills/下skills/ └── my-skill/ ├── SKILL.md └── scripts/SKILL.md描述这个技能是什么、适用场景、执行步骤。OpenClaw在遇到相关任务时会把skill内容作为上下文的一部分喂给模型让它知道该怎么干。如果你想偷懒可以从ClawHub之类的社区获取现成skill。热词里有关“openclaw跟clawhub的区别”的问题我理解ClawHub是OpenClaw的技能/插件分发社区类似软件源OpenClaw本体是运行框架ClawHub是扩充它能力的仓库。一个回答是“运行基础扩展源”的关系。另外热词里还有“openclaw接入飞书”“openclaw微信”这些需求本质上都是通过写skill或配置webhook把OpenClaw接进IM平台让对话消息转发给OpenClaw处理。这一步属于进阶玩法等基础部署跑通后再研究更稳妥。5. 常见问题排查与避坑实录5.1 command not found / PATH不生效很多人在安装时执行openclaw提示“无法将openclaw项识别为 cmdlet”在Ubuntu下则是bash: openclaw: command not found。两个平台原因一样安装目录没加进PATH。先确认OpenClaw装到哪里了ls ~/.openclaw/bin/如果有openclaw文件就把PATH加上。Windows的话是系统环境变量Path里加C:\Users\你的用户名\.openclaw\binUbuntu是加~/.bashrc别忘了source ~/.bashrc。这个问题的根源不是安装失败而是当前Shell没找到可执行文件所以别急着重装。5.2 Ubuntu SSH无法连接排查顺序先看服务状态systemctl status ssh再看防火墙sudo ufw status最后看监听端口ss -tlnp | grep 22。遇到过最隐蔽的坑是VMware虚拟机装完Ubuntu网络模式是NAT宿主机根本ping不同虚拟机SSH自然连不上。解决方式是在VMware的NAT设置里做端口转发把宿主机的2222端口映射到虚拟机22端口然后ssh -p 2222 用户127.0.0.1。或者更省事把网络模式改成桥接让虚拟机直接拿局域网IP。5.3 Docker权限被拒绝现象是docker inspect或docker ps报错“permission denied”。解法在上面已经提到了把用户加进docker组然后重新登录。注意的是SSH会话里只有当次连接生效的是旧权限newgrp docker只能临时让当前终端生效最保险的方式是断开SSH重连。5.4 exec-approvals.json相关报错这个坑我觉得值得单独拿出来说。升级OpenClaw或切换运行用户后有可能看到类似这样的提示legacy exec approvals exist at /root/.openclaw/exec-approvals.json. run openclaw migrate or move it to ~/.config/openclaw/...意思是旧版本生成的执行审批文件还在老位置新版本可能换了读取路径或者文件格式升级了。最稳妥的办法是按提示执行迁移命令比如openclaw migrate如果确认不需要保留历史审批记录备份后删掉这个文件再重新运行也可以。别直接忽略因为审批文件丢失可能导致OpenClaw在需要执行危险命令时反复要求授权体验很差。5.5 模型API报401/404/400401一般是API key错误检查环境变量是否真的传进去了可以用env | grep API确认。404一般是base_url路径不对OpenAI兼容接口通常要求以/v1结尾。400则大概率是模型名写错比如模型中带了版本号但实际不存在。这类问题在Ollama和NIM上尤其常见因为不同模型的命名规则不一样。最直接的验证方式是用curl手动调一次接口curl http://localhost:11434/v1/chat/completions \ -H Content-Type: application/json \ -d {model:qwen2.5:14b-instruct,messages:[{role:user,content:hi}]}能正常返回就说明接口没问题问题一定出在OpenClaw配置这一层。5.6 想卸载OpenClaw怎么办热词里有“openclaw卸载”。卸载其实很简单rm -rf ~/.openclaw但如果你把它注册了systemd服务得先停掉sudo systemctl stop openclaw sudo systemctl disable openclaw sudo rm /etc/systemd/system/openclaw.service sudo systemctl daemon-reload再把~/.bashrc里的PATH配置删掉就行。Windows下也是类似删目录、清理环境变量、若有服务则删除。最后的几点体会这套流程我从零开始折腾了两天最深的感受是OpenClaw本身安装并不难难的是“环境”两个字。PATH没配好、Docker权限不对、模型API地址写错每一个看起来都是小事但串起来能卡住人很久。所以我强烈建议部署时每一步都验证一次结果不要想着“先全装完再一起调”。如果你是在家里找一台老Ubuntu机器部署后续可以继续研究两个扩展方向一是把它注册成systemd服务做成常驻Agent通过HTTP接口或IM机器人远程调用二是把它和本地NAS、代码仓库连起来让Agent能处理你日常的自动化任务。OpenClaw这个项目迭代很快但底层这套“模型工具审批”的架构在Ubuntu上是稳定的值得投入时间研究。