跳到主要内容

故障排除

本文档帮助您解决 OpenHuman 使用中的常见问题。

认证问题​

API 密钥无效​

症状： 调用 API 时返回 401 Unauthorized

解决方案：

  1. 检查 API 密钥是否正确设置
  2. 确认密钥未过期
  3. 验证环境变量配置
echo $OPENHUMAN_API_KEY

OAuth 连接失败​

症状： 集成 OAuth 连接时出错

解决方案：

  1. 确认集成服务账号未被封禁
  2. 检查 OAuth scopes 权限
  3. 重新授权集成

网络问题​

请求超时​

症状： API 请求超时

解决方案：

  1. 检查网络连接
  2. 增加超时时间配置
  3. 使用重试机制
const client = new OpenHuman({
  apiKey: process.env.OPENHUMAN_API_KEY,
  timeout: 60000,  // 60 秒
});

远程 Core 无法连接​

症状： 远程 core 连接失败

解决方案：

  1. 确认远程 core URL 可访问
  2. 验证 token 正确性
  3. 检查防火墙设置
curl -I https://your-core.example/rpc

记忆树问题​

记忆检索不准确​

症状： recall 返回不相关的结果

解决方案：

  1. 使用更精确的查询词
  2. 指定 scope 缩小范围
  3. 检查记忆是否正确存储
const memories = await client.memory.recall({
  query: '用户对哪些话题感兴趣',
  scope: 'user_preference',
  limit: 5,
});

记忆存储失败​

症状： store 操作失败

解决方案：

  1. 检查磁盘空间
  2. 确认数据库文件未损坏
  3. 验证写入权限

工具问题​

工具调用失败​

症状： 工具执行时出错

解决方案：

  1. 检查工具参数是否正确
  2. 确认网络连接正常
  3. 查看具体错误信息
try {
  const result = await client.tools.execute('web-search', {
    query: 'test',
  });
} catch (error) {
  console.error('工具错误:', error.message);
}

浏览器控制无响应​

症状： 浏览器控制操作无反应

解决方案：

  1. 确认 CEF 浏览器已安装
  2. 检查浏览器进程是否运行
  3. 重启浏览器控制会话

性能问题​

响应缓慢​

症状： Agent 响应时间过长

解决方案：

  1. 减少上下文长度
  2. 使用流式响应
  3. 考虑使用更轻量的模型

Token 用量过高​

症状： Token 消耗超出预期

解决方案：

  1. 启用 token 压缩
  2. 减少历史消息
  3. 限制 recall 返回数量

部署问题​

Docker 容器启动失败​

症状： 容器无法启动

解决方案：

  1. 检查端口是否被占用
  2. 验证环境变量配置
  3. 查看容器日志
docker logs openhuman-container

云端部署连接失败​

症状： 云端部署后无法连接

解决方案：

  1. 确认安全组规则配置
  2. 检查域名 DNS 解析
  3. 验证 SSL 证书

获取帮助​

如果问题仍未解决：

  1. 查看 GitHub Issues
  2. 查阅 官方文档
  3. 加入社区讨论