常见问题

约 2417 字大约 8 分钟

2026-03-02

这里汇总了 OpenClaw 使用过程中的常见问题和解决方案。如果你的问题没有在这里找到答案，欢迎在 GitHub Discussions 提问。

📦 安装与部署

Q1: OpenClaw 支持哪些操作系统？

A: OpenClaw 支持以下操作系统：

Windows: Windows 10/11（需要 Node.js ≥ 22）
macOS: macOS 10.15 及以上
Linux: Ubuntu 20.04+, Debian 11+, CentOS 8+, Arch Linux
Docker: 支持所有能运行 Docker 的平台

详见安装指南。

Q2: 安装时提示 "Node.js 版本过低" 怎么办？

A: OpenClaw 需要 Node.js ≥ 22.0.0。

解决方案:

# 使用 nvm 安装最新版本
nvm install 22
nvm use 22

# 或使用 n
npm install -g n
n latest

# 验证版本
node --version

Q3: npm install 很慢或失败怎么办？

A: 尝试以下方法：

方法 1: 使用国内镜像

npm config set registry https://registry.npmmirror.com
npm install -g openclaw@latest

方法 2: 使用 pnpm

npm install -g pnpm
pnpm install -g openclaw@latest

方法 3: 使用代理

npm config set proxy http://proxy.example.com:8080
npm config set https-proxy http://proxy.example.com:8080

Q4: Docker 部署时容器无法启动？

A: 检查以下几点：

端口占用:

# 检查端口是否被占用
netstat -an | grep 18789

# 使用其他端口
docker run -p 18790:18789 openclaw

权限问题:

# 添加当前用户到 docker 组
sudo usermod -aG docker $USER

# 重新登录或执行
newgrp docker

查看日志:

docker logs openclaw

🔧 配置问题

Q5: OpenClaw 是否必须联网？

A: 不是必须的，取决于你的使用场景：

本地模型: 使用 Ollama 等本地模型可以完全离线运行
云端模型: 使用 Claude、GPT、DeepSeek 等需要联网
渠道接入: Telegram、Discord、飞书等需要联网
技能功能: 浏览器、搜索等功能需要联网

离线使用示例:

{
  "models": {
    "default": {
      "provider": "ollama",
      "model": "llama2",
      "baseURL": "http://localhost:11434"
    }
  }
}

Q6: 如何选择合适的 AI 模型？

A: 根据不同场景选择：

场景	推荐模型	原因
日常对话	Kimi, MiniMax	国内可用，响应快，成本低
代码编程	Claude Sonnet, GPT-4	代码能力强，理解准确
长文档处理	Claude Opus, Kimi	支持长上下文
成本敏感	DeepSeek, Qwen	价格便宜，性能不错
隐私优先	Ollama (本地)	完全本地运行
复杂推理	GPT-4, Claude Opus	推理能力最强

详见模型配置指南。

Q7: 配置文件在哪里？

A: 配置文件位置：

Linux/macOS: ~/.openclaw/config.json
Windows: %USERPROFILE%\.openclaw\config.json

查看配置:

# 查看配置文件路径
openclaw config path

# 编辑配置
openclaw config edit

# 验证配置
openclaw config validate

Q8: 如何配置多个 AI 模型？

A: 在配置文件中添加多个模型：

{
  "models": {
    "default": {
      "provider": "kimi",
      "apiKey": "sk-xxx",
      "model": "moonshot-v1-8k"
    },
    "coding": {
      "provider": "claude",
      "apiKey": "sk-xxx",
      "model": "claude-3-sonnet"
    },
    "cheap": {
      "provider": "deepseek",
      "apiKey": "sk-xxx",
      "model": "deepseek-chat"
    }
  }
}

使用时指定模型:

@OpenClaw --model coding 帮我写一个 Python 脚本

🔌 渠道接入

Q9: 哪个聊天平台最容易接入？

A: 推荐顺序：

Telegram ⭐⭐⭐⭐⭐
- 配置最简单
- 功能最完整
- 无需审核
Discord ⭐⭐⭐⭐
- 配置简单
- 适合团队使用
- 功能丰富
飞书 ⭐⭐⭐
- 适合企业
- 需要审核
- 功能完善
微信 ⭐⭐
- 配置复杂
- 需要第三方桥接
- 功能受限

