OpenCode 完全入门指南：开源 AI 编程代理从安装到实战

OpenCode 完全入门指南开源 AI 编程代理从安装到实战OpenCode 是当前 GitHub 上星标最高的开源 AI 编程代理截至2026年8月已获得超过18.9 万Star。本文将从零开始带你完成 OpenCode 的安装、配置与实战上手。一、OpenCode 是什么OpenCode 是一款开源MIT 协议、模型中立的 AI 编程代理AI Coding Agent。它运行在终端中能够读取你的项目代码、理解上下文、修改文件并执行开发命令。简单说你给它一个任务比如“修复这个 Bug”或“添加登录功能”它会自主规划、执行并把改动直接写入你的代码库。它和 ChatGPT 有什么区别ChatGPTOpenCode交互方式你问一句它答一句你说目标它执行任务代码操作你复制粘贴它直接读写文件、运行命令项目理解需要你贴上下文自动理解整个项目结构OpenCode 不是帮你补全一行代码的工具是替你把完整编码任务做完的 Agent。核心优势100% 开源免费MIT 协议工具本身不收一分钱模型中立无供应商锁定支持75 种以上模型提供商包括 OpenAI、Anthropic、Google、DeepSeek以及本地部署的 Ollama 等终端优先本地运行所有代码解析、生成、修改全部在本地完成不上传云端Plan/Build 双模式先规划再执行避免 AI 盲目修改注博客https://blog.csdn.net/badao_liumang_qizhi二、核心功能详解1. Plan / Build 双模式OpenCode 最具标志性的设计是Plan规划和 Build构建双模式。Plan 模式只读AI 只分析代码、制定方案不会做任何实际修改。适合探索不熟悉的项目或评估改动影响。Build 模式执行AI 拥有完整权限可直接读写文件、执行命令、运行测试。两种模式通过Tab 键一键切换右下角会显示当前模式指示器。官方建议新功能先切 Plan 模式看方案满意后再切 Build 模式执行。2. 主 / 子 Agent 协作架构OpenCode 采用主 Agent 调度 子 Agent 执行的分层架构主 Agent负责任务拆解、调度和全局把控子 Agent由主 Agent 生成负责执行具体的独立子任务如调研、编码、测试这种设计实现了上下文隔离和任务并行在处理大型项目时优势尤为明显。3. 多端支持OpenCode 支持三种使用方式形态适用场景终端 TUI主力交互方式键盘驱动响应快桌面应用BetaWindows / macOS / Linux 图形界面IDE 扩展VS Code、Cursor 等编辑器插件4. LSP 语言服务器联动OpenCode 内置自动 LSP 加载机制能根据项目编程语言自动匹配对应的语言服务器精准识别代码语法规范、工程结构、变量依赖和接口定义错误定位准确率突破 90%。三、安装 OpenCodeOpenCode 依赖Node.js 18 及以上版本。先确认版本node-v如果版本过低先去 Node.js 官网 下载 18.x 或更高版本。方式一一键安装脚本最推荐新手这是官方最推荐的入门方式curl-fsSLhttps://opencode.ai/install|bash脚本会自动检测操作系统和架构下载对应二进制文件并配置 PATH。方式二npm 全局安装最常用如果你已有 Node.js 环境这是最顺手的方式npminstall-gopencode-ai安装后验证opencode--version方式三包管理器安装macOS / LinuxHomebrewbrewinstallsst/tap/opencodeWindowsScoopscoopinstallopencode方式四下载桌面应用访问opencode.ai/download或 GitHub Releases 页面 下载对应平台安装包。平台下载文件macOS (Apple Silicon)opencode-desktop-mac-arm64.dmgmacOS (Intel)opencode-desktop-mac-x64.dmgWindowsopencode-desktop-windows-x64.exe四、配置 AI 模型OpenCode 本身是免费的但你需要自己准备一个 AI 模型的 API Key。方式一环境变量最快上手在终端中设置环境变量# Anthropic ClaudeexportANTHROPIC_API_KEY你的API密钥# OpenAIexportOPENAI_API_KEY你的API密钥# Google GeminiexportGEMINI_API_KEY你的API密钥# DeepSeekexportDEEPSEEK_API_KEY你的API密钥Windows PowerShell$env:ANTHROPIC_API_KEY 你的API密钥方式二配置文件推荐更灵活在项目根目录或~/.config/opencode/下创建opencode.json配置文件。以配置阿里云百炼平台为例使用通义千问模型{$schema:https://opencode.ai/config.json,provider:{qwen:{npm:ai-sdk/openai-compatible,name:Qwen,apiKey:你的百炼API Key,baseURL:https://dashscope.aliyuncs.com/compatible-mode/v1}},model:qwen/qwen3.7-max}方式三使用 OpenCode Zen零配置入门如果你是第一次接触 LLM 提供商推荐使用OpenCode Zen。在 TUI 中执行/connect命令选择opencode然后访问 opencode.ai/auth 完成认证即可获得经过验证的精选模型。五、开始使用1. 初始化项目进入你的项目目录启动 OpenCodecd你的项目目录 opencode首次启动时执行以下命令为项目初始化/initOpenCode 会分析你的项目并在根目录创建AGENTS.md文件帮助它理解项目结构和编码规范。2. 切换 Plan / Build 模式在 TUI 界面中按Tab 键在 Plan 和 Build 模式间切换。右下角会显示当前模式。Plan 模式适合让 AI 先分析、规划不做任何修改Build 模式适合让 AI 实际执行编码任务3. 常用命令命令功能/model切换当前使用的 AI 模型/connect配置新的模型提供商/init初始化项目生成 AGENTS.md/undo撤销上一次 AI 做的修改4. 实战示例场景为项目添加一个新功能在项目目录启动opencode按Tab切换到Plan 模式输入“我想在用户登录后增加一个欢迎邮件发送功能请先给出实现方案”审阅 AI 给出的计划如有需要可补充细节对计划满意后按Tab切回Build 模式输入“按刚才的方案开始实施”AI 会自动读写文件、执行命令完成整个功能的开发六、常见问题Q1OpenCode 和 Claude Code / Cursor 有什么区别OpenCode 是开源、模型中立的 Agent 框架你可以自由选择任何模型。Claude Code 绑定 Anthropic 模型Cursor 绑定自己的模型套餐。OpenCode 解决的核心问题是“供应商锁定”——把模型选择权彻底交还给开发者。Q2我需要在 OpenCode 上花钱吗工具本身完全免费MIT 协议。你只需要为自己调用的 AI 模型 API 付费——用多少付多少OpenCode 不抽成。Q3能接入本地模型吗可以。OpenCode 支持通过 Ollama 接入本地部署的开源模型。Q4Windows 用户安装有什么注意事项如果遇到兼容性问题强烈推荐在 WSL 环境中运行wsl--install# PowerShell 管理员模式wsl# 进入 WSLcurl-fsSL https://opencode.ai/install|bash# 在 WSL 中安装七、总结特性说明开源协议MIT完全免费模型支持75 家提供商任意切换核心模式Plan规划/ Build执行双模式使用方式终端 TUI / 桌面应用 / IDE 扩展数据安全本地优先不上传云端GitHub Star18.9 万截至2026年8月OpenCode 代表了一种新的开发理念把模型选择权、成本控制权与数据主权彻底交还给开发者。无论你使用 Claude、GPT、Gemini 还是本地模型OpenCode 都提供了统一的 Agent 框架让 AI 真正成为你终端里的“程序员同事”。八、免费额度关于 OpenCode 的桌面版和免费额度根据目前的信息情况是这样的OpenCode 本身是一个免费且开源MIT 协议的 AI 编程工具。你可以免费使用它的软件但使用其内置的模型会受一定的免费额度限制。️ 关于桌面端OpenCode 确实有桌面端应用主要有以下几种形式官方桌面客户端OpenCode 官方提供了一个桌面版程序你可以在官网下载。它支持在终端、IDE 或桌面应用中使用。第三方桌面应用此外还有第三方基于 OpenCode 开发的桌面应用例如OpenCode Superapp。它是一个本地优先的 macOS 桌面工作区提供了图形界面UI核心功能免费。其付费的“Superpowers”功能如浏览器自动化等是一次性买断制。 关于免费额度OpenCode 的免费额度主要分为以下几种免费模型/方式每日额度频率限制备注内置免费模型(如 DeepSeek V4 Flash, MiMo V2.5)700 - 1400次调用每5小时约150-300次调用无需任何配置开箱即用。额度用完后需等待重置。OpenCode Zen 免费层200次请求每5小时200次请求可能是体验特定模型的免费层级。Qwen OAuth 插件(如opencode-qwen-auth)1000或2000次请求60次/分钟需通过插件用qwen.ai账号认证免费额度在UTC午夜重置。根据实测内置的免费模型如DeepSeek V4 Flash无需注册或登录即可使用其额度对于日常体验和个人开发已经足够。如果额度用完了可以等待第二天重置再继续使用。 总结OpenCode 是一款值得尝试的开源 AI 编程工具。它不仅有桌面版还提供了非常慷慨的免费额度。你可以直接下载桌面版无需任何配置即可开始使用内置的免费模型。九、使用技巧以下是基于官方文档整理的 opencode 使用指南。1、TUI 使用手册斜杠命令输入/触发命令功能快捷键/help帮助对话框-/new新建会话ctrlx n/sessions列出/切换会话ctrlx l/undo撤销上一条消息及文件更改ctrlx u/redo重做需要 git 仓库ctrlx r/compact压缩当前会话上下文ctrlx c/init生成/更新 AGENTS.md-/models列出可用模型ctrlx m/share分享会话生成链接-/export导出会话为 Markdownctrlx x/connect添加 LLM 提供商-/themes切换主题ctrlx t/thinking切换思考过程显示-/editor用外部编辑器写消息ctrlx e/exit退出ctrlx q默认领导键leader为ctrlx按下后 2 秒内再按对应键。可在tui.json自定义。常用操作技巧引用文件src/foo.ts做模糊搜索文件内容自动加入上下文!运行命令!git status把命令输出作为上下文Tab切换模式Plan 模式只给方案不动代码↔Build 模式直接改代码ctrlt循环模型变体如推理强度ctrla切换提供商ctrlp命令面板拖拽图片到终端可加入提示词让模型参考2、CLI 非交互用法opencode runExplain closures in JS# 一次性提问opencode run-c继续上个会话# 继续会话opencode run--modelanthropic/claude-3-5-sonnet...# 指定模型opencode serve# 启动 headless 服务器HTTP APIopencode web# 启动 Web 界面opencode auth login# 登录提供商opencode models# 列出可用模型opencode session list# 查看会话opencode stats# 查看 token 使用与费用opencodeexportid# 导出会话 JSONopencodeimportfile/url# 导入会话opencode upgrade# 升级版本opencode agent create# 创建自定义 Agentopencode mcpadd# 添加 MCP 服务器opencode pluginmodule# 安装插件3、使用示例工作流询问代码用指文件How is auth handled in packages/functions/src/api/index.ts实现功能三步走Tab进入 Plan 模式 →When a user deletes a note, flag it as deleted...查看方案给反馈迭代Tab切回 Build 模式 →Sounds good! Go ahead.直接改代码Add authentication to /settings. Look at how /notes handles it in notes.ts and implement the same in settings.ts撤销修改/undo多次执行可撤多步/redo恢复。4、自定义配置opencode.json模型、Agent、权限、命令、MCP、LSP、格式器等运行时配置tui.json主题、快捷键、滚动、提示音等界面配置自定义命令在.opencode/commands/test.md写 Markdownfrontmatter 定义 description/agent/model正文为提示词模板支持$ARGUMENTS、$1/$2、!命令注入、文件引用然后在 TUI 里/test使用自定义 Agentopencode agent create生成带独立 system prompt 和权限的 agent用Tab/shifttab切换Skills通过.opencode/skills注入专项工作流