【手把手教】本地部署OpenClaw安装、配置、使用
本文详细介绍了OpenClaw的本地部署方式,包括两种安装方法:通过npm安装和脚本命令行安装。重点说明了Node.js版本要求、安装步骤、常见问题解决方案(如Git Key配置、网络问题等),并提供了完整的配置流程指引。此外还介绍了Web界面配置、Nginx反向代理、Docker部署方案以及日常维护命令,涵盖了从安装到运维的全流程操作指南。
一、本地部署方式
官网地址: https://github.com/openclaw/openclaw
(一)第一种安装方式
1.安装npm
首先,安装Nodejs版本22.0以上,如果是Linux CentOS版本要求CentOS Stream 9。
千万不要用CentOS7低版本系统中运行,会无法安装。
(1)以下是在CentOS Stream 9系统安装
# CentOS8、ubuntu22等系统用高版本的
wget https://nodejs.org/dist/v24.13.0/node-v24.13.0-linux-x64.tar.xz
# 解压缩
tar -xf node-v24.13.0-linux-x64.tar.xz
# 把这个解压缩的文件放到用户目录/usr/local
mv node-v24.13.0-linux-x64 /usr/local/node
# 配置软连接方便进行全局调用
sudo ln -s /usr/local/node/bin/node /usr/bin/node
sudo ln -s /usr/local/node/bin/npm /usr/bin/npm
2.安装openclaw
# 执行安装
npm install -g openclaw@latest
# 配置软连接
sudo ln -s /usr/local/node/bin/openclaw /usr/bin/openclaw
# 查看是否安装成功
openclaw --help
出现以下说明安装成功

(二)第2种安装方式
1.使用脚本命令行安装
curl -fsSL https://openclaw.ai/install.sh | bash
OpenClaw 大龙虾官网https://docs.openclaw.ai/start/getting-started
这种安装方式,中间会出现很多失败可能性。
一些解决方案:
# 输出安装所有日志,便于解决报错
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh \
| CLAWDBOT_NPM_LOGLEVEL=verbose bash -s -- --verbose
# 将报错信息丢给Gemini分析
## 常见原因
### Git Key 问题
#### 日志中出现:git@github.com、Permission denied (publickey)、npm ERR! code 128
##### 根本原因:npm 表面失败,但根因在 git clone 私有仓库访问权限,所以要配置Git SSH Key 已配置看看有没有配置错误
##### 解决步骤
1. 检查 SSH Key 配置
# 查看现有 SSH Key
ls -la ~/.ssh
# 测试能否连接GitHub
ssh -T git@github.com
2. 生成或配置 SSH Key
如果还没有SSH Key:
# 生成新的 SSH Key
ssh-keygen -t ed260310 -C "your_email@example.com"
# 将公钥添加到 GitHub
cat ~/.ssh/id_ed260310.pub
3. 将公钥添加到 GitHub
复制公钥内容
GitHub → Settings → SSH and GPG keys → New SSH key
粘贴刚复制公钥并保存
### 其他常见问题
#### 1. 网络问题
# 配置 npm 镜像
npm config set registry https://registry.npmmirror.com
####2. Node 版本不兼容
# 检查 Node 版本
node -v
### 推荐使用 nvm 管理 Node 版本
nvm install 24
nvm use 24
2.运行指引并安装守护进程
(1)手动配置
OpenClaw与常见的应用模板一样,官方提供了若干,需要用户自行手动配置的步骤,在首次登入服务器后,输入并回车运行如下命令开始配置:
openclaw onboard --install-daemon
运行上面的命令后,出现同意免责声明,是否知晓风险,选择Yes就行。
(2)配置模式选择:快速入门 QuickStart
选择Onboarding的模式。
第一个,是快速启动(后续通过 openclaw configure 命令来配置信息)
第二个,是先手动配置。
我们选择QuickStart。
(3)模型配置
接下来会让你配置AI大模型。
千问、火山引擎、很多人说智谱的GLM4.7比较好,但过于太火爆了,还买不到。
我目前用的是字节火山引擎。
OpenClaw configure
火山引擎查看Model ID/接入点 ID

https://console.volcengine.com/ark/region:ark+cn-beijing/endpoint
火山引擎模型为例子:
【Base URL】
各接口类型对应的 Base URL。
- 数据面 API:https://ark.cn-beijing.volces.com/api/v3
- 管控面 API:https://ark.cn-beijing.volcengineapi.com/
https://www.volcengine.com/docs/82379/1298459?lang=zh
【API Key】
https://console.volcengine.com/ark/region:ark+cn-beijing/apiKey?apikey=%7B%7D
【Model ID/接入点 ID】
https://console.volcengine.com/ark/region:ark+cn-beijing/endpoint?config=%7B%7D

