OpenClaw AI 个人助理部署手册

发布于 7 天前  29 次阅读

OpenClaw AI 个人助理部署手册

目录

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

项目简介

OpenClaw 是一个开源的个人 AI 助手，可以在本地设备上运行，支持多平台多渠道接入。

主要特性：

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

项目地址： https://github.com/openclaw/openclaw

环境要求

系统要求

项目 要求
操作系统 Linux / macOS / Windows
Node.js 24+ (推荐) 或 22.14+
内存 建议 8GB+
存储 500MB+

检查当前环境

# 检查 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
      }
    }
  }
}

配置说明：

字段 说明
baseUrl API 服务地址
apiKey API 密钥
api API 类型，支持 openai-completions 等格式
contextWindow 上下文窗口大小
maxTokens 最大输出 token 数

步骤 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 install
systemctl --user start openclaw-gateway.service

步骤 3: 扫码登录

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

用手机微信扫描以下二维码，以继续连接：

▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
█ ▄▄▄▄▄ █▄▄▄ ▀ ▄██▄▄▀▀ ▄██▄██ █ ▄▄▄▄▄ █
...
▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀

若二维码未能显示或无法使用，你可以访问以下链接以继续：
https://liteapp.weixin.qq.com/q/xxx

操作步骤：

  1. 用手机微信扫描二维码
  2. 在手机上确认登录
  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"

日志分析关键字段：

字段 含义 正常值
auth 认证时间 < 5000ms
model-resolution 模型解析 < 3000ms
stream-setup 流设置 < 10000ms

优化方案：

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

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

  2. 检查系统资源：

    
# 查看内存
free -h

查看 CPU 负载

uptime

查看进程

top


### 问题 3: 微信无法连接

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

**排查步骤：**

```bash
# 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.json
chmod 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-cache
mkdir -p /var/tmp/openclaw-compile-cache

4. 禁用自重启

export OPENCLAW_NO_RESPAWN=1

5. 系统资源优化

确保系统有足够的资源：

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

常用命令

服务管理

# 启动 Gateway
openclaw 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. 安装 - 通过 npm 全局安装
  2. 配置 - 设置模型和 Gateway
  3. 微信接入 - 安装插件并扫码登录
  4. 问题排查 - 常见问题的诊断和解决
  5. 性能优化 - 提升响应速度的方法

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

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

新一技术 – 个人博客
最后更新于 2026-05-02
啥也没有呀