企业官网建设流程全解析

每次换新工具，我习惯先去翻官方文档把"为什么"搞清楚，而不是上来就复制安装命令。OpenCode 这个开源 AI 编程 CLI 能在 GitHub 上挂出 160K 级别的 star，不是靠界面好看，而是它重新定义了"终端里写代码"这件事。这篇文章我从安装讲到模型接入，再深入到 LSP 集成的底层机制，最后用真实项目把完整工作流串一遍。无论你是第一次听说 AI 编程 CLI，还是已经在用 Codex、Claude Code 想换个更自由的开源方案，这篇都值得你花十分钟读完。

1. 先搞清楚这回事：OpenCode 和 Codex、Claude Code 差在哪

1.1 它是什么：一个跑在终端里的 AI 结对编程 Agent

OpenCode 本质上是一个基于终端 UI（TUI）的 AI 编程 Agent，你可以把它理解成一个"坐进终端里的结对程序员"。它不是简单的补全工具，而是能自己读代码、改代码、执行命令、看结果、再根据结果继续修改的自主型 Agent。启动 opencode 之后，你会进入一个交互式对话界面：左侧是对话区，像聊天一样描述需求；右侧或下方是改动后的 diff 预览；你可以逐行 approve、拒绝，或者让 AI 重新调整。

和传统的"一次性问答"命令行工具不同，OpenCode 是有状态的长会话工具。你可以让它处理一条完整的任务链路：先了解项目结构，再制定修改方案，然后分步实施，最后跑测试看结果。这一点上，它和 GitHub Copilot coding agent、OpenAI Codex CLI、Anthropic Claude Code 属于同一类产品，都在往"一个会写代码的副驾接管整条开发链路"的方向演进。

免费和开源是它最核心的竞争力。你只要有主流模型厂商的 API Key，或者本地有能跑的模型，就能直接用。它不绑架你到某家特定的编辑器，也不要求你买任何订阅套餐，从官网或 GitHub Releases 拉一个二进制就能开工。

1.2 为什么值得用 CLI 而不是 IDE 插件做 AI 编程

很多人的第一反应是：VS Code 里的 AI 插件多如牛毛，为什么还要退回命令行？

我自己的体验是，CLI 形态有三个 IDE 插件替代不了的价值。

第一是沉浸感。IDE 里面永远有文件树、侧边栏、通知、插件图标在分散注意力。AI 生成的代码被各种 UI 包裹，你很难聚焦在"改了什么"和"改得对不对"上。而 CLI 的世界里只有代码和命令，AI 的每次改动都以最原始的 diff 形式怼到你面前，思考的干扰项少了很多。

第二是上下文控制。IDE 插件的自动补全依赖"当前文件加少量索引"，而 CLI Agent 可以通过命令行工具自然而然地扩大搜索范围。它甚至能自己执行git log、rg "functionName"、npm test，然后把输出结果喂回给模型。举个例子，你让它"找出所有调用某某接口的地方"，它可以真的去跑 grep 并把结果一点一点收敛到目标文件上。

第三是可脚本化。只要是命令行工具，它就能被塞进 CI/CD 脚本、能被 alias 包装、能被 tmux 分成多个 pane 同时跑。IDE 插件很难做到这种程度的自动化组合。

1.3 关于 star 数与项目背景的谨慎判断

很多人是被 star 数字吸引过来的，这完全可以理解。160K 级别的 star 说明这个工具踩中了一个大规模需求，同时社区贡献非常活跃。但我要泼一盆冷水：star 多不代表它的成熟度已经超过商业产品。OpenCode 正处在一个快速迭代期，更新频率高、新功能每天都有，但某次升级也可能带来破坏性变更，配置格式说改就改。

因此我的建议是：把它当成一个"处于快速迭代期的工具"来用，而不是当成一个稳定的基础设施来依赖。生产环境里使用，固定一个 release 版本，不要默认自动升级。后面我会具体讲怎么锁版本。

2. 安装环节：三种平台、两种安装方式，以及最容易踩的 PATH 坑

2.1 macOS 与 Linux 的快速安装

在 macOS 上，如果 Homebrew 装好了，两条路都可以走。

第一条路是 Homebrew：

brew install opencode

第二条路是官方安装脚本：

curl -fsSL https://opencode.ai/install | bash

两条路装完之后，二进制所在目录不一样。安装脚本默认放在~/.opencode/bin，Homebrew 会软链到/opt/homebrew/bin（Apple Silicon）或/usr/local/bin（Intel）。如果你后面要同时用 OpenCode 和它的 VSCode 插件、JetBrains 插件，建议让 PATH 里同时包含这两个目录，避免插件找不到可执行文件。

Linux 上同样可以用官方脚本。另外不少发行版也提供了软件包，比如 Debian/Ubuntu 可以直接下 .deb 装，Fedora 有 .rpm。我的习惯是：开发机用官方脚本，因为版本最新；生产环境或者公司统一环境，用系统软件包管理器固定版本，方便回滚。

2.2 Windows 上的安装思路与 PowerShell 报错处理

Windows 是重灾区，因为大量 AI 编程 CLI 生态以 Unix 为中心。很多人在 PowerShell 里走完安装流程，然后遇到一个经典报错：

opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称

这个报错翻译成人话就是：PowerShell 在当前 PATH 环境变量里找不到opencode可执行文件。出现这种情况，通常是因为安装脚本往%USERPROFILE%\.opencode\bin里放了可执行文件，但该目录没有追加进系统 PATH。

你可以先在 PowerShell 里手动追加一次：

$env:PATH = "$env:PATH;$env:USERPROFILE\.opencode\bin"

然后重新打开 PowerShell，再验证：

opencode --version

如果还是报错，建议查一下%USERPROFILE%\.opencode\bin目录下到底有没有opencode.exe。有时候是安装脚本中途被安全软件拦了，文件根本没落盘。

如果你的日常开发环境是 WSL，那我强烈建议直接在 WSL 里按 Linux 的方式安装。原因很简单：OpenCode 在 Linux 环境下的文件权限模型、git hook 机制、子进程调度都更顺畅。Windows 原生跑也能用，但很容易遇到一些玄学问题，比如 LSP 进程路径解析出错、git 命令执行超时等。

2.3 PATH 问题排查链路：从报错定位到最终解决

PATH 问题虽然基础，但值得展开讲一遍完整的排查链路，因为 90% 的"安装失败"最后都落在这。

第一步，先确认可执行文件到底在不在：

ls -la ~/.opencode/bin which opencode

ls检查文件是否真实存在，which检查当前 shell 能不能解析到它。如果ls能看到文件但which找不到，那一定是 PATH 配置问题。

第二步，把二进制目录加进 shell 配置文件。bash 用户改~/.bashrc，zsh 用户改~/.zshrc：

echo 'export PATH="$HOME/.opencode/bin:$PATH"' >> ~/.bashrc source ~/.bashrc

第三步，再次验证：

which opencode opencode --version

如果你用的是 fish shell，语法不太一样，需要改成：

fish_add_path ~/.opencode/bin

还有一个很多人忽略的细节：如果你是在终端已经打开的状态下安装了 OpenCode，PATH 不会自动刷新。要么重新打开一个终端窗口，要么手敲source让配置生效。很多人的报错其实就卡在这一步。

2.4 确认安装成功：版本号与配置文件初建

安装完成后，先跑一下：

opencode --version

看到版本号说明二进制没问题。接着我建议跑一下诊断命令，不同版本的命令名略有差异，可能是opencode doctor也可能是opencode debug，它会把当前环境、可用的 provider、配置文件路径、默认模型全部打印出来。这个命令非常有用，后面配置模型和 LSP 时你会不断回来翻它的输出。

OpenCode 配置文件默认在~/.config/opencode/opencode.json，同时支持项目下的./opencode.json覆盖用户级配置。第一次安装完不一定需要立刻建配置文件，先用默认设置跑通一个对话，再逐步加配置。上来就写一大堆配置，很容易把某个字段写错，然后分不清到底是模型问题还是配置文件问题。

3. 模型接入这一关：官方 API、开源模型、本地模型的一次配齐

3.1 认证的核心机制：auth login 和环境变量的优先级关系

OpenCode 支持多家模型提供商，认证方式却统一得很。运行：

opencode auth login

它会弹出交互式菜单，让你选 provider（Anthropic、OpenAI、Google、DeepSeek、Ollama、其他兼容 OpenAI 的服务等），然后让你粘贴 API Key。

