OpenCode 完全学习指南

OpenCode 学习指南

一、概述

1.1 什么是 OpenCode？

OpenCode 是一个开源的 AI 编程代理（AI coding agent），帮助开发者完成代码编写、调试、重构等软件工程任务。与 IDE 内置的 AI 辅助工具不同，OpenCode 是一款命令行优先（CLI-first） 的工具，提供原生的终端用户界面（TUI），让你可以在熟悉的命令行环境中直接与 AI 对话，无需频繁切换窗口。

OpenCode 可以帮助你完成以下任务：

编写和编辑代码：跨多个文件进行代码编写和修改
调试和修复问题：智能定位并修复代码缺陷
重构和优化代码：优化现有代码结构和性能
生成文档：自动创建代码注释和项目文档
理解代码库：快速分析项目结构和代码逻辑

1.2 核心特色

OpenCode 能够在众多 AI 编程工具中脱颖而出，主要得益于以下独特之处：

特性	说明
完全开源	MIT 开源协议，代码透明可审计，GitHub 上已有超过 70,000 颗星标，社区驱动开发，每月有超过 650,000 名开发者使用
模型无关	支持 75+ 模型提供商，包括 OpenAI、Anthropic、Google 等，可自由切换
隐私优先	不存储任何代码或上下文数据，可完全自托管
零成本起步	OpenCode 本身完全免费，只需按需支付 API 费用
TUI 原生体验	提供功能完整的终端用户界面，响应快，支持自定义主题

1.3 与同类工具的对比

特性	OpenCode	Claude Code	Cursor
类型	终端 CLI + 桌面应用	终端 CLI	完整 IDE
价格	完全免费（按 API 用量付费）	$17-200/月	$20/月
模型灵活性	75+ 模型提供商	仅支持 Claude	多模型支持
开源	✅ 完全开源	❌ 闭源	❌ 闭源
隐私保护	✅ 不存储任何代码	⚠️ 部分存储	⚠️ 部分存储
学习成本	中	中	低
自动化能力	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐
实时编辑体验	⭐⭐⭐	⭐⭐	⭐⭐⭐⭐⭐
可扩展性	⭐⭐⭐⭐⭐（Skills + MCP）	⭐⭐	⭐⭐⭐
最佳场景	预算敏感、隐私优先、终端用户	复杂自主任务	实时编辑

二、安装配置

2.1 系统要求

安装 OpenCode 需要满足以下条件：

Node.js 18 或更高版本（用于 npm 安装）
建议安装 git 用于版本管理
支持现代特性的终端模拟器
至少一个受支持的 AI 提供商的 API 访问权限

2.2 安装方式

下载地址：https://opencode.ai/download

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

这是最简单快捷的安装方法，脚本会自动检测系统架构、下载对应版本并自动配置环境变量：

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

脚本特性：

自动支持 Windows x64、Linux x64/arm64、macOS x64/arm64 全平台
自动识别当前 shell（fish/zsh/bash/ash/sh）并将安装路径 $HOME/.opencode/bin 写入对应配置文件
检测 GitHub Actions 环境自动添加到 GITHUB_PATH
支持指定版本安装：VERSION=1.2.3 curl -fsSL https://opencode.ai/install | bash

等待安装完成后，执行以下命令验证安装：

opencode --version

注意事项：

无需使用 sudo 运行安装脚本，否则可能导致权限问题
安装后若提示“command not found”，请关闭终端重新打开
网络不稳定时可添加 --verbose 参数查看详细安装过程

方式二：npm 包管理器

npm install -g opencode-ai

2.3 配置 AI 模型

方法一：使用 auth 命令（推荐）

OpenCode 提供了专门的认证命令来管理 API 密钥：

opencode auth login

按提示选择 AI 提供商（Anthropic、OpenAI、Google 等），输入对应的 API Key。配置信息存储在 ~/.local/share/opencode/auth.json 中。

方法二：环境变量配置

# Anthropic Claude
export ANTHROPIC_API_KEY=your_api_key_here

# OpenAI
export OPENAI_API_KEY=your_api_key_here

# Google Gemini
export GOOGLE_API_KEY=your_api_key_here

如需永久保存，可将上述命令添加到 ~/.bashrc 或 ~/.zshrc 文件中。

方法三：配置文件

