gcop-rs

简体中文

English

简体中文

English

Appearance

故障排除 ​

gcop-rs 的常见问题和解决方案。

安装问题 ​

问题: cargo build 失败 ​

解决方案:

bash
# 更新 Rust
rustup update

# 清理并重新编译
cargo clean
cargo build --release

问题: 安装后找不到二进制文件 ​

解决方案:

bash
# 检查二进制文件是否存在
ls -la /usr/local/bin/gcop-rs

# 验证 PATH 包含 /usr/local/bin
echo $PATH

# 如需要添加到 PATH
export PATH="/usr/local/bin:$PATH"

配置问题 ​

问题: "Provider 'xxx' not found in config" ​

原因: Provider 未在 ~/.config/gcop/config.toml 中配置

解决方案:

bash
# 检查配置文件
cat ~/.config/gcop/config.toml

# 复制示例配置
cp examples/config.toml.example ~/.config/gcop/config.toml

# 编辑并添加 provider
vim ~/.config/gcop/config.toml

问题: "API key not found" ​

原因: 配置文件和环境变量中都没有 API key

解决方案:

选项 1: 添加到配置文件

toml
[llm.providers.claude]
api_key = "sk-ant-your-key"

选项 2: 使用环境变量

bash
export ANTHROPIC_API_KEY="sk-ant-your-key"

问题: "Unsupported api_style" ​

原因: 配置中的 api_style 值无效

解决方案: 使用支持的值之一：

  • "claude" - 用于 Anthropic API 兼容服务
  • "openai" - 用于 OpenAI API 兼容服务
  • "ollama" - 用于本地 Ollama

API 问题 ​

问题: "401 Unauthorized" ​

原因: API key 无效或已过期

解决方案:

  1. 验证 API key 是否正确
  2. 检查 key 是否过期
  3. 从 provider 控制台重新生成 key
  4. 更新 config.toml 中的新 key

问题: "429 Rate Limit Exceeded" ​

原因: 请求过多

解决方案:

  1. 稍等片刻再重试
  2. 升级你的 API 计划
  3. 临时切换到其他 provider

问题: "500 Internal Server Error" ​

原因: API 服务暂时不可用

解决方案:

  1. 等待并重试
  2. 检查 provider 的状态页面
  3. 尝试其他 provider

网络问题 ​

问题: "API request timeout" ​

原因: 请求超过 120 秒超时

解决方案:

  1. 检查网络连接
  2. 重试（可能是服务器临时慢）
  3. 如使用代理，验证代理是否工作：
    bash
    curl -x $HTTP_PROXY https://api.openai.com
  4. 请求会自动重试最多 3 次并退避

问题: "API connection failed" ​

原因: 无法建立到 API 服务器的连接

解决方案:

  1. 检查网络连通性：

    bash
    ping 8.8.8.8
curl https://api.openai.com

  2. 验证 API endpoint 正确：

    toml
    [llm.providers.openai]
endpoint = "https://api.openai.com"  # 检查拼写

  3. 检查 DNS 解析：

    bash
    nslookup api.openai.com

  4. 启用详细模式查看重试尝试：

    bash
    gcop-rs -v commit
# 你会看到：
# WARN OpenAI API request failed (attempt 1/4): connection failed. Retrying in 1.0s...
# WARN OpenAI API request failed (attempt 2/4): connection failed. Retrying in 2.0s...

注意: 连接失败会自动重试，使用指数退避（1s, 2s, 4s）。

问题: "网络需要代理" ​

原因: 你的网络需要代理才能访问外部服务

解决方案:

HTTP/HTTPS 代理：

bash
# 临时使用（当前会话）
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
gcop-rs commit

# 永久配置（添加到 ~/.bashrc 或 ~/.zshrc）
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080

SOCKS5 代理：

bash
export HTTP_PROXY=socks5://127.0.0.1:1080
export HTTPS_PROXY=socks5://127.0.0.1:1080

带认证的代理：

bash
export HTTP_PROXY=http://username:password@proxy.example.com:8080
export HTTPS_PROXY=http://username:password@proxy.example.com:8080

验证代理是否工作：

bash
gcop-rs -v commit
# 查找：
# DEBUG reqwest::connect: proxy(http://127.0.0.1:7890/) intercepts 'https://api.openai.com/'

绕过特定域名的代理：

bash
export NO_PROXY=localhost,127.0.0.1,.local

问题: 即使自动重试仍然遇到限流 ​

原因: 429 错误在重试后依然存在

解决方案:

  1. 等待更长时间 - 重试机制使用指数退避，但你可能需要等待几分钟
  2. 检查 API 使用情况，在 provider 控制台查看
  3. 升级套餐，如果你在免费层
  4. 临时切换 provider：
    bash
    gcop-rs --provider claude commit  # 切换 provider

理解自动重试 ​

从 v0.1.6 开始，gcop-rs 会自动重试失败的请求：

会被重试的错误：

  • ✅ 连接失败
  • ✅ 429 限流错误
  • ❌ 401/403 认证错误（不重试）
  • ❌ 400 请求格式错误（不重试）

重试策略：

  • 最多重试 3 次（总共 4 次尝试）
  • 指数退避：1s → 2s → 4s
  • 在详细模式（-v）下可见

重试日志示例：

WARN  OpenAI API request failed (attempt 1/4): connection failed. Retrying in 1.0s...
WARN  OpenAI API request failed (attempt 2/4): connection failed. Retrying in 2.0s...
INFO  OpenAI API request succeeded after 3 attempts

问题: "Failed to parse Claude/OpenAI response" ​

原因: API 响应格式异常

解决方案:

bash
# 使用详细模式查看原始响应
gcop-rs -v commit

# 在调试输出中查找
# 查找 "Claude API response body:" 或 "OpenAI API response body:"

代码审查问题 ​

问题: "Failed to parse review result" ​

原因: LLM 没有返回有效的 JSON

解决方案:

  1. 使用详细模式查看原始响应：

    bash
    gcop-rs -v review changes

  2. 检查自定义 prompt（如果使用）：

    • 确保明确要求 JSON 格式
    • 提供准确的 JSON schema 示例

  3. 尝试不同模型：

    bash
    # 某些模型处理 JSON 更好
gcop-rs --provider openai review changes

  4. 调整 temperature：

    toml
    temperature = 0.1  # 更低 = 更一致的输出

Git 问题 ​

问题: "No staged changes found" ​

原因: Git 暂存区为空

解决方案:

bash
# 先暂存变更
git add <files>

# 或暂存所有变更
git add .

# 然后运行 gcop
gcop-rs commit

问题: "Not a git repository" ​

原因: 当前目录不是 git 仓库

解决方案:

bash
# 初始化 git 仓库
git init

# 或在 git 仓库中运行 gcop
cd /path/to/your/git/repo

调试模式 ​

对于任何问题，启用详细模式获取详细信息：

bash
gcop-rs -v commit
gcop-rs -v review changes

这会显示：

  • 配置加载过程
  • API 请求和响应
  • 发送给 LLM 的 prompt
  • 响应解析过程

获取帮助 ​

如果遇到这里未列出的问题：

  1. 使用 --verbose 运行并检查日志
  2. 查看配置参考
  3. 查看 Provider 设置指南
  4. 在 GitHub 上开 issue，包括：
    • 你的配置文件（删除 API keys！）
    • 运行的命令
    • 错误信息
    • gcop-rs -v 的输出（删除敏感信息）

参考 ​