目标：了解 OpenCode 是什么、能做什么、适合谁用
OpenCode 是什么
OpenCode 是一个开源的 AI 编码代理（AI Coding Agent）。简单来说，它是一个住在你的终端/编辑器里的智能助手，能帮你：
- 💬 聊天式编程 — 用自然语言描述需求，它帮你写代码
- 🔍 代码分析 — 理解整个代码库，回答你关于代码的任何问题
- 🛠️ 自动修改 — 直接编辑文件、重构代码、添加功能
- 🧠 计划与执行 — 复杂任务先制定计划，你确认后再执行
AI 代理架构图
OpenCode 核心架构
请求处理流程
与类似工具对比
| 工具 | 类型 | 开源 | 界面 | 模型支持 | 特点 |
|---|---|---|---|---|---|
| OpenCode | AI Agent | ✅ | TUI/Web/IDE | 75+ 提供商 | 开源、多界面、MCP 扩展 |
| Claude Code | AI Agent | ❌ | CLI | 仅 Claude | 官方出品、深度集成 |
| Cursor | IDE | ❌ | 桌面应用 | 多模型 | 完整 IDE、Composer |
| GitHub Copilot | 代码补全 | ❌ | IDE 插件 | OpenAI/Copilot | 实时代码补全 |
| Aider | AI Agent | ✅ | CLI | 多模型 | 专注 Git 集成 |
| Continue | IDE 插件 | ✅ | VS Code 插件 | 多模型 | 开源 IDE 助手 |
功能矩阵对比
| 功能 | OpenCode | Claude Code | Cursor | Copilot | Aider |
|---|---|---|---|---|---|
| 开源 | ✅ | ❌ | ❌ | ❌ | ✅ |
| 多 LLM 支持 | ✅ 75+ | ❌ | ✅ | ❌ | ✅ |
| TUI 界面 | ✅ | ✅ | ❌ | ❌ | ✅ |
| Web 界面 | ✅ | ❌ | ❌ | ❌ | ❌ |
| 计划/构建模式 | ✅ | ❌ | ✅ | ❌ | ❌ |
| MCP 扩展 | ✅ | ❌ | ❌ | ❌ | ❌ |
| 撤销/重做 | ✅ | ❌ | ✅ | ❌ | ✅ |
| 对话分享 | ✅ | ❌ | ❌ | ❌ | ❌ |
核心概念
1. 代理（Agent）
OpenCode 的核心是一个代理 — 一个能自主决策的 AI 程序。它会：
- 理解你的需求
- 决定使用什么工具
- 执行操作（读文件、写代码、运行命令）
- 返回结果
2. 工具（Tools）
工具是代理的"手脚"。OpenCode 自带丰富的内置工具：
| 工具 | 作用 | 示例 |
|---|---|---|
edit | 编辑文件 | 修改函数实现、添加新组件 |
bash | 运行终端命令 | npm test、数据库迁移 |
webfetch | 获取网页内容 | 查文档、读 API 说明 |
read | 读取文件 | 分析代码、理解上下文 |
skill | 加载代理技能 | 加载自动化工作流 |
你也可以通过 MCP（Model Context Protocol） 添加外部工具，如数据库查询、Slack 通知等。
3. 模式（Modes）
OpenCode 有两种工作模式，按 Tab 键切换：
| 模式 | 说明 | 适合场景 |
|---|---|---|
| 计划模式 Plan | 只分析不修改，输出执行计划 | 复杂功能开发 |
| 构建模式 Build | 直接执行修改 | 简单修改、快速迭代 |
4. 配置文件
OpenCode 使用 opencode.json（或 opencode.jsonc）配置文件：
- 全局配置 —
~/.config/opencode/opencode.json，你的个人偏好 - 项目配置 — 项目根目录的
opencode.json，团队共享设置 - AGENTS.md — 项目说明文件，帮助 AI 理解项目
实际使用场景案例
案例 1：快速理解陌生代码库
场景：你刚入职，接手一个 10 万行的微服务项目，需要在 3 天内修复一个生产 Bug。
传统方式：
- 花 2 天阅读文档和代码
- 第 3 天才能定位问题
使用 OpenCode：
cd /project
opencode🤖 帮我找到处理支付回调的逻辑，特别是当支付状态为 pending 时的处理流程
- AI 自动读取相关文件、绘制调用链
- 30 分钟内定位到问题根因
- 给出修复建议和代码修改
案例 2：跨语言技术迁移
场景：团队决定把 Python Flask 后端迁移到 Go，需要重写核心 API。
使用 OpenCode：
🤖 参考 @app/routes/user.py 的实现，在 Go 中创建对应的 user handler，
使用 Gin 框架，包含相同的认证和验证逻辑
- AI 读取 Python 代码理解业务逻辑
- 生成符合 Go 惯用法的等效代码
- 自动处理类型转换、错误处理等细节
案例 3：紧急热修复
场景：凌晨 2 点，生产环境出现数据一致性问题，需要紧急修复。
使用 OpenCode：
opencode --no-plan # 直接进入构建模式🤖 @src/services/order.ts 中的 createOrder 函数没有事务包裹，
当库存扣减失败后，订单状态未回滚。请添加事务处理。
- AI 立即定位问题代码
- 生成带事务的修复版本
- 显示 diff 供你快速审查
安装决策树
适合谁用
| 人群 | 使用场景 | 推荐模式 |
|---|---|---|
| 编程小白 | 学习代码、理解项目、快速原型 | 计划模式，多问多确认 |
| 全栈开发者 | 日常开发、重构、跨语言项目 | 构建模式为主，复杂任务切计划 |
| 技术负责人 | 代码审查、架构设计、团队规范 | 计划模式，输出方案 |
| 开源贡献者 | 快速理解陌生代码库、提交 PR | 混合使用，代码解释 + 修改 |
| DevOps 工程师 | 配置管理、脚本编写、故障排查 | 构建模式，配合 bash 工具 |
FAQ
Q: OpenCode 和 GitHub Copilot 有什么区别？ A: Copilot 是实时代码补全工具，在你打字时给出建议；OpenCode 是 AI Agent，能自主阅读、分析、修改整个代码库，两者可以互补使用。
Q: 我的代码会被上传到云端吗？ A: 只有发送给 LLM 的部分代码片段会传输，OpenCode 本身是本地运行的。企业用户可以选择本地部署模型（如 Ollama）实现完全离线。
Q: OpenCode 免费吗？ A: OpenCode 本身开源免费，但你需要自行准备 LLM API 密钥（各提供商计费不同）。OpenCode Zen 提供入门套餐。
Q: 支持哪些编程语言？ A: 所有语言！因为 AI 模型（如 Claude、GPT-4）具备多语言能力。但编辑工具对某些语言（TypeScript、Python、Go、Rust）的体验更优。
Q: 可以离线使用吗？
A: 可以，通过 Ollama 或 LM Studio 运行本地模型，配合 --local 参数即可。
避坑清单
| ⚠️ 坑点 | 说明 | 解决方案 |
|---|---|---|
| 用 Windows 原生终端 | 功能受限、显示异常 | 使用 WSL2 + WezTerm |
| 忽视 AGENTS.md | AI 不了解项目规范 | 项目根目录务必创建并维护 |
| 生产环境直接运行 | AI 可能引入破坏性变更 | 始终在开发/测试环境验证 |
| API 密钥泄露 | 误提交到 Git | 已自动加入 .gitignore，勿手动移除 |
| 期望一次完美 | AI 需要迭代 | 小步快跑，多用 /undo |
| 不检查 diff | 未审查就接受修改 | 养成查看 diff 的习惯 |
你需要准备什么
- 现代终端 — WezTerm、Alacritty、Ghostty、Kitty 等
- API 密钥 — 任意 LLM 提供商（推荐 OpenCode Zen 入门）
- 一颗好奇的心 💡
下一篇：02. 安装与环境准备