创建时间：2026-03-18 
     
更新时间：2026-03-18 
 
 
 




    
 
  
    
    
 
     
 
      
系统要求
 
      
OpenClaw 安装
 
      
OpenClaw 配置
 
      
 机器人接入
 
      
验证与测试
 
      
常见问题排查
 
      
参考资源
 
     
 
     
 
      
硬件要求
 
      
 
       
CPU：2 核心以上
 
       
内存：4GB 以上（推荐 8GB）
 
       
硬盘：20GB 以上可用空间
 
      
 
      
软件要求
 
      
 
       
操作系统：Linux (Ubuntu 20.04+ 推荐推荐)、macOS、Windows
 
       
Node.js：v18+ （推荐 v20+）
 
       
npm：v9+
 
       
Git
 
      
 
      
网络要求
 
      
 
       
稳定的互联网连接
 
       
如果需要访问国外网站，建议配置代理
 
      
 
      
 
       
1. 安装 Node.js 和 npm
 
       
Ubuntu/Debian:
 
       
# 安装 Node.js 20.xcurl-fsSL https://deb.nodesource.com/setup_20.x |sudo-Ebash - sudoapt-getinstall-y nodejs # 验证安装node--versionnpm--version
 
       
macOS:
 
       
# 使用 Homebrew 安装 brew installnode# 验证安装node--versionnpm--version
 
       
Windows:
 
       
访问 Node.js 官网 下载并安装 LTS 版本。
 
       
2. 安装 OpenClaw
 
       
# 全局安装 OpenClaw CLInpminstall-g openclaw # 验证安装 openclaw --version# 查看帮助信息 openclaw help
 
       
3. 初始化 OpenClaw
 
       
# 创建工作目录mkdir-p ~/.openclaw/workspace cd ~/.openclaw/workspace # 初始化（首次运行会自动初始化） openclaw gateway status 
 
       
4. 启动 OpenClaw Gateway
 
       
# 启动 Gateway 守护进程 openclaw gateway start # 查看 Gateway 状态 openclaw gateway status # 查看 Gateway 日志 openclaw gateway logs # 重启 Gateway openclaw gateway restart # 停止 Gateway openclaw gateway stop 
 
       
 
        
1. 配置文件位置
 
        
配置文件位于：~/.openclaw/config/config.yaml
 
        
2. 基本配置示例
 
        
# Gateway 配置gateway:host: 127.0.0.1 port:8765debug:false# AI 模型配置models:default: zai/glm-4.7reasoning: zai/glm-4.7# 工具配置tools:browser:enabled:trueheadless:trueweb:search:provider: perplexity apiKey:"YOUR_PERPLEXITY_API_KEY"# 通道配置channels:bot:enabled:trueautoReply:true
 
        
3. 配置环境变量
 
        
# 编辑环境变量文件nano ~/.openclaw/.env # 添加以下内容（根据实际情况填写）PERPLEXITY_API_KEY=your_api_key_here OPENCLAW_LOG_LEVEL=info 
 
        
4. 安装常用依赖
 
        
# 安装 Chrome 浏览器（用于 browser 工具）sudoapt-get update sudoapt-getinstall-ywget gnupg ca-certificates # 添加 Chrome 仓库wget-q-O - https://dl-ssl.google.com/linux/linux_signing_key.pub |sudo gpg --dearmor-o /usr/share/keyrings/google-chrome.gpg echo"deb [arch=amd64 signed-by=/usr/share/keyrings/google-chrome.gpg] http://dl.google.com/linux/chrome/deb/ stable main"|sudotee /etc/apt/sources.list.d/google-chrome.list # 更新并安装sudoapt-get update sudoapt-getinstall-y google-chrome-stable # 验证安装 google-chrome --version# 安装 Chrome 依赖sudoapt-getinstall-y libnss3 libxss1 libasound2 libatk-bridge2.0-0 libatk1.0-0 libatspi2.0-0 libcairo2 libcups2 libdbus-1-3 libdrm2 libgbm1 libgtk-3-0 libnspr4 libxcomposite1 libxdamage1 libxfixes3 libxrandr2 xdg-utils 
 
        
 
         
方式一：使用已有的 Bot 扩展
 
         
假设你已经有了 Bot 扩展（基于当前环境判断），以下是配置步骤：
 
         
1. 检查 Bot 扩展
 
         
# 查看已安装的扩展ls-la ~/.openclaw/extensions/ # 或查看扩展目录ls-la ~/.local/share/pnpm/global/*/node_modules/openclaw/extensions/ 
 
         
2. 配置 Bot
 
         
编辑 Bot 配置文件（位置可能有所不同）：
 
         
# 找到 Bot 配置文件find ~/.openclaw -name"*bot*"-type f # 编辑配置nano ~/.openclaw/extensions/bot/config.yaml 
 
         
3. Bot 配置示例
 
         
#  机器人配置bot:enabled:trueaccount:uin:"你的号"password:"你的密码"server:host: 127.0.0.1 port:8080features:autoReply:trueimageDownload:truevoiceUpload:truevideoUpload:truefileUpload:true
 
         
4. 重启 Gateway 使配置生效
 
         
openclaw gateway restart 
 
         
方式二：安装 Bot 扩展
 
         
如果需要安装 Bot 扩展：
 
         
# 使用 ClawHub 安装 clawhub search bot # 安装找到的 Bot 扩展 clawhub install 
         
      
           
             # 或者手动安装cd ~/.openclaw/extensions git clone https://github.com/your-repo/bot.git cd bot npminstall 
           
 
         