创建并编辑配置文件 ~/.config/opencode/opencode.json：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "coreshub": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "CoresHub",
      "options": {
        "baseURL": "https://openapi.coreshub.cn/v1",
        "apiKey": "your-api-key"
      },
      "models": {
        "MiniMax-M2.1": { "name": "MiniMax-M2.1" },
        "GLM-4.7": { "name": "GLM-4.7" }
      }
    }
  }
}

2.4 模型选择策略

不同模型各有优势，可根据任务类型灵活选择：

模型类型	响应速度	代码质量	适用场景
Claude 3.5 Sonnet	中等	优秀	复杂代码生成、架构设计
GPT-4	中等	优秀	通用编程任务
Gemini	快速	良好	快速查询、简单任务
Grok Code	快速	良好	免费试用（限时）

三、核心功能

3.1 启动与基本使用

进入项目目录并启动 OpenCode：

cd your-project
opencode

标准启动流程：

1. 进入目标项目目录
2. 启动 opencode
3. /init 初始化项目上下文
4. 进入 Plan 模式设计方案
5. 切换到 Build 模式执行开发
6. /undo 回滚错误修改

这将启动 TUI（终端用户界面），你可以在此与 AI 代理进行交互。启动后的 TUI 界面包含以下功能：

实时聊天：与 AI 模型实时对话
会话管理：创建、切换和管理多个对话会话
工具集成：AI 可以执行命令、搜索文件、修改代码
文件追踪：可视化会话期间的文件变更
外部编辑器：打开首选编辑器撰写消息
LSP 集成：语言服务器协议支持，提供代码智能提示

3.2 两种工作模式

OpenCode 提供了两种内置的 Agent 模式，可通过 Tab 键快速切换：

模式	权限	适用场景	本质
Build 模式	全权限，可直接编辑文件、执行命令	实际开发、代码编写	自动执行工程师
Plan 模式	只读规划，默认拒绝编辑，需要确认	代码分析、方案设计	架构设计师

核心最佳实践：永远先 Plan 确认方案，再进入 Build 模式执行，避免 AI 无预期乱改代码。

Plan 模式右下角会显示模式指示器，确保你在使用前知道当前所处的模式。

3.3 内置命令

在交互模式中，可以通过 Ctrl+K 访问内置命令：

命令	功能
`/init`	创建或更新 `AGENTS.md` 记忆文件，帮助 AI 理解项目结构和上下文
`/compact`	手动触发会话摘要，减少上下文大小同时保留重要信息
`/models`	切换不同的 AI 模型
`/undo`	回滚 AI 的错误修改，支持多次撤销多步操作
`/redo`	重做之前撤销的操作
`/share`	生成公开链接，分享对话记录给同事，自动复制到剪贴板
`/themes`	切换终端主题（或按 Ctrl+X 再按 T）
`/connect`	可视化向导配置模型 API 密钥
`/clear`	清空当前会话所有上下文记录
`/help`	查看所有可用命令说明

3.4 非交互模式

当你使用 -p 标志提供提示时，OpenCode 以非交互模式运行：

立即处理提示
将 AI 响应打印到标准输出
完成后退出
自动批准会话的所有权限

opencode -p "解释这个项目的认证流程"

支持多种输出格式，可通过 -f 或 --output-format 指定：

opencode -p "列出所有函数" -f json

四、使用场景

4.1 理解代码库

示例一：理解项目整体逻辑

opencode
> 这个项目的认证流程是如何工作的？

OpenCode 会分析你的文件，提供详细的认证流程说明，包括关键文件、函数调用和数据流向。

示例二：精准定位特定文件
使用 @ 键可以模糊搜索项目中的文件：

> @packages/functions/src/api/index.ts 中的身份验证是如何处理的？

4.2 添加新功能

建议遵循标准三步骤流程实现新功能：

创建计划：按 Tab 切换到 Plan 模式，描述功能需求，让 OpenCode 生成完整的实现方案，禁用所有修改操作仅输出设计
迭代计划：补充细节需求、上传设计图/参考案例，不断调整方案直到完全符合预期
构建功能：确认方案后再次按 Tab 切换回 Build 模式，让 OpenCode 自动执行所有代码修改

示例完整流程：

