前言你是不是还在为每个月花20美元订阅Cursor而心疼或者每次用Claude Code都得小心翼翼地计算Token消耗更别提那些被厂商绑定、想换个模型就得换整套工具的尴尬了。大家好欢迎来到《全网最新OpenCode入门到精通》专栏的第一篇文章。这个专栏的目标只有一个——手把手带你从零掌握OpenCode真正把AI编程Agent用起来而不是装完就吃灰。本篇是这个专栏的导论篇也是整个系列的基础。读完这一篇你会完成OpenCode的完整安装和配置在终端里跑起一个能对话的TUI界面并了解两种核心工作模式的区别。学完本篇你就能在终端里跟AI对话了——对就是这么直接。建议先点个关注收藏这个专栏后续每一篇都会带你往前迈一步从环境搭建到实际项目落地不绕路、不废话。环境与前置说明因为是专栏的第一篇所以没有任何前置依赖。你只需要准备一台电脑Windows、macOS、Linux都行网络环境能正常访问外网安装时需要拉取资源本篇会用到的核心依赖依赖版本要求说明Node.js18.0 或更高推荐v22 LTSOpenCode基于Node.js运行npm随Node.js一起安装用于全局安装OpenCodeOpenCode最新版通过npm安装本篇主角如果你用的是Windows强烈建议在WSL2环境中操作能省掉很多兼容性问题。当然直接用Windows PowerShell或CMD也行只是遇到问题的概率会高一点。核心内容第一步检查Node.js环境目标确认你的电脑已经安装了Node.js且版本符合要求。OpenCode是一个Node.js工具必须先有Node.js环境才能安装。这一步看似简单但很多人卡在这一步——要么没装要么版本太低。打开你的终端Windows用PowerShell或CMDmacOS/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-ailatest这里解释一下这条命令在做什么npm install -g全局安装这样你在任何目录下都能直接使用opencode命令opencode-aiOpenCode在npm上的包名latest安装最新版本避免装到旧版安装过程需要从npm仓库下载依赖包取决于你的网络速度可能需要1-3分钟。如果卡住了别急着CtrlC耐心等一等。国内用户如果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有三个核心特点值得你记住模型中立不绑定任何一家模型厂商。Claude、GPT、Gemini、DeepSeek或者本地跑的Ollama你想用哪个用哪个。终端优先跑在终端里不需要打开笨重的IDE。启动快、资源低。本地优先代码、对话历史默认存在本地不上传云端。截至2026年7月OpenCode在GitHub上已经积累了超过17万颗Star月活用户达到750万。这个数字说明了一件事开发者对“被锁住”这件事比想象中更敏感。第四步配置AI模型最关键的一步目标告诉OpenCode用哪个AI模型来帮你干活。OpenCode本身是完全免费的但它本身不提供AI模型——你需要自己准备一个API Key。这就像你买了辆车OpenCode但得自己加油API Key才能跑。你可能会问那我能不能不配置直接用答案是不行。OpenCode是一个“空壳工具”没有模型它就不知道该怎么帮你写代码。方式一环境变量最快上手这是最直接的配置方式适合快速测试。macOS / Linux# 以Anthropic Claude为例exportANTHROPIC_API_KEYsk-ant-你的API密钥# 或者用OpenAIexportOPENAI_API_KEYsk-你的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实现“项目级”的模型配置。运行验证配置完成后先别急着启动。在终端输入以下命令确认配置能被正确读取# 查看当前配置不会启动TUIopencode 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的响应过程Plan阶段如果你在Plan模式下它会先分析任务列出实施方案Build阶段切换过去之后它会生成代码、创建文件、执行验证如果一切顺利你会看到OpenCode在对话区域输出它的思考过程它创建了一个.py文件它甚至可能直接运行了脚本并展示结果运行验证检查当前目录下是否出现了新的Python文件文件内容是否合理。如果有说明你的OpenCode环境已经完全跑通了如果第一次请求没有生成预期结果别急。AI编程本身就有试错成本——继续在对话里补充说明、纠正方向直到它产出你想要的东西。异常处理与常见坑报错1opencode 不是内部或外部命令opencode 不是内部或外部命令也不是可运行的程序或批处理文件。原因npm全局安装的包没有被加到系统的PATH环境变量里。解决方案先找到npm全局安装的路径npmroot-g输出类似C:\Users\你的用户名\AppData\Roaming\npm\node_modules找到对应的bin目录Windows通常在C:\Users\你的用户名\AppData\Roaming\npm把这个路径加到系统的PATH环境变量中Windows右键“此电脑” → 属性 → 高级系统设置 → 环境变量 → 在“系统变量”或“用户变量”中找到Path → 编辑 → 新建 → 粘贴npm的bin目录路径macOS/Linux在~/.bashrc或~/.zshrc中添加exportPATH$PATH:$(npmroot-g)/bin重新打开终端再次运行opencode --version报错2Node.js版本过低error: opencode-aix.x.x requires Node.js version 18原因你的Node.js版本低于18.0。解决方案去 Node.js官网 下载最新的LTS版本推荐v22.x安装完成后重新打开终端运行node -v确认版本已更新重新执行npm install -g opencode-ailatest报错3API Key invalid或模型无响应Error: 401 Unauthorized或者你输入了问题OpenCode一直转圈但没有输出。原因API Key没有正确配置或者配置的Key无效/已过期。解决方案确认API Key是从正规渠道获取的Anthropic官网、OpenAI平台等检查环境变量名称是否正确Anthropic Claude 用ANTHROPIC_API_KEYOpenAI 用OPENAI_API_KEYGoogle Gemini 用GEMINI_API_KEY如果在配置文件中设置检查JSON格式是否正确——多一个逗号、少一个引号都会导致配置失效在终端中echo $ANTHROPIC_API_KEYmacOS/Linux或$env:ANTHROPIC_API_KEYWindows PowerShell确认环境变量已正确设置本章产出总结完成本篇所有步骤后你获得了以下成果序号产出物说明1Node.js 18 环境已安装并验证2OpenCode CLI工具全局可用opencode命令可执行3OpenCode配置文件~/.config/opencode/opencode.json已配置4API Key认证环境变量或配置文件已设置5TUI界面可运行opencode命令能启动交互界面6第一个AI对话成功生成了一段代码恭喜你你已经在自己的电脑上搭建好了OpenCode开发环境。接下来你可以随时在终端里召唤一个AI编程助手帮你读代码、写代码、改代码。作者互动与资源引导写教程最怕的就是“读者照着做但跑不通”。如果你在安装过程中遇到了任何本文没有覆盖到的问题欢迎在评论区留言我会一一回复。另外如果你觉得这个专栏对你有帮助关注我后续每一篇更新你都能第一时间看到关注后私信我发送暗号“爱学Python”我会把完整的Python全栈学习路线图和本专栏的源码包发给你我们也建了一个技术交流群群里有一群正在学习和使用OpenCode的朋友大家一起讨论、一起踩坑、一起进步。想进群的朋友在评论区扣个“1”我拉你。下篇预告下一篇文章是[[导论02] 编写OpenCode首个代码生成请求]我们会真正进入OpenCode的核心功能——用自然语言驱动代码生成。从“能跑”到“会用”下一篇带你写出第一个像样的项目代码。如果觉得本篇对你有帮助点赞、收藏、关注走一波咱们下篇见