除了交互式登录，OpenCode 也直接读环境变量，常见的有：

• ANTHROPIC_API_KEY
• OPENAI_API_KEY
• GEMINI_API_KEY
• DEEPSEEK_API_KEY

这里有一个极容易踩的坑：环境变量的优先级在多数版本里高于 auth login 保存的凭证。也就是说，如果你在系统里设置了ANTHROPIC_API_KEY，然后又在 opencode.json 里精心配置了另一个 provider，实际请求大概率还是走环境变量指向的那个服务。排查问题的第一件事永远是看环境变量有没有"劫持"请求，这个顺序反了的话，你会浪费大量时间。

3.2 主力模型怎么选：从 Claude 到 Gemini 免费额度

模型选择决定了 OpenCode 的实际体验，这里没有银弹，要根据你的任务类型和预算来。

如果你追求最强代码能力，Anthropic 的 Claude 系列是首选。在 OpenCode 里你可以直接指定模型名，比如：

{ "model": "anthropic/claude-sonnet-4-5" }

anthropic/前缀是 provider 名，后面是模型名。能不能写对模型名，直接决定了能不能跑通。我建议先跑一个简单的对话测试，比如让它解释当前目录下的某个文件，确认模型响应正常再上复杂任务。

如果你想零成本起步，Google 的 Gemini 是目前比较友好的免费选项。Google AI Studio 注册后能领到一定量的免费额度，OpenCode 里选择 Google provider 并填入GEMINI_API_KEY即可。Gemini 的上下文窗口很大，适合让 AI 一次性读入大量代码文件，但它的代码生成风格在某些场景下偏"啰嗦"，审查 diff 时要注意。

另外 DeepSeek 这类国产模型虽然不免费，但价格便宜得惊人，很适合日常频繁调试。它的代码理解能力在开源模型里属于第一梯队，配合 OpenCode 做重构、写单测、改 bug，性价比很高。

3.3 只花电费的本地模型方案：Ollama

如果你有数据隐私要求，或者干脆想在离线环境里跑，本地模型是唯一选择。OpenCode 官方支持 Ollama provider。

先安装 Ollama，然后拉一个代码专用模型：

ollama pull qwen2.5-coder:14b

然后在 OpenCode 里指定 provider 和模型：

{ "provider": { "ollama": { "models": [ { "name": "qwen2.5-coder:14b" } ] } }, "model": "qwen2.5-coder:14b" }

说实话，本地 7B 到 14B 的模型在简单重构、脚本生成、单测补全上已经能干活了，但和商用闭源模型相比，长链路任务（比如"先读整个模块再重构"）的理解能力差距还是明显的。我的定位是：本地模型适合处理私有仓库里的探索性改动，不适合接手大型复杂工程的架构级重构。

3.4 配置文件的正确写法和热加载

OpenCode 的配置文件遵循"项目级覆盖用户级"的规则，这和其他开发工具一致。一个最简配置可能是：

{ "model": "anthropic/claude-sonnet-4-5" }

就这么简单，完全可以先跑起来。当你需要配置 LSP、技能、自定义 provider 时，再逐步添加字段。

配置文件修改之后，OpenCode 会热加载大部分改动，不需要重启进程。但我要提醒一句：LSP 相关配置和 provider 认证改动，热加载不一定可靠。遇到改了配置但行为没变化，直接退出会话重新opencode启动一次，比什么都快。

还有一个常见的误解：很多人以为配置文件里能配的东西越多越好。实际上 OpenCode 的配置字段版本之间变动很快，你从网上抄来的配置文件大概率已经过时。我的建议是，用opencode doctor/opencode debug输出当前版本实际支持的字段，再决定改哪些。

4. LSP 集成不是锦上添花，是决定 AI 代码理解的天花板

4.1 为什么 LSP 这个机制比"把文件塞进提示词"更靠谱

LSP（Language Server Protocol，语言服务器协议）最早是微软为了解决不同编辑器重复实现语言功能而设计的标准化协议。它把"语法分析、类型检查、自动补全、跳转定义、诊断报错"这些语言智能从编辑器里抽出来，变成独立的语言服务器进程，编辑器通过标准 JSON-RPC 协议和它通信。VS Code、Neovim、JetBrains、vim 都能通过同一套协议接入同一个语言服务器。

