返回
Opencode-Tutorials

[系列第1篇] OpenCode 快速入门指南：5分钟上手开源AI编程助手

本文提供OpenCode的快速入门指南，通过简单步骤帮助开发者在5分钟内完成安装配置，体验AI编程助手的基础功能。涵盖安装、代理系统、基础命令和首个AI编程任务。

系列前言

本文是 OpenCode 从入门到精通 系列的第一篇，专注于快速上手。如果您是第一次接触OpenCode，建议从这里开始。本系列将逐步深入OpenCode的各个功能模块，帮助您全面掌握这一强大的开源AI编程助手。

系列导航：

什么是OpenCode？

OpenCode是一个开源AI编程助手，支持在终端、IDE和桌面应用中智能生成和分析代码。与商业AI工具不同，OpenCode：

  • ✅ 完全开源：MIT许可证，社区驱动
  • ✅ 多模型支持：Claude、GPT、Gemini等75+提供商
  • ✅ 终端优先：为命令行开发者优化体验
  • ✅ 隐私保护：默认不存储您的代码数据

5分钟快速安装

方法一：一键安装脚本（推荐）

# 直接运行安装脚本
curl -fsSL https://opencode.ai/install | bash

安装脚本会自动检测系统并安装OpenCode到合适的目录。

方法二：包管理器安装

根据您的系统选择：

# npm/yarn/bun/pnpm
npm i -g opencode-ai@latest

# macOS/Linux (Homebrew)
brew install anomalyco/tap/opencode

# Arch Linux
sudo pacman -S opencode        # 稳定版
paru -S opencode-bin           # AUR最新版

# Windows (Scoop)
scoop install opencode

# Windows (Chocolatey)
choco install opencode

方法三：桌面应用（Beta）

从 OpenCode下载页面 下载适合您系统的桌面应用：

  • macOS：Apple Silicon 或 Intel版本
  • Windows：64位安装程序
  • Linux：.deb、.rpm或AppImage

验证安装

安装完成后，运行以下命令验证：

# 检查版本
opencode --version

# 查看帮助信息
opencode --help

如果看到版本信息和命令列表，说明安装成功。

第一次使用OpenCode

启动OpenCode

# 直接启动（使用默认配置）
opencode

# 指定工作目录
opencode /path/to/your/project

启动后，您会看到类似以下的终端界面：

🦀 OpenCode v1.2.14
📁 Working directory: /home/user/project
🤖 Agent: build (full access)
💬 Type your request or command...

了解代理系统

OpenCode内置两种代理模式，按 Tab 键切换：

  1. build代理（默认）：全功能开发代理，支持文件编辑和命令执行
  2. plan代理：只读分析代理，专注于代码探索和规划

使用场景：

  • 写代码、修改文件 → 使用 build 代理
  • 阅读代码、分析架构 → 使用 plan 代理

执行第一个AI编程任务

让我们从简单的任务开始：

# 1. 首先确保在项目目录中
cd ~/your-project

# 2. 启动OpenCode
opencode

# 3. 输入您的第一个请求
# 例如："创建一个简单的Express服务器"

OpenCode会开始分析您的代码库上下文，然后生成相应的代码。

基础命令速查

常用快捷键

快捷键 功能
Tab 切换 build/plan 代理
Ctrl+C 中断当前任务
Ctrl+D 退出OpenCode
/ 输入命令模式
↑/↓ 浏览历史命令

基本工作流

  1. 描述需求：用自然语言描述您想要的功能
  2. 审查代码：OpenCode会生成代码并询问您的意见
  3. 测试运行：让OpenCode运行测试或执行命令
  4. 迭代改进：根据结果进一步优化

示例：创建React组件

# 启动OpenCode
opencode

# 输入请求：
"在src/components目录下创建一个UserProfile组件，包含头像、姓名和个人简介"

OpenCode会：

  1. 分析现有项目结构
  2. 生成相应的React组件代码
  3. 询问是否要创建文件
  4. 提供后续优化建议

配置您的API密钥

要使用OpenCode的全部功能，您需要配置AI模型提供商：

1. 获取API密钥

2. 配置OpenCode

# 交互式配置向导
opencode config setup

# 或手动设置环境变量
export ANTHROPIC_API_KEY="sk-..."
export OPENAI_API_KEY="sk-..."

# 保存到配置文件
opencode config set providers.anthropic.apiKey "$ANTHROPIC_API_KEY"
opencode config set providers.openai.apiKey "$OPENAI_API_KEY"

3. 测试配置

# 检查可用模型
opencode models list

# 测试连接
opencode test --provider anthropic

常见问题解答

Q: 安装后找不到opencode命令？

A: 尝试重新打开终端，或手动添加安装目录到PATH：

# 查看安装位置
which opencode

# 如果未找到，手动添加到PATH
export PATH="$HOME/.opencode/bin:$PATH"

Q: 运行速度很慢？

A:

  • 确保网络连接正常（使用云模型时）
  • 尝试切换到更快的模型（如Claude 3.5 Haiku）
  • 使用 opencode config set context.window 8000 减少上下文窗口

Q: 如何查看使用情况？

A:

# 查看会话历史
opencode sessions list

# 查看API使用统计
opencode usage stats

下一步行动

完成快速入门后，您可以：

  1. 探索实际项目：在现有代码库中尝试OpenCode
  2. 了解核心概念：学习代理系统、会话管理等
  3. 配置多模型：设置多个AI提供商进行成本优化
  4. 集成到工作流：将OpenCode融入您的日常开发流程

资源与支持

系列预告

在下一篇 《OpenCode 核心概念解析》 中，我们将深入探讨：

  • 代理系统的工作原理
  • 会话管理与上下文保持
  • LSP集成与代码理解
  • 多模型路由策略

📚 完整系列导航

你正在阅读本系列的 第 1 篇，以下是完整目录：

  1. 系列概述：开源 AI 编程助手全景解析
  2. 快速入门指南：5 分钟上手（当前）
  3. 核心概念解析：深入理解代理系统与架构设计
  4. 模型配置实战：多提供商集成与成本优化策略
  5. 从入门到精通：完整指南
  6. 系列索引：完整系列教程目录

更新时间：2026-02-26
OpenCode版本：v1.2.14+
反馈建议：如果您发现本文有任何问题或改进建议，欢迎通过GitHub Issues反馈。