HCLIer

常见问题

2026-09-01

H CLIer 常见问题

本文档收集了用户常见的问题和解答。

安装问题

Q1：安装时提示"Windows 已保护你的电脑"

原因：新软件需要时间建立信誉，Windows Defender 会发出警告。

解决方法：

  1. 点击"更多信息"
  2. 点击"仍要运行"
  3. 如果仍有问题，可以暂时关闭 Windows Defender 实时保护

Q2：安装失败

可能原因：

  1. 权限不足：以管理员身份运行安装程序
  2. 磁盘空间不足：清理磁盘空间
  3. 杀毒软件拦截：暂时关闭杀毒软件

Q3：启动时崩溃

可能原因：

  1. WebView2 未安装：Windows 10/11 通常已预装，如果没有，请从 Microsoft 官网下载
  2. 显卡驱动问题：更新显卡驱动
  3. 系统版本过低：确保 Windows 版本 >= 10

Claude CLI 问题

Q4：Claude CLI 未检测到

解决方法：

  1. 确保已安装 Claude Code CLI：
    bash npm install -g @anthropic-ai/claude-code

  2. 检查 PATH 环境变量是否包含 npm 全局目录

  3. 在设置中手动指定 Claude CLI 路径

Q5：Claude CLI 启动失败

可能原因：

  1. Node.js 版本过低：需要 Node.js >= 18
  2. 网络问题：检查网络连接和代理设置
  3. API Key 未配置：确保已配置 Anthropic API Key

Q6：会话无法恢复

可能原因：

  1. 会话 ID 无效：会话可能已过期或被删除
  2. 项目路径变更：项目目录可能已移动或删除
  3. 权限问题：检查文件权限

终端问题

Q7：终端显示乱码

解决方法：

  1. 打开设置
  2. 选择"终端"选项卡
  3. 将编码设置为 "UTF-8"

Q8：终端无法输入

可能原因：

  1. 焦点问题：点击终端区域获取焦点
  2. PTY 实例崩溃：重启会话
  3. 系统资源不足：关闭其他程序释放资源

Q9：终端历史丢失

原因：终端历史存储在本地日志文件中。

解决方法：

  1. 检查日志目录：%APPDATA%/com.hcl-ier.dev/terminal_logs/
  2. 确保目录存在且有写入权限
  3. 检查磁盘空间

Token 统计问题

Q10：Token 统计不准确

可能原因：

  1. 文件未更新：Claude 可能还在写入，等待几秒后刷新
  2. 文件路径错误：检查 Claude 的会话目录是否正确
  3. 格式变更：Claude 更新了 JSONL 格式，等待 H CLIer 更新

Q11：Token 统计为 0

可能原因：

  1. 未使用 Claude 会话：只有 Claude 会话才会统计 Token
  2. JSONL 文件不存在：检查 Claude 的会话目录
  3. 权限问题：检查文件读取权限

Q12：费用估算不准确

原因：费用估算基于 Anthropic 官方定价，实际费用可能因：

  1. 定价调整
  2. 免费额度
  3. 优惠活动

检查点问题

Q13：检查点创建失败

可能原因：

  1. 磁盘空间不足：清理磁盘空间
  2. 文件被占用：关闭正在使用这些文件的程序
  3. 权限不足：以管理员身份运行

Q14：检查点回滚失败

可能原因：

  1. 文件被占用：关闭正在使用这些文件的程序
  2. 权限不足：以管理员身份运行
  3. 磁盘空间不足：清理磁盘空间

Q15：检查点数量限制

说明：

  • 免费版：每项目最多 3 个检查点
  • Pro 版：无限制

性能问题

Q16：应用启动缓慢

优化方法：

  1. 减少开机自启项
  2. 使用 SSD 硬盘
  3. 保持软件更新
  4. 减少同时打开的会话数量

Q17：内存占用过高

优化方法：

  1. 关闭不使用的会话
  2. 定期清理检查点
  3. 限制终端历史记录长度
  4. 重启应用

Q18：CPU 占用过高

可能原因：

  1. 终端输出过多：减少终端历史记录长度
  2. Token 统计扫描：等待扫描完成
  3. 后台任务：检查是否有其他程序占用

网络问题

Q19：无法连接到 Claude API

可能原因：

  1. 网络问题：检查网络连接
  2. 代理设置：配置正确的代理
  3. 防火墙：检查防火墙设置
  4. API Key 问题：检查 API Key 是否有效

Q20：自动更新失败

解决方法：

  1. 检查网络连接
  2. 手动下载更新：https://github.com/Fancyhe1/H-CLIer/releases
  3. 检查代理设置

数据问题

Q21：会话数据丢失

原因：会话数据存储在 SQLite 数据库中。

解决方法：

  1. 检查数据库文件：%APPDATA%/com.hcl-ier.dev/sessions.db
  2. 检查备份（如果有）
  3. 联系开发者

Q22：配置文件损坏

解决方法：

  1. 删除配置文件：%APPDATA%/com.hcl-ier.dev/config/config.json
  2. 重启应用
  3. 重新配置

其他问题

Q23：如何导出会话？

方法：

  1. 右键会话
  2. 选择"导出"
  3. 选择保存位置
  4. 导出的文件为 JSON 格式

Q24：如何导入会话？

方法：

  1. 点击侧边栏 "+" 按钮
  2. 选择"导入会话"
  3. 选择 JSON 文件
  4. 确认导入

Q25：如何联系开发者？

方式：

  • GitHub Issues：https://github.com/Fancyhe1/H-CLIer/issues
  • 邮箱：[待添加]

反馈问题

如果以上解答无法解决你的问题，请通过以下方式反馈：

  1. GitHub Issues（推荐）：https://github.com/Fancyhe1/H-CLIer/issues
  2. 提供以下信息：
  3. 操作系统版本
  4. H CLIer 版本
  5. 错误信息或截图
  6. 复现步骤

最后更新：2026-07-12