[导论01] 搭建OpenCode开发环境与命令行工具

前言

你是不是还在为每个月花20美元订阅Cursor而心疼？或者每次用Claude Code都得小心翼翼地计算Token消耗？更别提那些被厂商绑定、想换个模型就得换整套工具的尴尬了。

大家好，欢迎来到《全网最新OpenCode入门到精通》专栏的第一篇文章。这个专栏的目标只有一个——手把手带你从零掌握OpenCode，真正把AI编程Agent用起来，而不是装完就吃灰。

本篇是这个专栏的导论篇，也是整个系列的基础。读完这一篇，你会完成OpenCode的完整安装和配置，在终端里跑起一个能对话的TUI界面，并了解两种核心工作模式的区别。学完本篇，你就能在终端里跟AI对话了——对，就是这么直接。

建议先点个关注，收藏这个专栏，后续每一篇都会带你往前迈一步，从环境搭建到实际项目落地，不绕路、不废话。

环境与前置说明

因为是专栏的第一篇，所以没有任何前置依赖。你只需要准备：

• 一台电脑：Windows、macOS、Linux都行
• 网络环境：能正常访问外网（安装时需要拉取资源）

本篇会用到的核心依赖：

依赖	版本要求	说明
Node.js	18.0 或更高（推荐v22 LTS）	OpenCode基于Node.js运行
npm	随Node.js一起安装	用于全局安装OpenCode
OpenCode	最新版（通过npm安装）	本篇主角

如果你用的是Windows，强烈建议在WSL2环境中操作，能省掉很多兼容性问题。当然，直接用Windows PowerShell或CMD也行，只是遇到问题的概率会高一点。

核心内容

第一步：检查Node.js环境

目标：确认你的电脑已经安装了Node.js，且版本符合要求。

OpenCode是一个Node.js工具，必须先有Node.js环境才能安装。这一步看似简单，但很多人卡在这一步——要么没装，要么版本太低。

打开你的终端（Windows用PowerShell或CMD，macOS/Linux直接用Terminal），输入：

# 检查Node.js版本node-v

运行验证：如果看到类似v22.14.0这样的版本号，且数字大于等于18.0，说明环境OK，可以跳过安装Node.js直接进入第二步。

如果提示'node' 不是内部或外部命令，或者版本低于18.0，你需要先去 Node.js官网 下载安装最新的LTS版本。下载安装包后一路“下一步”就行，没什么特别的门道。

安装完成后，重新打开终端，再次运行node -v确认版本。

第二步：安装OpenCode

目标：通过npm全局安装OpenCode命令行工具。

确认Node.js环境没问题之后，安装OpenCode就非常简单了——一条命令的事：

# 全局安装OpenCodenpminstall-gopencode-ai@latest

这里解释一下这条命令在做什么：

• npm install -g：全局安装，这样你在任何目录下都能直接使用opencode命令
• opencode-ai：OpenCode在npm上的包名
• @latest：安装最新版本，避免装到旧版

安装过程需要从npm仓库下载依赖包，取决于你的网络速度，可能需要1-3分钟。如果卡住了别急着Ctrl+C，耐心等一等。

国内用户如果npm下载太慢，可以考虑切换到淘宝镜像源：

npmconfigsetregistry https://registry.npmmirror.com

然后再执行安装命令。

运行验证：安装完成后，输入以下命令确认安装成功：

# 验证OpenCode是否安装成功opencode--version

如果看到类似0.2.x的版本号，恭喜你，安装成功了！

如果提示'opencode' 不是内部或外部命令，说明安装路径没有被加到系统的PATH环境变量里。这个问题通常出现在Windows系统上，解决方案见文末的“异常处理与常见坑”部分。

第三步：了解OpenCode是什么（1分钟速览）

目标：在开始使用之前，先搞清楚你装的到底是个什么东西。

很多人装完OpenCode之后一脸懵，不知道它跟ChatGPT、Cursor有什么区别。这里用一句话给你说明白：

ChatGPT是你问一句它答一句，代码你自己复制粘贴。OpenCode是一个AI编程Agent——它能理解你的项目结构、读取文件、规划修改方案、执行命令，然后把改动直接写进你的代码库。

OpenCode有三个核心特点值得你记住：

1. 模型中立：不绑定任何一家模型厂商。Claude、GPT、Gemini、DeepSeek，或者本地跑的Ollama，你想用哪个用哪个。
2. 终端优先：跑在终端里，不需要打开笨重的IDE。启动快、资源低。
3. 本地优先：代码、对话历史默认存在本地，不上传云端。

