OpenCode使用体验

OpenCode是最近Github上超级火爆的开源AI编码工具项目，作为极度封闭的ClaudeCode的开源替代品，OpenCode能在这么短时间内拥有极高的完成度，TUI交互设计体验极佳，而且更具可定制性和可扩展性，确实相当厉害了。这篇文章我们大致介绍一下OpenCode的使用方式，作为一个和AI编程工具相关的简略入门教程。

简介

OpenCode是一个MIT协议开源的AI编码智能体工具，和ClaudeCode类似，OpenCode本体也是基于终端的工具，实现了类似Vim的TUI（Terminal User Interface）交互界面，此外也以插件形式提供了主流编辑器/IDE的集成。无论是在现有项目基础上开发还是完全新建项目，OpenCode都能应付并节省我们的大量时间。

项目Github地址：https://github.com/anomalyco/opencode

官方文档：https://opencode.ai

安装

OpenCode本质还是一个NodeJS程序，最简单的方式是使用NPM安装。

npm install -g opencode-ai

不过实际测试发现国内的镜像源同步可能有点Bug，使用淘宝的NPM镜像会报如下错误。

It seems that your package manager failed to install the right version of the opencode CLI for your platform. You can try manually installing the "opencode-windows-x64" package

我是通过特别指定使用NPM官方源下载的，如果你也遇到类似的问题可以试试这个解决办法。

npm install -g opencode-ai --registry https://registry.npmjs.org

启动

安装完成后就可以在终端用命令启动OpenCode了。

opencode

启动后，大致会看到类似下面的界面。

和大多数AI编程工具类似，操作OpenCode的指令都是以/开头的，输入/help可以查看帮助信息，输入/exit退出工具。

连接模型Provider

我们输入/connect指令，可以看到OpenCode可用的模型提供商。OpenCode内置支持了许多模型提供商，许多流行的公网LLM API都可以在这里使用，我们也可以接入自己部署的LLM。不过本着~~能白嫖就白嫖~~的原则，OpenCode自己的OpenCode Zen目前有免费试用，其中国产的GLM 4.7和MiniMax M2.1可以不用付费直接使用，下面都以这些免费模型作为例子演示。

使用谷歌账号登录OpenCode Zen，将API Key复制到OpenCode工具里就行了（实际上如果是用当前免费模型也并不需要API Key，直接开始用就可以）。

使用/models指令可以切换可用的模型。

基本概念

如果你完全没用过ClaudeCode、GeminiCLI等AI编程工具，在具体使用OpenCode之前，我们还是要先了解类似工具中的一些基本概念。

Session（会话）：LLM是无状态的，没有记忆，因此多轮对话中每次和LLM“聊天”时都要把之前的“聊天记录”发给大模型，这些“聊天记录”通常包含系统提示词、用户消息、AI消息、工具消息，一组这样的多轮对话就是一个会话。如果把会话清理掉，在用户看来对方就“失忆（重置）”了。如果会话中的内容过多即将溢出模型的上下文，一般做法是调用LLM将消息做总结和摘要，这通常被称为会话中消息的“压缩”。OpenCode中，使用/session指令查看会话列表，我们可以选择之前的会话以继续，或连按两次CTRL + D删除会话，当上下文不够用时，使用/compact指令压缩会话。

Plan/Build模式：类似ClaudeCode，OpenCode也有Plan/Build模式。Plan模式中，智能体会查看项目和做规划，而不会实际修改任何内容。用户可以通过对话交互让智能体了解更多信息、不断修正自己的规划。Build模式下智能体才会真正编辑文件。OpenCode中，随时可以使用Tab键切换Plan/Build模式。

Tools（工具）：OpenCode搜索文件、查看文件、编辑文件、执行Shell命令都是通过“工具”实现的，智能体的“工具”简而言之就是一堆具有具体功能的代码函数（比如读取文件），函数的JSON Schema以提示词形式告知了LLM，LLM会按照参数调用这些函数。OpenCode内置的工具可以通过配置文件进行开关，不过一般来说这些内置工具都是作为一个AI编码智能体所需的，不需要手动调整。

MCP：MCP描述的其实也是工具，但MCP（Model Context Protocol）使用的是一种相对标准并被广泛认可的交互协议，相比于智能体的内置工具，MCP工具通常更倾向于扮演外置工具的角色，MCP工具会提供标准接口与外围集成，而非以某种插件形式直接将工具函数注入到智能体实现代码里。

配置

OpenCode配置文件

OpenCode的配置是通过配置文件实现的，OpenCode支持全局配置文件、单个工程的局部配置文件，还支持从远程加载配置文件，如果有多个配置文件，他们是按优先级的合并关系。不过我们这里不弄那么复杂，我们只要知道全局配置在~/.config/opencode/opencode.json，局部配置文件在工程目录下opencode.json即可，实际开发中一般也就只会用到这两个。配置文件中的可配置项非常多，具体用到时可以查看官方文档。

