Opencode Everything You Need To Know

OpenCode：终极AI编码助手

开源、多提供商的人工智能编码工具，让您摆脱供应商锁定

🎯 为什么选择OpenCode？

如果你来自 克劳德代码, 光标，或 GitHub Copilot，OpenCode提供了一些根本不同的东西：

OpenCode的优势：

• 无供应商锁定：使用OpenAI、Anthropic、谷歌、本地模型或所有这些模型
• 只为你使用的东西付费：无需每月订阅，每个代币定价透明
• 终端优先工作流程：留在您的开发环境中
• 可扩展架构：创建自定义技能、代理和工作流
• 企业就绪：SSO、团队工作区、集中配置

______________________________________________________________________

🚀 快速入门（5分钟）

1.安装OpenCode

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

# Alternative: Homebrew
brew install anomalyco/tap/opencode

# Verify installation
opencode --version

2.设置禅（建议初学者）

# Start OpenCode
opencode

# In the TUI, run:
/connect

# Select "opencode" and follow the link to get your API key
# Zen provides curated models with pay-as-you-go pricing

3.尝试你的第一个命令

# Start in your project directory
cd /path/to/your/project
opencode .

# Ask OpenCode to analyze your code
What does this project do? @README.md

# Get help with a specific file
Help me understand the authentication in @src/auth/

# Switch between Plan and Build modes (Tab key)
[Plan] How would you implement this feature?
[Build] Go ahead and implement it

4.基本键盘快捷键

• 选项卡：在计划（只读）和构建（读写）模式之间切换
• @：项目中的参考文件
• !：执行shell命令
• /：访问斜线命令
• Ctrl+C：退出OpenCode

______________________________________________________________________

📚 核心概念

OpenCode围绕四个协同工作的关键支柱构建：

1. Zen模型路由器 -您的AI模型网关

Zen提供精心策划、优化的模型，专门用于按需付费的编码定价。

主要优势：

• 使用一个API密钥访问75+AI模型
• 按代币付费（无月度订阅）
• 免费模型可供学习
• 具有集中计费功能的团队工作区

快速设置：

# Get your Zen API key
1. Visit: https://opencode.ai/auth
2. Sign up and add billing
3. Copy your API key
4. In OpenCode: /connect → select "opencode"

# See available models
/models

热门型号和价格：

💡 专业建议：从免费模型开始学习，然后根据需要进行升级。大多数开发人员每月花费5-20美元。

📖 完整禅宗指南 | 💰 成本计算器

2. TUI精通 -终端优先工作流

OpenCode的终端用户界面是魔法发生的地方。它是为居住在终端中的开发人员设计的。

基本特征：

• 文件引用：使用 @ 引用项目中的任何文件
• Shell 集成：使用执行命令 ! 前缀
• 图像分析：拖放图像以供UI/设计参考
• 实时成本显示：工作时查看令牌使用情况

工作流示例：

# Reference files naturally
Can you fix the bug in @src/utils/validation.ts?

# Use shell commands in context
!git status
Based on the changes, write commit messages

# Analyze images
[Drag dashboard-mockup.png into terminal]
Create React components matching this design

生产力提示：

• 使用 Tab 在计划（分析）和构建（实施）之间切换
• 链命令： !git diff | /analyze-changes
• 搜索文件： @utils 查找utils目录或utils.ts文件
• 多线输入： Shift+Enter 用于复杂查询

🎮 完整的TUI指南 | ⌨️ 键盘快捷键

3. AI代理 -专门的人工智能个性

代理是具有特定工具、权限和行为的专门AI角色。

内置代理：

• 计划代理 （选项卡）：只读分析和规划
• 生成代理 （选项卡）：读写实现
• 探索子代理：代码库探索
• 总代理：复杂的任务执行

创建自定义代理：

# ~/.config/opencode/agents/code-reviewer.md
name: Code Reviewer
model: claude-sonnet-4.6
temperature: 0.2

## Instructions
You are a senior code reviewer. Focus on:
1. Security vulnerabilities
2. Performance bottlenecks
3. Code style consistency
4. Maintainability issues

## Tools
- read: true
- ask: true
- write: false  # Reviewer doesn't make changes

代理工作流模式：

# Plan → Build cycle
[Plan] How would you implement user authentication?
[Build] Implement the authentication system

# Multi-agent collaboration
@explore Analyze security in @src/auth/
@code-reviewer Review the proposed implementation
[Build] Implement with the suggested improvements

🤖 完整代理指南 | 🎭 代理模板

4. OpenCode技能 -工作流自动化

技能是可重用的行为定义，可以将复杂的工作流转换为简单的命令。

示例技能：

# Code review skill
/review @src/auth/ --focus security

# Pull request creation
/pr "Add user authentication"

# Test-driven development
/tdd "User registration with email validation"

# Documentation generation
/docs api --output markdown

创造自己的技能：

# .opencode/skills/deploy.md
---
name: "Deploy"
description: "Automated deployment workflow"
tools: ["read", "write", "bash"]
---

# Deploy
1. Run tests: !npm test
2. Build project: !npm run build
3. Deploy to production: !deploy.sh

🔧 完整技能指南 | 💼 技能示例

______________________________________________________________________

🔄 经验丰富的开发人员迁移指南

来自克劳德代码

相似之处：

• 编辑器中的AI辅助编码
• 文件上下文感知
• 对话历史

有什么不同：

• 模型灵活性：多供应商vs仅克劳德
• 定价模式：按需付费与订阅
• 主接口：终端原生与桌面应用
• 定制深度：高功能与有限功能

