OpenClaw AI “小龙虾”部署手册

目录

1. 1. 项目简介
2. 2. 环境要求
3. 3. 安装步骤
4. 4. 配置说明
5. 5. 微信接入
6. 6. 常见问题与排查
7. 7. 性能优化
8. 8. 常用命令

项目简介

OpenClaw 是一个开源的个人 AI 助手，可以在本地设备上运行，支持多平台多渠道接入，这期教程将教会大家部署小龙虾和微信连接。

主要特性：

• • 本地优先网关 – 统一会话、渠道、工具和事件控制
• • 多渠道收件箱 – 支持 WhatsApp、Telegram、Slack、Discord、微信、QQ 等
• • 多代理路由 – 将入站渠道/账户路由到隔离的代理
• • 语音唤醒 + 对话模式
• • 实时 Canvas – 代理驱动的可视化工作区

项目地址：

 https://github.com/openclaw/openclaw

环境要求

系统要求

检查当前环境

# 检查 Node.js 版本node --version# 检查 npm 版本npm --version

安装步骤

步骤 1: 安装 OpenClaw

npm install -g openclaw@latest

安装完成后验证：

openclaw --version

预期输出类似：OpenClaw 2026.4.29 (xxxxxxx)

步骤 2: 创建配置目录

mkdir -p ~/.openclaw

步骤 3: 创建配置文件

创建配置文件 ~/.openclaw/openclaw.json：

{"models":{"mode":"merge","providers":{"myprovider":{"baseUrl":"https://your-api-endpoint.com/v2","apiKey":"YOUR_API_KEY","api":"openai-completions","models":[{"id":"your-model-id","name":"your-model-id","reasoning":false,"input":["text"],"contextWindow":92160,"maxTokens":32768}]}}},"agents":{"defaults":{"model":{"primary":"myprovider/your-model-id"},"models":{"myprovider/your-model-id":{"alias":"myprovider"}}}},"gateway":{"mode":"local"},"plugins":{"allow":["openclaw-weixin"],"entries":{"openclaw-weixin":{"enabled":true}}}}

配置说明：

步骤 4: 设置 Gateway 模式

openclaw config set gateway.mode local

步骤 5: 运行诊断检查

openclaw doctor

如果提示需要修复依赖，运行：

openclaw doctor --fix

配置说明

模型配置

OpenClaw 支持多种模型提供商，配置格式遵循 OpenAI 兼容格式：

{"models":{"providers":{"provider-name":{"baseUrl":"API地址","apiKey":"API密钥","api":"openai-completions","models":[{"id":"模型ID","name":"模型名称","contextWindow": 上下文大小,"maxTokens": 最大输出}]}}}}

Gateway 配置

# 设置为本地模式openclaw config set gateway.mode local# 查看当前配置openclaw config get gateway

微信接入

步骤 1: 安装微信插件

方式一：自动安装（推荐）

npx -y @tencent-weixin/openclaw-weixin-cli install

方式二：手动安装

openclaw plugins install "@tencent-weixin/openclaw-weixin"openclaw config set plugins.entries.openclaw-weixin.enabled true

步骤 2: 启动 Gateway

openclaw gateway --port 18789 --verbose

或安装为系统服务：

openclaw gateway installsystemctl --user start openclaw-gateway.service

步骤 3: 扫码登录

运行微信插件安装命令后，终端会显示二维码：

用手机微信扫描以下二维码，以继续连接：▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄█ ▄▄▄▄▄ █▄▄▄ ▀ ▄██▄▄▀▀ ▄██▄██ █ ▄▄▄▄▄ █...▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀若二维码未能显示或无法使用，你可以访问以下链接以继续：https://liteapp.weixin.qq.com/q/xxx

操作步骤：

1. 1. 用手机微信扫描二维码
2. 2. 在手机上确认登录
3. 3. 等待终端显示 “已将此 OpenClaw 连接到微信”

步骤 4: 验证连接状态

openclaw status

查看 Channels 部分，应显示：

┌─────────────────┬─────────┬────────┬─────────────────┐│ Channel         │ Enabled │ State  │ Detail          │├─────────────────┼─────────┼────────┼─────────────────┤│ openclaw-weixin │ ON      │ OK     │ configured      │└─────────────────┴─────────┴────────┴─────────────────┘

步骤 5: 配对审批（可选）

如果需要审批发送者：

# 查看待审批列表openclaw pairing list openclaw-weixin# 审批发送者openclaw pairing approve openclaw-weixin <CODE>

常见问题与排查

问题 1: Gateway unreachable

现象：

Gateway │ local · ws://127.0.0.1:18789 (local loopback) · unreachable (timeout)

排查步骤：

# 1. 检查服务状态systemctl --user status openclaw-gateway.service# 2. 查看服务日志journalctl --user -u openclaw-gateway.service -n 50 --no-pager# 3. 检查端口占用netstat -tlnp | grep 18789# 4. 重启服务systemctl --user restart openclaw-gateway.service

