第九章：常见问题 FAQ

这一页专门回答用户最常搜、最容易卡住的问题。你可以把它当成“快速排障入口”，也可以把它发给刚开始接触 OpenCode 的同事。

1. 安装与启动

Q1：安装完成后，为什么还不能直接开始干活？

因为安装只是把 OpenCode 客户端装到了本机。真正开始使用前，你还需要：

• 运行 opencode 进入 TUI。
• 执行 /connect 连接 provider。
• 执行 /models 确认当前可用模型。
• 进入项目后运行 /init 生成 AGENTS.md。

Q2：Windows 用户最容易踩什么坑？

最大的坑通常不是“不能装”，而是“体验不稳定”。复杂项目通常还是建议优先使用 WSL。桌面端如果出现空白页或无法启动，还要优先排查 WebView2 运行时是否缺失。

Q3：Linux 下为什么复制粘贴不顺？

很多时候是系统层剪贴板工具没装好。常见方向是给 X11 装 xclip，或给 Wayland 装 wl-clipboard。

2. 模型与连接

Q4：为什么我明明配置了 provider，却还是找不到模型？

因为“配置写上了”不等于“这个 provider 当前真的暴露了该模型”。最稳妥的方式是：

opencode
/models

先以 OpenCode 实际显示的模型列表为准，不要只靠博客里抄来的模型名。

Q5：国内用户应该先接哪个 provider？

如果你想省心，优先试官方内置路线；如果你更在意成本与访问速度，通常会优先考虑 DeepSeek、Qwen 或企业自己的 OpenAI 兼容网关。

Q6：本地模型路线适合所有人吗？

不适合。Ollama、本地兼容服务更适合内网、隐私优先或原型验证场景。它们在“能否稳定完成工具调用、长链路修改和复杂工程分析”上，和顶级云模型仍有明显差异。

3. 配置与排错

Q7：为什么我的配置明明写了，却没有按预期生效？

因为 OpenCode 的配置是合并而不是替换。常见配置来源包括：

• 远程配置
• 全局配置
• 自定义配置路径或环境变量覆盖
• 项目根目录的 opencode.json
• .opencode 目录

最好直接运行：

opencode debug config

Q8：全局配置和项目配置应该怎么分工？

最简单的经验是：

• 全局配置放个人偏好，例如主题、默认模型、个人插件。
• 项目配置放团队共识，例如默认 agent、watcher ignore、MCP、instructions。
• AGENTS.md 放项目背景、风格要求、工作约束，不要什么都往 JSON 里塞。

Q9：为什么项目越来越卡？

先别急着怪模型。更常见的原因其实是：

• 没有配置 watcher.ignore
• 接了太多插件或 MCP
• 上下文过长，长期不整理任务
• 把所有规则都写成超长 Prompt

4. 插件、命令与扩展

Q10：我应该先学 plugins、commands 还是 MCP？

推荐顺序通常是： commands → plugins → MCP。

• commands 最容易上手，适合沉淀重复 Prompt。
• plugins 适合做安全、通知、环境注入和自定义工具。
• MCP 更适合连接外部系统，例如浏览器、数据库、Jira。

Q11：插件写在本地目录和通过 npm 装，有什么区别？

本地插件适合项目私有逻辑和快速试验；npm 插件适合复用、共享和版本管理。OpenCode 支持两种方式并存，但要记得插件的加载顺序会影响最终覆盖效果。

Q12：最值得先做的 command 是什么？

• /test：跑测试并总结失败原因。
• /review-changes：基于最近 diff 做评审。
• /ship-check：发布前检查关键风险。

5. Agent 使用习惯

Q13：新手默认应该用 build 还是 plan agent？

新手更建议先多用 plan agent。先让它分析、拆计划、指出风险，再切到 build agent 执行。这样更安全，也更容易建立对 OpenCode 的正确预期。

Q14：什么时候需要自定义 agent？

当你发现自己总在重复同一类工作，例如代码评审、写文档、排障分析，就很适合拆成专用 agent。这样你可以给不同 agent 不同模型、不同权限和不同 Prompt。

6. 最后一个建议

OpenCode 真正的门槛，不是“安装命令会不会敲”，而是你能不能把它从一个聊天工具，变成一个可复用、可协作、可约束的工作流系统。