> 当用户删除一个笔记时，我们希望在数据库中将其标记为已删除。然后创建一个屏幕，显示所有最近删除的笔记。在这个屏幕上，用户可以恢复笔记或永久删除它。

> 我们希望使用我之前用过的设计来设计这个新屏幕。
> [直接拖拽截图/设计稿到终端] 看看这张图片并以此作为参考。

[Tab 切换到 Build 模式]
> 按照刚才确认的方案开始实现完整功能

4.3 调试问题

> 登录表单无法提交。错误信息：[粘贴错误信息]，错误位置在 auth.ts 第 45 行

OpenCode 会追踪问题并建议修复方案。

4.4 重构代码

> 将 UserService 类重构为使用依赖注入，遵循 SOLID 设计原则

OpenCode 会在保持功能的同时现代化你的代码。

4.5 生成文档

> 为 api/users.ts 生成符合项目规范的 TypeScript 文档注释

OpenCode 会自动分析函数签名和参数，生成符合规范的文档。

完整开发案例

# 1. 初始化项目上下文
/init
# 2. 切换 Plan 模式设计架构
> 我想实现一个用户登录系统，使用 JWT + Redis + Next.js + Prisma + PostgreSQL
# 3. 补充细节调整方案
> 补充要求：支持邮箱验证码登录，密码使用 bcrypt 加密，token 有效期 7 天
# 4. 切换 Build 模式执行
Tab → Build
> 按照确认的架构开始完整实现

五、高级特性

5.1 配置文件完全指南

OpenCode 配置支持 JSON 和 JSONC（带注释的 JSON）两种格式，优先级遵循 项目配置 > 自定义路径 > 全局配置，所有配置会自动合并而非覆盖，冲突项高优先级配置会覆盖低优先级项。

配置文件位置

你可以将配置放在多个不同的位置，OpenCode 启动时会自动合并加载：

配置类型	路径	适用场景
全局配置	`~/.config/opencode/opencode.json`	设置全局通用的主题、模型、权限默认值
项目配置	项目根目录下的 `opencode.json`	单独配置当前项目专属规则，可提交到 Git 共享给团队
自定义路径	通过 `OPENCODE_CONFIG` 环境变量指定任意路径	多配置快速切换场景
自定义目录	通过 `OPENCODE_CONFIG_DIR` 环境变量指定自定义配置目录	批量管理多套配置集合

完整配置项说明

OpenCode 提供全维度自定义能力，所有配置均符合官方 Schema 规范：

TUI 配置：自定义滚动速度、滚动加速开关、差异展示样式
Server 配置：开启 HTTP 服务、自定义端口、配置 mDNS 局域网发现、设置 CORS 跨域规则
Models 配置：灵活设置主模型、轻量小模型，自定义提供商超时时间、缓存策略
Permissions 配置：细粒度控制所有工具的权限，支持 allow/ask/deny 三级权限，避免 AI 随意修改生产代码
Agents 配置：自定义专属子代理（如代码审查员、测试工程师），为不同任务绑定独立模型和权限
Commands 配置：将高频重复指令保存为自定义快捷命令，搭配参数占位符大幅提升效率
Themes 配置：切换内置主题或自定义终端界面配色
Autoupdate 配置：控制自动更新行为，支持完全禁用或仅通知不更新
Formatter 配置：配置自定义代码格式化工具，自动调用 prettier 等工具格式化新生成的代码
MCP 配置：接入各类第三方 MCP 服务，扩展 AI 的外部数据访问能力
网络与代理配置：完全遵循标准代理环境变量，支持 HTTP/HTTPS 代理、带认证的代理，企业内网环境友好

# HTTPS 代理（推荐）
export HTTPS_PROXY=https://proxy.example.com:8080
# HTTP 代理（如果 HTTPS 不可用）
export HTTP_PROXY=http://proxy.example.com:8080
# 为本地服务绕过代理（必需，避免路由循环）
export NO_PROXY=localhost,127.0.0.1

配置高级技巧

支持环境变量引用：使用 {env:VARIABLE_NAME} 直接读取系统环境变量作为配置值，避免硬编码密钥
支持文件内容引用：使用 {file:path/to/file} 读取外部文件内容作为配置值，将敏感密钥单独存储在安全路径

5.2 Agent Skills（技能系统）

