Docs指南更新与故障排除
返回文档
指南

更新与故障排除

更新 YeePilot、排查常见问题并管理您的安装

最后更新: 2026年3月1日

更新 YeePilot

YeePilot 内置了更新程序，可以直接从命令行下载和安装新版本。

检查更新

查看是否有新版本可用而不安装：

bash
yeepilot update --check

这显示当前版本、最新可用版本以及变更内容。

安装最新版本

下载并安装最新版本：

bash
yeepilot update

更新程序将：

  1. 检查最新版本。
  2. 下载适合您平台的二进制文件。
  3. 验证下载校验和。
  4. 替换当前二进制文件。

强制重新安装

如果安装已损坏或您想重新安装同一版本：

bash
yeepilot update --force

即使已经是最新版本，这也会下载并安装最新版本。

回滚到上一版本

如果新版本引入了问题，回滚到之前安装的版本：

bash
yeepilot update --rollback

YeePilot 保留了上一个二进制文件的备份以实现回滚。回滚仅适用于最近一次更新 -- 您无法回滚多个版本。

自动更新

默认情况下，YeePilot 每小时自动检查更新，并在有新版本可用时通知您。

配置

yaml
# ~/.yeepilot/config.yaml
update:
  auto_check: true
  check_interval_hours: 1

禁用自动更新检查

如果您偏好手动管理更新：

yaml
update:
  auto_check: false

或通过环境变量：

bash
export YEEPILOT_UPDATE_AUTO_CHECK=false

调整检查频率

降低检查频率以减少网络请求：

yaml
update:
  check_interval_hours: 24  # 每天一次

排查常见问题

"Connection refused" 或 "Connection timed out"

**症状：**YeePilot 无法连接到 AI 提供商 API。

原因和解决方案：

  1. API 密钥无效 -- 验证您的 API 密钥是否正确：

    bash
    yeepilot status

    如果密钥错误，重新配置：

    bash
    yeepilot setup --auth

  2. 提供商 URL 错误 -- 如果使用自定义 base_url，验证其可达性：

    bash
    curl -I https://api.openai.com/v1/models

  3. 网络问题 -- 检查您的网络连接以及代理/防火墙设置。如果您在公司代理后面，确保其允许到 AI 提供商 API 端点的 HTTPS 流量。

  4. 沙箱阻止网络 -- 如果 sandbox.network_access 设为 false，YeePilot 执行的命令无法访问网络。但 YeePilot 自身的 API 调用不受沙箱设置影响。此错误更可能来自网络配置。

"Model not found" 或 "Invalid model"

**症状：**AI 提供商拒绝模型 ID。

原因和解决方案：

  1. 模型 ID 不正确 -- 模型标识符是提供商特定的。验证您使用的格式正确：

    提供商示例模型 ID
    OpenAIgpt-4o, gpt-4o-mini
    Anthropicclaude-sonnet-4-20250514
    OpenRouteropenai/gpt-4o, anthropic/claude-sonnet-4-20250514

  2. 模型访问未启用 -- 某些模型需要提供商的明确访问批准。检查您的提供商仪表板以确保您有权访问该模型。

  3. 提供商不匹配 -- 确保模型 ID 与配置的提供商匹配。Anthropic 模型 ID 不能在 OpenAI 提供商设置下使用。

    yaml
    # 正确：模型与提供商匹配
ai:
  provider: anthropic
  model: claude-sonnet-4-20250514
 
# 错误：Anthropic 模型配合 OpenAI 提供商
ai:
  provider: openai
  model: claude-sonnet-4-20250514

"Permission denied"

**症状：**YeePilot 无法执行命令或访问文件。

原因和解决方案：

  1. 二进制文件权限 -- YeePilot 二进制文件需要执行权限：

    bash
    chmod +x /usr/local/bin/yeepilot

  2. 安装位置 -- 如果安装到 /usr/local/bin/ 需要 root 权限，使用 sudo：

    bash
    sudo curl -fsSL https://yee.to/install.sh | bash

  3. 沙箱禁止路径 -- 检查目标路径是否在 sandbox.denied_paths 列表中：

    yaml
    sandbox:
  denied_paths:
    - "/etc/shadow"  # 命令无法访问此路径

  4. 文件所有权 -- 确保配置目录归您的用户所有：

    bash
    ls -la ~/.yeepilot/
# 如果归 root 所有：
sudo chown -R $(whoami) ~/.yeepilot/

"Keyring not available" 或凭据存储错误

**症状：**YeePilot 无法从系统密钥环存储或检索 API 密钥。

原因和解决方案：

  1. Linux：安装 libsecret-tools

    bash
    # Ubuntu / Debian
sudo apt install libsecret-tools
 
# Fedora / CentOS
sudo dnf install libsecret
 