详见渠道接入指南。

Q10: Telegram Bot 不回复消息？

A: 检查以下几点：

服务是否运行:

openclaw status

Token 是否正确:

# 测试 Token
curl https://api.telegram.org/bot<YOUR_TOKEN>/getMe

查看日志:

openclaw logs --tail 50

检查网络:

# 测试 Telegram API 连通性
curl https://api.telegram.org

重启服务:

openclaw restart

Q11: 如何在多个平台同时使用？

A: 配置多个渠道：

{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "telegram-bot-token"
    },
    "discord": {
      "enabled": true,
      "token": "discord-bot-token"
    },
    "feishu": {
      "enabled": true,
      "appId": "feishu-app-id",
      "appSecret": "feishu-app-secret"
    }
  }
}

所有渠道会共享同一个 AI 助手，对话历史独立。

🧩 技能与功能

Q12: 如何安装技能？

A: 三种方式：

方法 1: 从 ClawHub 安装

openclaw skill install <skill-name>

方法 2: 从 npm 安装

npm install -g @openclaw/skill-<name>

方法 3: 从 GitHub 安装

openclaw skill install github:username/repo

详见技能市场。

Q13: 技能安装后不生效？

A: 尝试以下步骤：

重启 OpenClaw:

openclaw restart

检查技能状态:

openclaw skill list

启用技能:

openclaw skill enable <skill-name>

查看技能日志:

openclaw skill logs <skill-name>

Q14: 浏览器技能无法使用？

A: 确保已安装 Chromium：

# 安装 Chromium
npx puppeteer browsers install chrome

# 或指定系统 Chrome
export PUPPETEER_EXECUTABLE_PATH=/usr/bin/google-chrome

# 测试浏览器
openclaw skill test browser

详见浏览器工具。

🔒 安全问题

Q15: 如何保证 OpenClaw 的安全性？

A: OpenClaw 提供多层安全防护：

配对机制: 只有配对的客户端才能连接
白名单: 限制可访问的用户/群组
技能审核: ClawHub 的技能经过安全扫描
权限控制: 限制技能的操作权限
日志审计: 记录所有操作日志

启用安全配置:

{
  "security": {
    "pairing": {
      "enabled": true,
      "token": "your-secret-token"
    },
    "whitelist": {
      "enabled": true,
      "users": ["user-id-1", "user-id-2"]
    },
    "skillSandbox": true,
    "auditLog": true
  }
}

详见安全配置。

Q16: API Key 会被泄露吗？

A: OpenClaw 采取以下措施保护 API Key：

本地存储: API Key 只存储在本地配置文件中
加密存储: 可选择加密存储敏感信息
环境变量: 支持使用环境变量
权限控制: 配置文件权限设置为 600

使用环境变量:

export OPENCLAW_API_KEY="sk-xxx"
openclaw start

Q17: 如何防止误操作？

A: 启用确认机制：

{
  "safety": {
    "confirmDangerousActions": true,
    "dangerousActions": [
      "file.delete",
      "system.shutdown",
      "browser.submit"
    ]
  }
}

执行危险操作时会要求确认。

💰 成本与性能

Q18: 使用 OpenClaw 需要多少费用？

A: 成本主要来自：

OpenClaw 本身: 免费开源
AI 模型 API: 按使用量付费
服务器: 如果云端部署需要服务器费用

成本估算（每月）:

使用场景	模型选择	预估成本
轻度使用	DeepSeek	¥1-5
中度使用	Kimi	¥10-30
重度使用	GPT-4	¥100-300
本地部署	Ollama	¥0

节省成本技巧:

使用国产模型（DeepSeek、Kimi）
启用缓存减少重复请求
使用本地模型处理简单任务
设置每日预算限制

Q19: OpenClaw 占用多少资源？

A: 资源占用取决于配置：

最小配置:

CPU: 1 核
内存: 512MB
磁盘: 500MB

推荐配置:

CPU: 2 核
内存: 2GB
磁盘: 2GB

高负载配置:

CPU: 4 核
内存: 4GB
磁盘: 10GB

Q20: 如何优化性能？

A: 性能优化建议：

启用缓存:

{
  "cache": {
    "enabled": true,
    "ttl": 3600,
    "maxSize": "1GB"
  }
}

限制并发:

{
  "concurrency": {
    "maxConcurrentRequests": 5,
    "queueSize": 100
  }
}

使用更快的模型:

{
  "models": {
    "default": {
      "provider": "kimi",
      "model": "moonshot-v1-8k"
    }
  }
}

🔄 更新与维护

Q21: 如何升级 OpenClaw？

A: 升级方法：

# 查看当前版本
openclaw --version

# 升级到最新版本
npm update -g openclaw

# 或重新安装
npm install -g openclaw@latest

# 验证升级
openclaw --version

Q22: 如何切换版本通道？

A: OpenClaw 提供三个版本通道：

stable: 稳定版（推荐）
beta: 测试版（新功能）
dev: 开发版（最新但可能不稳定）

切换通道:

# 切换到 beta 通道
openclaw update --channel beta

# 切换回 stable
openclaw update --channel stable

Q23: 如何备份和恢复配置？

A: 备份配置：

# 备份配置目录
tar -czf openclaw-backup.tar.gz ~/.openclaw/

# 恢复配置
tar -xzf openclaw-backup.tar.gz -C ~/

自动备份:

{
  "backup": {
    "enabled": true,
    "schedule": "0 2 * * *",
    "retention": 7
  }
}

🐛 故障排除

Q24: 遇到 "access not configured" 错误？

A: 这是配对认证失败的错误。

解决方案:

# 检查配对 token
openclaw config get security.pairing.token

# 重新生成 token
openclaw pairing reset

# 或禁用配对（不推荐）
openclaw config set security.pairing.enabled false

Q25: 提示 "rate limit exceeded" 怎么办？

A: API 请求频率超限。

解决方案:

等待一段时间后重试
升级 API 套餐
启用请求队列：

{
  "rateLimit": {
    "enabled": true,
    "maxRequestsPerMinute": 60,
    "queue": true
  }
}

Q26: 日志文件太大怎么办？

A: 配置日志轮转：

{
  "logging": {
    "level": "info",
    "maxSize": "100MB",
    "maxFiles": 5,
    "compress": true
  }
}

手动清理:

# 清理旧日志
openclaw logs clean --older-than 7d

# 查看日志大小
du -sh ~/.openclaw/logs/

📱 移动端与跨平台

Q27: OpenClaw 是否支持 Android/iOS？

A: OpenClaw 是服务端工具，不直接支持移动端，但可以：

Android:

使用 Termux 运行 OpenClaw
通过 Telegram/Discord 等 App 交互

iOS:

在服务器上部署 OpenClaw
通过 Telegram/Discord 等 App 交互

推荐方案: 在云端或本地服务器部署，通过移动端聊天 App 使用。

Q28: 可以在树莓派上运行吗？

A: 可以！

要求:

树莓派 4B 或更新型号
至少 2GB 内存
Raspberry Pi OS (64-bit)

安装:

# 安装 Node.js
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

# 安装 OpenClaw
npm install -g openclaw@latest

🌐 其他问题

Q29: OpenClaw 支持哪些语言？

A: OpenClaw 支持多语言：

界面语言: 中文、英文
AI 对话: 取决于所用模型，主流模型都支持中英文
文档: 提供中英文文档

切换语言:

{
  "language": "zh-CN"
}

Q30: 如何参与 OpenClaw 开发？

A: 欢迎贡献！

报告问题: GitHub Issues
提交代码: Pull Requests
参与讨论: GitHub Discussions
开发技能: 查看技能开发文档
完善文档: 提交文档改进

📚 相关资源

💡 没找到答案？

如果你的问题没有在这里找到答案，可以：

搜索 GitHub Discussions
查看 GitHub Issues
加入社区群组寻求帮助
提交新的问题

我们会持续更新这个 FAQ 页面，添加更多常见问题和解决方案。