AI 编程 CLI 的朴素方案是"找文件 + 塞提示词"。模型读到的是一堆拼起来的纯文本，它不知道这个项目能不能编译，不知道某个函数被谁调用，也不知道当前代码里有没有未捕获的类型错误。这就导致模型经常给出"看起来合理、实际一编译就挂"的代码。

LSP 解决的正是这个问题。OpenCode 通过 LSP 拿到了语义级信息：类型定义、符号位置、诊断错误、补全候选。它不是靠猜，而是真正"看"到了编译器的视角。

打个比方：普通塞文件的 AI 像一个刚入职的实习生，只能靠翻文档猜业务流程；接入 LSP 的 Agent 像一个手里握着编译器、对整个代码库了如指掌的资深工程师，你刚说"改这个函数"，它马上能发现三个调用方会受影响。

4.2 OpenCode 里 LSP 的启动与自动发现机制

OpenCode 内置了 LSP 客户端，它启动后做的事情有几件：

第一，探测当前目录的项目类型。看有没有package.json、go.mod、pyproject.toml、Cargo.toml、pom.xml这些标志性文件。

第二，根据探测结果找到对应的语言服务器命令。OpenCode 内置了一张常见语言服务器映射表，比如 TypeScript 项目会尝试启动typescript-language-server，Python 项目会尝试启动pyright-langserver或pylsp，Go 项目会尝试启动gopls。

第三，在项目根目录拉起语言服务器进程，建立 LSP 会话。

第四，AI 在执行代码任务时，动态向语言服务器发请求，比如textDocument/documentSymbol拿符号列表，textDocument/diagnostic拿诊断信息，textDocument/definition找定义位置，把结果合并进模型上下文。

这里最关键的一点是：OpenCode 内置的是"默认映射"，不是"语言服务器本体"。你本机如果没有安装对应的语言服务器二进制，LSP 功能就静默失效，OpenCode 不会主动报错，但 AI 的代码理解质量会明显下降。很多人觉得"AI 怎么变笨了"，根源可能根本不是模型问题，而是 LSP 压根没起来。

4.3 语言服务器清单与配置方式

以下是常用语言服务器和安装方式，建议按需选择：

配置文件里可以自定义 LSP 服务器，下面是一个参考示例：

{ "lsp": { "servers": { "typescript": { "command": ["typescript-language-server", "--stdio"], "extensions": [".ts", ".tsx", ".js", ".jsx"] }, "python": { "command": ["pyright-langserver", "--stdio"], "extensions": [".py"] }, "go": { "command": ["gopls"], "extensions": [".go"] } } } }

command数组的写法、extensions字段名在不同版本里可能有出入。我的建议是：先只配置一个当前项目在用的语言，跑通之后再逐步增加。不要一上来就把七八种语言全配上，否则语言服务器进程占用资源不说，调试时你根本分不清是哪个服务器出了问题。

4.4 虚拟机里折腾 LSP 的坑：路径、端口与进程残留

很多人是在虚拟机里搞开发环境，热搜词里也有"虚拟机里怎么使用 lsp 框架"这种问题。LSP 在虚拟机和远程环境里有一个典型的三重坑。

第一是路径转换问题。典型的场景是：Windows 虚拟机里装了 WSL，你在 WSL 里跑 OpenCode，但系统 PATH 里残留了 Windows 的 Node.js 和 Python 路径。OpenCode 尝试启动语言服务器时，可能调用了 Windows 版的 Node，结果语言服务器拿到的是/mnt/c/project/这种 WSL 路径，根本没法解析，直接启动失败。解决办法很简单：在 WSL 内部完整安装一套 Linux 版的 Node、Python 和语言服务器二进制，确保运行时没有调用 Windows 工具链。

第二是端口与进程冲突。部分 LSP 服务器默认走 TCP 端口（比如 jdtls 的 8000 端口），多个项目同时存在时可能发生端口占用。排查命令很简单：

lsof -i :8000 netstat -tunlp | grep 8000

如果端口被残留进程占住，kill 掉再重启。这种情况在 VMware、VirtualBox 虚拟机里尤其常见，因为虚拟机的网络配置相比本机会多一些奇怪的路由。

第三是资源不足导致的语言服务器崩溃。LSP 服务器本身占用内存，模型推理又占用大量 CPU 和内存，在资源受限的虚拟机里，语言服务器很容易被 OOM 杀掉。表现是 OpenCode 的会话还活着，但 AI 的代码理解突然"断片"，给了明显错误的建议。这时候用dmesg | tail能看到 OOM 记录。解决办法：给虚拟机多分配内存和核数，或者把模型切到云端 API，别让本地模型和 LSP 抢资源。

还有一个老生常谈的细节：LSP 的初始化只在会话开始时做一次。你改了 LSP 配置后，不重启 OpenCode 是不生效的。很多人折腾半天以为配置写错了，其实只是没重启会话。

4.5 看不见的 LSP 在起作用：诊断、补全、跳转和 hover 如何影响 AI 输出

在 OpenCode 里，你基本看不到 LSP 的图形界面，但这些能力被注入到 AI 的决策链路中，直接影响它每一步的代码修改。

诊断（diagnostics）是最重要的一项。AI 在修改代码之前和之后，都会主动拉取工作区的诊断信息。如果发现语法错误或类型错误，它会收到类似"这个文件第 120 行有个类型不匹配"的信号，然后尝试修正。这就是为什么同样尺寸的模型，接入 LSP 后生成代码的正确率会显著提升——它不再盲目生成，而是有"编译器反馈"护航。

跳转到定义（definition）让 AI 能深入追查符号。当你让它修改某个函数时，它会请求 LSP 返回函数定义，以及当前文件包含的函数签名。它能理解"这个函数的第二个参数其实是某个枚举类型"这种深层次的语义关系，而不是靠猜。

hover 信息提供了完整的类型签名、文档注释和参数说明。这些信息会被拼进提示词里，让模型在调用不熟悉的 API 时能拿到最准确的定义。

你可以打开 OpenCode 的 verbose / debug 模式观察日志，会发现 LSP 请求和响应在持续流动。看到有诊断信息进入上下文，就知道 LSP 在工作。如果日志里完全没有 LSP 相关的条目，那就要回头检查语言服务器是不是压根没启动。

5. 从独占到协作：技能、插件与 IDE 生态的整合玩法

5.1 Skills 机制：让 AI 学会你的项目规范

OpenCode 的 Skills 机制借鉴了 Claude Skills 的设计思路，简单来说就是"指令 + 行为准则"的可复用模块。当项目的规范比较复杂时，比如"提交信息必须符合 Conventional Commits 规范""所有新增代码必须带错误处理""禁止使用 any 类型"，你不应该在每次提问时都重复一遍，而是把它写进一个 skill。

我的习惯是放在用户级目录~/.config/opencode/skills/<skill-name>/SKILL.md，也支持项目级.opencode/skills。SKILL.md 通常带一个 frontmatter 格式的头部，声明 skill 名称和适用场景，正文部分用人类语言定义行为规则。

以下面的"commit 规范"skill 为例：

--- name: commit-message description: 生成符合 Conventional Commits 规范的提交信息 --- 当你被要求生成 commit message 时，必须按以下格式组织： 1. type 使用 feat、fix、refactor、docs、test、chore 之一 2. 正文说明改动动机，而不是只复述改动内容 3. 如果存在 breaking change，在 footer 里注明

写了 skill 之后，AI 在相关场景里会自动加载这套规则。不需要你反复叮嘱，规范就内化到它的行为里了。

5.2 社区技能包：oh-my-claudecode 这类项目怎么用

因为 OpenCode 和 Claude Code 的概念高度相似，社区里已经出现了一批打包好的技能集和规则集，比如oh-my-claudecode。这类项目把一整套 prompt、skills、AGENTS.md、工具配置打包，下载后软链到 OpenCode 的 skills 目录就能用。

用法大致是：

git clone https://github.com/xxx/oh-my-claudecode ln -s $(pwd)/oh-my-claudecode/skills ~/.config/opencode/skills

然后进入 OpenCode 会话，通过技能列表选择合适的 skill 启用。

我不建议全盘照搬社区技能包，原因有两个：一是里面的规则设计者自身的口味很重，可能和你的项目规范冲突；二是规则太多会撑爆上下文窗口，反而影响模型的注意力。我一般只挑两三个核心的留用——代码审查规则、commit message 格式、项目结构总结模板——其余全部删掉。

5.3 VS Code 与 JetBrains 插件：是锦上添花还是替代方案

