从零开始：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 Claude

export ANTHROPIC_API_KEY=your-key-here

OpenAI

export OPENAI_API_KEY=your-key-here

Google Gemini

export 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-project
opencode
OpenCode会以当前目录作为项目上下文，自动读取文件结构。

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

四、一个真实的上手案例
假设你要给一个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之后，你做的第一件事是什么？

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

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

推荐学习
软件测试开发快速落地智能化测试公开课，从Web/App/接口测试智能体，再到业务测试用例生成，爱测智能化测试平台，手把手带你掌握AI智能体与智能化测试平台！

👇扫码进群，报名学习！

你准备拿OpenCode做的第一个真实任务是什么？留言聊聊。

关于我们
霍格沃兹测试开发学社，隶属于 测吧（北京）科技有限公司，是一个面向软件测试爱好者的技术交流社区。

学社围绕现代软件测试工程体系展开，内容涵盖软件测试入门、自动化测试、性能测试、接口测试、测试开发、全栈测试，以及人工智能测试与 AI 在测试工程中的应用实践。

我们关注测试工程能力的系统化建设，包括 Python 自动化测试、Java 自动化测试、Web 与 App 自动化、持续集成与质量体系建设，同时探索 AI 驱动的测试设计、用例生成、自动化执行与质量分析方法，沉淀可复用、可落地的测试开发工程经验。

在技术社区与工程实践之外，学社还参与测试工程人才培养体系建设，面向高校提供测试实训平台与实践支持，组织开展 “火焰杯” 软件测试相关技术赛事，并探索以能力为导向的人才培养模式，包括高校学员先学习、就业后付款的实践路径。

同时，学社结合真实行业需求，为在职测试工程师与高潜学员提供名企大厂 1v1 私教服务，用于个性化能力提升与工程实践指导。