常见原因：

• • 服务未启动
• • 端口被占用
• • 配置文件错误

问题 2: 响应缓慢

现象： 微信发消息后几分钟才收到回复

排查步骤：

# 查看日志中的时间分析journalctl --user -u openclaw-gateway.service -n 30 --no-pager | grep -E "stream|dispatch|auth"

日志分析关键字段：

优化方案：

1. 1. 限制加载的插件（在配置文件中）：

{"plugins":{"allow":["openclaw-weixin"],"entries":{"openclaw-weixin":{"enabled":true}}}}

1. 2. 检查系统资源：

# 查看内存free -h# 查看 CPU 负载uptime# 查看进程top

问题 3: 微信无法连接

现象： 微信插件显示连接失败

排查步骤：

# 1. 检查插件状态openclaw status# 2. 重新登录微信openclaw channels login --channel openclaw-weixin# 3. 查看微信相关日志journalctl --user -u openclaw-gateway.service --no-pager | grep weixin

问题 4: 模型 API 调用失败

现象： AI 不回复或回复错误

排查步骤：

# 1. 测试 API 连通性curl -X POST "YOUR_API_BASE_URL/chat/completions" \  -H "Content-Type: application/json" \  -H "Authorization: Bearer YOUR_API_KEY" \  -d '{"model": "your-model", "messages": [{"role": "user", "content": "test"}]}'# 2. 检查配置cat ~/.openclaw/openclaw.json | grep -A 5 "providers"# 3. 查看错误日志journalctl --user -u openclaw-gateway.service --no-pager | grep -i error

问题 5: 配置文件权限问题

现象： 启动时报配置文件权限警告

解决：

# 设置正确的文件权限chmod 600 ~/.openclaw/openclaw.jsonchmod 700 ~/.openclaw

性能优化

1. 减少插件加载

只启用必要的插件：

{"plugins":{"allow":["openclaw-weixin"]}}

2. 禁用 mDNS 发现

如果不需要本地发现功能：

openclaw config set discovery.mdns.mode off

3. 设置编译缓存

export NODE_COMPILE_CACHE=/var/tmp/openclaw-compile-cachemkdir -p /var/tmp/openclaw-compile-cache

4. 禁用自重启

export OPENCLAW_NO_RESPAWN=1

5. 系统资源优化

确保系统有足够的资源：

• • 内存：建议 8GB+
• • CPU：建议 4 核+
• • 关闭不必要的后台程序

常用命令

服务管理

# 启动 Gatewayopenclaw gateway --port 18789# 安装为系统服务openclaw gateway install# 启动服务systemctl --user start openclaw-gateway.service# 停止服务systemctl --user stop openclaw-gateway.service# 重启服务systemctl --user restart openclaw-gateway.service# 查看服务状态systemctl --user status openclaw-gateway.service

状态检查

# 查看整体状态openclaw status# 查看详细状态openclaw status --deep# 运行诊断openclaw doctor# 修复问题openclaw doctor --fix

配置管理

# 设置配置项openclaw config set <path> <value># 获取配置项openclaw config get <path># 查看完整配置cat ~/.openclaw/openclaw.json

微信相关

# 查看配对列表openclaw pairing list openclaw-weixin# 审批发送者openclaw pairing approve openclaw-weixin <CODE># 重新登录openclaw channels login --channel openclaw-weixin

日志查看

# 查看服务日志journalctl --user -u openclaw-gateway.service -f# 查看最近日志journalctl --user -u openclaw-gateway.service -n 100 --no-pager# 查看日志文件tail -f /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log

测试命令

# 测试 AI 响应openclaw agent --message "你好"# 发送测试消息openclaw message send --target <target> --message "测试消息"

附录：配置文件完整示例

{"models":{"mode":"merge","providers":{"myprovider":{"baseUrl":"https://api.example.com/v2","apiKey":"YOUR_API_KEY_HERE","api":"openai-completions","models":[{"id":"model-name","name":"model-name","reasoning":false,"input":["text"],"contextWindow":92160,"maxTokens":32768}]}}},"agents":{"defaults":{"model":{"primary":"myprovider/model-name"},"models":{"myprovider/model-name":{"alias":"myprovider"}},"compaction":{"mode":"safeguard"}}},"gateway":{"mode":"local"},"plugins":{"allow":["openclaw-weixin"],"entries":{"openclaw-weixin":{"enabled":true}}}}

总结

本手册涵盖了 OpenClaw AI 个人助理的完整部署流程：

1. 1. 安装 – 通过 npm 全局安装
2. 2. 配置 – 设置模型和 Gateway
3. 3. 微信接入 – 安装插件并扫码登录
4. 4. 问题排查 – 常见问题的诊断和解决
5. 5. 性能优化 – 提升响应速度的方法

如有更多问题，请参考官方文档：https://docs.openclaw.ai

关注/点赞下一期出Hermes”养马“教程

文档版本：1.0更新日期：2026-05-02