(4)选择频道
选择聊天频道,即IM 即时通讯方式。
选项都是海外的IM,我们先用不了,所以选择最后一个,直接跳过。
(5)配置Skills
配置技能,选YES
依赖Homebrew也选Yes装上。
然后会让你选择用什么管理器安装,一般选用npm,其实前面已安装过了。
再然后,会给你一堆Skills:直接跳过吧,后续跟它对话也能装。
(6)配置Hooks
继续下一步,会问你要不要配置hooks。
可以理解为三个插件:
- boot-md:
启动时自动加载一段markdown文本当默认引导内容。常用于把你的规则、偏好、项目背景在每次启动时塞进去。
- command-logger:
把你在Clawdbot里执行过的命令和关键操作记一份日志,方便排查问题和复盘。如果你比较在意隐私或不想留痕,就别开它。
- session-memory:
保存会话相关的状态或记忆,让它下次能延续上下文,体验会更连贯。
建议都开,都非常实用。
(7)选择交互方式
用什么方式孵化你的机器人?
- 命令行方式(推荐)
- web界面方式
- 稍后选择
肯定有图形化界面最好了!
这个新手选web界面方式吧。
除非你是老程序员,才会用命令行界面方式交互。
4.配置web界面
如果是用ubuntu系统安装的,不一定能打开网页界面。
它只能本地http ://127.0.0.1:18789进行访问,那就需要修改下网络访问权限配置
(1)配置远程访问
首先,让防火墙放行端口
# 放行TCP端口
sudo ufw allow 18789/tcp
# 查看规则
sudo ufw status numbered
运行项目并下载源码
然后修改~/.openclaw/openclaw.json配置文件
vim openclaw.json
把bind的配置改为lan
"gateway": {
"mode": "local",
"auth": {
"mode": "token",
"token": "***********"
},
"port": 18789,
"bind": "loopback", // 改为lan
"tailscale": {
"mode": "off",
"resetOnExit": false
}
},
ESC Shift+:输入wq! 回车
保存退出
重启应用
openclaw gateway restart
浏览器访问http://xxxxx:18789
(2)解决报错
提示 disconnected (1008): control ui requires HTTPS or localhost (secure context)
所以什么都操作不了。
解决办法:
继续编辑配置,修改~/.openclaw/openclaw.json配置文件
vim ~/.openclaw/openclaw.json
"gateway": {
"port": 18789,
"mode": "local",
"bind": "lan",
// 加入下面这行配置
"controlUi": {
"allowInsecureAuth": true
},
"auth": {
"mode": "token",
"token": "*************************************"
},
"tailscale": {
"mode": "off",
"resetOnExit": false
},
"http": {
"endpoints": {
"responses": {
"enabled": true
}
}
}
}
然后重启应用
openclaw gateway restart
现在就不报错,能正常访问了。
(3)修改模型选择
如果要修改模型选择,需要在配置文件进行修改。
①使用云平台的模型
openclaw config set 'models.providers.mass' --json '{
"baseUrl": "https://api.modelarts-maas.com/openai/v1",
"apiKey": "api值",
"api": "openai-completions",
"models": [
{ "id": "DeepSeek-V3", "name": "DeepSeek-V3" },
{ "id": "deepseek-r1-250528", "name": "deepseek-r1-250528" }
]
}'
# 设置 models.mode 为 merge
openclaw config set models.mode merge
# 设置默认模型(以deepseek-chat为例)
openclaw models set mass/DeepSeek-V3
openclaw gateway restart
{
"agents": {
"defaults": {
"model": { "primary": "bailian/qwen3-max-2026-01-23" },
"models": {
"bailian/qwen3-max-2026-01-23": { "alias": "通义千问 Max Thinking 版" }
}
}
},
"models": {
"mode": "merge",
"providers": {
"bailian": {
"baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
"apiKey": "${DASHSCOPE_API_KEY}",
"api": "openai-completions",
"models": [
{
"id": "qwen3-max-2026-01-23",
"name": "通义千问 Max Thinking 版",
"reasoning": false,
"input": ["text"],
"cost": { "input": 0.0025, "output": 0.01, "cacheRead": 0, "cacheWrite": 0 },
"contextWindow": 262144,
"maxTokens": 65536
}
]
}
}
}
}
②使用本地ollama平台
"my-ollama": {
"baseUrl": "http://127.0.0.1:11434/v1",
"apiKey": "ollama",
"api": "openai-completions",
"models": [
{
"id": "qwen3:32b",
"name": "Local Qwen3 32B",
"reasoning": false,
"input": ["text"],
"contextWindow": 32000,
"maxTokens": 4096,
"cost": {"input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0}
}
]
}
3.查看token
openclaw dashboard --no-open
浏览器访问截图中,带token的URL
【遇到问题】
Q1: Gateway无法连接
症状: Web UI显示"disconnected (1006): no reason"
解决方案:
# 1. 检查Gateway是否运行
ps aux | grep clawdbot-gateway
# 2. 检查端口占用
lsof -i :18789
# 3. 检查配置文件是否有效
cat ~/.openclaw/openclaw.json | jq '.'
# 4. 重启Gateway
openclaw gateway restart
# 5. 查看错误日志
tail -50 ~/.clawdbot/logs/gateway.err.log

Q2: 飞书插件连接失败
[症状表现]
频道状态显示:Running: No, Configured: No, Connected: n/a
右上角显示:disconnected (1006): no reason
日志错误:
TypeError: (0 , _pluginSdk.createFixedWindowRateLimiter) is not a function
[根本原因]
OpenClaw 2026.2.26 版本的插件 SDK 中,createFixedWindowRateLimiter 函数被移除或重命名,但飞书插件仍在调用旧 API,导致插件加载失败。
[解决方案]
方案 A:删除冲突插件(推荐)
# 1. 停止服务
openclaw gateway stop
# 2. 删除所有飞书插件目录
Remove-Item -Recurse -Force "C:\Users\dell\AppData\Roaming\npm\node_modules\openclaw\extensions\feishu" -ErrorAction SilentlyContinue
Remove-Item -Recurse -Force "C:\Users\dell\.openclaw\extensions\feishu" -ErrorAction SilentlyContinue
# 3. 清理僵尸进程
Q2: API调用失败
症状: 日志显示"TypeError: fetch failed"
解决方案:
# 1. 测试API端点可访问性
curl -s https://code.claude-opus.top/api/v1/messages \
-H "x-api-key: 你的API密钥" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{"model":"claude-sonnet-4-5","max_tokens":100,"messages":[{"role":"user","content":"hi"}]}'
# 2. 验证配置文件
cat ~/.clawdbot/clawdbot.json | jq '.models.providers.anthropic'
# 3. 确保包含所有必需字段
# - baseUrl
# - apiKey
# - api: "anthropic-messages"
# - models: []
# 4. 重启Gateway
clawdbot gateway restart
常见问题速查
再来看看如何用Openclaw来远程登录Linux机器,并执行任务。
首先,你要让Openclaw生成密钥对,并将公钥给到我们
- 我想要远程登录一台Linux机器,要使用SSH密钥验证的方式,
- 请生成一对密钥对,并提供给我公钥
它不仅提供了公钥内容,还告诉我们如何配置。
我把公钥放到目标服务器上,然后告诉它可以登录服务器了
然后我再次发出需求
5.nginx反向代理
sudo apt install nginx
sudo vim /etc/nginx/nginx.conf
注释掉如下行
#include /etc/nginx/sites-enabled/*;
上传SSL证书至/etc/nginx/ssl/
cd /etc/nginx/conf.d/
sudo vim openclaw_nginx_reverse_proxy.conf
添加如下行
server {
# 将原有 listen 80 修改为 listen 80 改为 listen 443 ssl
listen 443 ssl;
# 原有 server_name,可继续新增更多当前证书支持的域名
server_name openclaw.openjarvis.net;
# ======================= 证书配置开始 =======================
# 指定证书文件(中间证书可以拼接至该pem文件中),请将 /etc/ssl/cert/ssl.pem 替换为您实际使用的证书文件的绝对路径
ssl_certificate /etc/nginx/ssl/openclaw.openjarvis.net.pem;
# 指定私钥文档,请将 /etc/ssl/cert/ssl.key 替换为您实际使用的私钥文件的绝对路径
ssl_certificate_key /etc/nginx/ssl/openclaw.openjarvis.net.key;
# 配置 SSL 会话缓存,提高性能
ssl_session_cache shared:SSL:1m;
# 设置 SSL 会话超时时间
ssl_session_timeout 5m;
# 自定义设置使用的TLS协议的类型以及加密套件(以下为配置示例,请您自行评估是否需要配置)
ssl_ciphers ECDHE-RSA-AES128-GCM-SHA256:ECDHE:ECDH:AES:HIGH:!NULL:!aNULL:!MD5:!ADH:!RC4;
# 指定允许的 TLS 协议版本,TLS协议版本越高,HTTPS通信的安全性越高,但是相较于低版本TLS协议,高版本TLS协议对浏览器的兼容性较差
ssl_protocols TLSv1.2 TLSv1.3;
# 优先使用服务端指定的加密套件
ssl_prefer_server_ciphers on;
# ======================= 证书配置结束 =======================
# 其它配置
location / {
proxy_pass http://127.0.0.1:18789;
# WebSocket升级头
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection 'upgrade';
# 客户端真实信息
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
# 缓冲区设置
proxy_buffering off;
# 超时设置
proxy_read_timeout 86400s;
proxy_send_timeout 86400s;
proxy_connect_timeout 30s;
}
}
6.接入IM
(1)钉钉
安装openclaw-channel-dingtalk插件
插件Github地址:https://github.com/soimy/openclaw-channel-dingtalk
git clone https://github.com/soimy/openclaw-channel-dingtalk.git
cd openclaw-channel-dingtalk
openclaw plugins install -l .
钉钉应用及机器人
- 创建钉钉应用
- 访问 钉钉开发者后台
- 创建企业内部应用
- 添加「机器人」能力
- 配置消息接收模式为 Stream 模式
发布应用
配置权限管理
在应用的权限管理页面,需要开启以下权限:
✅ Card.Instance.Write — 创建和投放卡片实例
✅ Card.Streaming.Write — 对卡片进行流式更新 步骤:
进入应用 → 权限管理 搜索「Card」相关权限 勾选上述两个权限 保存权限配置
建立卡片模板 如需使用 AI 互动卡片功能,需要在钉钉卡片平台创建模板:
- 访问 钉钉卡片平台
- 进入「我的模板」
- 点击「创建模板」
- 卡片模板场景选择 「AI 卡片」
- 无需选择预设模板,直接点击保存
- 复制模板 ID(格式如:xxxxx-xxxxx-xxxxx.schema)
- 在OpenClaw控制台的Channel标签->Dingtalk配置面板-> Card Template Id填入
获取凭证 从开发者后台获取:
Client ID (AppKey)
Client Secret (AppSecret)
Robot Code (与 Client ID 相同)
Corp ID (企业 ID)
Agent ID (应用 ID)
6. 重启 Gateway
openclaw gateway restart
7、与机器人进行对话进行验证
Docker 部署 OpenClaw 程教程
使用 Docker Compose
version: '3.8'
services:
openclaw:
image: 1186258278/openclaw-zh:latest
container_name: openclaw
ports:
- "18789:18789"
volumes:
- openclaw-data:/root/.openclaw
restart: unless-stopped
command: openclaw gateway run
# 新增优化配置
environment:
- TZ=Asia/Shanghai # 统一时区,避免日志时间错乱
- NODE_ENV=production
logging: # 日志配置(限制日志大小,避免占满磁盘)
driver: "json-file"
options:
max-size: "100m" # 单个日志文件最大100M
max-file: "3" # 最多保留3个日志文件
privileged: false # 非特权模式(提升安全性)
mem_limit: 1G # 限制容器内存使用(避免占用过多资源)
volumes:
openclaw-data:
driver: local
###先执行初始化基础数据的命令
//1. 手动初始化
docker-compose run --rm openclaw openclaw setup
docker-compose run --rm openclaw openclaw config set gateway.mode local
//2. 配置绑定和认证
docker-compose run --rm openclaw openclaw config set gateway.bind lan
docker-compose run --rm openclaw openclaw config set gateway.auth.token YOUR_TOKEN
//3. 设置模型配置,newapiapp是自定义的供应商名称,配置相应的apikey、baseurl、默认Id,可以设置多个
docker-compose run --rm openclaw openclaw config set models.providers.newapiapp '{
"api": "openai-completions",
"apiKey": "sk-xxxx",
"baseUrl": "https://api.openai.com/v1",
"models": [
{
"id": "modelscope-k2.5",
"name": "modelscope-k2.5"
}
]
}'
//设置默认主模型,后面的对话就可以默认使用对应供应商的模型了
docker-compose run --rm openclaw openclaw config set agents.defaults.model.primary "newapiapp/modelscope-k2.5"
//4. 允许不完全访问,可以通过ip、域名反代等远程访问
docker-compose run --rm openclaw openclaw config set gateway.controlUi.allowInsecureAuth true
###配置初始化完成后,可以启动服务,执行如下命令
docker-compose up -d
使用 Docker Compose 部署
# 启动服务
docker-compose up -d
# 查看日志
docker-compose logs -f
# 停止服务
docker-compose down
# 重启服务
docker-compose restart
8.2 Nginx 反向代理 + HTTPS
# HTTP 80端口:强制跳转到HTTPS
server {
listen 80;
listen [::]:80; # 兼容IPv6(可选,建议加)
server_name your-domain.com; # 替换为你的实际域名(如openclaw.example.com)
# 强制HTTPS跳转(保留原请求路径和参数)
return 301 https://$server_name$request_uri;
}
# HTTPS 443端口:代理到openclaw容器(18789端口)
server {
listen 443 ssl http2;
listen [::]:443 ssl http2; # 兼容IPv6
server_name your-domain.com; # 必须和证书域名一致
# SSL证书路径(certbot自动生成,无需手动改)
ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;
# 可选:SSL安全配置(提升HTTPS安全性,建议添加)
ssl_protocols TLSv1.2 TLSv1.3; # 禁用低版本TLS
ssl_prefer_server_ciphers on;
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384;
ssl_session_cache shared:SSL:10m;
ssl_session_timeout 10m;
# 反向代理到openclaw容器(localhost:18789)
location / {
proxy_pass http://localhost:18789;
proxy_http_version 1.1;
# WebSocket兼容(openclaw若用WebSocket,这两行必须加)
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
# 传递客户端真实IP/域名/协议
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
# 禁用缓存(适配动态服务)
proxy_cache_bypass $http_upgrade;
proxy_connect_timeout 30s; # 连接超时(可选优化)
proxy_send_timeout 30s;
proxy_read_timeout 30s;
}
}
完整实操步骤(从安装证书到验证生效)
前置条件
域名 your-domain.com 已解析到宿主机公网 IP(必须!否则 certbot 无法验证);
宿主机 80/443 端口已开放(防火墙 / 安全组需放行);
Nginx 已安装并运行(systemctl status nginx 确认 active)。
步骤 1:安装 Certbot(获取 Let's Encrypt 证书)
bash
运行
# 更新apt源(避免安装失败)
sudo apt update
# 安装certbot和Nginx插件(自动配置Nginx)
sudo apt install -y certbot python3-certbot-nginx
步骤 2:获取 SSL 证书(自动配置 Nginx)
bash
运行
# 替换为你的实际域名(如openclaw.example.com)
sudo certbot --nginx -d your-domain.com
执行后按提示操作:输入邮箱 → 同意条款 → 是否共享邮箱(选 N) → 选择是否自动跳转 HTTPS(选 2,强制跳转);
成功后,certbot 会自动修改 Nginx 配置,无需手动改ssl_certificate路径。
步骤 3:验证证书配置
bash
运行
# 检查Nginx配置语法(避免格式错误)
sudo nginx -t
# 重载Nginx配置(无需重启,平滑生效)
sudo systemctl reload nginx
# 验证HTTPS是否生效
curl -I https://your-domain.com
# 输出包含「Server: nginx」「Strict-Transport-Security」即为成功
步骤 4:配置证书自动续期(Let's Encrypt 证书 90 天过期)
bash
运行
# 测试自动续期(仅测试,不实际续期)
sudo certbot renew --dry-run
# 添加定时任务(每天自动检查续期)
sudo crontab -e
# 粘贴以下内容(每天凌晨3点检查,证书快过期则自动续期)
0 3 * * * /usr/bin/certbot renew --quiet && systemctl reload nginx
8.日常命令
(1)版本更新
更新到最新版本
# 1. 停止并删除旧容器
docker stop openclaw && docker rm openclaw
# 2. 拉取最新镜像
docker pull 1186258278/openclaw-zh:latest
# 3. 启动新容器
docker run -d --name openclaw -p 18789:18789 \
-v openclaw-data:/root/.openclaw --restart unless-stopped \
1186258278/openclaw-zh:latest \
openclaw gateway run
(2)监控与日志
查看容器资源使用
# 查看资源使用情况 docker stats openclaw
# 查看详细信息 docker inspect openclaw
日志管理
# 查看最近 100 行日志 docker logs --tail 100 openclaw
# 查看最近 10 分钟的日志 docker logs --since 10m openclaw
# 导出日志到文件 docker logs openclaw > openclaw.log
# 清理日志(谨慎使用)
docker run --rm -v /var/lib/docker/containers:/containers \
ubuntu find /containers -name "*.json" -type f -size +100M -delete
(3)完全卸载
# 1. 停止并删除容器
docker stop openclaw && docker rm -f openclaw
# 2. 删除数据卷(⚠️ 会删除所有配置和日志)
docker volume rm openclaw-data
# 3. 删除镜像
docker rmi 1186258278/openclaw-zh:latest
# 4. 清理悬空镜像和容器
docker system prune -a
更多推荐




所有评论(0)