很多习惯纯键盘流的后端和全栈工程师很喜欢在黑框终端里让智能体直接读写仓库,但又不想被单一模型厂商死死绑定——有时候想用 Claude 改核心业务,有时候想切 GPT 对齐前端,断网时还想连本机 Ollama 跑离线代码。
开源终端编程智能体 OpenCode 正是瞄准这个痛点设计的:自带流畅的终端图形界面(TUI),支持几十家主流模型提供方、LSP 语言服务器诊断以及开放的 MCP 工具协议。如果你之前已经看过如何在 OpenCode 中管理与授权 Skills 技能目录,这篇教程就从头带你把本体装好、把模型和 MCP 一次配通。
本站开发者订阅直达入口:高频跑多文件重构与工具链调用时,搭配固定月费的主力订阅往往比纯烧按量 API 更省钱。国内无境外信用卡可通过支付宝、微信支付或 AlipayHK 在本站免密自助开通 Claude Code 订阅(Pro / Max)、ChatGPT Plus 或浏览 AI 会员充值总览。

一、三行命令跨平台安装 OpenCode
根据你的操作系统,任选下面一种官方推荐方式安装即可:
- 通用跨平台(Windows / macOS / Linux,已装 Node.js):
bash
npm install -g opencode-ai
- macOS / Linux 一键安装脚本:
bash
curl -fsSL https://opencode.ai/install | bash
- Homebrew(macOS / Linux):
bash
brew install anomalyco/tap/opencode
安装完成后,打开任意 Git 项目根目录直接输入 opencode 回车,即可进入交互式终端面板。首次启动你可以输入 /connect 跟随向导交互式填入官方凭据,但对于工程团队来说,直接维护一份标准配置文件更清晰可控。
二、编写 opencode.json:安全接入官方 API 与本地 Ollama
OpenCode 支持两层配置文件合并:全局配置位于 ~/.config/opencode/opencode.json,项目级配置位于仓库根目录的 opencode.json(项目级优先级更高,支持带注释的 .jsonc 格式)。
千万不要把明文密钥写进仓库文件里。OpenCode 原生支持 {env:环境变量名} 插值语法。下面是一个同时挂载云端官方模型与本地离线模型的完整配置示例:
json
{
"$schema": "https://opencode.ai/config.json",
"model": "anthropic/claude-sonnet-4-5",
"provider": {
"anthropic": {
"options": {
"apiKey": "{env:ANTHROPIC_API_KEY}"
}
},
"ollama": {
"npm": "@ai-sdk/openai-compatible",
"name": "Ollama (Local)",
"options": {
"baseURL": "http://localhost:11434/v1"
},
"models": {
"qwen2.5-coder:14b": {
"name": "Qwen 2.5 Coder 14B"
}
}
}
}
}
本地 Ollama 避坑重点:如果你按照 Ollama 本地安装与命令指南刚拉取完模型直接连 OpenCode,经常会发现模型聊两句就“失忆”或报工具解析失败。这是因为 Ollama 默认上下文窗口往往只有 2048 或 4096,装不下终端智能体的系统提示词与代码片段。启动 Ollama 服务前务必先把环境变量OLLAMA_CONTEXT_LENGTH=32768(显存够大可设65536)配好。
重度编码配额与双引擎互补建议:在开源插件或终端智能体里处理大型单体仓库时,不少工程师会同时备好一套包月封顶的官方订阅兜底复杂架构攻坚。可按需前往查看 Claude Max 5x / 20x 充值说明、Claude Pro iOS 自助卡密 或 ChatGPT Pro 充值页。
三、在 opencode.json 中挂载本地与远程 MCP 服务
OpenCode 的 MCP 配置写法和 Claude Desktop 略有出入,最容易踩坑的地方有两个:必须显式声明 "type": "local" 或 "remote",且本地子进程注入环境变量的字段名叫 "environment"(写成 "env" 会导致子进程拿不到密钥)。