# Arch
sudo pacman -S libsecret

  2. Linux 无图形界面服务器：无密钥环守护程序 -- 在没有桌面环境的服务器上，YeePilot 回退到 ~/.yeepilot/credentials.json 加密 JSON 文件。如果此回退不起作用，确保配置目录存在且可写：

    bash
    mkdir -p ~/.yeepilot
chmod 700 ~/.yeepilot

  3. macOS：钥匙串访问提示 -- 如果钥匙串提示反复出现，点击始终允许以授予 YeePilot 永久访问权限。

  4. 使用环境变量作为替代方案 -- 如果凭据存储持续出现问题，通过环境变量设置 API 密钥：

    bash
    export OPENAI_API_KEY=sk-...

沙箱错误

**症状：**命令因命名空间或沙箱相关错误而失败。

原因和解决方案：

  1. 用户命名空间已禁用 -- 某些 Linux 内核或加固配置禁用了用户命名空间。检查：

    bash
    cat /proc/sys/kernel/unprivileged_userns_clone

    如果输出为 0，要么启用它：

    bash
    sudo sysctl kernel.unprivileged_userns_clone=1

    要么禁用命名空间沙箱：

    yaml
    sandbox:
  use_namespaces: false

  2. macOS 或 Windows -- 这些平台不支持命名空间沙箱。YeePilot 会自动禁用它，但如果看到错误，请明确设置：

    yaml
    sandbox:
  use_namespaces: false

  3. 沙箱限制过严 -- 如果合理的命令被阻止，调整限制：

    yaml
    sandbox:
  max_cpu_seconds: 600    # 从 300 增加
  max_memory_mb: 1024     # 从 512 增加
  max_processes: 128      # 从 64 增加

"Token limit exceeded" 或上下文过大

**症状：**AI 提供商因消息过长而拒绝请求。

原因和解决方案：

  1. 减少对话历史 -- 更少的消息意味着更少的上下文需要发送：

    yaml
    ai:
  conversation_max_history: 5

  2. 减少输出截断 -- 限制包含的命令输出量：

    yaml
    ai:
  output_truncate_length: 200

  3. 启用 Token 节省模式 -- 更积极地压缩上下文：

    yaml
    ai:
  token_mode: saver

  4. 开始新会话 -- 如果当前会话积累了过多上下文，重新开始。AI 不会在会话之间传递上下文。

TUI 显示问题

**症状：**输出乱码、方框绘制字符损坏或颜色缺失。

原因和解决方案：

  1. 使用现代终端 -- 较旧的终端可能不支持 Unicode 或真彩色。在 Windows 上使用 Windows Terminal。在 Linux 上使用任何现代终端模拟器（GNOME Terminal、Konsole、Alacritty、Kitty）。

  2. 检查区域设置 -- 确保您的区域设置支持 UTF-8：

    bash
    locale

    如果 LANG 不以 .UTF-8 结尾，请设置：

    bash
    export LANG=en_US.UTF-8

  3. 切换主题 -- 如果颜色看起来不正确，尝试不同的主题：

    yaml
    tui:
  theme: dark  # 或 light、neon、auto

  4. 禁用实时流面板 -- 如果实时面板导致闪烁：

    yaml
    tui:
  live_stream_panel_enabled: false

重置配置

如果配置文件损坏或您想重新开始：

bash
yeepilot setup --reset

这会使用默认值重新生成 ~/.yeepilot/config.yaml 并再次引导您完成设置向导。

手动重置，删除配置文件并运行设置：

bash
rm ~/.yeepilot/config.yaml
yeepilot setup

卸载 YeePilot

完全卸载

移除二进制文件、配置、审计日志、保险库和所有存储的数据：

bash
yeepilot uninstall --all

保留配置

移除二进制文件但保留配置文件（如果计划重新安装，这很有用）：

bash
yeepilot uninstall --keep-config

仅二进制文件

仅移除二进制文件，其他一切保持不变：

bash
yeepilot uninstall --binary-only

手动卸载

如果 uninstall 命令不可用或二进制文件缺失：

Linux/macOS：

bash
sudo rm /usr/local/bin/yeepilot
rm -rf ~/.yeepilot

Windows（PowerShell）：

powershell
Remove-Item "C:\Program Files\YeePilot\yeepilot.exe"
Remove-Item -Recurse "$env:USERPROFILE\.yeepilot"

记得在 Windows 上同时从 PATH 中移除 C:\Program Files\YeePilot。

获取帮助

如果您遇到此处未涵盖的问题：

  1. 检查版本 -- 确保您运行的是最新版本：

    bash
    yeepilot update

  2. 检查状态 -- 查看当前活动的配置：

    bash
    yeepilot status

  3. 查看审计日志 -- 审计日志可能包含错误详情：

    bash
    tail -50 ~/.yeepilot/audit.log

  4. 访问网站 -- 查看 yee.to (opens in new tab) 获取最新文档和公告。

上一篇

最佳实践

Guides