常见问题排查

本文汇总了 Opencode 使用过程中最常见的问题和解决方案，帮助你快速排查故障。

安装与启动问题

问题 1：安装后无法启动

症状：

  • 双击图标没反应
  • 命令行运行报错
  • 启动后立即崩溃

可能原因：

  1. 系统权限不足
  2. 依赖缺失
  3. 版本不兼容

解决方案：

macOS：

# 检查是否被系统阻止
xattr -d com.apple.quarantine /Applications/Opencode.app

# 重新安装
brew uninstall opencode
brew install anomalyco/tap/opencode

# 检查版本
opencode --version

Windows：

# 以管理员身份运行
# 右键 Opencode → 以管理员身份运行

# 或重新安装
choco uninstall opencode
choco install opencode

# 检查版本
opencode --version

Linux：

# 检查依赖
ldd /usr/bin/opencode

# 安装缺失的依赖
sudo apt-get install -f

# 检查权限
chmod +x /usr/bin/opencode

问题 2：启动慢或卡顿

症状：

  • 启动需要很长时间
  • 打开文件夹后 CPU 占用高
  • 界面响应缓慢

可能原因：

  • 监控了大型目录（如 node_modules）
  • 索引文件过多
  • 内存不足

解决方案：

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

{
  "watcher": {
    "ignore": [
      "node_modules/**",
      "dist/**",
      "build/**",
      ".git/**",
      ".next/**",
      "target/**",
      "venv/**",
      "__pycache__/**",
      "*.log"
    ]
  },
  // 禁用自动索引（可选）
  "indexing": {
    "auto": false
  }
}

重启 Opencode 后生效。

问题 3：版本过低导致功能不可用

症状：

  • 某些功能无法使用
  • 插件报错
  • 配置不生效

检查版本：

opencode --version

要求：版本需要 >= 1.0.150

更新方法：

macOS：

brew upgrade opencode

Windows：

choco upgrade opencode

Linux：

# 下载最新版本
curl -fsSL https://opencode.ai/install | bash

配置问题

问题 4：JSON 配置解析失败

症状：

  • 配置不生效
  • 启动时报错：JSON parse error
  • 日志显示配置文件错误

可能原因：

  1. JSON 语法错误（多余的逗号、缺少引号）
  2. 在 .json 文件中写了注释

解决方案：

方法一：使用 JSONC 格式

将文件重命名为 .jsonc：

mv ~/.config/opencode/opencode.json ~/.config/opencode/opencode.jsonc

方法二：验证 JSON 语法

使用在线工具验证：jsonlint.com

常见错误：

❌ 错误：

{
  "model": "claude-sonnet-4-5",  // 注释不允许
  "theme": "dark",               // 最后一项有逗号
}

✅ 正确：

{
  "model": "claude-sonnet-4-5",
  "theme": "dark"
}

或使用 JSONC：

{
  "model": "claude-sonnet-4-5",  // 可以写注释
  "theme": "dark"
}

问题 5：配置修改后不生效

症状：

  • 修改了配置文件
  • 重启后仍然使用旧配置

可能原因：

  1. 配置文件位置错误
  2. 配置被其他文件覆盖
  3. 需要重启才能生效

排查步骤：

1. 确认配置文件位置：

# macOS/Linux
ls -la ~/.config/opencode/

# Windows
dir %USERPROFILE%\.config\opencode\

应该看到：

  • opencode.json 或 opencode.jsonc
  • auth.json（如果已登录）

2. 检查配置优先级：

配置优先级（从低到高）：

  1. 全局配置：~/.config/opencode/opencode.json
  2. 项目配置：./opencode.json
  3. 项目目录配置：./.opencode/opencode.json

如果项目配置覆盖了全局配置，需要修改项目配置。

3. 验证配置：

opencode config list

4. 重启 Opencode：

某些配置（如 Provider、插件）需要重启才能生效。

问题 6：模型名称不正确

症状：

  • 运行 /models 看不到想要的模型
  • 提示模型不存在
  • 使用了错误的模型

可能原因：

  • 模型名称拼写错误
  • Provider 未正确配置
  • 插件未安装

解决方案：

1. 检查 Provider 配置：

opencode config get provider

2. 检查插件：

cat ~/.config/opencode/opencode.json | grep plugin

确保包含需要的插件，例如：

{
  "plugin": [
    "opencode-openai-codex-auth@latest",
    "opencode-antigravity-auth@latest"
  ]
}

3. 使用正确的模型名称：

常见模型名称：

  • Claude: anthropic/claude-sonnet-4-5
  • GPT: openai/gpt-5.2
  • DeepSeek: deepseek/deepseek-coder
  • Ollama: ollama/llama3

4. 重新认证：

opencode auth login

Provider 和认证问题

问题 7：API Key 无效

症状：

  • 提示 API Key 错误
  • 无法连接到模型
  • 认证失败

解决方案：

1. 检查 API Key：

# 查看认证信息
cat ~/.config/opencode/auth.json

2. 重新认证：

opencode auth login

3. 检查 API Key 权限：

  • 确保 API Key 未过期
  • 确保 API Key 有足够的配额
  • 确保 API Key 有正确的权限

4. 检查网络连接：

# 测试连接
curl https://api.anthropic.com/v1/messages
curl https://api.openai.com/v1/models

问题 8：Ollama 连接失败

症状：

  • 提示无法连接到 Ollama
  • 模型加载失败

解决方案：

1. 确认 Ollama 正在运行：

# 检查 Ollama 进程
ps aux | grep ollama

# 启动 Ollama
ollama serve

2. 检查端口：

# 默认端口是 11434
curl http://localhost:11434/api/tags

3. 检查配置：

{
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "http://localhost:11434/v1"  // 注意 /v1 后缀
      }
    }
  }
}

4. 确认模型已下载：

# 查看已下载的模型
ollama list

# 下载模型
ollama pull llama3

问题 9：Claude Pro/ChatGPT Plus 认证失败

症状：

  • OAuth 认证失败
  • 提示订阅无效
  • 无法使用订阅模型

解决方案：

1. 确认订阅状态：

  • 登录 Claude.ai 或 ChatGPT 确认订阅有效
  • 确认订阅未过期

2. 清除旧的认证信息：

rm ~/.config/opencode/auth.json

3. 重新认证：

opencode auth login

4. 检查插件版本：

cat ~/.config/opencode/opencode.json | grep plugin

确保使用最新版本：

{
  "plugin": [
    "opencode-openai-codex-auth@latest"
  ]
}

5. 清除浏览器缓存：

OAuth 认证时，清除浏览器的 Cookie 和缓存。

性能问题

问题 10：Token 超限

症状：

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

解决方案：

方法一：手动压缩

/compact

方法二：启用自动压缩

编辑 opencode.json：

{
  "compaction": {
    "auto": true,      // 自动压缩
    "prune": true      // 删除旧的工具输出
  }
}

方法三：使用更大的模型

切换到支持更大上下文的模型：

  • Claude Opus 4.5: 200K tokens
  • GPT-5.2: 128K tokens

方法四：开启新会话

/new

问题 11：响应速度慢

症状：

  • AI 响应需要很长时间
  • 经常超时
  • 界面卡顿

可能原因：

  1. 网络问题
  2. 模型负载高
  3. 上下文过大

解决方案：

1. 检查网络：

# 测试延迟
ping api.anthropic.com
ping api.openai.com

2. 切换到更快的模型：

{
  "small_model": "anthropic/claude-haiku-4-5"  // 更快的模型
}

3. 使用本地模型：

{
  "model": "ollama/deepseek-coder"  // 本地模型，无网络延迟
}

4. 增加超时时间：

{
  "provider": {
    "anthropic": {
      "options": {
        "timeout": 600000  // 10 分钟
      }
    }
  }
}

权限问题

问题 12：无法读取/修改文件

症状：

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

解决方案：

1. 检查权限配置：

opencode config get permission

2. 临时提升权限：

在对话中明确说明：

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

3. 修改权限配置：

{
  "permission": {
    "read": {
      "*": "allow"  // 允许读取所有文件
    },
    "edit": "ask",  // 修改前询问
    "bash": "ask"   // 执行命令前询问
  }
}

4. 检查文件系统权限：

# 检查文件权限
ls -la /path/to/file

# 修改权限
chmod 644 /path/to/file

问题 13：命令执行被拒绝

症状：

  • AI 无法执行命令
  • 提示命令被禁止

解决方案：

1. 检查命令权限：

{
  "permission": {
    "bash": {
      "*": "ask",           // 默认询问
      "git status": "allow" // 允许特定命令
    }
  }
}

2. 临时允许：

在对话中说明：

我确认要执行 [命令]，请执行

3. 添加到白名单：

{
  "permission": {
    "bash": {
      "npm test": "allow",
      "git diff": "allow"
    }
  }
}

Agent 问题

问题 14：Agent 不可用

症状：

  • 运行 /agents 看不到 Agent
  • @ 提及 Agent 无效

解决方案：

1. 检查 Agent 配置：

opencode config get agent

2. 确认 Agent 名称：

运行 /agents 查看可用的 Agent 列表。

3. 检查拼写：

Agent 名称区分大小写：

  • ✅ @architect
  • ❌ @Architect

问题 15：Agent 行为异常

症状：

  • Agent 不按预期工作
  • Agent 修改了不该修改的文件

解决方案：

1. 检查 Agent 配置：

{
  "agent": {
    "my-agent": {
      "prompt": "你的角色定义",  // 检查 prompt 是否清晰
      "tools": {
        "write": false  // 检查工具权限
      }
    }
  }
}

2. 重新定义 Agent：

在对话中明确说明：

@my-agent 你的角色是 [角色定义]，你应该 [行为规范]

3. 使用默认 Agent：

如果自定义 Agent 有问题，先使用默认 Agent：

/agents
# 选择 plan 或 build

其他问题

问题 16：日志在哪里？

日志位置：

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

查看日志：

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

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

问题 17：如何重置配置？

完全重置：

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

# 删除配置
rm -rf ~/.config/opencode

# 重启 Opencode，会生成默认配置

只重置特定配置：

# 只删除认证信息
rm ~/.config/opencode/auth.json

# 只删除配置文件
rm ~/.config/opencode/opencode.json

问题 18：如何报告 Bug？

收集信息：

  1. Opencode 版本：opencode --version
  2. 操作系统版本
  3. 错误日志：~/.config/opencode/logs/error.log
  4. 复现步骤

报告渠道：

诊断工具

健康检查

运行诊断命令：

# 检查配置
opencode config validate

# 检查 Provider
opencode provider list

# 检查 Agent
opencode agent list

# 检查权限
opencode permission check

调试模式

启用详细日志：

{
  "logging": {
    "level": "debug"  // 启用调试日志
  }
}

获取帮助

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

  1. 查看官方文档：opencode.ai/docs
  2. 搜索社区：OpenCodex 社区
  3. 提问：在 GitHub Issues 或社区论坛提问
  4. 联系支持：发送邮件到官方支持

下一步

本文由 OpenCodex 社区整理，如果你遇到了新的问题，欢迎贡献解决方案。

最近更新: