从零开始:OpenCode AI 编程助手完整配置指南

关注霍格沃兹软件测试开发公众号，回复「资料」, 领取人工智能测试开发技术合集

一、终端里的那个提示符，正在被重新定义
二、本质不是另一个ChatGPT，是给你配了个干活的人
三、从零到一：完整安装与配置拆解
四、一个真实的上手案例
五、对你意味着什么
六、最后问你一个问题

一、终端里的那个提示符，正在被重新定义

先问一个问题。

你打开终端，面对那个闪烁的光标，脑子里想的还是一行一行敲命令吗？

过去几个月，越来越多人的终端里多了一个东西——一个能读代码、能改文件、能跑命令、能自己规划任务然后执行的AI Agent。它不是帮你补全一行代码，是帮你完成一个完整的编码任务。

OpenCode在GitHub上已经积累了超过17万颗星，月活用户达到750万。支持75种以上的AI模型提供商，从Claude、GPT、Gemini到本地部署的Ollama，全部可以接入。

但很多人装完OpenCode之后，面对TUI界面不知道该做什么。API Key不知道放哪，模型不知道怎么切，Plan和Build两种模式搞不清楚什么时候用。

这篇文章不讲概念，讲步骤。

二、本质不是另一个ChatGPT，是给你配了个干活的人

先搞清楚OpenCode到底是什么。

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

核心差异有三点。

模型中立。OpenCode不绑定任何一家模型厂商。你可以用Claude、用GPT、用Gemini、用DeepSeek，也可以用Ollama跑本地模型。想换就换，配置文件里改一行的事情。

终端优先。OpenCode运行在终端里，不需要打开一个重型IDE。启动速度快、资源占用低，适合远程开发、服务器端调试、快速脚本编写。

本地优先。代码、对话历史、文件操作默认全部存储在本地，不上传云端。支持完全离线部署。

本质上，OpenCode解决的是一个老问题：你脑子里的想法，怎么最快变成代码。传统方式是键盘敲、鼠标点、窗口切。OpenCode的方式是：你说目标，它执行。

可以被截图传播的观点句1：OpenCode不是帮你写代码的工具，是替你把代码写完的Agent。

三、从零到一：完整安装与配置拆解

下面按步骤来。

3.1 环境准备

OpenCode依赖Node.js环境，版本需要18及以上。

node -v

如果版本过低，去Node.js官网下载18.x或更高版本。

3.2 安装OpenCode

三种主流安装方式。

方式一：npm全局安装（最常用）

npm install -g opencode-ai

安装完成后验证：

opencode --version

出现版本号即表示安装成功。

方式二：一键安装脚本（适合新手）

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

方式三：包管理器安装

macOS/Linux用Homebrew：

brew install sst/tap/opencode

Windows用Scoop：

scoop install opencode

Windows用户如果遇到兼容性问题，推荐在WSL环境中运行。

3.3 配置AI模型

这是最关键的一步。OpenCode本身是免费的，但你需要自己准备一个AI模型的API Key。

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

# Anthropic Claudeexport ANTHROPIC_API_KEY=your-key-here# OpenAIexport OPENAI_API_KEY=your-key-here# Google Geminiexport GEMINI_API_KEY=your-key-here

Windows PowerShell：

$env:ANTHROPIC_API_KEY = "your-key-here"

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

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

{"$schema": "https://opencode.ai/config.json","provider": {"my-provider": {"npm": "@ai-sdk/openai-compatible","name": "MyProvider","options": {"baseURL": "https://api.your-provider.com/v1","apiKey": "your-api-key-here"      },"models": {"model-name": {"name": "model-name"        }      }    }  },"model": "my-provider/model-name"}

不同操作系统的配置文件路径：

macOS/Linux: ~/.config/opencode/opencode.json
Windows: C:\Users\你的用户名\.config\opencode\opencode.json

配置完成后，在OpenCode中输入 /model 即可看到已配置的模型列表。

方式三：交互式配置

在OpenCode TUI中输入 /connect 命令，按提示完成配置。

3.4 国内用户的模型选择

国内网络环境下，有几个推荐方案：

DeepSeek API：国产模型，国内可直接访问
阿里通义千问：通过阿里云百炼接入
本地Ollama模型：完全本地运行，无需网络

3.5 启动OpenCode

进入你的项目目录：

cd your-projectopencode

OpenCode会以当前目录作为项目上下文，自动读取文件结构。

首次启动后，你会看到一个TUI界面。直接输入问题即可开始对话。

人工智能技术学习交流群

伙伴们，对AI测试、大模型评测、质量保障感兴趣吗？我们建了一个 「人工智能测试开发交流群」，专门用来探讨相关技术、分享资料、互通有无。无论你是正在实践还是好奇探索，都欢迎扫码加入，一起抱团成长！期待与你交流！👇

四、一个真实的上手案例

假设你要给一个Python项目添加一个新的API接口。

传统方式：打开代码、看现有路由结构、写新路由函数、写参数校验、写单元测试、手动运行测试、看报错、改代码、再测。

用OpenCode的方式：

在项目目录下启动OpenCode，输入：

在现有的FastAPI应用中，添加一个GET接口 /api/v1/users/{user_id}，返回用户信息。参考已有的用户模块写法，同时生成对应的单元测试。

OpenCode会做这些事情：读取现有代码结构、理解FastAPI的路由模式、生成符合项目风格的新接口代码、生成对应的测试用例、直接把改动写入文件。

你只需要review改动，然后运行测试验证。

整个过程从“几十分钟的机械劳动”变成“几分钟的review和验证”。

Plan与Build两种模式的用法：

Plan模式：只分析和规划，不修改任何文件。适合在动手之前先确认方案。
Build模式：完整工具访问权限，可以编辑文件、执行命令。适合确认方案后的实际执行。

按Tab键可以在两种模式间切换。

可以被截图传播的观点句2：Plan模式让你先确认方向对不对，Build模式让你直接拿到结果。两个模式，一个用来防错，一个用来提效。

五、对你意味着什么

对在校生

你现在看到的OpenCode，代表的是未来三到五年开发方式的一个方向。不是“AI帮你写代码”，是“AI Agent替你完成编码任务”。理解Agent的工作机制——怎么收集上下文、怎么规划步骤、怎么调用工具——比学会某个具体工具的用法重要得多。

对初级工程师

你可能已经在用AI辅助编程了。但如果你只是复制粘贴ChatGPT的代码，那你的效率提升有限。OpenCode这类工具的真正价值在于：它能把“意图”直接变成“代码变更”。你不需要会写每一行代码，但你需要会描述清楚你要什么，以及会review AI生成的结果。

对中级工程师

你面临的已经不是“工具怎么用”的问题，而是“工具怎么融入团队工作流”的问题。OpenCode支持项目级配置文件、支持MCP扩展、支持Oh-My-OpenCode多Agent编排。你可以把团队的编码规范、项目规则写进配置文件，让AI自动遵守。这才是可规模化的提效。

六、最后问你一个问题

装完OpenCode、配好API Key之后，你做的第一件事是什么？

是随便问一句“帮我写个排序函数”试试水，还是打开一个真实项目，让它帮你完成一个真正的开发任务？

这两个选择的差距，就是“玩一玩”和“用起来”的差距。