热搜词里出现了"vscode opencode 插件""opencode jetbrains idea 插件"，可见大家都想把它塞进熟悉的 IDE 里。OpenCode 的 IDE 插件目前有官方和社区维护的多款，但成熟度远远比不上 Claude Code 的官方 IDE 集成，更比不上 Copilot 的 GUI 体验。

我的实际用法是：在 VS Code 里开一个集成终端面板，保持 OpenCode 在里面跑着，右侧用自己的编辑器看代码。这样 OpenCode 作为一个并行 Agent 存在，负责探索代码库、生成方案、批量修改；我自己的编辑器负责精确修改、查看文件详情。两边不冲突。

如果你想彻底用 OpenCode 替代 IDE 的 AI 插件，我的建议是先从轻量项目开始试用，别在职级评审或者紧急交付的时候切换到全新工具链，风险太大。

5.4 接上 GitHub CLI，让 Agent 参与 Issue 和 PR 全流程

OpenCode 本身不带 GitHub 集成，但它可以调用外部命令行工具。装好并认证 GitHub CLI：

brew install gh gh auth login

之后你就可以在 OpenCode 会话里让它执行gh issue list、gh pr status、gh pr create --draft这类命令。比如接手开源项目时，可以让 AI 先拉取 issue 列表，分析哪些适合新贡献者，再基于某个 issue 制定修改方案；写完代码后直接让它生成 commit message，再通过gh发起 PR。

这种组合的价值在于：AI 不再只是"改文件的工具"，而是能参与整个协作流程。当然，前提是你给了它足够的权限，并且审查它的每一步操作。

6. 用真实的项目练一遍：从接手旧代码到提交 PR 的操作流

6.1 第一步：让 AI 先"读懂"项目，而不是急着改代码

我见过很多人把 OpenCode 当成高配版搜索引擎，上来就说"帮我加个功能"。结果 AI 对项目结构一无所知，给出的方案完全是空中楼阁。

正确做法是：开局先让 AI 做一个"项目侦察"。把它开到一个陌生的仓库里，提示词大概是：

这是一个基于 React + TypeScript 的项目，入口在 src/main.tsx。 先不要改任何代码，帮我摸清结构： 1. 核心模块的依赖关系是怎样的？ 2. 数据流从哪里开始，到哪里结束？ 3. 测试命令和启动命令分别是什么？ 4. README 里有没有提到重要的注意事项？

你会发现 AI 会运行ls、cat README.md、git log、cat package.json，甚至自己跑rg "someFunction"寻找关键调用点。这个过程花的时间不多，但对后续每一步修改都至关重要。

6.2 第二步：改代码前后用 LSP 诊断兜底

项目摸清楚之后，开始改动前，先发一条约束指令：

在改动之前，请先运行项目的类型检查或 lint， 列出当前工作区已有的全部错误。 然后基于这些错误和我的需求，给出修改方案。

这一条非常有效。它强迫 AI 在建方案之前先通过 LSP 拿到诊断信息，而不是凭空设计。等 AI 改完代码，再让它自己验证：

请运行测试和类型检查，确认你的改动没有引入新的错误。 如果测试失败，请先查看失败原因，然后继续修复。

LSP 诊断在这里扮演了"哨兵"角色。AI 的每次修改，都会带着编译器反馈继续迭代，直到测试通过为止。这样下来，你审查 diff 的压力会小很多。

6.3 第三步：提交信息、PR 描述和代码审查的协助

代码跑通并不意味着任务结束。OpenCode 还应该在提交和协作环节帮你一把。

要求它生成符合规范的提交信息：

请根据当前 git diff 内容，生成一个 Conventional Commits 格式的提交信息。 scope 用改动涉及的模块名。

如果你配置了对应的 skill，它会自动套用规则，不需要你每次提醒。

接着，让它整理 PR 描述：

基于当前分支的改动，帮我写一份 PR 描述。 结构按背景、改动点、测试方式三段来写。 改动点部分要列出具体文件和核心逻辑变化。

最后你还可以让它做一轮自我代码审查：

请以资深 reviewer 的视角审查本次改动， 重点关注边界条件、错误处理、性能隐患。 只要列出具体问题和修复建议，不要修改代码。

