OpenCode 操作指导书八常见问题与最佳实践适用版本OpenCode v1.18.3本篇目标汇总安装/认证/模型报错排查、省钱与隐私建议、性能与上下文管理以及推荐工作习惯。1. 安装与启动问题Q1opencode命令找不到检查安装目录是否在PATHecho $PATH确认含~/.opencode/bin或~/.local/bin。重新执行安装脚本或显式设置OPENCODE_INSTALL_DIR后重装。Windows 优先用 WSL原生可用 scoop/choco 或下载 Release 二进制。Q2Windows 自动安装失败使用 WSL2wsl --install在 Ubuntu 内按 Linux 方式安装。或直接从 Releases 取opencode-windows-*.zip解压到 PATH。Q3升级失败 / 想回退opencode upgrade v1.18.3# 升到指定版本opencode upgrade# 升到最新2. 认证与模型问题Q4opencode 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_MODELStrue。3. 省钱与模型选择日常编码用 Claude Sonnet 级别兼顾质量与成本轻量任务标题/总结交给small_model如 Haiku。本地模型对隐私/成本敏感场景配置 Ollama 等本地提供方零 API 费用。自有订阅可用 GitHub Copilot / ChatGPT Plus·Pro 登录复用既有权益。避免浪费开启 Plan 模式先确认方案减少无效 Build 调用长会话及时/compact。4. 隐私与数据安全OpenCode不上传你的源代码与上下文数据推理仅通过你配置的提供方 API 进行。敏感项目使用本地模型或私有部署提供方不要将 Key 写进会提交的配置文件用{env:}/{file:}。分享会话前确认不含密钥可用OPENCODE_AUTO_SHAREfalse关闭自动分享。5. 性能与上下文管理问题做法上下文过长、变慢/compactLeader→c压缩为摘要想重新开始/clear清屏开新会话重复冷启动慢先opencode serve再用run --attachLSP 下载慢/失败OPENCODE_DISABLE_LSP_DOWNLOADtrue关闭自动下载6. 推荐工作习惯新项目先 /init复杂需求先 Plan 再 Build权限初次逐项确认长会话定期 /compact改错用 /undo结果可分享会话链接先/init让 OpenCode 理解项目后续更准。复杂改动走 Plan减少返工。权限渐进放开熟悉后对相关命令设allow。小步快跑一次聚焦一个清晰任务比大而全的指令效果更好。善用引用与图片给足上下文模型少猜。多会话并行探索类用explore子 Agent主会话保持专注。7. 故障排查清单渲染错误:Mermaid 渲染失败: Lexical error on line 7. Unrecognized text. ... --|点错| Z5[/undo 回退] -----------------------^8. 进阶资源官方文档https://opencode.ai/docs配置 Schemahttps://opencode.ai/config.json TUIhttps://opencode.ai/tui.json模型列表https://models.dev仓库与 Issuehttps://github.com/anomalyco/opencode至此八篇指导书完结。建议按01→08顺序通读并实操案例 1–6即可熟练掌握 OpenCode v1.18.3。本篇为 OpenCode 操作指导书系列之一版本 v1.18.3。