Skills（技能） 是 Agent 的能力扩展模块，就像给 AI 装上专业技能包（本质是 AI 插件系统）。通过安装不同的 Skills，OpenCode 可以掌握特定领域的最佳实践、获得专业工具的操作能力、执行标准化的工作流程。

推荐组合

npx skills add obra/superpowers -y
npx skills add OthmanAdi/planning-with-files -y

obra/superpowers：为 AI 引入 14 个结构化工作流（如需求澄清、TDD、代码审查等），强制遵循专业工程流程，避免跳过设计、测试等关键步骤，提升代码质量。
OthmanAdi/planning-with-files：通过创建 task_plan.md、findings.md、progress.md 三个持久化文件，帮助 AI 在长周期任务中记录规划、发现与进度，防止上下文丢失和目标漂移。

Skill 的存放位置
OpenCode 会自动在当前工作目录下创建 .agents/skills 文件夹作为 Skills 的默认安装目录，你可以手动创建该目录，也可以直接执行 skill 添加命令让系统自动生成路径。安装后的每个 skill 都是一个独立的子文件夹，包含该技能对应的提示词、工具定义、工作流规则，完全以开源文件形式托管在项目中。

六、最佳实践与效率技巧

6.1 提示词编写原则

为了获得高质量的 AI 输出，遵循以下提示词原则：

明确说明项目类型："这是一个使用 React + TypeScript 的 Next.js 电商项目"
指定具体文件位置："修改 src/components/Navbar.tsx 中的登录按钮样式"
提供上下文约束："遵循项目现有的 ESLint 配置和代码风格"
分步骤迭代：先设计整体架构，再逐步细化实现细节，避免一次性抛出过于复杂的需求

6.2 上下文管理

大型项目中 AI 很容易丢失关键上下文信息，可通过这些方法优化：

使用 /init 命令自动生成 AGENTS.md 记忆文件，记录项目核心结构和规则
定期使用 /compact 命令整理会话摘要，压缩冗余上下文不丢失核心信息
开启自动压缩配置，当对话上下文长度超过 90% 模型窗口大小时，自动执行摘要清理
重要的历史信息及时导出到项目文档中，不要完全依赖 AI 会话记忆
开启 file-allow 配置，将高频使用的源码目录设置为默认允许访问，减少每次确认的操作成本

6.3 团队协作配置

当多人共同使用 OpenCode 开发同一个项目时：

将项目级的 opencode.json 配置文件提交到 Git 仓库，统一团队默认模型、权限和规范
把自定义的 Agent Skills 文件夹一同提交，保证所有开发者使用相同的 AI 工作流
生成的会话分享链接可直接同步给队友，快速定位问题复现场景，不需要重复描述上下文
配置团队专用的自定义命令集，将项目常用的 lint、启动、测试命令封装为快捷指令，减少重复输入

七、常见问题排查

问题现象	解决方案
安装后提示 command not found	关闭终端重新打开，手动执行 `source ~/.zshrc` 或对应 shell 配置文件
API 连接超时 / 网络错误	检查代理配置是否正确，添加 `OPENCODE_AGENT_TIMEOUT=600` 延长超时时间
AI 生成代码不符合项目风格	在配置中添加 formatter 规则，指定项目的 prettier/eslint 路径，AI 修改完文件会自动格式化
会话上下文太大响应变慢	使用 `/compact` 手动压缩会话，或者开启自动压缩功能
撤销操作无效	确保你开启了 Git 集成，OpenCode 的撤销功能依赖项目的版本管理记录
终端主题显示异常	通过 `/themes` 切换适配当前终端模拟器的内置主题，避免自定义配色和终端底色冲突

八、进阶学习资源

官方文档：https://docs.opencode.ai （覆盖所有配置项、命令、API 的完整说明）
GitHub 开源仓库：https://github.com/opencode-ai/opencode （提交 Issue 反馈问题、查看最新功能迭代）
Skills 市场：https://skills.sh （社区贡献的大量专业技能包，可直接安装使用）
社区 Discord：OpenCode 官方 Discord 频道，数千开发者实时交流使用经验，获取最新功能内测资格

posted @ 2026-05-03 18:27 小郑[努力版] 阅读(904) 评论(0) 收藏举报

刷新页面返回顶部

小郑在努力

记录学习笔记