这一轮审查经常能发现一些低级失误，比如漏掉的 null 判断、多余的日志输出、可能的内存泄漏。把它养成的"发现问题先列举、不急着改"的习惯，比让它直接改有效得多。

6.4 一次真实的翻车复盘：LSP 没启动时的"AI 变笨"现象

有一次我让 OpenCode 重构一个 Python 模块的重试逻辑，模型一开始给了一个很合理的方案，但改完代码测试全红。我打开 debug 日志一看，LSP 根本没启动——原因是新开的虚拟环境里没装 pyright，OpenCode 静默回退到了纯文本模式。

没有诊断信息兜底，AI 对"当前代码有没有类型错误"一无所知，只能靠模型对代码的"感觉"来改。这种感觉在短代码片段上还行，在跨文件的复杂重构里就是灾难。

这次翻车之后，我把"检查 LSP 是否启动"放进了每次新环境的固定检查清单里。方法很简单：启动 OpenCode 后，跑一个简单的任务让 AI "列出当前文件的类型错误"，如果能准确回答，说明 LSP 在工作；如果说"我看看"然后给出模糊回答，基本可以断定 LSP 挂了。

7. 用了一个月后的"祛魅"：OpenCode 的长板、短板和真正的适用边界

7.1 我眼中最不可替代的长板

OpenCode 最让我回不去的，是它把 AI 编程工具的理念拉回到了终端本身。所有操作都是命令式的，所有过程都可追溯，所有配置都是文本文件。这意味着你可以把整套环境打包、迁移、版本化，而不是依赖某个 IDE 的图形界面。

多 provider 的支持是另一个实打实的长板。你不需要为某一个模型买断一套工具链，只要你想，Claude 做架构设计，Gemini 跑长上下文分析，本地模型处理隐私代码，全都能在同一个界面里切换。

LSP 深度集成则让它在代码理解能力上拉开了和"纯文本塞提示词"工具的差距。它不只是让 AI 更"懂代码"，而是给 AI 接上了编译器的眼睛。

7.2 不能回避的短板

更新太快是个双刃剑。功能上天的同时，文档经常追不上代码。我在配置某个 provider 时遇到过字段名和网上文档对不上的情况，最后只能去翻 GitHub 的 changelog。

大型 monorepo 仍然是它的软肋。虽然 LSP 解决了理解精度的问题，但整个仓库的体量一旦超过某个阈值，上下文窗口还是不够用。AI 的策略通常是"只看和你任务相关的几个包"，但有时候相关性的判断本身就容易出错。

TUI 的全键盘操作对新手有门槛。习惯了鼠标点来点去的开发者，刚开始会非常不适应。

7.3 适用边界：这类工具到底该用在哪

我最推荐的使用场景是：中大型代码库的 bug 修复、跨文件重构、测试代写、开源项目调研、脚本类代码生成。这些任务的特点是逻辑性强、结果可验证、修改范围相对明确。

不太适合的场景是：需要大量视觉反馈的前端 UI 调优、对代码库完全不了解的新手做一些"懵懂式"需求、需要强图形验证的环境。在这些场景里，它往往只能给你一个方向性的参考，还得靠人工一点点调。

7.4 最后分享几个实战心得

第一，永远把 AI 当成"聪明的实习生"。它的产出必须经过 diff 审查，尤其是删除和移动的代码，容易在你不注意时把某段重要逻辑顺手干掉了。

第二，任务拆得越细，效果越稳定。与其让 AI 一口气"重构整个模块"，不如拆成"先列出调用点，再改核心函数，再改调用面，最后跑测试"这四步。拆解之后，每一步的上下文都很清晰，模型的失误率会大幅下降。

第三，固定版本。如果你不想某天醒来发现配置文件格式全变了，建议固定一个 OpenCode release 版本，不要盲目升级。升级前先看 changelog，确认没有破坏性变更再动手。

第四，用opencode doctor/opencode debug作为一切问题的起点。排查问题先看诊断输出，而不是反复试配置。很多"工具不行"的结论，最后都只是环境问题。

OpenCode 这类 AI 编程 CLI 还在快速演进，现在的短板可能过几周就被补上了。但无论它怎么变，用好它的核心方法论不会变：让 Agent 拥有编译器的视角，把任务拆到可验证的粒度，永远保持人类对代码的最终审查权。这套方法放之四海而皆准。