❓ 常见问题 FAQ

Q: 安装失败怎么办？

原因：Node.js 版本不够或缺少构建工具 解决：

1. 确保 Node.js >= v22：node --version
2. 运行 pnpm approve-builds 批准原生模块
3. macOS 需要 Xcode CLT：xcode-select --install

Q: Gateway 启动后机器人不回消息？

原因：API Key 未配置或通道未启用 解决：

1. 检查 openclaw doctor --non-interactive
2. 确认 channels.telegram.enabled: true
3. 确认 models.providers 里有正确的 API Key
4. 检查 channels.telegram.botToken 是否正确

Q: Token 超限 / 上下文溢出？

原因：对话太长，超过模型的 context window 解决：

1. 发送 /compact 手动压缩
2. 发送 /new 开启新会话
3. 调整 contextWindow 或 reserveTokensFloor

Q: 子代理无输出（返回空）？

原因：模型在子代理环境中表现不稳定，或任务描述不够具体 解决：

1. 任务描述要极其详细（子代理看不到主会话上下文）
2. 把内容直接写在 task 里，不要让子代理自己去搜
3. 给子代理设置超时：runTimeoutSeconds: 300
4. 检查模型是否支持子代理的工具调用

Q: 记忆丢失？压缩后忘了之前的事？

原因：Compaction 会摘要旧内容，细节可能丢失 解决：

1. 确保 memoryFlush.enabled: true（压缩前自动保存）
2. 重要信息主动写入 MEMORY.md
3. 说「记住这个」让 AI 写入 memory 文件

Q: API Key 401 错误？

原因：Key 无效、过期或格式错误 解决：

1. 检查 openclaw.json 中的 apiKey
2. 确认 Key 前缀正确（sk- 等）
3. 配置多个 auth profile 实现自动轮转

Q: 群聊中机器人不回复？

原因：激活模式设为 mention-only 解决：

1. 在群里 @机器人 触发回复
2. 或修改 channels.telegram.groupPolicy 为 "open"
3. 检查 messages.ackReactionScope