方式三：使用第三方 机器人框架（如 NapCat）
 
         
如果需要使用 NapCat（基于 NT 的 机器人框架）：
 
         
1. 安装 NapCat
 
         
# 克隆 NapCatcd ~ git clone https://github.com/NapNeko/NapCat.git cd NapCat # 安装依赖npminstall# 配置 NapCatcp config.example.json config.json nano config.json 
 
         
2. NapCat 配置示例
 
         
{"":{"account":"你的号","password":"你的密码"},"server":{"host":"127.0.0.1","port":3000,"httpApi":true,"wsApi":true},"message":{"ignoreSelf":true,"enableGroupMessage":true,"enablePrivateMessage":true}}
 
         
3. 启动 NapCat
 
         
npm start 
 
         
4. 配置 OpenClaw 连接 NapCat
 
         
编辑 OpenClaw 配置文件：
 
         
# 添加 NapCat 连接配置channels:bot:enabled:truetype: napcat endpoint:host: 127.0.0.1 port:3000account:uin:"你的号"
 
         
 
          
1. 验证 OpenClaw Gateway
 
          
# 查看 Gateway 状态 openclaw gateway status # 预期输出：# ✓ OpenClaw Gateway is running# Version: x.x.x# Runtime: Linux x.x.x
 
          
2. 验证 Bot 连接
 
          
# 查看 OpenClaw 日志 openclaw gateway logs # 检查是否有 Bot 连接成功的日志# 预期输出类似：# [INFO] Bot connected: account=xxxxx
 
          
3. 测试机器人
 
          
通过你的另一个 号向机器人发送测试消息：
 
          
测试消息 
 
          
机器人应该会回复（根据配置）。
 
          
4. 测试功能
 
          
测试图片发送：
 
          
发送一张图片（聊天窗口发送图片） 
 
          
机器人应该能接收并处理图片。
 
          
测试命令：
 
          
/help /status 
 
          
 
           
问题 1：OpenClaw Gateway 无法启动
 
           
症状：
 
           
$ openclaw gateway start Error: Failed to start Gateway 
 
           
解决方法：
 
           
# 检查端口占用lsof-i :8765 # 查看详细日志 openclaw gateway logs --tail=100# 尝试重启系统sudoreboot
 
           
问题 2：Bot 连接失败
 
           
症状：
 
           
[ERROR] Failed to connect to Bot 
 
           
解决方法：
 
           
 
            
检查 账号密码是否正确
 
            
检查网络连接
 
            
检查 Bot 服务是否运行
 
            
查看详细日志
 
           
 
           
# 查看 Gateway 日志 openclaw gateway logs # 测试 Bot API 连接curl http://127.0.0.1:8080/status 
 
           
问题 3：Browser 工具无法使用
 
           
症状：
 
           
Error: No supported browser found 
 
           
解决方法：
 
           
# 检查 Chrome 是否安装which google-chrome # 安装 Chrome（如果未安装）sudoapt-getinstall-y google-chrome-stable # 检查依赖 ldd /usr/bin/google-chrome |grep"not found"# 安装缺失的依赖sudoapt-getinstall-y libnss3 libxss1 libasound2 ... # 重启 Gateway openclaw gateway restart 
 
           
问题 4：命令执行无输出
 
           
症状：
 
           
$ whoami# 无输出
 
           
解决方法：
 
           
 
            
检查沙箱权限
 
            
检查是否在正确的用户下运行
 
            
尝试使用绝对路径
 
           
 
           
# 检查当前用户id# 使用绝对路径执行 /usr/bin/whoami 
 
           
问题 5：npm 安装失败
 
           
症状：
 
           
Error: EACCES: permission denied 
 
           
解决方法：
 
           
# 方法 1：使用 sudosudonpminstall-g 
           
      
             
               # 方法 2：修复 npm 权限mkdir ~/.npm-global npm config set prefix '~/.npm-global'echo'export PATH=~/.npm-global/bin:$PATH'>> ~/.bashrc source ~/.bashrc 
             
 
           
 
            
官方文档
 
            
 
             
OpenClaw 官方文档
 
             
OpenClaw GitHub
 
             
ClawHub 技能市场
 
            
 
            
 机器人相关
 
            
 
             
NapCat GitHub
 
             
Go-CQHTTP
 
             
OneBot v11 标准
 
            
 
            
其他工具
 
            
 
             
Node.js 官网
 
             
npm 文档
 
            
 
            
 
             
A. 常用命令速查
 
             
# OpenClaw Gateway openclaw gateway start # 启动 openclaw gateway stop # 停止 openclaw gateway restart # 重启 openclaw gateway status # 状态 openclaw gateway logs # 日志# 技能管理 clawhub search 
             
      
               
                 # 搜索技能 clawhub install 
                
                  # 安装技能 clawhub update # 更新技能# 会话管理 openclaw sessions list # 列出会话 openclaw session status # 会话状态# 帮助 openclaw help# 帮助信息 openclaw --version# 版本信息 
                 
               
 
             
B. 配置文件模板
 
             
完整配置文件示例：config.yaml
 
             
# OpenClaw 完整配置示例# Gateway 配置gateway:host: 0.0.0.0 port:8765debug:falselogLevel: info # 模型配置models:default: zai/glm-4.7reasoning: zai/glm-4.7# 工具配置tools:browser:enabled:trueheadless:truenoSandbox:falseweb:search:provider: perplexity apiKey:"${PERPLEXITY_API_KEY}"# 通道配置channels:bot:enabled:truetype: napcat endpoint:host: 127.0.0.1 port:3000account:uin:"YOUR__NUMBER"# 技能配置skills:autoLoad:trueloadPaths:- ~/.openclaw/extensions/*/skills/*- ~/.openclaw/workspace/skills/* 
 
             
 
              
文档结束
 
              
如有问题，请查看日志文件：
 
              
 
               
Gateway 日志：~/.openclaw/logs/gateway.log
 
               
通道日志：~/.openclaw/logs/bot.log