以配置MCP为例，我们这里增加一个开发中常用的Context7 MCP的配置。Context7是一个聚合了各种项目在线文档的检索服务，它专为LLM设计，提供了MCP与各种编码智能体集成，将Context7集成到OpenCode能很方便的让编码智能体在工作中检索最新的在线文档。举例来说，假如我们要使用LangChain框架开发一款AI应用，LLM训练时的知识截止日期可能是2025年1月，此时的LangChain版本还是v0.3.x，但最新（2026年1月）的LangChain版本已经是v1.1.x了，新版本相比之前改动巨大，LLM如果不靠外部知识显然无法写对代码。为了解决这个问题最简单的方式是从LangChain官网把文档复制下来手动粘贴给LLM，但手动操作比较麻烦，使用Context7 MCP意味着LLM可以在他“认为”需要查文档时自动调用Context7来检索最新的文档，遵照最新文档编写代码。

我们这里添加一个全局配置文件。

~/.config/opencode/opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "context7": {
      "type": "local",
      "command": ["npx", "-y", "@upstash/context7-mcp", "--api-key", "<API_KEY>"],
      "enabled": true
    }
  }
}

这里API_KEY需要替换为你自己的，它可以从Context7官网获取并粘贴进来，Context7有每月500次的免费调用额度，通常都是够用的。配置完成后，我们可以在OpenCode中使用/mcp指令查看已经配置好的MCP工具，使用空格键可以切换其启用和禁用。

忽略设置

实际开发中，如果有编译产物或巨大的日志文件，如果不屏蔽，它们可能会迅速消耗LLM的上下文并降低“智商”，默认情况下，OpenCode会根据.gitignore中的规则忽略文件，此外如果我们还有特殊指定的忽略文件，可以配置在额外的.ignore文件中，格式与.gitignore相同。

OpenCode工作流程

分析项目

对于一个已有项目，OpenCode一上来肯定是什么都不知道的，我们需要告知OpenCode项目的目录结构，阅读源代码文件、配置文件、文档说明等内容，不过现在这不需要我们手动粘贴这些内容，OpenCode中内置了项目分析功能，我们使用Tab键切换到Build模式，然后直接输入/init指令，智能体会自动使用内置工具检查项目结构、读取各种关键信息，最重要的是该指令能够在项目根目录中写入一个AGENTS.md，OpenCode默认会读取项目根目录的AGENTS.md作为全局的提示词，避免后面忘掉项目的关键信息。

虽然上面的AGENTS.md是瞬间自动生成的，但实际上它非常重要，AGENTS.md有误或信息不全很可能导致后续智能体的工作流程或编写的代码存在错误。当然，对于简单的项目，LLM生成的AGENTS.md已经差不多够用了，然而对于更复杂的项目，我们可能需要深度手写AGENTS.md，准确的描述所用技术栈、项目结构、代码风格、工作流程以及更多的关键信息。如果是完全新建的项目，我们通常也可以手动编写AGENTS.md以正确的指导编码智能体该怎么做。

以目前的LLM生态来看，对于国产模型，使用中文编写这些内容效果是可以的甚至还可能优于英文，不过对于国外模型可能还是英文提示词效果更好。

Plan模式

假设我们现在要正式开始用OpenCode编写代码了，直接把需求一下子粘贴到OpenCode中让其执行可能不是个好主意，我们的需求表述可能是模糊、缺少关键信息的，此时最佳实践是先使用Tab键切换到Plan模式，与LLM反复“沟通确认”（其实就是通过内置的提示词让LLM总结一份工作计划，如果缺少关键信息则反问用户，目前需要某种程度“深度规划”功能的智能体大多都是类似的设计），当形成的工作计划没问题时再切换到Build模式执行。

规划模式中，我们可以根据模型提示补充关键信息。

Build模式

当Plan模式输出的计划已经满足我们的需求时，我们就可以把OpenCode切换到Build模式开始编码了，现在我们唯一需要的就是等待（或者规划下一个项目、摸鱼、看猫猫视频、喝茶、睡觉...），编码智能体会自动写入文件、执行Bash命令，直到最终完成工作。

当然，你的工作仍未结束，LLM编写的代码可能仍存在Bug或对需求理解有误，或者我们的需求又有变化了，我们需要仔细验证代码的可用性和安全性，修复Bug（或指出Bug让OpenCode修复）。如果你完全不懂代码，想让OpenCode完全、100%的按预期工作这是不可能的，当智能体陷入无法解决问题的死循环时，仍需人工指导或手动修复。

总结

以上就是OpenCode的介绍和简要的使用流程指导，希望对你有帮助。