截至2026年7月，OpenCode在GitHub上已经积累了超过17万颗Star，月活用户达到750万。这个数字说明了一件事：开发者对“被锁住”这件事，比想象中更敏感。

第四步：配置AI模型（最关键的一步）

目标：告诉OpenCode用哪个AI模型来帮你干活。

OpenCode本身是完全免费的，但它本身不提供AI模型——你需要自己准备一个API Key。这就像你买了辆车（OpenCode），但得自己加油（API Key）才能跑。

你可能会问：那我能不能不配置直接用？答案是不行。OpenCode是一个“空壳工具”，没有模型它就不知道该怎么帮你写代码。

方式一：环境变量（最快上手）

这是最直接的配置方式，适合快速测试。

macOS / Linux：

# 以Anthropic Claude为例exportANTHROPIC_API_KEY="sk-ant-你的API密钥"# 或者用OpenAIexportOPENAI_API_KEY="sk-你的API密钥"

Windows PowerShell：

# 以Anthropic Claude为例$env:ANTHROPIC_API_KEY ="sk-ant-你的API密钥"

设置完环境变量后，在当前终端窗口直接运行opencode就能生效。

方式二：配置文件（推荐，更灵活）

如果你不想每次打开终端都重新设置环境变量，可以用配置文件的方式。

创建配置文件~/.config/opencode/opencode.json：

{"$schema":"https://opencode.ai/config.json","provider":{"anthropic":{"apiKey":"sk-ant-你的API密钥"}},"model":"anthropic/claude-sonnet-4-5"}

这里的~代表你的用户目录。Windows用户路径是%USERPROFILE%\.config\opencode\opencode.json。

配置文件的好处是：一次配置，永久生效。而且你可以在不同项目里放不同的opencode.json，实现“项目级”的模型配置。

运行验证：配置完成后，先别急着启动。在终端输入以下命令，确认配置能被正确读取：

# 查看当前配置（不会启动TUI）opencode config

如果能看到你配置的provider和model信息，说明配置生效了。

第五步：启动OpenCode TUI

目标：在终端里跑起OpenCode的交互式界面。

一切准备就绪，终于到了最激动人心的时刻——启动OpenCode。

在终端里输入：

# 启动OpenCode TUI（交互式终端界面）opencode

第一次启动时，OpenCode会在当前目录创建一个.opencode文件夹，用来存放会话数据、配置缓存等。这个过程需要几秒钟，不要着急关掉。

如果一切正常，你会看到一个精致的TUI界面出现在终端里——有状态栏、输入框、对话区域，看起来就像一个专门为AI编程设计的“终端里的IDE”。

界面上的核心元素：

• 底部输入框：在这里输入你的问题或指令
• 状态栏：显示当前使用的是Build还是Plan模式（按Tab键切换）
• 对话区域：显示你和AI的对话历史

运行验证：看到TUI界面出现，并且底部有输入光标在闪烁，说明OpenCode已经成功运行了。

你可以试着在输入框里打一句话：

帮我写一个Python的hello world程序

然后按回车，看看OpenCode怎么回应你——它应该会开始思考、规划，然后生成代码。

注意：如果OpenCode没有任何反应或者报错，大概率是API Key配置有问题。回到第四步检查一下。

第六步：认识两种核心工作模式

目标：理解Build和Plan两种模式的区别，知道什么时候该用哪个。

OpenCode内置了两种主要Agent（智能体），你可以用Tab键随时切换。

Build模式（默认）

职责：代码实现、重构、文件读写——日常开发的主力。

权限：拥有全部工具权限——可以读文件、写文件、执行Shell命令。

什么时候用：当你已经想好了要做什么，直接让AI去执行的时候。比如：“把这个函数的返回值改成布尔类型”、“给这个模块添加单元测试”。

Plan模式

职责：代码库分析、架构规划、安全探索。

权限：拒绝修改文件（edit权限被明确禁止），运行bash命令需要用户确认。

什么时候用：当你不确定改动方案、或者面对一个陌生代码库的时候。先用Plan模式让AI分析、出方案，确认无误后再切换到Build模式执行。

这里有个重要的工作习惯：任何非trivial的任务，永远先跑Plan。先规划、后执行，能避免AI乱改代码带来的灾难。

运行验证：在TUI界面里按一下Tab键，观察状态栏的显示变化——从Build变成Plan，或者反过来。这就是模式切换。

第七步：跑通第一个对话（终极验证）

目标：用OpenCode完成一次真实的代码生成，确认整套环境跑通了。

现在我们来做一个完整的测试——让OpenCode帮你写一个实际能用的东西。

在TUI的输入框里输入以下内容（或者类似的任务）：

