1. 项目概述
最近在折腾一个叫OpenClaw的开源AI助手项目,准备在Ubuntu 24系统上部署。OpenClaw是一个可扩展的AI助手框架,支持对接多种AI模型和聊天平台。相比直接使用网页版的AI服务,本地部署OpenClaw可以更好地保护隐私,还能根据需求定制功能。
作为一个长期在Linux环境下工作的开发者,我习惯把这类工具直接部署在本地服务器上。下面就把整个安装配置过程记录下来,包括一些踩坑经验和优化技巧。
2. 环境准备
2.1 系统要求
OpenClaw对系统要求不高,但建议使用较新的Ubuntu LTS版本(20.04/22.04/24.04)。我选择Ubuntu 24.04是因为它提供了最新的Node.js软件包,能更好地兼容OpenClaw的依赖。
提示:虽然可以在其他Linux发行版上安装,但官方文档主要针对Ubuntu/Debian系做了优化,使用这些系统能减少兼容性问题。
2.2 Node.js安装
OpenClaw基于Node.js开发,所以需要先安装Node环境。这里有个重要注意事项:
警告:不要使用nvm等版本管理工具安装Node.js!因为OpenClaw需要以系统服务方式运行,nvm安装的Node环境可能导致服务启动失败。
正确的安装步骤如下:
bash复制# 安装curl工具(如果尚未安装)
sudo apt install curl -y
# 添加NodeSource仓库(使用Node.js 22.x LTS版本)
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
# 安装Node.js和npm
sudo apt install -y nodejs
安装完成后验证版本:
bash复制node -v # 应该显示v22.x.x
npm -v # 应该显示10.x.x
2.3 配置npm镜像
国内直接使用npm官方源速度很慢,建议切换为淘宝镜像:
bash复制npm config set registry https://registry.npmmirror.com
npm config get registry # 验证是否设置成功
如果需要管理多个镜像源,可以安装nrm工具:
bash复制sudo npm install -g nrm
nrm ls # 列出可用镜像源
nrm use taobao # 切换到淘宝镜像
2.4 Git安装
虽然OpenClaw可以通过npm直接安装,但Git在某些情况下还是需要的:
bash复制sudo apt update
sudo apt install git -y
git --version # 验证安装
3. OpenClaw安装与配置
3.1 全局安装OpenClaw
bash复制sudo npm install -g openclaw
openclaw --version # 验证安装
注意:必须使用-g参数全局安装,否则后续服务注册会失败。
3.2 初始化向导配置
运行初始化向导:
bash复制openclaw onboard --install-daemon
关键参数说明:
--install-daemon:将OpenClaw注册为系统服务,开机自动启动(强烈推荐)
3.2.1 安装模式选择
code复制How would you like to set up OpenClaw?
> Quick start (recommended)
Advanced
直接回车选择"Quick start",这会自动处理大多数配置,适合初次使用者。
3.2.2 AI提供商选择
code复制Which AI provider do you want to use?
> Anthropic (Claude) — recommended
OpenAI (ChatGPT)
Custom provider
由于国内无法直接使用Anthropic和OpenAI,我们需要选择"Custom provider",然后手动配置:
baseUrl:填写你的AI服务API地址(如国内代理的OpenAI兼容接口)apiKey:填写对应的API密钥models:填写可用的模型名称列表
3.2.3 聊天平台连接
可以选择跳过此步骤,后续再配置。支持的平台包括飞书、Slack等。
3.2.4 推荐技能安装
code复制Install recommended skills?
> Yes (recommended)
No
建议选择"Yes",这些预设技能能快速体验OpenClaw的核心功能。
3.3 局域网访问配置
默认情况下,OpenClaw的Web界面(18789端口)只能在本机访问。要通过局域网其他设备访问,可以使用SSH隧道:
bash复制ssh -N -L 18789:127.0.0.1:18789 用户名@OpenClaw服务器IP
然后在浏览器访问:
code复制http://127.0.0.1:18789#token=你的token
技巧:如果想直接通过IP访问,可以修改OpenClaw配置文件中的
host参数为0.0.0.0,但这样会降低安全性。
4. 模型管理
4.1 查看已配置模型
bash复制openclaw models list
4.2 添加自定义模型
可以通过命令添加:
bash复制openclaw config set 'models.providers.custom-openai' --json '{
"baseUrl": "https://你的API地址/v1",
"apiKey": "你的API密钥",
"api": "openai-responses",
"models": [
{
"id": "gpt-5.2",
"name": "gpt-5.2"
}
]
}'
或者直接编辑配置文件:
bash复制sudo vim ~/.openclaw/openclaw.json
4.3 设置默认模型
bash复制openclaw models set custom-openai/gpt-5.2
4.4 调整模型参数
编辑配置文件修改token限制:
json复制"contextWindow": 32768,
"maxTokens": 8192
注意:修改后需要重启服务生效:
bash复制sudo systemctl restart openclaw
5. 常见问题与优化
5.1 服务启动失败排查
如果OpenClaw服务无法启动,可以检查日志:
bash复制journalctl -u openclaw -f
常见问题:
- Node.js路径错误 → 确认使用系统安装的Node.js而非nvm版本
- 端口冲突 → 检查18789端口是否被占用
- 权限问题 → 确保配置文件(~/.openclaw)有正确权限
5.2 性能优化建议
-
增加Node.js内存限制:
bash复制sudo systemctl edit openclaw添加:
code复制[Service] Environment="NODE_OPTIONS=--max-old-space-size=4096" -
启用gzip压缩:
修改配置文件中:json复制"server": { "compression": true }
5.3 安全加固措施
-
修改默认token:
bash复制openclaw config set server.token "你的强密码" -
启用HTTPS:
bash复制openclaw config set server.ssl --json '{ "enabled": true, "key": "/path/to/key.pem", "cert": "/path/to/cert.pem" }'
6. 进阶使用技巧
6.1 插件开发
OpenClaw支持自定义插件,开发步骤:
-
创建插件目录:
bash复制mkdir -p ~/.openclaw/plugins/my-plugin cd ~/.openclaw/plugins/my-plugin npm init -y -
编写插件代码(参考官方文档)
-
启用插件:
bash复制openclaw plugins enable my-plugin
6.2 备份与迁移
重要配置文件位置:
~/.openclaw/openclaw.json:主配置文件/etc/systemd/system/openclaw.service:服务文件
建议定期备份这些文件。
迁移到新服务器时:
- 安装相同版本的Node.js和OpenClaw
- 复制上述配置文件
- 恢复插件和数据
6.3 监控与日志
查看实时日志:
bash复制journalctl -u openclaw -f
性能监控:
bash复制openclaw status # 查看资源使用情况
设置日志轮转:
bash复制sudo vim /etc/logrotate.d/openclaw
添加:
code复制/var/log/openclaw.log {
daily
missingok
rotate 7
compress
delaycompress
notifempty
create 640 openclaw openclaw
sharedscripts
postrotate
systemctl restart openclaw
endscript
}
我在实际使用中发现,OpenClaw的稳定性很大程度上取决于Node.js版本和系统资源分配。建议在正式环境中部署时,使用PM2等进程管理工具来增强可靠性。另外,定期检查官方GitHub仓库的更新,及时获取安全补丁和新功能。