企业官网建设流程全解析

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。