创建一个Python脚本，读取当前目录下所有CSV文件，把每个文件的前5行打印出来

然后按回车。

观察OpenCode的响应过程：

1. Plan阶段（如果你在Plan模式下）：它会先分析任务，列出实施方案
2. Build阶段（切换过去之后）：它会生成代码、创建文件、执行验证

如果一切顺利，你会看到：

• OpenCode在对话区域输出它的思考过程
• 它创建了一个.py文件
• 它甚至可能直接运行了脚本并展示结果

运行验证：检查当前目录下是否出现了新的Python文件，文件内容是否合理。如果有，说明你的OpenCode环境已经完全跑通了！

如果第一次请求没有生成预期结果，别急。AI编程本身就有试错成本——继续在对话里补充说明、纠正方向，直到它产出你想要的东西。

异常处理与常见坑

报错1：'opencode' 不是内部或外部命令

'opencode' 不是内部或外部命令，也不是可运行的程序或批处理文件。

原因：npm全局安装的包没有被加到系统的PATH环境变量里。

解决方案：

1. 先找到npm全局安装的路径：

   npmroot-g

   输出类似C:\Users\你的用户名\AppData\Roaming\npm\node_modules

2. 找到对应的bin目录（Windows通常在C:\Users\你的用户名\AppData\Roaming\npm）

3. 把这个路径加到系统的PATH环境变量中：

   • Windows：右键“此电脑” → 属性 → 高级系统设置 → 环境变量 → 在“系统变量”或“用户变量”中找到Path → 编辑 → 新建 → 粘贴npm的bin目录路径
   • macOS/Linux：在~/.bashrc或~/.zshrc中添加：

     exportPATH="$PATH:$(npmroot-g)/bin"

4. 重新打开终端，再次运行opencode --version

报错2：Node.js版本过低

error: opencode-ai@x.x.x requires Node.js version >=18

原因：你的Node.js版本低于18.0。

解决方案：

1. 去 Node.js官网 下载最新的LTS版本（推荐v22.x）
2. 安装完成后重新打开终端
3. 运行node -v确认版本已更新
4. 重新执行npm install -g opencode-ai@latest

报错3：API Key invalid或模型无响应

Error: 401 Unauthorized

或者：你输入了问题，OpenCode一直转圈但没有输出。

原因：API Key没有正确配置，或者配置的Key无效/已过期。

解决方案：

1. 确认API Key是从正规渠道获取的（Anthropic官网、OpenAI平台等）
2. 检查环境变量名称是否正确：
   • Anthropic Claude 用ANTHROPIC_API_KEY
   • OpenAI 用OPENAI_API_KEY
   • Google Gemini 用GEMINI_API_KEY
3. 如果在配置文件中设置，检查JSON格式是否正确——多一个逗号、少一个引号都会导致配置失效
4. 在终端中echo $ANTHROPIC_API_KEY（macOS/Linux）或$env:ANTHROPIC_API_KEY（Windows PowerShell）确认环境变量已正确设置

本章产出总结

完成本篇所有步骤后，你获得了以下成果：

序号	产出物	说明
1	Node.js 18+ 环境	已安装并验证
2	OpenCode CLI工具	全局可用，opencode命令可执行
3	OpenCode配置文件	~/.config/opencode/opencode.json已配置
4	API Key认证	环境变量或配置文件已设置
5	TUI界面可运行	opencode命令能启动交互界面
6	第一个AI对话	成功生成了一段代码

恭喜你！你已经在自己的电脑上搭建好了OpenCode开发环境。接下来，你可以随时在终端里召唤一个AI编程助手，帮你读代码、写代码、改代码。

作者互动与资源引导

写教程最怕的就是“读者照着做但跑不通”。如果你在安装过程中遇到了任何本文没有覆盖到的问题，欢迎在评论区留言，我会一一回复。

另外，如果你觉得这个专栏对你有帮助：

• 关注我，后续每一篇更新你都能第一时间看到
• 关注后私信我，发送暗号“爱学Python”，我会把完整的Python全栈学习路线图和本专栏的源码包发给你

我们也建了一个技术交流群，群里有一群正在学习和使用OpenCode的朋友，大家一起讨论、一起踩坑、一起进步。想进群的朋友在评论区扣个“1”，我拉你。

下篇预告

下一篇文章是[[导论02] 编写OpenCode首个代码生成请求]，我们会真正进入OpenCode的核心功能——用自然语言驱动代码生成。从“能跑”到“会用”，下一篇带你写出第一个像样的项目代码。

如果觉得本篇对你有帮助，点赞、收藏、关注走一波，咱们下篇见！