OpenCode入门使用学习总结
执行摘要
OpenCode是一款开源的多提供商AI编程助手，为开发者提供了摆脱厂商锁定的自由，同时提供终端优先的工作流程。与Claude Code、Cursor或GitHub Copilot等专有替代品不同，OpenCode通过其独特的四大支柱架构强调模型灵活性、透明的按使用量付费定价和广泛的自定义能力。
核心差异化特性
| 特性 | OpenCode | 传统工具 |
|---|---|---|
| 模型灵活性 | 75+个提供商（OpenAI、Anthropic、Google等） | 单一提供商或有限选择 |
| 定价模式 | 按Token付费（无月度订阅） | 固定月度订阅 |
| 主要界面 | 终端原生（CLI优先） | IDE扩展或桌面应用 |
| 自定义能力 | 高（代理、技能、工作流） | 限于基本配置 |
| 开源 | ✅ 完全开源 | Claude Code 源码泄漏后开源，其他仍为专有 |
核心架构：四大支柱
1. Zen模型路由器 - AI模型网关
它是什么： 一个精选的模型网关，为编程任务提供经过验证和优化的AI模型，采用透明的按使用量付费定价。
工作原理： 为75+个AI提供商的统一API层
核心优势：
- 成本效益：大多数开发者每月花费5-20美元，而固定订阅为20-30美元
- 模型多样性：可访问GPT 5.2 Codex、Claude Sonnet 4.6、Gemini 2.5 Pro、Qwen 2.5 Coder和免费模型
- 无厂商锁定：可在提供商之间无缝切换
热门模型及定价：
| 模型 | 输入成本 | 输出成本 | 最佳用途 |
|---|---|---|---|
| GPT 5.2 Codex | 1.75美元/百万 | 14美元/百万 | 通用编程 |
| Claude Sonnet 4.6 | 3-6美元/百万 | 15-22.50美元/百万 | 复杂推理 |
| Qwen 2.5 Coder | 0.50美元/百万 | 2美元/百万 | 经济实惠的编程 |
| MiniMax M2.5 Free | 免费 | 免费 | 学习和实验 |
设置流程：
- 访问opencode.ai/auth创建账户
- 添加用于按使用量付费的账单信息
- 复制API密钥并通过
/connect命令在OpenCode中配置 - 使用
/models命令选择模型
2. TUI - 终端优先工作流程
它是什么： 为主要在终端环境中工作的开发者设计的复杂终端用户界面。
核心功能及工作原理：
-
文件引用系统（@语法）：使用
@文件名引用项目文件，支持模糊搜索功能- 示例：
修复@src/utils/validation.ts中的bug - 支持特定行引用：
检查@file.ts的第45-60行
- 示例：
-
Shell命令集成（!前缀）：直接在TUI中执行shell命令
- 示例：
!git status后跟基于变更，编写提交消息 - 命令在项目上下文中执行，输出可用于AI分析
- 示例：
-
图像分析：拖放图像以进行UI/设计参考
- 支持PNG、JPEG、GIF、WebP格式
- 适用于从模型图实现设计
-
实时成本显示：显示Token使用情况和成本
基本键盘快捷键：
| 快捷键 | 动作 | 用途 |
|---|---|---|
| Tab | 切换代理 | 在计划和构建模式之间切换 |
| @ | 文件搜索 | 引用项目文件 |
| ! | Shell前缀 | 执行shell命令 |
| / | 命令模式 | 访问斜杠命令 |
| Ctrl+C | 退出 | 退出OpenCode |
3. AI代理 - 专门的AI角色
它们是什么： 具有特定提示、工具权限和行为的专门AI角色，专为特定开发任务设计。
工作原理：
- 每个代理都有定义其角色和行为的自定义提示
- 配置有特定的工具权限（读取、写入、编辑、bash、询问）
- 可以使用不同的AI模型和温度设置
- 通过
@提及语法或Tab切换调用
内置代理：
-
构建代理（主要）：
- 目的：实现和代码变更
- 工具：完全访问（读取、写入、编辑、bash）
- 温度：0.1（代码生成的确定性）
- 激活：当显示
[构建]时按Tab
-
计划代理（主要）：
- 目的：分析、规划和头脑风暴
- 工具：有限（通常默认为只读）
- 温度：0.3（创意构思的轻微创造性）
- 激活：当显示
[计划]时按Tab
-
探索子代理：
- 目的：代码库探索和分析
- 工具：只读文件访问
- 调用：
@explore 分析@src/auth/
-
通用子代理：
- 目的：复杂多步骤任务执行
- 工具：完全访问（如构建代理）
- 调用：复杂任务时自动调用
创建自定义代理：
# ~/.config/opencode/agents/code-reviewer.md
name: 代码审查员
model: claude-sonnet-4.6
temperature: 0.2
## 指令
你是一名高级代码审查员。专注于：
1. 安全漏洞（OWASP十大风险）
2. 性能瓶颈
3. 代码风格一致性
4. 可维护性问题
## 工具
- read: true
- ask: true
- write: false # 审查员不进行更改
代理工作流程模式：
- 计划→构建循环：在计划模式分析，在构建模式实现
- 多代理协作：使用
@提及调用专门代理 - 专门任务委派：为不同任务创建领域特定代理
4. OpenCode技能 - 工作流程自动化
它们是什么： 可重用的行为定义，将复杂的工作流程转换为简单、可重复的命令。可以将它们视为"AI的宏"，将多步骤过程封装为单个调用。
工作原理：
- 定义为带有YAML前置元数据的markdown文件
- 指定所需工具、权限和行为指令
- 通过斜杠命令调用（例如
/review、/pr、/tdd） - 可以是项目特定或全局可用
关键特性：
- 可重用：定义一次，随处使用
- 可共享：提交到版本控制，与团队共享
- 可定制：针对特定项目或工作流程进行修改
- 安全：权限控制执行
- 可发现：在OpenCode界面中自动列出
示例技能：
-
代码审查技能（
/review）：/review @src/auth/ --focus security- 执行综合代码审查
- 专注于安全、性能和风格
- 提供带有代码示例的可操作建议
-
拉取请求创建（
/pr）：/pr "添加用户认证"- 从当前更改创建功能分支
- 使用项目格式化器格式化代码
- 将更改拆分为逻辑提交
- 生成描述性提交消息
- 创建带有摘要和测试计划的PR
-
测试驱动开发（
/tdd）：/tdd "带邮箱验证的用户注册"- 强制执行红-绿-重构循环
- 首先创建失败的测试
- 实现最小解决方案
- 为质量进行重构
技能文件结构：
---
name: "代码审查"
description: "具有安全、性能和风格检查的综合代码审查"
version: "1.0.0"
tools: ["read", "ask"]
permissions: ["project"]
---
# 代码审查
执行专注于安全、性能和可维护性的综合代码审查。
## 行为
1. 分析指定的文件或目录
2. 检查安全漏洞（OWASP十大风险）
3. 审查性能影响和瓶颈
4. 评估代码风格和一致性
5. 提出带有示例的具体改进建议
6. 提供可操作的建议
学习路径
第1周：基础
- ✅ 安装OpenCode并设置Zen
- ✅ 学习基本TUI导航（Tab、@、!、/）
- ✅ 试用免费模型进行实验
- ✅ 完成快速入门指南
第2周：核心工作流程
- ✅ 掌握文件引用和shell集成
- ✅ 练习计划→构建循环
- ✅ 设置您的第一个自定义代理
- ✅ 探索TUI精通指南
第3周：高级功能
- ✅ 创建项目特定技能
- ✅ 设置团队工作区（如果适用）
- ✅ 实现CI/CD集成
- ✅ 学习代理指南
第4周：精通
- ✅ 构建自定义MCP服务器
- ✅ 为团队创建技能模板
- ✅ 优化模型使用和成本
- ✅ 探索工作流程示例
基本命令参考
斜杠命令
/help # 显示所有命令
/connect # 添加/配置提供商
/models # 列出可用模型
/agents # 管理AI代理
/skills # 列出可用技能
/init # 初始化项目分析
/undo, /redo # 基于Git的撤销/重做
/share # 创建可共享的对话链接
/export # 导出为markdown
CLI命令
# 启动交互式TUI
opencode
# 运行单个命令
opencode run "修复@src/utils/validation.ts中的bug"
# 启动HTTP服务器
opencode serve --port 3000
# 检查使用统计
opencode stats
项目配置
AGENTS.md模板
每个项目都可以有一个AGENTS.md文件来指导OpenCode：
# 项目指南
**项目类型**：React/TypeScript Web应用
**目的**：电商平台
**关键技术**：React、TypeScript、Node.js、PostgreSQL
## 代码约定
- 文件：kebab-case
- 组件：PascalCase
- 函数：camelCase
- 2空格缩进
- 单引号
## 开发指南
- 为所有实用程序编写测试
- 验证所有外部输入
- 不要提交机密信息
- 使用环境变量
.opencode/目录结构
.opencode/
├── agents/
│ ├── code-reviewer.md
│ └── test-writer.md
├── skills/
│ ├── review.md
│ └── pr.md
└── config.json
技术术语解释
模型上下文协议（MCP）
一个开放协议，使AI助手能够连接外部工具和数据源。MCP服务器通过提供对数据库、API和其他系统的结构化访问来扩展OpenCode的功能。
温度（在AI模型中）
控制AI模型输出随机性的参数。较低的值（0.1-0.3）产生更确定、更专注的响应，适合编程。较高的值（0.4-0.7）产生更有创意、更多样化的响应，适合头脑风暴。
Token
AI模型处理的基本文本单位。在定价中，成本通常按每百万Token计算。一个Token可以是一个单词、单词的一部分或标点符号。
模糊搜索
一种即使在搜索查询包含错误或不完整时也能找到匹配项的搜索技术。OpenCode对文件引用使用模糊搜索，允许您使用部分名称查找文件。
计划vs构建模式
- 计划模式：只读分析和规划阶段，OpenCode在不进行更改的情况下建议方法
- 构建模式：读写实现阶段，OpenCode进行实际代码更改
子代理
可以调用以执行特定任务的专门AI代理，而主要对话继续进行。它们使用自己的配置运行，并将结果返回到主要对话。
最佳实践和专业提示
💡 成本优化
- 从免费模型开始（LongCat-Flash-Chat）进行学习
- 定期使用
!opencode stats监控使用情况 - 为任务选择合适的模型（轻量级模型用于简单任务）
- 使用
/compact总结长对话并减少Token使用
🚀 生产力提示
- 掌握Tab键在计划和构建模式之间切换
- 高效使用@语法进行文件引用
- 链式命令与shell集成：
!git diff | /analyze-changes - 为您的特定工作流程需求创建自定义代理
- 为重复性任务构建可重用技能
🔒 安全最佳实践
- 限制敏感代理的bash访问
- 为客户工作使用项目特定代理
- 不要将API密钥提交到版本控制
- 定期审查代理权限
- 验证技能参数并清理输入
社区和资源
官方资源
- 网站：opencode.ai
- 文档：docs.opencode.ai
- GitHub：github.com/anomalyco/opencode
- Discord：加入社区
学习资源
- 快速入门指南 - 5分钟
- Zen模型路由器指南 - 15分钟
- TUI精通指南 - 20分钟
- 代理指南 - 25分钟
- 技能指南 - 20分钟
结论
OpenCode代表了AI辅助开发的范式转变，优先考虑开发者自由、成本透明度和可扩展性。其四大支柱架构（Zen、TUI、代理、技能）为AI增强开发提供了一个全面的框架，该框架适应个人工作流程，而不是强迫开发者进入预定模式。
该工具的开源性质、多提供商支持和按使用量付费定价使其对寻求避免厂商锁定同时保持对AI辅助开发工作流程控制的开发者和组织特别有吸引力。
通过掌握OpenCode的核心概念并实施推荐的最佳实践，开发者可以显著提高生产力，同时保持将工具适应其特定需求和偏好的灵活性。
💡 记住：OpenCode是一个增强您技能的工具，而不是取代它们。最好的开发者将AI用作强大的助手，而不是拐杖。
报告根据OpenCode Everything You Need to Know文档生成
AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。
更多推荐
0
0- 0
已为社区贡献6条内容
所有评论(0)