故障排除中心

遇到 Opencode 使用问题？本指南提供了最全面的故障排查和解决方案。

📋 快速导航

常见问题分类

🔥 最常见的问题

1. Opencode Bad Request

症状：

  • API 调用返回 400 错误
  • 提示 "Bad Request"
  • 无法连接到模型

原因：

  • API Key 失效或错误
  • API 配额耗尽
  • 请求格式不正确

解决方案：

# 重新认证
opencode auth login

# 或运行
/connect

# 检查 API Key 状态
cat ~/.config/opencode/auth.json

详细解决方案：Provider 和认证问题

2. 退出 Plan Mode (Exit Plan Mode)

症状：

  • 卡在 Plan 模式无法生成代码
  • AI 只规划不执行

解决方案：

  • 按 Tab 键切换到 Build 模式
  • 或输入 /build 命令
  • 或输入 /reset 重置会话

详细说明：Plan & Build 模式

3. 导出会话 (Export Session)

需求：保存对话记录分享给同事

方法：

# 方法一：生成分享链接
/share

# 方法二：导出为 Markdown
/export

# 方法三：导出为 JSON
/export --format json

会话存储位置：

  • macOS/Linux: ~/.config/opencode/sessions/
  • Windows: %USERPROFILE%\.config\opencode\sessions\

4. Token 超限

症状：

  • 对话到一半报错
  • 提示上下文窗口已满

快速解决：

# 压缩上下文
/compact

# 或开启新会话
/new

长期解决：

编辑 ~/.config/opencode/opencode.json：

{
  "compaction": {
    "auto": true,
    "prune": true
  }
}

详细说明：性能问题

5. 无法读取/修改文件

症状：

  • AI 提示没有权限
  • 文件操作被拒绝

快速解决：

在对话中说明：

我确认要执行这个操作，请忽略权限限制

长期解决：

配置权限：

{
  "permission": {
    "read": {
      "*": "allow"
    },
    "edit": "ask",
    "bash": "ask"
  }
}

详细说明：权限问题

📚 完整故障排查指南

详细问题分类

安装与启动问题

  • 安装后无法启动
  • 启动慢或卡顿
  • 版本过低导致功能不可用

查看详细解决方案 →

配置问题

  • JSON 配置解析失败
  • 配置修改后不生效
  • 模型名称不正确

查看详细解决方案 →

Provider 和认证问题

  • API Key 无效
  • Ollama 连接失败
  • Claude Pro/ChatGPT Plus 认证失败

查看详细解决方案 →

性能问题

  • Token 超限
  • 响应速度慢
  • CPU 占用高

查看详细解决方案 →

权限问题

  • 无法读取/修改文件
  • 命令执行被拒绝

查看详细解决方案 →

Agent 问题

  • Agent 不可用
  • Agent 行为异常

查看详细解决方案 →

🛠️ 诊断工具

健康检查

# 检查配置
opencode config validate

# 检查 Provider
opencode provider list

# 检查 Agent
opencode agent list

# 查看版本
opencode --version

查看日志

# 查看最新日志
tail -f ~/.config/opencode/logs/main.log

# 查看错误日志
cat ~/.config/opencode/logs/error.log

重置配置

# 备份配置
cp -r ~/.config/opencode ~/.config/opencode.backup

# 删除配置（会重新生成默认配置）
rm -rf ~/.config/opencode

🔍 按症状查找

启动相关

连接相关

功能相关

性能相关

💬 获取帮助

如果以上方法都无法解决问题：

官方资源

社区资源

报告 Bug

提交 Bug 时请包含：

  1. Opencode 版本：opencode --version
  2. 操作系统：macOS/Windows/Linux + 版本
  3. 错误日志：~/.config/opencode/logs/error.log
  4. 复现步骤：详细的操作步骤
  5. 配置文件：~/.config/opencode/opencode.json（删除敏感信息）

📖 相关文档

🔧 环境与配置

配置文件位置

  • 全局配置：~/.config/opencode/opencode.json
  • 项目配置：./opencode.json 或 ./.opencode/opencode.json
  • 认证信息：~/.config/opencode/auth.json
  • 会话记录：~/.config/opencode/sessions/
  • 日志文件：~/.config/opencode/logs/

最佳终端推荐

虽然 Opencode 支持所有终端，但以下终端体验最佳：

  1. Ghostty / Kitty - GPU 加速，渲染流畅
  2. iTerm2 / WezTerm - 经典稳定
  3. Windows Terminal - Windows 用户的最佳选择
  4. Alacritty - 轻量高性能

环境变量

# 自定义配置文件位置
export OPENCODE_CONFIG="/path/to/config.json"

# 自定义配置内容
export OPENCODE_CONFIG_CONTENT='{"model":"claude-sonnet-4-5"}'

# 启用调试模式
export OPENCODE_DEBUG=1

本指南持续更新中，如果你遇到了新的问题或有更好的解决方案，欢迎贡献。

最近更新: