OpenCode 操作指导书（八）：常见问题与最佳实践

适用版本：OpenCode v1.18.3
本篇目标：汇总安装/认证/模型报错排查、省钱与隐私建议、性能与上下文管理，以及推荐工作习惯。

1. 安装与启动问题

Q1：opencode 命令找不到

• 检查安装目录是否在 PATH：echo $PATH，确认含 ~/.opencode/bin 或 ~/.local/bin。
• 重新执行安装脚本，或显式设置 OPENCODE_INSTALL_DIR 后重装。
• Windows 优先用 WSL；原生可用 scoop/choco 或下载 Release 二进制。

Q2：Windows 自动安装失败

• 使用 WSL2：wsl --install，在 Ubuntu 内按 Linux 方式安装。
• 或直接从 Releases 取 opencode-windows-*.zip 解压到 PATH。

Q3：升级失败 / 想回退

opencode upgrade v1.18.3     # 升到指定版本
opencode upgrade             # 升到最新

2. 认证与模型问题

Q4：opencode auth login 后模型仍不可用

• 确认 Key 环境变量已导出：echo $ANTHROPIC_API_KEY。
• 检查提供方是否在 enabled_providers 白名单、未被 disabled_providers 屏蔽。
• 列出已认证：opencode auth list；必要时 opencode auth logout <p> 后重登。

Q5：模型名称怎么查？

opencode models                 # 全部
opencode models anthropic       # 指定提供方
opencode models --refresh       # 刷新缓存（提供方上新模型时用）

Q6：提示模型不存在 / 404

• 用 opencode models 复制准确的 provider/model 字符串填入配置 model 字段。
• 部分模型需 --enable-experimental 或 OPENCODE_ENABLE_EXPERIMENTAL_MODELS=true。

3. 省钱与模型选择

• 日常编码：用 Claude Sonnet 级别兼顾质量与成本；轻量任务（标题/总结）交给 small_model（如 Haiku）。
• 本地模型：对隐私/成本敏感场景，配置 Ollama 等本地提供方，零 API 费用。
• 自有订阅：可用 GitHub Copilot / ChatGPT Plus·Pro 登录，复用既有权益。
• 避免浪费：开启 Plan 模式先确认方案，减少无效 Build 调用；长会话及时 /compact。

4. 隐私与数据安全

• OpenCode 不上传你的源代码与上下文数据；推理仅通过你配置的提供方 API 进行。
• 敏感项目：使用本地模型或私有部署提供方；不要将 Key 写进会提交的配置文件，用 {env:}/{file:}。
• 分享会话前确认不含密钥；可用 OPENCODE_AUTO_SHARE=false 关闭自动分享。

5. 性能与上下文管理

6. 推荐工作习惯

1. 先 /init：让 OpenCode 理解项目，后续更准。
2. 复杂改动走 Plan：减少返工。
3. 权限渐进放开：熟悉后对相关命令设 allow。
4. 小步快跑：一次聚焦一个清晰任务，比大而全的指令效果更好。
5. 善用 @引用 与图片：给足上下文，模型少猜。
6. 多会话并行：探索类用 explore 子 Agent，主会话保持专注。

7. 故障排查清单

8. 进阶资源

• 官方文档：https://opencode.ai/docs
• 配置 Schema：https://opencode.ai/config.json ｜ TUI：https://opencode.ai/tui.json
• 模型列表：https://models.dev
• 仓库与 Issue：https://github.com/anomalyco/opencode

至此，八篇指导书完结。建议按 01→08 顺序通读并实操案例 1–6，即可熟练掌握 OpenCode v1.18.3。

本篇为 OpenCode 操作指导书系列之一，版本 v1.18.3。