我一开始是在 Ubuntu 服务器上试着跑 OpenClaw 的当时的想法很简单既然它主打“通用 AI 助理框架”那与其在 Windows 上折腾各种路径和防火墙不如直接放到 Linux 环境里用终端和 systemd 把它当正经服务养起来。结果一路踩下来发现安装部署这件事看着简单实际还是有不少门道——从一键脚本到源码构建再到 Docker 容器化和模型后端配置每一步都有取舍。这篇文章就是一份完整的 Ubuntu 部署实录。我会把 OpenClaw 是什么、为什么值得装在 Ubuntu 上、三种安装方式怎么做、模型怎么接、服务怎么常驻、遇到问题怎么排查全部讲清楚。如果你手里有一台 Ubuntu 机器想自己动手把 AI 助理跑起来这篇文章可以直接当操作手册用。1. 理解 OpenClaw 与部署形态选型1.1 一句话认识 OpenClawOpenClaw 是一个开源的个人 AI 助理框架它脱胎于之前的“妙想”项目开源后以 OpenClaw 的名字对外发布。和网页版聊天机器人最大的区别是OpenClaw 不是跑在别人服务器上的一个对话框而是装在你自己机器上的一个 Agent 运行时。它运行在终端里能做的事情远不止“聊天”。模型可以通过它读写本地文件、执行命令、调用外部工具甚至按你的授权操作浏览器和电脑桌面。这种“模型 工具调用”的组合是它和普通聊天界面之间的本质区别。部署 OpenClaw本质上是在自己机器上搭建一个能被模型安全调用的 Agent 环境。1.2 为什么 Ubuntu 是合适的部署平台OpenClaw 支持多平台但如果要做正经部署我建议选 Ubuntu。原因很朴素系统干净。Ubuntu Server 默认没有桌面应用干扰跑 Agent 这种需要长期占用的进程更稳。环境隔离方便。配合 Docker能把 OpenClaw 的运行时、配置目录、日志全部隔离在容器里宿主机只暴露数据和端口。后台服务好管理。Ubuntu 自带 systemd一条命令就能让 OpenClaw 开机自启、崩溃自动拉起。远程管理成熟。SSH 过去一个 tmux 窗口就能随时查看对话界面和日志。尤其当你打算把 OpenClaw 部署在服务器上常驻运行时Ubuntu 的这套运维链路比桌面系统顺手太多。1.3 先定部署形态本地二进制、Docker 还是源码构建很多人上来就执行安装脚本装完能用就完事。但我的建议是动手前先花两分钟想清楚自己属于哪种情况因为不同安装方式对应的升级路径、隔离程度和排查难度完全不一样。安装方式适合场景优点需要注意的点一键脚本安装绝大多数用户想快速体验命令少、安装快、自动处理依赖环境变更不直观升级靠重跑脚本Docker 容器化服务器常驻、多环境隔离环境隔离干净、升级回滚方便需要熟悉 Docker 基本操作目录挂载要对Git 源码构建开发者、想尝试 main 分支新特性代码可控、方便二次开发需要 Node.js/pnpm 环境构建体积大如果你只是想在本地试玩选一键脚本就好。如果你和我一样准备把它当服务部署在云服务器上长期跑建议直接上 Docker。如果你对最新功能好奇或者打算给 OpenClaw 贡献代码、写自己的技能插件那就老老实实走源码构建。2. 安装前的环境准备与依赖检查2.1 硬件和系统版本要求OpenClaw 本身是一个控制框架真正的算力消耗来自你接入的大模型后端。如果你接的是云端 API比如 DeepSeek、OpenAI 等那么 2 核 4G 内存的机器跑它绰绰有余如果接的是本地 Ollama 之类的大模型那内存和 GPU 就看模型规模了。系统层面建议 Ubuntu 20.04 LTS 或更新的版本。装之前先确认一下环境cat /etc/os-release uname -m free -h df -h /x86_64 架构是最省心的主流教程和依赖包基本都优先支持。ARM64 也能跑但个别本地依赖需要额外编译新手不建议自己制造难度。磁盘剩余空间至少留 5GBOpenClaw 本体不大但日志、模型缓存、技能依赖会慢慢涨。2.2 先把基础依赖补齐不同安装方式对系统包的要求不同但有几个基础工具是共通的。打开终端先执行一遍sudo apt update sudo apt install -y curl git unzip ca-certificates这三个是用来下载脚本、拉取仓库、解压资源包的。如果你要走源码构建还需要 Node.js 18 以上和 pnpm我一般这么装curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt install -y nodejs sudo npm install -g pnpm装完用node -v和pnpm -v确认版本。注意不要用 Ubuntu 自带 apt 源里的老版本 Node版本太低会导致 OpenClaw 启动直接报错。2.3 用普通用户跑别装完就 sudo这里想提前打个预防针。OpenClaw 默认会安装在当前用户的 home 目录下一般是~/.openclaw配置文件、技能、日志都放在里面。这个设计本身就不希望你用 root 去跑。原因很实际OpenClaw 能调用工具、读写文件如果以 root 身份运行一旦配置不当模型拿到的是整台机器的权限。普通用户安装运行天然就多了一层限制。安装系统依赖的时候用 sudo 没问题但执行 OpenClaw 安装脚本、初始化、启动服务全程用普通用户身份做。后面的所有步骤我都默认你是普通用户。3. 三种安装路径的实操记录3.1 一键脚本安装最快跑起来的方式OpenClaw 官网提供了一键安装脚本理论上你只需要一行命令curl -fsSL https://openclaw.ai/install.sh | bash脚本会检测当前系统的依赖情况自动下载 OpenClaw 的核心文件然后帮你把命令行工具配置好。整个过程快的两分钟慢的看网络情况。安装完成后执行openclaw --version能正常输出版本号说明安装成功。这时候先别急着下一步确认一下命令路径which openclaw如果提示找不到命令常见原因是安装脚本把可执行文件放到了~/.openclaw/bin下面但对应目录还没有加到 PATH 里。检查一下 shell 配置文件echo $PATH没看到~/.openclaw/bin的话在~/.bashrc末尾加一行export PATH$HOME/.openclaw/bin:$PATH然后source ~/.bashrc重新加载。3.2 源码方式让安装脚本从 GitHub main 分支检出 OpenClaw如果你关注 OpenClaw 的新特性想在发布正式版之前就用上最新的改动那源码安装是更合适的选择。OpenClaw 的安装脚本本身支持指定 git 安装方式从 GitHub 的 main 分支直接检出源码进行构建。用环境变量的方式export OPENCLAW_INSTALL_METHODgit curl -fsSL https://openclaw.ai/install.sh | bash也可以先克隆仓库再手动构建。我习惯这样操作mkdir -p ~/projects cd ~/projects git clone https://github.com/openclawcat/openclaw.git cd openclaw pnpm install pnpm build手动构建的好处是每一步都看得见哪一个环节依赖装不上、哪一个包有兼容问题都清清楚楚。缺点是时间确实比一键脚本长而且对网络要求更高。从 main 分支检出的版本属于“最新代码”新功能确实第一时间能用上但偶尔也会撞上还没来得及修的 bug。我的建议是尝鲜可以但如果 OpenClaw 对你来说是要稳定用的工具等一等正式 release 版本更稳妥。如果你在 main 分支上发现问题可以去项目 issue 区搜一下很可能别人已经报了也很有可能官方在下一版就修了。3.3 Docker 方式环境隔离适合服务化如果你和我一样准备把 OpenClaw 长期部署在云服务器上Docker 是很推荐的方案。它能帮你把 OpenClaw 运行时和宿主机的其他程序隔离开升级和回滚也变成拉镜像、换容器这么简单。Ubuntu 上安装 Docker 最简单的方式是直接用系统自带的 docker.io 包sudo apt update sudo apt install -y docker.io sudo systemctl enable --now docker然后把当前用户加入 docker 组避免每条命令都写 sudosudo usermod -aG docker $USER执行完记得退出 SSH 重连一次让用户组权限生效。用docker --version确认安装结果。拉取镜像时OpenClaw 官方镜像的名称和标签建议以官网文档或 Docker Hub 上 OpenClaw 项目页为准。运行容器的基本思路是这样的docker run -it --name openclaw \ -v ~/.openclaw:/data \ openclaw 镜像名称:标签重点说一下目录挂载-v ~/.openclaw:/data表示把宿主机的~/.openclaw目录映射到容器内的/data。OpenClaw 的配置、技能、日志都在这个目录里映射出去之后以后升级容器、重建容器数据都还在。这一步做错了容器一删配置全没这个坑我踩过。3.4 初始化配置目录与项目三种安装方式装完之后下一步都是初始化。运行openclaw init这个命令会在当前用户的 home 目录下创建 OpenClaw 的配置目录默认是~/.openclaw。里面大致有这么几个部分路径用途~/.openclaw/config.yaml主配置文件模型、权限、工具开关都在这~/.openclaw/skills技能目录放各种扩展能力~/.openclaw/logs运行日志~/.openclaw/data会话记录、记忆数据初始化完成后我建议先打开config.yaml看一眼不用急着改但要知道每个区块大概是干嘛的。后面配置模型的时候经常要回到这个文件里加内容。4. 把模型接进来后端配置与切换4.1 OpenClaw 的模型接入逻辑OpenClaw 本身不包含大模型它更像一个遥控器需要你给它配一个信号源。这个信号源可以是你自己的云端 API Key也可以是你内网里用 Ollama 跑起来的本地模型。接入方式统一走“provider”的概念。一个 provider 就是一类模型服务的连接配置里面包括接口地址、API Key、可用模型列表。OpenClaw 启动时读取这些配置你选择用哪个模型它就调用哪个 provider 的接口。所以部署 OpenClaw 只完成了一半把模型配置好整个链路才能真正跑通。4.2 以 Ollama 为例配置本地模型如果你想完全免费、数据不出本机地跑 OpenClaw那本地模型是最合适的方案。Ollama 是目前最省心的本地模型运行工具安装也很简洁curl -fsSL https://ollama.com/install.sh | sh装完之后拉一个模型比如 Qwen 系列ollama pull qwen2.5:7b然后在 OpenClaw 的配置文件~/.openclaw/config.yaml里增加一个 providerproviders: - name: ollama base_url: http://localhost:11434/v1 api_key: ollama models: - qwen2.5:7b这里有个细节本地 Ollama 服务不需要真实的 API Key所以api_key填什么都能用我一般统一填ollama占位。base_url指向的是 Ollama 默认监听的端口如果你的 Ollama 跑在其他机器上这里改成对应地址即可。4.3 云端 API 的配置样例没有本地显卡、不想折腾模型文件的话接云端 API 是更省事的选择。以 DeepSeek 为例providers: - name: deepseek base_url: https://api.deepseek.com/v1 api_key: sk-你的密钥 models: - deepseek-chatOpenAI 系的配置结构也大同小异把base_url和api_key换成你自己的服务商信息即可。很多兼容 OpenAI 协议的网关服务也都是这么配的。关于密钥我强烈建议用环境变量传递而不是明文写在配置文件里尤其是配置目录有被同步到 git 仓库习惯的朋友。OpenClaw 支持通过环境变量注入 API Key具体变量名可以用openclaw init --help或者直接查官方文档确认。4.4 用 ccswitch 切换当前模型配置好多个 provider 之后经常需要在不同模型之间切换。比如日常对话用便宜的快速模型处理复杂任务时切换到更强的模型。OpenClaw 提供了 ccswitch 相关能力用来切换模型后端。在 OpenClaw 的交互式对话界面里直接输入 ccswitch 命令就可以看到当前可用的 provider 和模型列表选择要切换的目标即可。不同版本的具体命令形式可能略有差异以你当前版本的/help输出为准。这个功能用起来很像遥控器换台配置好多个 provider 之后不用重启服务切模型就是一瞬间的事。多模型对比测试的时候特别有用。5. 启动、验证和后台常驻5.1 前台启动先聊一句确认链路通配置好模型之后先不要急着搞后台服务第一步是前台启动确认整条链路能走通。openclaw正常的话你会看到一个交互式界面。首次启动可能会有权限确认的提示比如“是否允许 OpenClaw 读取指定目录”按需选择就好。看到对话提示符之后随便说一句“你好”模型能正常回复说明部署和模型接入都成功了。这一步一定要耐心别嫌慢。链路不通的时候后面挂多少层服务都是白搭。5.2 用 tmux 快速常驻如果你只是临时跑一下比如远程 SSH 进去想保持对话界面不退出用一个 tmux 就够sudo apt install -y tmux tmux new -s openclaw openclaw然后按CtrlB再按D分离会话OpenClaw 就会继续在后台跑着。下次用tmux attach -t openclaw重新进入对话界面。这是最轻量的一种常驻方式缺点是服务器重启后不会自动拉起需要手动恢复。5.3 用 systemd 做成正式服务如果你想要“开机自启 崩溃重启”的正式服务体验那就用 systemd。在/etc/systemd/system/openclaw.service里写一个服务单元文件内容模板如下[Unit] DescriptionOpenClaw AI Assistant Afternetwork-online.target Wantsnetwork-online.target [Service] User你的用户名 WorkingDirectory/home/你的用户名 ExecStart/home/你的用户名/.openclaw/bin/openclaw Restarton-failure RestartSec5 EnvironmentHOME/home/你的用户名 [Install] WantedBymulti-user.targetExecStart的路径最好用which openclaw查一下实际路径再填不要照抄。写完之后sudo systemctl daemon-reload sudo systemctl enable --now openclaw查看运行状态systemctl status openclaw看到active (running)服务就起来了。以后升级 OpenClaw 只需要重装完了再重启一下服务不需要关心进程是怎么拉起来的。5.4 查看日志与安全注意用 systemd 托管的好处之一是日志统一管理journalctl -u openclaw -f日志是排查问题最重要的线索报错的时候先翻日志比盲目改配置有效率得多。安全方面再说两句。OpenClaw 这类 Agent 框架本质上是把“执行权”交给了模型模型行为的不确定性决定了你必须在权限上做限制。我实际部署后的做法是始终用非 root 用户运行。在配置里严格控制允许读写的工作目录不要让模型可以无边界访问文件系统。涉及 CAU Computer控制电脑桌面的能力时先在虚拟机或隔离环境里测试确认行为可控再放到生产环境。6. 常见问题与排查技巧实录6.1 安装脚本中断、超时的处理一键脚本安装最常见的失败原因是下载中断具体表现为脚本执行到一半卡住或者提示 curl 拉取失败。这种情况没有特别取巧的办法基本就是检查网络连通性之后重试。如果你执行安装脚本时习惯性地加了sudo会遇到权限相关报错。OpenClaw 安装脚本默认写入当前用户的 home 目录不需要 root 权限。用普通用户重跑一次即可。如果系统提示Node.js version is too low说明 OpenClaw 要求的 Node 版本高于系统自带版本。去 NodeSource 装一个新版 Node再重跑安装脚本。6.2 启动时报错与模型连接失败OpenClaw 启动时报错先确认是不是端口被占用。如果使用本地模型或网关检查对应端口是否被其他进程占用用ss -lntp看一眼监听状态。模型连接失败是最常见的问题。如果报 401 或认证失败大概率是 API Key 没生效。检查配置文件写对没有环境变量有没有覆盖配置文件里的值API Key 本身有没有过期。如果报 404 或 model not found那就是模型名写错了。去你的 provider 服务商页面确认可用的模型标识符OpenAI 系的模型名和 DeepSeek 系的模型名格式不一样直接从网页控制台复制才是最靠谱的。6.3 OpenClaw 升级与卸载升级 OpenClaw 最简单的方式是重新执行一次安装脚本。它会检测到已有安装自动覆盖更新。升级后记得让服务重启一下sudo systemctl restart openclaw源码方式升级则回到仓库目录执行git pull后重新构建git pull pnpm install pnpm build卸载 OpenClaw安装脚本通常带有卸载参数。具体以你当前版本的--help输出为准有的版本需要传--uninstall有的版本直接删目录就行。如果你当初没有用到系统目录那么手动清理也就是删除~/.openclaw和可执行文件的事。需要提醒的是卸载前先备份~/.openclaw里的config.yaml和数据目录以免误删重要配置。6.4 关于 CAU Computer 的设置建议有朋友私信问过 OpenClaw 的 CAU Computer 怎么设置这里一并说一下。CAU 的全称是 Computer Agent Unit是 OpenClaw 里让模型“动手操作电脑”的模块相当于给模型装了手脚它可以在授权范围内操作文件、运行命令、控制应用。这类能力非常强大也正因如此配置时需要额外谨慎。设置入口在配置文件的 CAU 相关配置段里首次启用时建议把工作目录限制在一个专门的空目录里比如~/openclaw-cau-workspace不要让模型拥有对整个 home 目录的写权限。在正式环境里我对 CAU Computer 的态度是默认关闭需要时再开用完就关。模型操作电脑这件事识别能力和判断能力都还在快速进化中给它的权限越小你晚上睡得越香。一点个人体会部署 OpenClaw 的本质不是跑通一个安装命令而是搭建一套“模型 工具 权限”的完整 Agent 环境。我在实际部署中体会最深的一件事是安全边界一定要在一开始就定好不要等出了问题再补。OpenClaw 的能力上限很高但使用边界完全取决于你的配置习惯。最后再分享一个小技巧如果你打算长期使用 OpenClaw建议把整个~/.openclaw目录纳入备份计划里配置、技能、对话记忆都在这里面。这样无论是迁移机器还是重装系统恢复环境都只是拷贝目录再重装一次本体的事能省掉很多重新配置的重复劳动。
OpenClaw 在 Ubuntu 上的完整部署指南：从安装到常驻服务
我一开始是在 Ubuntu 服务器上试着跑 OpenClaw 的当时的想法很简单既然它主打“通用 AI 助理框架”那与其在 Windows 上折腾各种路径和防火墙不如直接放到 Linux 环境里用终端和 systemd 把它当正经服务养起来。结果一路踩下来发现安装部署这件事看着简单实际还是有不少门道——从一键脚本到源码构建再到 Docker 容器化和模型后端配置每一步都有取舍。这篇文章就是一份完整的 Ubuntu 部署实录。我会把 OpenClaw 是什么、为什么值得装在 Ubuntu 上、三种安装方式怎么做、模型怎么接、服务怎么常驻、遇到问题怎么排查全部讲清楚。如果你手里有一台 Ubuntu 机器想自己动手把 AI 助理跑起来这篇文章可以直接当操作手册用。1. 理解 OpenClaw 与部署形态选型1.1 一句话认识 OpenClawOpenClaw 是一个开源的个人 AI 助理框架它脱胎于之前的“妙想”项目开源后以 OpenClaw 的名字对外发布。和网页版聊天机器人最大的区别是OpenClaw 不是跑在别人服务器上的一个对话框而是装在你自己机器上的一个 Agent 运行时。它运行在终端里能做的事情远不止“聊天”。模型可以通过它读写本地文件、执行命令、调用外部工具甚至按你的授权操作浏览器和电脑桌面。这种“模型 工具调用”的组合是它和普通聊天界面之间的本质区别。部署 OpenClaw本质上是在自己机器上搭建一个能被模型安全调用的 Agent 环境。1.2 为什么 Ubuntu 是合适的部署平台OpenClaw 支持多平台但如果要做正经部署我建议选 Ubuntu。原因很朴素系统干净。Ubuntu Server 默认没有桌面应用干扰跑 Agent 这种需要长期占用的进程更稳。环境隔离方便。配合 Docker能把 OpenClaw 的运行时、配置目录、日志全部隔离在容器里宿主机只暴露数据和端口。后台服务好管理。Ubuntu 自带 systemd一条命令就能让 OpenClaw 开机自启、崩溃自动拉起。远程管理成熟。SSH 过去一个 tmux 窗口就能随时查看对话界面和日志。尤其当你打算把 OpenClaw 部署在服务器上常驻运行时Ubuntu 的这套运维链路比桌面系统顺手太多。1.3 先定部署形态本地二进制、Docker 还是源码构建很多人上来就执行安装脚本装完能用就完事。但我的建议是动手前先花两分钟想清楚自己属于哪种情况因为不同安装方式对应的升级路径、隔离程度和排查难度完全不一样。安装方式适合场景优点需要注意的点一键脚本安装绝大多数用户想快速体验命令少、安装快、自动处理依赖环境变更不直观升级靠重跑脚本Docker 容器化服务器常驻、多环境隔离环境隔离干净、升级回滚方便需要熟悉 Docker 基本操作目录挂载要对Git 源码构建开发者、想尝试 main 分支新特性代码可控、方便二次开发需要 Node.js/pnpm 环境构建体积大如果你只是想在本地试玩选一键脚本就好。如果你和我一样准备把它当服务部署在云服务器上长期跑建议直接上 Docker。如果你对最新功能好奇或者打算给 OpenClaw 贡献代码、写自己的技能插件那就老老实实走源码构建。2. 安装前的环境准备与依赖检查2.1 硬件和系统版本要求OpenClaw 本身是一个控制框架真正的算力消耗来自你接入的大模型后端。如果你接的是云端 API比如 DeepSeek、OpenAI 等那么 2 核 4G 内存的机器跑它绰绰有余如果接的是本地 Ollama 之类的大模型那内存和 GPU 就看模型规模了。系统层面建议 Ubuntu 20.04 LTS 或更新的版本。装之前先确认一下环境cat /etc/os-release uname -m free -h df -h /x86_64 架构是最省心的主流教程和依赖包基本都优先支持。ARM64 也能跑但个别本地依赖需要额外编译新手不建议自己制造难度。磁盘剩余空间至少留 5GBOpenClaw 本体不大但日志、模型缓存、技能依赖会慢慢涨。2.2 先把基础依赖补齐不同安装方式对系统包的要求不同但有几个基础工具是共通的。打开终端先执行一遍sudo apt update sudo apt install -y curl git unzip ca-certificates这三个是用来下载脚本、拉取仓库、解压资源包的。如果你要走源码构建还需要 Node.js 18 以上和 pnpm我一般这么装curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt install -y nodejs sudo npm install -g pnpm装完用node -v和pnpm -v确认版本。注意不要用 Ubuntu 自带 apt 源里的老版本 Node版本太低会导致 OpenClaw 启动直接报错。2.3 用普通用户跑别装完就 sudo这里想提前打个预防针。OpenClaw 默认会安装在当前用户的 home 目录下一般是~/.openclaw配置文件、技能、日志都放在里面。这个设计本身就不希望你用 root 去跑。原因很实际OpenClaw 能调用工具、读写文件如果以 root 身份运行一旦配置不当模型拿到的是整台机器的权限。普通用户安装运行天然就多了一层限制。安装系统依赖的时候用 sudo 没问题但执行 OpenClaw 安装脚本、初始化、启动服务全程用普通用户身份做。后面的所有步骤我都默认你是普通用户。3. 三种安装路径的实操记录3.1 一键脚本安装最快跑起来的方式OpenClaw 官网提供了一键安装脚本理论上你只需要一行命令curl -fsSL https://openclaw.ai/install.sh | bash脚本会检测当前系统的依赖情况自动下载 OpenClaw 的核心文件然后帮你把命令行工具配置好。整个过程快的两分钟慢的看网络情况。安装完成后执行openclaw --version能正常输出版本号说明安装成功。这时候先别急着下一步确认一下命令路径which openclaw如果提示找不到命令常见原因是安装脚本把可执行文件放到了~/.openclaw/bin下面但对应目录还没有加到 PATH 里。检查一下 shell 配置文件echo $PATH没看到~/.openclaw/bin的话在~/.bashrc末尾加一行export PATH$HOME/.openclaw/bin:$PATH然后source ~/.bashrc重新加载。3.2 源码方式让安装脚本从 GitHub main 分支检出 OpenClaw如果你关注 OpenClaw 的新特性想在发布正式版之前就用上最新的改动那源码安装是更合适的选择。OpenClaw 的安装脚本本身支持指定 git 安装方式从 GitHub 的 main 分支直接检出源码进行构建。用环境变量的方式export OPENCLAW_INSTALL_METHODgit curl -fsSL https://openclaw.ai/install.sh | bash也可以先克隆仓库再手动构建。我习惯这样操作mkdir -p ~/projects cd ~/projects git clone https://github.com/openclawcat/openclaw.git cd openclaw pnpm install pnpm build手动构建的好处是每一步都看得见哪一个环节依赖装不上、哪一个包有兼容问题都清清楚楚。缺点是时间确实比一键脚本长而且对网络要求更高。从 main 分支检出的版本属于“最新代码”新功能确实第一时间能用上但偶尔也会撞上还没来得及修的 bug。我的建议是尝鲜可以但如果 OpenClaw 对你来说是要稳定用的工具等一等正式 release 版本更稳妥。如果你在 main 分支上发现问题可以去项目 issue 区搜一下很可能别人已经报了也很有可能官方在下一版就修了。3.3 Docker 方式环境隔离适合服务化如果你和我一样准备把 OpenClaw 长期部署在云服务器上Docker 是很推荐的方案。它能帮你把 OpenClaw 运行时和宿主机的其他程序隔离开升级和回滚也变成拉镜像、换容器这么简单。Ubuntu 上安装 Docker 最简单的方式是直接用系统自带的 docker.io 包sudo apt update sudo apt install -y docker.io sudo systemctl enable --now docker然后把当前用户加入 docker 组避免每条命令都写 sudosudo usermod -aG docker $USER执行完记得退出 SSH 重连一次让用户组权限生效。用docker --version确认安装结果。拉取镜像时OpenClaw 官方镜像的名称和标签建议以官网文档或 Docker Hub 上 OpenClaw 项目页为准。运行容器的基本思路是这样的docker run -it --name openclaw \ -v ~/.openclaw:/data \ openclaw 镜像名称:标签重点说一下目录挂载-v ~/.openclaw:/data表示把宿主机的~/.openclaw目录映射到容器内的/data。OpenClaw 的配置、技能、日志都在这个目录里映射出去之后以后升级容器、重建容器数据都还在。这一步做错了容器一删配置全没这个坑我踩过。3.4 初始化配置目录与项目三种安装方式装完之后下一步都是初始化。运行openclaw init这个命令会在当前用户的 home 目录下创建 OpenClaw 的配置目录默认是~/.openclaw。里面大致有这么几个部分路径用途~/.openclaw/config.yaml主配置文件模型、权限、工具开关都在这~/.openclaw/skills技能目录放各种扩展能力~/.openclaw/logs运行日志~/.openclaw/data会话记录、记忆数据初始化完成后我建议先打开config.yaml看一眼不用急着改但要知道每个区块大概是干嘛的。后面配置模型的时候经常要回到这个文件里加内容。4. 把模型接进来后端配置与切换4.1 OpenClaw 的模型接入逻辑OpenClaw 本身不包含大模型它更像一个遥控器需要你给它配一个信号源。这个信号源可以是你自己的云端 API Key也可以是你内网里用 Ollama 跑起来的本地模型。接入方式统一走“provider”的概念。一个 provider 就是一类模型服务的连接配置里面包括接口地址、API Key、可用模型列表。OpenClaw 启动时读取这些配置你选择用哪个模型它就调用哪个 provider 的接口。所以部署 OpenClaw 只完成了一半把模型配置好整个链路才能真正跑通。4.2 以 Ollama 为例配置本地模型如果你想完全免费、数据不出本机地跑 OpenClaw那本地模型是最合适的方案。Ollama 是目前最省心的本地模型运行工具安装也很简洁curl -fsSL https://ollama.com/install.sh | sh装完之后拉一个模型比如 Qwen 系列ollama pull qwen2.5:7b然后在 OpenClaw 的配置文件~/.openclaw/config.yaml里增加一个 providerproviders: - name: ollama base_url: http://localhost:11434/v1 api_key: ollama models: - qwen2.5:7b这里有个细节本地 Ollama 服务不需要真实的 API Key所以api_key填什么都能用我一般统一填ollama占位。base_url指向的是 Ollama 默认监听的端口如果你的 Ollama 跑在其他机器上这里改成对应地址即可。4.3 云端 API 的配置样例没有本地显卡、不想折腾模型文件的话接云端 API 是更省事的选择。以 DeepSeek 为例providers: - name: deepseek base_url: https://api.deepseek.com/v1 api_key: sk-你的密钥 models: - deepseek-chatOpenAI 系的配置结构也大同小异把base_url和api_key换成你自己的服务商信息即可。很多兼容 OpenAI 协议的网关服务也都是这么配的。关于密钥我强烈建议用环境变量传递而不是明文写在配置文件里尤其是配置目录有被同步到 git 仓库习惯的朋友。OpenClaw 支持通过环境变量注入 API Key具体变量名可以用openclaw init --help或者直接查官方文档确认。4.4 用 ccswitch 切换当前模型配置好多个 provider 之后经常需要在不同模型之间切换。比如日常对话用便宜的快速模型处理复杂任务时切换到更强的模型。OpenClaw 提供了 ccswitch 相关能力用来切换模型后端。在 OpenClaw 的交互式对话界面里直接输入 ccswitch 命令就可以看到当前可用的 provider 和模型列表选择要切换的目标即可。不同版本的具体命令形式可能略有差异以你当前版本的/help输出为准。这个功能用起来很像遥控器换台配置好多个 provider 之后不用重启服务切模型就是一瞬间的事。多模型对比测试的时候特别有用。5. 启动、验证和后台常驻5.1 前台启动先聊一句确认链路通配置好模型之后先不要急着搞后台服务第一步是前台启动确认整条链路能走通。openclaw正常的话你会看到一个交互式界面。首次启动可能会有权限确认的提示比如“是否允许 OpenClaw 读取指定目录”按需选择就好。看到对话提示符之后随便说一句“你好”模型能正常回复说明部署和模型接入都成功了。这一步一定要耐心别嫌慢。链路不通的时候后面挂多少层服务都是白搭。5.2 用 tmux 快速常驻如果你只是临时跑一下比如远程 SSH 进去想保持对话界面不退出用一个 tmux 就够sudo apt install -y tmux tmux new -s openclaw openclaw然后按CtrlB再按D分离会话OpenClaw 就会继续在后台跑着。下次用tmux attach -t openclaw重新进入对话界面。这是最轻量的一种常驻方式缺点是服务器重启后不会自动拉起需要手动恢复。5.3 用 systemd 做成正式服务如果你想要“开机自启 崩溃重启”的正式服务体验那就用 systemd。在/etc/systemd/system/openclaw.service里写一个服务单元文件内容模板如下[Unit] DescriptionOpenClaw AI Assistant Afternetwork-online.target Wantsnetwork-online.target [Service] User你的用户名 WorkingDirectory/home/你的用户名 ExecStart/home/你的用户名/.openclaw/bin/openclaw Restarton-failure RestartSec5 EnvironmentHOME/home/你的用户名 [Install] WantedBymulti-user.targetExecStart的路径最好用which openclaw查一下实际路径再填不要照抄。写完之后sudo systemctl daemon-reload sudo systemctl enable --now openclaw查看运行状态systemctl status openclaw看到active (running)服务就起来了。以后升级 OpenClaw 只需要重装完了再重启一下服务不需要关心进程是怎么拉起来的。5.4 查看日志与安全注意用 systemd 托管的好处之一是日志统一管理journalctl -u openclaw -f日志是排查问题最重要的线索报错的时候先翻日志比盲目改配置有效率得多。安全方面再说两句。OpenClaw 这类 Agent 框架本质上是把“执行权”交给了模型模型行为的不确定性决定了你必须在权限上做限制。我实际部署后的做法是始终用非 root 用户运行。在配置里严格控制允许读写的工作目录不要让模型可以无边界访问文件系统。涉及 CAU Computer控制电脑桌面的能力时先在虚拟机或隔离环境里测试确认行为可控再放到生产环境。6. 常见问题与排查技巧实录6.1 安装脚本中断、超时的处理一键脚本安装最常见的失败原因是下载中断具体表现为脚本执行到一半卡住或者提示 curl 拉取失败。这种情况没有特别取巧的办法基本就是检查网络连通性之后重试。如果你执行安装脚本时习惯性地加了sudo会遇到权限相关报错。OpenClaw 安装脚本默认写入当前用户的 home 目录不需要 root 权限。用普通用户重跑一次即可。如果系统提示Node.js version is too low说明 OpenClaw 要求的 Node 版本高于系统自带版本。去 NodeSource 装一个新版 Node再重跑安装脚本。6.2 启动时报错与模型连接失败OpenClaw 启动时报错先确认是不是端口被占用。如果使用本地模型或网关检查对应端口是否被其他进程占用用ss -lntp看一眼监听状态。模型连接失败是最常见的问题。如果报 401 或认证失败大概率是 API Key 没生效。检查配置文件写对没有环境变量有没有覆盖配置文件里的值API Key 本身有没有过期。如果报 404 或 model not found那就是模型名写错了。去你的 provider 服务商页面确认可用的模型标识符OpenAI 系的模型名和 DeepSeek 系的模型名格式不一样直接从网页控制台复制才是最靠谱的。6.3 OpenClaw 升级与卸载升级 OpenClaw 最简单的方式是重新执行一次安装脚本。它会检测到已有安装自动覆盖更新。升级后记得让服务重启一下sudo systemctl restart openclaw源码方式升级则回到仓库目录执行git pull后重新构建git pull pnpm install pnpm build卸载 OpenClaw安装脚本通常带有卸载参数。具体以你当前版本的--help输出为准有的版本需要传--uninstall有的版本直接删目录就行。如果你当初没有用到系统目录那么手动清理也就是删除~/.openclaw和可执行文件的事。需要提醒的是卸载前先备份~/.openclaw里的config.yaml和数据目录以免误删重要配置。6.4 关于 CAU Computer 的设置建议有朋友私信问过 OpenClaw 的 CAU Computer 怎么设置这里一并说一下。CAU 的全称是 Computer Agent Unit是 OpenClaw 里让模型“动手操作电脑”的模块相当于给模型装了手脚它可以在授权范围内操作文件、运行命令、控制应用。这类能力非常强大也正因如此配置时需要额外谨慎。设置入口在配置文件的 CAU 相关配置段里首次启用时建议把工作目录限制在一个专门的空目录里比如~/openclaw-cau-workspace不要让模型拥有对整个 home 目录的写权限。在正式环境里我对 CAU Computer 的态度是默认关闭需要时再开用完就关。模型操作电脑这件事识别能力和判断能力都还在快速进化中给它的权限越小你晚上睡得越香。一点个人体会部署 OpenClaw 的本质不是跑通一个安装命令而是搭建一套“模型 工具 权限”的完整 Agent 环境。我在实际部署中体会最深的一件事是安全边界一定要在一开始就定好不要等出了问题再补。OpenClaw 的能力上限很高但使用边界完全取决于你的配置习惯。最后再分享一个小技巧如果你打算长期使用 OpenClaw建议把整个~/.openclaw目录纳入备份计划里配置、技能、对话记忆都在这里面。这样无论是迁移机器还是重装系统恢复环境都只是拷贝目录再重装一次本体的事能省掉很多重新配置的重复劳动。
