大概从今年年初开始我身边越来越多原本习惯在 IDE 里装 AI 插件的朋友开始往终端里跑opencode这类 AI 编程 CLI。一开始我也觉得是折腾直到自己把 OpenCode 接上项目、配完 LSP、用它在远程服务器上改完几个 bug 之后才明白 CLI 形态在特定场景下是真的顺。如果你也好奇这个 GitHub 上 160K Star 的免费开源工具为什么这么火或者你已经装到一半卡在某个报错上这篇就按我实际踩过的流程从安装、模型配置到 LSP 集成完整过一遍。OpenCode 说起来就是一个跑在终端里的 AI 编程助手但它跟常见的 IDE 插件不太一样插件是“住在编辑器里”OpenCode 是“住在命令行里”。它能自己读文件、跨文件搜索、执行命令、调用语言服务器获取代码语义几乎是把一个 AI 结对编程搭挡塞进了终端。适合什么人用我觉得最典型的是经常 SSH 到服务器、在容器里写代码、或者对编辑器插件不感冒但离不开终端的开发者。这篇文章不是官方文档翻译而是我实际从零跑到能干活的全过程记录包括那些文档里没写清楚的坑。1. 先搞清楚这是个什么东西再谈安装1.1 为什么终端 CLI 形态的 AI 编程工具突然火起来AI 编程工具现在基本分成三种形态我列个表就清楚了。形态代表优势短板IDE 插件GitHub Copilot、Cursor边写边补全上手零成本绑定编辑器跨项目协作麻烦桌面应用ChatGPT 桌面版等交互界面友好跟本地代码库隔着一层权限打通费劲终端 CLIOpenCode、Claude Code、Codex CLI轻量、可脚本化、天然适配远程开发需要一点命令行基础CLI 形态能火核心原因是它把“AI 改代码”这件事从“图形界面操作”变成了“可编写、可复用的命令流”。举个实际例子我在服务器上排查问题时以前要开 IDE、加载整个项目、等索引完成现在直接在终端跑opencode让它读日志、改配置、重跑测试整个过程不离开 SSH 会话。这种体验是 IDE 插件给不了的尤其是在网络条件一般、只有终端的场景下CLI 几乎是唯一顺手的选择。1.2 OpenCode 的定位和它跟 Claude Code、Codex CLI 的区别很多人会问OpenCode 和 Claude Code、Codex CLI 有什么区别。简单说Claude Code 是 Anthropic 推出的天然围绕着自家 Claude 模型设计Codex CLI 是 OpenAI 的工具同样偏向自家生态。它们都好用但都有一个共同点模型绑定比较死你想在两者之间切换基本等于把整个工具链换一遍。OpenCode 不一样。它是由 SST 团队发起并维护的开源项目定位是“模型中立”的终端 AI 编程客户端。你可以用 Anthropic 的模型也可以用 OpenAI、Google Gemini、本地 Ollama甚至 Groq 这类服务商提供的免费模型。这种“一个工具多种模型后端”的思路让我这种喜欢在不同模型间横跳的人很舒服。说实话所谓“AI 编程最厉害三个软件”这类话题争论意义不大因为工具本身只是载体重要的是你愿意花时间去摸透其中某一个而 OpenCode 因为开源、免费、可配置性强是个不错的长期选择。1.3 核心特性一览免费、多模型、LSP、SkillsOpenCode 的核心特性我梳理一下。首先是免费开源MIT 协议代码全部公开这点对在意数据隐私和二次开发的团队很重要其次是多模型支持官方文档列出来的 provider 覆盖了 Anthropic、OpenAI、Google、Mistral、Groq、OpenRouter、Ollama 等主流选择然后是 TUI 交互界面在终端里用方向键选择文件、浏览 diff体验出乎意料地顺再就是 LSP 集成这让 AI 不再靠猜文件名和代码文本来理解项目而是能拿到真实的语言语义信息最后是 Skills 机制可以把团队常用的操作流程写成一个“技能包”给 AI 调用相当于给 AI 加了一本操作手册。这些特性单拎出来别的工具多多少少都有但组合在一起而且完全免费、支持本地模型目前 OpenCode 是我用过最均衡的一个。接下来就进入正题先说安装。2. 安装与初始化从零跑起来只花五分钟2.1 安装前先确认环境OpenCode 依赖 Node.js 运行时官方建议 Node 20 以上。安装前我习惯先跑两条命令确认环境node -v npm -v如果node -v提示找不到命令说明环境里还没有 Node需要先去 Node 官网装长期支持版或者用 nvm 管理版本。另外一个隐蔽的坑是如果 Node 是刚装好的终端需要重启一次才能识别新加入 PATH 的命令。很多新手在这卡住以为安装失败其实只是 shell 没刷新。操作系统方面macOS 和 Linux 都比较省心Windows 用户建议用 Windows Terminal 搭配 PowerShell 7或者干脆在 WSL 里跑。不是说 Windows 原生不能跑而是 OpenCode 的 TUI 在 Windows 默认终端里偶尔会出现渲染问题在 WSL 和 Linux 下最稳定。2.2 三种安装方式选一种即可OpenCode 的安装方式有好几种我试过两种把经验写出来。第一种是 npm 全局安装最简单通用npm install -g opencode-ai装完之后运行opencode --version能输出版本号就说明成功了。第二种是官方脚本安装适合不想污染 npm 全局目录的情况curl -fsSL https://opencode.ai/install | bashmacOS 用户还可以用 Homebrewbrew install sst/tap/opencode三种方式选一种就行效果一样。我个人推荐第一种因为 npm 全局装的东西管理起来直观升级也方便直接npm update -g opencode-ai就能搞定。2.3 Windows 用户必踩的 PATH 坑Windows 下最常见的报错是opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称这个报错的本质是 npm 全局安装目录没有加入系统 PATH。解决方法是先查 npm 全局目录前缀npm config get prefix正常情况下会输出类似C:\Users\你的用户名\AppData\Roaming\npm的路径。把路径加进 PATH 的方法是打开系统环境变量设置在“用户变量”里找到 Path新建一条把这个目录填进去然后重启终端。如果不想改环境变量也可以用npx opencode-ai直接运行npx 会自动找到本地安装的包不过每次启动会比直接用全局命令慢一点。这个 PATH 问题不仅是 OpenCode 会遇到几乎所有的 npm 全局 CLI 工具在 Windows 上都会踩一遍建议一次性把%APPDATA%\npm加进 PATH以后省心很多。3. 模型接入与配置让 OpenCode 真正开始干活3.1 官方模型接入流程安装完成只是第一步还得让 OpenCode 接上模型才能真正用。首次运行直接输入opencode它会进入初始化流程提供两种认证方式一种是通过/login命令在交互界面里选择 provider 并完成登录另一种是直接在系统环境变量里配置 API Key。以 Anthropic 和 OpenAI 为例export ANTHROPIC_API_KEYsk-ant-... export OPENAI_API_KEYsk-...Windows PowerShell 里对应的写法是$env:ANTHROPIC_API_KEY ...。账号密码这类凭证 OpenCode 会存在本地的 auth 配置文件里位置一般在~/.local/share/opencode/auth.jsonWindows 上在用户目录下的.opencode文件夹里。需要说明的是密钥文件属于敏感信息注意别提交到代码仓库。3.2 免费模型与本地模型方案网上搜“opencode 免费模型”的人特别多因为很多人不想一上来就花钱买 API。OpenCode 对这块支持得很好核心方案是用本地模型最常见的是 Ollama。# 先安装 Ollama然后拉取一个适合编程的模型 ollama pull qwen2.5-coder:7b然后在 OpenCode 的配置文件里把本地模型加进去。OpenCode 的配置分为全局配置和项目配置全局配置在~/.config/opencode/opencode.json项目配置在项目根目录的opencode.json两者会被合并。一个典型的配置长这样{ provider: { ollama: { models: { qwen2.5-coder:7b: { name: qwen2.5-coder:7b } } } }, model: qwen2.5-coder:7b }除此之外还有一些云平台提供免费额度比如 Groq 的速度快、注册就有免费调用额度OpenRouter 也有不少免费的模型可选。这些平台各自的 API 申请方式多为注册后拿 Key按官方指引操作就行。实测下来免费模型在简单代码解释、单文件重构、写测试用例这些轻量任务上够用但如果要跨多个文件做大改动还是建议用模型能力更强的付费 API省下的反而是自己的时间。3.3 项目级配置与 AGENTS.md 提示词工程很多人觉得 AI 编程工具“不够聪明”其实问题常常出在没给 AI 足够的项目背景。OpenCode 支持通过AGENTS.md文件给 AI 写“项目说明书”这个文件放在项目根目录AI 在每次任务开始时都会读取它相当于你给 AI 的一份入职培训材料。我通常会在 AGENTS.md 里写清这些内容项目是什么、技术栈是什么、目录结构怎么组织、代码风格有哪些要求、常用的构建和测试命令是什么、有哪些约定俗成的规矩不能违反。比如一个 Python 后端项目# AGENTS.md ## 项目简介 基于 FastAPI 的订单服务使用 PostgreSQL 存储数据。 ## 常用命令 - 启动uvicorn app.main:app --reload - 测试pytest tests/ - 格式ruff check . ## 约定 - 所有数据库操作必须通过 SQLAlchemy 会话管理 - 新接口必须写 Pydantic 校验模型 - 错误信息统一使用中文有了这个文件AI 生成代码时会主动遵守项目约定而不是每次都要你在 prompt 里反复交代。至于提示词怎么写我的经验是五条铁律给出角色背景、说明当前任务、给出约束条件、给出期望输出格式、提供验收标准。别只说“帮我写个接口”而是说“你是这个项目的资深后端开发请按照项目现有结构新增一个订单查询接口使用异步 SQLAlchemy路由放在 app/api/v1/orders.py输出包含路由代码和对应的测试代码”。信息越完整AI 输出越接近你想要的。4. LSP 集成从“猜代码”升级到“懂代码”4.1 LSP 到底解决了什么问题LSP 全称是 Language Server Protocol语言服务器协议。用生活化的方式理解编译器是一个懂编程语言语法的“老师”LSP 就是这位老师对外提供的标准化接口让任何工具都能问它“这个函数在哪定义”“这个变量被谁引用了”“这里的代码有没有编译错误”。没有 LSP 之前AI 编程工具理解代码基本靠“猜”——通过分析代码文本、文件名、注释来推断逻辑。这种方法在小项目里还行项目一大就会出现各种荒谬错误比如搞错变量作用域、找不到真正的函数定义、改 A 文件却没意识到 B 文件的调用方会挂掉。有了 LSP 之后AI 能直接获取代码的语义级信息跳转到定义、查找引用、读取编译器诊断这些信息让 AI 的修改精确度高了一个档次。我在实际使用中感受最明显的是跨文件重构以前 AI 改完经常编译不过现在 OpenCode 有了 LSP 提供的实时诊断改完就能发现问题效率提升是肉眼可见的。4.2 OpenCode 中的 LSP 配置实操OpenCode 启用 LSP 并不复杂核心步骤是先安装对应语言的 language server然后在配置文件里声明。以 TypeScript 和 Python 为例# TypeScript 的 language server npm install -g typescript-language-server typescript # Python 的 language server pip install pyright然后在 opencode.json 里配置{ lsp: { typescript: { server: [typescript-language-server, --stdio], extensions: [.ts, .tsx] }, python: { server: [pyright-langserver, --stdio], extensions: [.py] } } }配置好后重启 OpenCode让它重新加载 LSP 服务。在 TUI 里可以通过相关命令查看 LSP 连接状态能看到对应语言 server 是否已经启动。这里有个注意点不同版本的 OpenCode 对 LSP 配置字段的支持可能有细微差别建议以官方文档为准。我用的配置格式在 1.x 版本上是稳定的如果换了版本发现没生效先查一下文档有没有更新字段。4.3 虚拟机、容器等远程环境下的 LSP 踩坑经验网上有人问“虚拟机里怎么使用 LSP 框架”其实就是前面那套配置流程在虚拟机或容器里再跑一遍。关键点是language server 必须和 OpenCode 运行在同一个环境里。比如你在容器里跑 OpenCode那typescript-language-server或者pyright也要装在这个容器里而不是宿主机上。FROM node:20-slim RUN npm install -g typescript-language-server typescript RUN pip install pyright RUN curl -fsSL https://opencode.ai/install | bash还有一个常见问题是语言服务器命令不在 PATH 里。比如通过pip install pyright装完的pyright-langserver脚本目录可能没加入 PATHOpenCode 启动 LSP 时就会报“找不到命令”。排查方法很简单在终端手动执行一遍 server 的启动命令能正常跑起来再回 OpenCode 里重启服务。遇到“gopls: command not found”这类报错基本都是同一个原因把对应 bin 目录加进 PATH 就行。5. 高频报错排查这些问题我基本都遇到过5.1 热门的“unable to locate the codex cli binary”这个报错最近搜的人特别多原话一般是Unable to locate the codex cli binary. Set CODEX_CLI_PATH or ensure the executable is in your PATH.出现这个报错通常是本机同时装着 Codex CLI但某个工具比如桌面版 ChatGPT启动时找不到 codex 可执行文件。解决办法是设置环境变量CODEX_CLI_PATH指向 codex 的实际路径。在 macOS 和 Linux 上export CODEX_CLI_PATH/usr/local/bin/codexWindows 上则是在系统环境变量里新建CODEX_CLI_PATH值为codex.exe的完整路径。这个报错和 OpenCode 的关联点在于如果你想让 OpenCode 也调用 Codex 环境的本地方案同样需要保证这个环境变量配置正确。实际上OpenCode 本身并不强依赖 Codex CLI但这个报错常常出现在开发者“装了 OpenCode 又装 Codex CLI”的过程中两个工具的环境变量互相干扰把路径理顺就好。5.2 LSP 启动失败与语言服务器版本问题LSP 相关的坑比模型配置多得多最常见的是服务器启动后立即崩溃或者一直卡在“connecting”。我的排查流程很固定先手动执行 language server 命令比如运行typescript-language-server --stdio看它能不能挂住等待输入。如果立刻报错基本是 server 版本和语言版本不匹配。举个例子TypeScript 5.5 之后旧版本的typescript-language-server可能无法解析新语法需要升级 npm 包。另一个坑是 pyright 的下载源问题某些网络环境下 pip 可能装到旧版本。我的建议是启用 LSP 后如果发现 AI 完全拿不到诊断信息不要怀疑模型先怀疑 language server 有没有起来。可以在 OpenCode 的日志里查lsp关键字通常能找到具体的启动失败原因。5.3 常见问题速查表我把高频问题整理成一张表方便你对照排查。现象原因解决办法opencode 命令找不到npm 全局目录不在 PATH执行npm config get prefix把 bin 路径加入 PATH启动后模型不响应API Key 未配置或已失效执行/login重新登录或检查环境变量提示 401 / authentication errorKey 权限不足或账户欠费检查 provider 控制台额度换一个有效 KeyLSP 服务无法启动language server 未安装或版本不兼容手动运行 server 命令验证升级 language serverTUI 界面乱码或卡死终端兼容性问题Windows 用 Windows TerminalmacOS 用 iTerm2AI 改代码总是跑偏缺少 AGENTS.md 项目说明在项目根目录补全 AGENTS.md写明结构和约定排查的思路永远是先看日志再查环境最后怀疑配置。OpenCode 的日志文件位置通常会在文档里标注遇到问题了先去翻日志比盲试配置高效得多。6. 进阶玩法Skills、VSCode 插件和团队协作6.1 Skills把团队经验固化成技能包Skills 是 OpenCode 一个非常容易被低估的功能它允许你把一套操作流程写成 Markdown 文件然后让 AI 按这个流程执行。举个例子我们团队每周都要做代码审查以前每次都要在 prompt 里写一遍“请按照数据库安全、性能、可读性三个维度审查”现在直接写成一个 skill# Code Review Skill 当用户请求代码审查时请按以下步骤执行 1. 获取当前改动文件列表 2. 按顺序检查数据库安全、性能瓶颈、错误处理、代码风格 3. 对每个问题标注严重级别P0 必须修复、P1 建议修复、P2 可选优化 4. 最后给出整体评分和修改建议摘要把这份文件放在项目.opencode/skills/目录下AI 就能在会话里识别并调用这个技能。团队协作时这份 skill 文件可以放进代码仓库所有开发者的 OpenCode 行为就统一了。这个机制有点像给 AI 装了一套“团队 SOP”非常适合规范化团队的工作流。6.2 VSCode 插件、桌面版怎么选热词里有很多人搜 opencode 的 VSCode 插件和桌面版。我的建议是不同形态对应不同场景。CLI 适合跑在服务器、容器里适合批处理和脚本化操作VSCode 插件适合日常在 IDE 里开发时边写边看 AI 的变化diff 展示比终端更直观桌面版则适合不习惯终端操作的同事看起来更像一个聊天工具但底层配置和 CLI 共用同一套切换到别的形态没有迁移成本。我的个人习惯是“双开”日常开发用 VSCode 插件需要连服务器或跑批量任务时切到 CLI。两个进程只要不同时操作同一个文件不会有冲突。如果你刚开始接触 OpenCode我建议先固定在 CLI 形态跑熟等理解了核心概念再扩展插件和桌面版这样遇到问题时更容易定位。6.3 用 OpenCode 接手老项目的心得最后聊聊接老项目这件事。很多人拿 OpenCode 处理新项目很顺手但一接手老代码就抓瞎其实问题是没给 AI 足够的时间“读文档”。我踩过几次坑之后总结了一套固定流程先让 OpenCode 通读 README、AGENTS.md、package.json或 requirements.txt这些入口文件然后要求它输出一份项目认知摘要包括技术栈、目录结构、核心数据流、常见入口点。确认它理解对了再让它做影响面分析最后才动手写代码。这个流程看起来多花了五分钟但能避免 AI“没读懂就乱改”带来的大量返工。毕竟工具再智能也需要你先把它领进门。给 AI 补全项目背景就像给新同事做入职培训培训做得越好产出质量越高。最后再分享一个小习惯我每次启动 OpenCode 后第一件事不是直接下指令而是先让它描述当前项目结构和关键入口文件。如果它说出来的内容和你看到的一致再开始干活如果不一致说明 AGENTS.md 没写清楚先回去补文档。这个习惯让我少踩了无数“AI 自作主张”的坑你可以试试。