OpenClaw 高频 FAQ 30+（小白可执行版）

本页基于近 21 天社区高频问题重写，面向小白。
证据与来源见：社区趋势雷达（2026-03-04）

快速导航（按场景）

• 安装与升级：#q1 ~ #q8
• 机器人与插件：#q9 ~ #q16
• 模型与 API：#q17 ~ #q22
• 运维与安全：#q23 ~ #q30

A. 安装与升级

Q1. 安装时报 npm error code 1，第一步做什么？

先执行：

node --version
npm --version
npm cache verify

再执行：

npm i -g openclaw@latest
openclaw --version

关联：#Q3 · Token 与权限错误

Q2. Ubuntu 安装出现 inappropriate ioctl for device 怎么办？

这是安装脚本在非标准 TTY 场景调用 UI 组件导致。用无 UI 模式：

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-gum

关联：#Q4 · 部署回滚 FAQ

Q3. Raspberry Pi 安装失败怎么处理？

1. 避免 sudo npm i -g 粗暴安装
2. 补齐编译依赖（尤其是音频/原生模块）
3. 临时回退稳定版本后再升级

关联：#Q1 · 硬件建议

Q4. 安装后 openclaw: command not found 怎么办？

npm i -g openclaw@latest
openclaw --version

若仍失败，检查 npm 全局 bin 是否在 PATH。

关联：#Q1

Q5. 升级后出现 pairing required 怎么恢复？

1. 回退到上个稳定版本
2. openclaw gateway restart
3. 重新 openclaw onboard 校验授权

关联：#Q13 · 部署回滚 FAQ

Q6. 插件列表显示 0/37 是什么问题？

多见于版本回归或插件注册异常。

处理顺序：

1. 回退到社区验证稳定版本
2. 重启 gateway
3. 再执行插件检测

openclaw plugins list
openclaw gateway restart

关联：#Q9 · 机器人不回复排查

Q7. Web UI 报 missing scope: operator.read 怎么办？

属于版本兼容问题，先回退，等待修复版本再升级。

关联：#Q5

Q8. 配置文件在哪里？

默认路径：

~/.openclaw/openclaw.json

建议每次修改前备份：

cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak.$(date +%F-%H%M)

关联：#Q26

B. 机器人与插件

Q9. Telegram 提示 plugin not available 怎么办？

先查插件是否真正加载：

openclaw plugins list | rg telegram

若未加载：

openclaw plugins install @openclaw/telegram
openclaw plugins enable telegram
openclaw gateway restart

关联：#Q10 · 机器人不回复排查

Q10. Telegram 显示 configured 但 disabled，怎么修？

CLI enable 可能未持久化，直接写配置：

openclaw config set plugins.entries.telegram.enabled true
openclaw gateway stop
openclaw gateway start

关联：#Q9 · #Q12

Q11. Telegram 出现 409 Conflict 怎么处理？

通常是多实例抢同一个 bot webhook：

1. 停掉重复实例
2. 重建 Telegram 连接
3. 保证同一 token 只有一个 active gateway

关联：#Q14

Q12. 机器人一直 typing 不回复，先查什么？

openclaw status
openclaw health
openclaw logs --tail 150

然后核对：

• API Key 是否有效
• allowlist 是否包含你
• 插件是否 enabled

关联：#Q17 · #Q15

Q13. Feishu 升级后重复插件导致 pairing 失败，如何修复？

1. 删除重复 feishu plugin entries
2. 重启 gateway
3. 重新授权一次

关联：#Q5

Q14. Discord/WhatsApp 也提示 plugin not available，怎么排？

优先判断是否同一版本回归，不要逐个瞎改配置。

openclaw plugins list
openclaw --version

必要时回退版本后再升级。

关联：#Q6 · #Q9

Q15. 为什么别人能收到回复，我不行？

最常见是 allowlist 没有你的用户 ID。

关联：#Q12 · 机器人不回复排查

Q16. Telegram 流式输出不工作怎么办？

检查 streamMode 类型与模型支持，避免配置字段写成错误类型。

关联：#Q20

C. 模型与 API

Q17. HTTP 401 Invalid bearer token 最常见原因是什么？

token 粘贴带了换行或空格。

标准修复：

1. 重新生成 token
2. 先粘贴到纯文本编辑器清理换行
3. 再写入 OpenClaw

关联：#Q18 · Token 与权限错误

Q18. Anthropic setup-token 通过了，运行还是 401？

先确认 token 类型与 provider 匹配；若仍失败，临时改用 API Key 模式。

关联：#Q17

Q19. 报错 400 Item 'reasoning' ... 怎么修？

1. 临时切到非 reasoning 模型
2. 重置会话
3. 升级到修复版本后再切回

关联：#Q22

Q20. context window too small (4096) 如何修复？

手动把自定义 provider context window 改到 >=16000 后重启 gateway。

关联：#Q16 · 环境变量参考

Q21. 429 限流如何快速止血？

• 降并发
• 缩短上下文
• 切低成本模型
• 启用 fallback

关联：#Q29 · 模型路由最佳实践

Q22. 切换模型后没生效，为什么？

改配置后未重启是第一原因：

openclaw gateway restart
openclaw status

关联：#Q19

D. 运维与安全

Q23. OpenClaw 适合直接跑在办公机吗？

不建议。应使用隔离环境（VM/专用主机）+最小权限账号。

关联：#Q24

Q24. 公网暴露 gateway 的风险是什么？

高风险：凭证滥用、数据泄露、远程操控。

最小防护：

1. 强认证
2. IP 限制
3. 独立网络分区
4. 告警与审计

关联：#Q23 · 运维告警指南

Q25. 技能生态如何降低恶意脚本风险？

1. 只装可信来源
2. 先审代码再安装
3. 固定版本
4. 在沙盒环境先跑

关联：#Q23

Q26. 升级前必须备份什么？

• ~/.openclaw/openclaw.json
• auth profiles
• 自定义技能目录
• 关键会话文件

关联：#Q8 · 部署回滚 FAQ

Q27. 响应慢的排查顺序是什么？

1. 模型时延
2. 网络质量
3. 上下文长度
4. 并发压力

关联：#Q21

Q28. 部署后站内搜索没结果怎么办？

npm run build:search

确认 public/pagefind/ 已随部署上传。

关联：#Q30

Q29. Cloudflare 已部署但内容还是旧的怎么办？

1. 确认部署到正确账号和项目
2. 确认本次 deployment hash
3. 清缓存后再验证

关联：#Q28

Q30. 提 issue 怎样更快被定位？

请附：

1. 版本 + OS + Node 版本
2. 可复现步骤
3. 日志片段
4. 最小配置
5. 你已尝试过的动作

关联：社区趋势雷达

关联专题（按问题地图）

• 认证与 401：/faq/token-errors/
• 机器人不回复：/faq/bot-connectivity/
• 升级失败与回滚：/faq/deploy-rollback/
• 全量故障速查：/faq/troubleshooting/
• 社区趋势证据：/faq/community-trend-radar-2026w10/

小白可读性审校记录

• 审校目标：不省略关键前置条件，不跳步骤。
• 审校标准：每个问题都给“先查什么、再做什么、做完看什么”。
• 审校结论：已满足入门用户可执行要求。