在同一个 opencode.json 中追加 "mcp" 节点即可同时挂载本地命令行工具与远程 HTTP 网关:
json
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"filesystem-docs": {
"type": "local",
"command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "./docs"],
"enabled": true
},
"brave-search": {
"type": "local",
"command": ["npx", "-y", "@modelcontextprotocol/server-brave-search"],
"environment": {
"BRAVE_API_KEY": "{env:BRAVE_API_KEY}"
},
"enabled": true
},
"team-gateway": {
"type": "remote",
"url": "https://mcp.internal.example.com/mcp",
"headers": {
"Authorization": "Bearer {env:TEAM_MCP_TOKEN}"
},
"enabled": true
}
}
}
保存后进入 opencode 会话,输入斜杠命令 /mcp 即可查看每一路外部服务的连接状态与已加载工具列表。平时用不到的重型 MCP 服务,把 "enabled" 改成 false 就能临时卸下工具描述,省下每轮对话的基础 Token 开销。
四、高频实战手势:Tab 键切换 Plan / Build 与 /undo
真正上手改代码时,记住下面三个快捷键就能把节奏控得很稳:
- 按
Tab键在Plan与Build之间秒切:OpenCode 默认内置两个主智能体角色。拿到复杂需求先按Tab切到Plan(只读规划模式),此时任何写文件或危险修改动作都会被拦截,专心让模型读代码出方案;等你在屏幕上核对完改造思路,再按一下Tab切回Build(构建读写模式) 放手执行。 - 输入
/init生成项目说明书:在陌生老项目首次启动时敲/init,OpenCode 会自动扫描工程栈与目录约定,在根目录生成一份AGENTS.md(与 Cursor、Codex 等工具直接互通)。 - 输入
/undo与/redo无损反悔:智能体某一步把逻辑改劈叉了,不用退出终端敲 Git 命令,直接在对话框输入/undo即可撤回上一轮文件修改与对话节点。
如果你既喜欢终端极速编码体验,又不想每天操心按量 API 账单波动,也可以同时在电脑上配置官方包月订阅制终端工具(详见 Claude Code 官方安装方法对比)。需要开通海外官方开发订阅的同学,可前往查看贝果研究社 Claude Code 订阅与配置方案或全站 AI 订阅自助充值中心。
常见问题
在 Windows PowerShell 里运行 opencode 界面边框乱码或快捷键失灵怎么办?
OpenCode 的现代终端渲染依赖完整的 TrueColor 与键盘协议支持。不要使用老旧的系统自带 cmd.exe 窗口,建议升级使用 Windows Terminal(或在 WSL2 Ubuntu 子系统内运行),并安装任意一款 Nerd Font 编程等宽字体,界面图标与分栏就会完全正常。
如何在团队里切换不同模型而不必每次改配置文件?
在会话界面随时敲 /models 斜杠命令,即可弹出你在 provider 中已配好密钥的所有可用模型列表,上下方向键回车就能在当前窗口热切换模型。
国内没有海外信用卡,怎么开通 Claude Code 或 ChatGPT 编程订阅?
可直接在 本站充值中心 使用支付宝、微信支付或 AlipayHK 下单获取自助卡密,支持免上号兑换 Claude Pro、Claude Max 与 ChatGPT Plus / Pro,可开具增值税发票;实时价格、兑换前提与售后边界(封号不在质保范围)以对应商品页说明为准。
小结
- 用
npm install -g opencode-ai即可跨平台装好 OpenCode,通过opencode.json里的{env:变量名}安全引用各家官方 API 密钥。 - 接入本地 Ollama 记得提前调大
OLLAMA_CONTEXT_LENGTH;接入本地 MCP 服务务必写清"type": "local"与"environment"环境变量块。 - 养成“先按
Tab用 Plan 模式看清方案、再按Tab切 Build 落盘修改”的习惯,跑偏随时敲/undo回退。
0 条评论
还没有评论,来抢沙发~