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

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

OpenCode 是当前 GitHub 上星标最高的开源 AI 编程代理，截至2026年8月，已获得超过 18.9 万 Star。本文将从零开始，带你完成 OpenCode 的安装、配置与实战上手。

一、OpenCode 是什么？

OpenCode 是一款开源（MIT 协议）、模型中立的 AI 编程代理（AI Coding Agent）。它运行在终端中，能够读取你的项目代码、理解上下文、修改文件并执行开发命令。简单说：你给它一个任务（比如“修复这个 Bug”或“添加登录功能”），它会自主规划、执行，并把改动直接写入你的代码库。

它和 ChatGPT 有什么区别？

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 支持三种使用方式：

4. LSP 语言服务器联动

OpenCode 内置自动 LSP 加载机制，能根据项目编程语言自动匹配对应的语言服务器，精准识别代码语法规范、工程结构、变量依赖和接口定义，错误定位准确率突破 90%。

三、安装 OpenCode

OpenCode 依赖 Node.js 18 及以上版本。先确认版本：

node -v

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

方式一：一键安装脚本（最推荐新手）

这是官方最推荐的入门方式：

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

脚本会自动检测操作系统和架构，下载对应二进制文件并配置 PATH。

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

如果你已有 Node.js 环境，这是最顺手的方式：

npm install -g opencode-ai

安装后验证：

opencode –version

方式三：包管理器安装

macOS / Linux（Homebrew） ：

brew install sst/tap/opencode

Windows（Scoop） ：

scoop install opencode

方式四：下载桌面应用

访问 opencode.ai/download 或 GitHub Releases 页面 下载对应平台安装包。

四、配置 AI 模型

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

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

在终端中设置环境变量：

# Anthropic Claude
export ANTHROPIC_API_KEY="你的API密钥"

# OpenAI
export OPENAI_API_KEY="你的API密钥"

# Google Gemini
export GEMINI_API_KEY="你的API密钥"

# DeepSeek
export DEEPSEEK_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. 初始化项目

进入你的项目目录，启动 OpenCode：

cd 你的项目目录
opencode

首次启动时，执行以下命令为项目初始化：

/init

OpenCode 会分析你的项目并在根目录创建 AGENTS.md 文件，帮助它理解项目结构和编码规范。

2. 切换 Plan / Build 模式

在 TUI 界面中，按 Tab 键在 Plan 和 Build 模式间切换。右下角会显示当前模式。

• Plan 模式：适合让 AI 先分析、规划，不做任何修改
• Build 模式：适合让 AI 实际执行编码任务

3. 常用命令

4. 实战示例

场景：为项目添加一个新功能

六、常见问题

Q1：OpenCode 和 Claude Code / Cursor 有什么区别？

OpenCode 是开源、模型中立的 Agent 框架，你可以自由选择任何模型。Claude Code 绑定 Anthropic 模型，Cursor 绑定自己的模型套餐。OpenCode 解决的核心问题是 “供应商锁定” ——把模型选择权彻底交还给开发者。

Q2：我需要在 OpenCode 上花钱吗？

工具本身完全免费（MIT 协议） 。你只需要为自己调用的 AI 模型 API 付费——用多少付多少，OpenCode 不抽成。

Q3：能接入本地模型吗？

可以。OpenCode 支持通过 Ollama 接入本地部署的开源模型。

Q4：Windows 用户安装有什么注意事项？

如果遇到兼容性问题，强烈推荐在 WSL 环境中运行：

wsl —install # PowerShell 管理员模式
wsl # 进入 WSL
curl –fsSL https://opencode.ai/install | bash # 在 WSL 中安装

七、总结

OpenCode 代表了一种新的开发理念：把模型选择权、成本控制权与数据主权彻底交还给开发者。无论你使用 Claude、GPT、Gemini 还是本地模型，OpenCode 都提供了统一的 Agent 框架，让 AI 真正成为你终端里的“程序员同事”。

八、免费额度

关于 OpenCode 的桌面版和免费额度，根据目前的信息，情况是这样的：

OpenCode 本身是一个免费且开源（MIT 协议） 的 AI 编程工具。你可以免费使用它的软件，但使用其内置的模型会受一定的免费额度限制。

🖥️ 关于桌面端

OpenCode 确实有桌面端应用，主要有以下几种形式：

• 官方桌面客户端：OpenCode 官方提供了一个桌面版程序，你可以在官网下载。它支持在终端、IDE 或桌面应用中使用。
• 第三方桌面应用：此外，还有第三方基于 OpenCode 开发的桌面应用，例如 OpenCode Superapp。它是一个本地优先的 macOS 桌面工作区，提供了图形界面（UI），核心功能免费。其付费的“Superpowers”功能（如浏览器自动化等）是一次性买断制。

🆓 关于免费额度

OpenCode 的免费额度主要分为以下几种：

根据实测，内置的免费模型（如DeepSeek V4 Flash）无需注册或登录即可使用，其额度对于日常体验和个人开发已经足够。如果额度用完了，可以等待第二天重置再继续使用。

💎 总结

OpenCode 是一款值得尝试的开源 AI 编程工具。它不仅有桌面版，还提供了非常慷慨的免费额度。你可以直接下载桌面版，无需任何配置即可开始使用内置的免费模型。

九、使用技巧

以下是基于官方文档整理的 opencode 使用指南。

1、TUI 使用手册

斜杠命令（输入 / 触发）

默认领导键（leader）为 ctrl+x，按下后 2 秒内再按对应键。可在 tui.json 自定义。

常用操作技巧

• @ 引用文件：@src/foo.ts 做模糊搜索，文件内容自动加入上下文
• ! 运行命令：!git status 把命令输出作为上下文
• Tab 切换模式：Plan 模式（只给方案不动代码）↔ Build 模式（直接改代码）
• ctrl+t 循环模型变体（如推理强度）；ctrl+a 切换提供商；ctrl+p 命令面板
• 拖拽图片到终端可加入提示词让模型参考

2、CLI 非交互用法

opencode run "Explain closures in JS" # 一次性提问
opencode run -c "继续上个会话" # 继续会话
opencode run –model anthropic/claude-3-5-sonnet "…" # 指定模型
opencode serve # 启动 headless 服务器（HTTP API）
opencode web # 启动 Web 界面
opencode auth login # 登录提供商
opencode models # 列出可用模型
opencode session list # 查看会话
opencode stats # 查看 token 使用与费用
opencode export <id> # 导出会话 JSON
opencode import <file/url> # 导入会话
opencode upgrade # 升级版本
opencode agent create # 创建自定义 Agent
opencode mcp add # 添加 MCP 服务器
opencode plugin <module> # 安装插件

3、使用示例（工作流）

询问代码（用 @ 指文件）：

How is auth handled in @packages/functions/src/api/index.ts

实现功能三步走：

直接改代码：

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 写 Markdown（frontmatter 定义 description/agent/model，正文为提示词模板），支持 $ARGUMENTS、$1/$2、!命令注入、@文件引用，然后在 TUI 里 /test 使用
• 自定义 Agent：opencode agent create 生成带独立 system prompt 和权限的 agent，用 Tab/shift+tab 切换
• Skills：通过 .opencode/skills 注入专项工作流