迁移步骤：

1. 安装OpenCode并设置Zen
2. 通过Zen尝试克劳德模型（通常更便宜）
3. 学习TUI键盘快捷键（Tab是你的朋友）
4. 为您的工作流程创建自定义代理

来自Cursor

相似之处：

• AI驱动的代码生成
• 项目背景理解
• 编辑命令

有什么不同：

• 哲学：开源vs专有
• 整合：终端vs IDE
• 可扩展性：技能系统与有限插件
• 定价：透明vs订阅

迁移步骤：

1. 安装OpenCode并连接提供者
2. 实践文件参考 @ 语法
3. 设置项目特定技能
4. 探索复杂任务的代理系统

来自GitHub Copilot

相似之处：

• AI代码完成
• 多语言支持
• IDE集成

有什么不同：

• 范围：全AI助手vs自动补全
• 上下文：整个项目与当前文件
• 交互：会话型vs预测型
• 定价：基于使用与订阅

迁移步骤：

1. 将OpenCode视为Copilot++（完整对话）
2. 用于自动完成之外的复杂任务
3. 利用项目范围内的背景
4. 培养重复性任务的技能

📋 完整迁移指南

______________________________________________________________________

🗺️ 学习路径

第1周：基础

• \[x\] 安装OpenCode并设置Zen
• \[x\] 学习基本的TUI导航（Tab、@、！、/）
• \[x\] 尝试免费模型进行实验
• \[\]完成 快速入门指南

第2周：核心工作流程

• \[\]主文件引用和shell集成
• \[\]实践计划→ 建造周期
• \[\]设置您的第一个定制代理
• \[\]探索 TUI精通指南

第3周：高级功能

• \[\]创建特定于项目的技能
• \[\]设置团队工作区（如适用）
• \[\]实施CI/CD集成
• \[\]研究 代理商指南

第4周：精通

• \[\]构建自定义MCP服务器
• \[\]为您的团队创建技能模板
• \[\]优化模型使用和成本
• \[\]探索 工作流示例

______________________________________________________________________

📖 详细文件

______________________________________________________________________

🛠️ 命令参考

基本击杀命令

/help                    # Show all commands
/connect                 # Add/configure providers
/models                  # List available models
/agents                  # Manage AI agents
/skills                  # List available skills
/init                    # Initialize project analysis
/undo, /redo             # Git-based undo/redo
/share                   # Create shareable conversation link
/export                  # Export to markdown

命令行命令

# Start interactive TUI
opencode

# Run single command
opencode run "Fix bug in @src/utils/validation.ts"

# Start HTTP server
opencode serve --port 3000

# Check usage stats
opencode stats

📜 完整命令参考

______________________________________________________________________

🔧 项目配置

AGENTS.md模板

每个项目都可以有一个 AGENTS.md 引导OpenCode的文件：

# Project Guidelines
**Project Type**: React/TypeScript web app
**Purpose**: E-commerce platform
**Key Technologies**: React, TypeScript, Node.js, PostgreSQL

## Code Conventions
- Files: kebab-case
- Components: PascalCase
- Functions: camelCase
- 2-space indentation
- Single quotes

## Development Guidelines
- Write tests for all utilities
- Validate all external inputs
- Never commit secrets
- Use environment variables

📋 样品试剂.md

.opencode/目录结构

.opencode/
├── agents/
│   ├── code-reviewer.md
│   └── test-writer.md
├── skills/
│   ├── review.md
│   └── pr.md
└── config.json

______________________________________________________________________

❓ 常见问题解答和故障排除

常见问题

Q： 未找到OpenCode命令

# Check installation
which opencode

# Add to PATH
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Q： Zen API密钥不工作

# Regenerate key at: https://opencode.ai/auth
# Then reconnect:
/connect
# Select "opencode" and paste new key

Q： 文件引用不起作用

# Check current directory
!pwd

# Use absolute path if needed
@/full/path/to/file.ts

Q： 代币使用率高

# Switch to lighter model
/models
# Select Qwen 2.5 Coder or MiniMax Free

# Use /compact to summarize long conversations
/compact

Q： 图像未显示在OpenCode的TUI中 OpenCode的TUI是基于文本的，不内联显示图像。图像链接显示为标记文本。

• 对于本地markdown预览工具（VS Code、Obsidian等），请使用相对路径： ``
• 如果这不起作用，请尝试从repo根目录开始的绝对路径： ``
• 对于公共存储库，请使用完整的GitHub URL： ``

❓ 完整常见问题解答和故障排除

______________________________________________________________________

🌐 社区与资源

官方资源

• 网站: opencode.ai
• 文档: docs.opencode.ai
• GitHub:
• Discord 的中文翻译是“不和谐”或“纷争”。: 加入社区

______________________________________________________________________

📈 接下来是什么？

立即行动

1. 安装OpenCode 并尝试免费模型
2. 练习 计划→ 构建周期（Tab键）
3. 创建 你的第一个定制代理或技能
4. 加入 社区的支持和灵感

长期目标

• 大师 所有四个支柱（禅、途、代理、技能）
• 构建 为您的工作流程提供可重用技能库
• 贡献 到OpenCode生态系统
• 优化 您的AI辅助开发工作流程

______________________________________________________________________

📄 许可证

OpenCode是根据 MIT许可证.

*最后更新日期：2026年2月*\ *为了获得最佳的阅读体验，请安装 黑曜石 查看这些文档。*

💡 记住OpenCode是一个增强你的技能的工具，而不是取代它们。最好的开发人员将人工智能用作强大的助手，而不是拐杖。