主權個人必看的 OpenCode 教程之第一課（2026版）

人工智能研究

主權個人必看的 OpenCode 教程之第一課（2026版）

發布人 Brave 2026-01-24 04:50

🌟 什么是 OpenCode？
🆚 OpenCode 与 Claude Code、Cursor 的对比
🔑 关键特性
🤖 两种内置 Agent 模式
🛠️ 内置工具集
📁 上下文感知
🔗 分享与协作
📦 安装 OpenCode
🚀 通用一键安装脚本（推荐）
📥 包管理器安装
💻 终端模拟器推荐
🖥️ 桌面应用
🚀 启动与使用
启动 OpenCode
首次启动配置
查看可用模型
🔐 配置 API 密钥与模型
连接 AI 提供商
🌟 使用 OpenCode Zen（推荐新手）
退出 OpenCode
📖 基本使用
启动项目
项目初始化
📂 文件引用
🖥️ 执行 Shell 命令
🎯 日常交互指南
提问与解释代码
添加功能
使用 Plan 模式规划功能（推荐）
撤销与重做
分享会话
交互模式（脚本化/非交互式）
🔧 内置工具详解
🎨 高级用法
📝 自定义命令
🎨 主题与按键
📂 多会话管理
🔌 IDE 集成
🔒 权限控制
🛠️ 实战示例：创建一个简单的 Node.js API
🔌 oh-my-opencode 插件
核心特性
安装方法
基本使用
📋 OpenCode TUI 常用 Slash 命令速查表
核心配置与初始化
会话管理
编辑与撤销
视图与辅助
退出
💻 OpenCode CLI 常用参数速查表
全局参数
使用示例
⚙️ TUI 配置选项
🔗 参考资源

🌟 什么是 OpenCode？

OpenCode 是一个开源的 AI 编程代理（AI coding agent），支持在终端（Terminal）、桌面应用和主流 IDE（如 VS Code）中与 AI 交互完成代码相关任务。

OpenCode 可以帮助我们：

🔍 理解代码库 — 快速分析项目结构和代码逻辑
✨ 编写新功能 — 通过自然语言描述需求，自动生成代码
🔧 重构代码 — 优化现有代码结构和性能
🐛 修复 Bug — 智能定位和修复代码问题
📝 生成文档 — 自动创建代码注释和项目文档

OpenCode 类似于 Anthropic 的 Claude Code 或 Cursor 的 Agent 功能，但它完全开源、隐私优先，支持多种大语言模型（LLM），并强调终端体验。

根据 2026 年 1 月的最新数据，OpenCode 已在 GitHub 上获得超过 70,000 颗星标、500+ 贡献者、7,000+ 次代码提交，每月有超过 650,000 名开发者使用和信任。

🆚 OpenCode 与 Claude Code、Cursor 的对比

在 2026 年的 AI 编程工具市场中，OpenCode、Claude Code 和 Cursor 是三大主流选择。以下是它们的核心差异：

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

核心优势总结：

🆓 零成本起步：OpenCode 本身免费，只需按需支付 API 费用
🔓 开源透明：完全开源，社区驱动，可审计代码
🔐 隐私第一：不存储任何代码或上下文数据
🔄 模型无关：不绑定任何提供商，可随时切换模型

🔑 关键特性

🤖 两种内置 Agent 模式

模式	说明	使用场景
Build 模式	全权限，可直接编辑文件、执行命令	实际开发、代码编写
Plan 模式	只读规划，默认拒绝编辑，需要确认	代码分析、方案设计

💡 提示：使用 Tab 键 可以在两种模式之间快速切换。Plan 模式右下角会显示模式指示器。

🛠️ 内置工具集

OpenCode 的 AI Agent 通过以下工具操作代码库（可在 opencode.json 中控制权限：allow/deny/ask）：

工具	功能描述
`bash`	执行 shell 命令（如 `git status`、`npm test`）
`write/edit/patch`	创建/修改/打补丁文件
`read`	读取文件内容（支持行范围）
`grep/glob/list`	搜索和列出文件（尊重 `.gitignore`）
`webfetch`	抓取网页内容（查文档）
`lsp` (实验性)	代码跳转、悬停提示等语言服务器协议支持
`question`	向用户提问确认
`todo`	维护任务清单

📁 上下文感知

OpenCode 能够自动分析项目结构，在初始化时生成 AGENTS.md 指南文件，帮助 AI 理解你的代码库结构、编码规范和项目特点。官方建议将此文件提交到 Git 仓库中，以便团队成员共享项目上下文。

🔗 分享与协作

一键生成会话分享链接，方便与团队成员协作讨论。分享的会话链接可以让其他人查看完整的对话历史和代码变更。

📦 安装 OpenCode

OpenCode 支持 macOS / Windows / Linux 多平台安装。

🚀 通用一键安装脚本（推荐）

这是最简单的方法：

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

安装完成后，验证安装是否成功：

opencode --version

如果输出类似 1.1.19 这样的版本号信息，表示安装成功。

⚠️ 注意：截至 2026 年 1 月，最新稳定版本为 v1.1.19，该版本新增了 Plan 模式的进入/退出工具、GPT 5.2 Codex 支持，以及 GitLab Duo Agentic Chat 提供商支持。

📥 包管理器安装

macOS / Linux

使用 Homebrew（推荐官方 tap 获取最新版本）：

brew install anomalyco/tap/opencode

💡 提示：官方 brew install opencode 公式由 Homebrew 团队维护，更新频率较低。推荐使用 OpenCode 官方 tap 以获取最新版本。

或使用 npm：

npm install -g opencode-ai

其他包管理器选项：

# Bun bun install -g opencode-ai

# pnpm   pnpm install -g opencode-ai

# Yarn yarn global add opencode-ai

Arch Linux：

paru -S opencode-bin

Windows

使用 Chocolatey：

choco install opencode

使用 Scoop：

scoop install opencode

使用 npm：

npm install -g opencode-ai

使用 Mise：

mise use -g github:anomalyco/opencode

使用 Docker：

docker run -it --rm ghcr.io/anomalyco/opencode

⚠️ 注意：Windows 上使用 Bun 安装的支持目前仍在开发中。

你也可以从 GitHub Releases 页面直接下载二进制文件。

💻 终端模拟器推荐

OpenCode 是在终端运行的，我们可以使用系统自带的终端，也可以使用以下现代化的终端工具以获得更好的体验：

终端	平台支持	特点
WezTerm	跨平台	GPU 加速，高度可配置
Alacritty	跨平台	极简高性能
Ghostty	Linux / macOS	现代化设计
Kitty	Linux / macOS	功能丰富，支持图形

🖥️ 桌面应用

OpenCode 也提供桌面端应用，无需终端即可使用完整功能，可直接从发布页面或 opencode.ai/download 下载。

系统平台	下载安装包
macOS（Apple Silicon）	`opencode-desktop-darwin-aarch64.dmg`
macOS（Intel）	`opencode-desktop-darwin-x64.dmg`
Windows	`opencode-desktop-windows-x64.exe`
Linux	`.deb`、`.rpm` 或 AppImage 格式

🚀 启动与使用

启动 OpenCode

在终端输入启动命令：

opencode

或指定项目目录启动：

opencode /path/to/project

首次启动配置

首次启动会引导完成基础配置：

模型选择：默认展示可用模型列表，可直接选择标注 Free 的免费模型（如 MiniMax M2.1、GLM-4.7、Grok Code Fast 1），无需 API Key 即可使用。
登录选项：可选择跳过登录，后续需对接商业模型时再配置 API Key。

启动成功后进入 TUI 界面（终端用户界面），即可开始使用核心功能。

查看可用模型

在终端输入 /models 查看可用的模型：

/models

右边显示 Free 字样的就是免费模型。

🔐 配置 API 密钥与模型

连接 AI 提供商

如果你需要连接 AI 提供商的 API 密钥（例如 OpenAI、Anthropic Claude、Google Gemini 等），有两种方式：

方式一：在启动前运行：

opencode auth login

方式二：在 TUI 界面中输入：

/connect

按照提示选择模型提供商，登录并粘贴你的 API Key。

🌟 使用 OpenCode Zen（推荐新手）

如果你是 LLM 提供商的新手，强烈推荐使用 OpenCode Zen。

OpenCode Zen 是由 OpenCode 官方推荐、经过测试的高质量模型集合，省去自己管理多个外部账户的麻烦。

Zen 的优势：

✅ 统一账单管理，无需分别注册多个提供商
✅ 模型经过专门针对编程任务的测试和优化
✅ 按用量付费（pay-as-you-go），每百万 token 计费
✅ 多个免费模型可用（限时）：GLM-4.7、MiniMax M2.1、Grok Code Fast 1、Big Pickle

Zen 计费说明：

基础服务费：$20 起
余额低于 $5 时自动充值 $20（可更改或禁用）
信用卡手续费按成本传递（4.4% + $0.30/笔）

连接 Zen：

运行 /connect 命令
选择 opencode 选项
前往 opencode.ai/auth 完成登录
添加付款信息，复制 API Key 并粘贴

退出 OpenCode

使用以下命令退出：

/exit

或使用快捷键：Ctrl+X Q

📖 基本使用

启动项目

进入你想处理的项目目录：

cd /path/to/your/project
opencode

示例：创建并进入测试目录：

mkdir opencode-runoob-test
cd opencode-runoob-test
opencode

💡 如果遇到权限问题，可以使用 sudo opencode

项目初始化

在 OpenCode 界面中，运行：

/init

这会：

生成 .opencode/ 文件夹，用于存储项目的向量化索引和自定义指令
扫描当前目录的代码结构
生成 AGENTS.md 文件，记录项目信息和编码规范

💡 提示：官方建议将 AGENTS.md 文件提交到 Git 仓库中，这样可以帮助 OpenCode 更好地理解你的项目。

初始化完成后，你可以用自然语言描述需求来发起任务：

在当前目录下创建一个登录页面

OpenCode 会开始分析需求并自动生成相应的代码文件。

📂 文件引用

使用 @ 符号可以引用项目中的文件，支持模糊搜索：

文件 @index.html 包含哪些功能？

How is authentication handled in @packages/functions/src/api/index.ts?

💡 提示：输入 @ 后会自动弹出文件搜索框，支持模糊匹配项目中的文件路径。

🖥️ 执行 Shell 命令

以 ! 开头的消息会作为 shell 命令执行：

!ls -la

命令输出会自动添加到对话中作为上下文。

🎯 日常交互指南

提问与解释代码

直接用自然语言向 OpenCode 询问代码库细节：

解释 src/main.ts 中的认证逻辑

@packages/functions/src/api.ts 这个文件是做什么的？

添加功能

描述你的需求，让 AI 帮你实现：

添加用户注册 API，支持邮箱验证

使用 Plan 模式规划功能（推荐）

对于复杂功能，建议先在 Plan 模式下规划，再切换到 Build 模式执行：

进入 Plan 模式：按 Tab 键切换到 Plan 模式（右下角会显示模式指示器）

描述需求：

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

迭代计划：根据 AI 的规划反馈，添加更多细节或修改方向
切换到 Build 模式：再次按 Tab 键

执行计划：

Sounds good! Go ahead and make the changes.

💡 提示：可以拖拽图片到终端，AI 会扫描图片内容并添加到提示中，非常适合 UI 设计参考。

撤销与重做

撤销变更：/undo 或 Ctrl+X U
重做：/redo 或 Ctrl+X R

⚠️ 注意：撤销/重做功能需要项目是 Git 仓库才能回滚文件变更。

分享会话

/share

生成的链接会自动复制到剪贴板，可以与团队成员分享。

示例会话：https://opencode.ai/s/4XP1fce5

交互模式（脚本化/非交互式）

OpenCode 支持非交互模式，适合 CI/CD 或自动化脚本：

opencode -p "修复 login 函数中的 bug"

输出 JSON 格式结果：

opencode -p "解释这段代码" -f json

🔧 内置工具详解

OpenCode 的 AI Agent 通过以下工具操作代码库。你可以在 opencode.json 中配置每个工具的权限：

权限设置	说明
`allow`	允许工具自动执行
`deny`	禁止使用该工具
`ask`	每次使用前询问确认

工具详细说明：

工具	功能	使用场景
`bash`	执行 shell 命令	运行 `git status`、`npm test`、`docker build` 等
`write`	创建新文件	生成新的代码文件、配置文件等
`edit`	修改现有文件	更新代码、修复 bug、重构
`patch`	打补丁	对文件进行精确的局部修改
`read`	读取文件内容	分析代码、理解逻辑（支持指定行范围）
`grep`	搜索文件内容	在代码库中查找特定模式
`glob`	匹配文件路径	查找符合模式的文件列表
`list`	列出目录内容	了解项目结构
`webfetch`	抓取网页内容	查阅在线文档、API 参考
`lsp` (实验性)	语言服务器协议	代码跳转、符号定义、类型提示等
`question`	向用户提问	需要用户确认或提供更多信息时
`todo`	维护任务清单	跟踪待办事项和任务进度

自定义工具和 MCP（Model Context Protocol）服务器支持扩展功能，如连接数据库、调用外部 API 等。

🎨 高级用法

📝 自定义命令

在 ~/.config/opencode/commands/ 创建 Markdown 文件作为预设命令：

示例：~/.config/opencode/commands/prime-context.md

# Prime Context 
请先阅读项目的 README.md 和 package.json，了解项目结构后再回答我的问题。

然后在 TUI 中使用 /prime-context 即可执行该预设命令。

🎨 主题与按键

切换主题：/theme 或 Ctrl+X T
自定义快捷键：在配置文件中设置 keybinds

📂 多会话管理

新建会话：/new 或 Ctrl+X N
切换会话：/sessions 或 Ctrl+X L
压缩会话：/compact 或 Ctrl+X C（总结当前会话以节省 token）

🔌 IDE 集成

目前支持：

✅ VS Code 扩展（搜索 "OpenCode extension"）
✅ 客户端/服务器架构远程控制
🔜 更多 IDE 支持开发中

🔒 权限控制

在配置文件中为敏感工具设置 ask 权限：

{
  "tools": {
    "bash": { "permission": "ask" },
    "write": { "permission": "ask" }
  }
}

🛠️ 实战示例：创建一个简单的 Node.js API

步骤演示：

新建项目目录：
```
mkdir my-api && cd my-api
```
初始化 npm：
```
npm init -y
```
启动 OpenCode：
bash
```
opencode
```
初始化 OpenCode：
```
/init
```

描述需求：

创建一个 Express.js 服务，支持 /hello 路由返回 JSON { message: 'Hello World' }，
并添加 README 文件说明如何运行。

OpenCode 会自动：

安装必要的依赖
创建服务器代码
编写 README 文档

🔌 oh-my-opencode 插件

oh-my-opencode 是一个为 OpenCode 设计的强大插件/扩展层，将单个 AI 代理升级为多智能体协作团队。

核心特性

特性	说明
Sisyphus 主智能体	负责持续执行复杂任务，直至完成
并行子智能体	Oracle（预言者）、Librarian（文档专家）、Frontend Engineer（前端工程师）、Explore（探索者）等
内置工具	LSP/AST 代码重构、MCP 模型调用插件、25+ 种事件触发钩子
多模型调度	自动分配任务给最适合的模型
自动化触发	关键词触发完整自动化（如 `ultrawork` 或 `ulw`）

安装方法

推荐让 OpenCode 自动完成安装：

复制以下提示并粘贴到 OpenCode 对话框：

按照以下说明安装和配置 oh-my-opencode：
https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/refs/heads/master/docs/guide/installation.md

或使用命令行安装器：

bunx oh-my-opencode install  # 推荐 npx oh-my-opencode install   # 备选

💡 注意：CLI 附带所有主要平台的独立二进制文件，安装后无需 Bun/Node.js 运行时。

基本使用

在 OpenCode 的提示词中加入关键词 ultrawork（或简写 ulw）：

ultrawork: 请帮我实现一个 React 组件，支持暗黑模式。

这会激活完整模式：

Sisyphus 主智能体接管任务
自动分配子任务给专业代理
并行执行（后台映射代码库、深度探索、自动重构等）
持续执行直至任务 100% 完成

精确控制模式：

按 Tab 进入 Prometheus（规划者）模式
通过访谈过程创建工作计划
运行 /start-work 执行完整编排

⚠️ 重要提示：Sisyphus 智能体强烈推荐使用 Claude Opus 4.5 模型。使用其他模型可能导致体验显著下降。

📋 OpenCode TUI 常用 Slash 命令速查表

OpenCode 的 Slash 命令（以 / 开头）用于快速控制会话、配置和操作。

核心配置与初始化

命令	描述	快捷键
`/connect`	添加或配置 LLM 提供商（API Key）	—
`/init`	创建或更新项目 `AGENTS.md` 文件	`Ctrl+X I`
`/models`	列出可用模型并切换	`Ctrl+X M`

会话管理

命令	描述	别名	快捷键
`/new`	开始新会话（清除当前）	`/clear`	`Ctrl+X N`
`/sessions`	列出并切换会话	`/resume`, `/continue`	`Ctrl+X L`
`/share`	分享当前会话（生成链接）	—	`Ctrl+X S`
`/unshare`	取消分享当前会话	—	—
`/compact`	压缩/总结当前会话	`/summarize`	`Ctrl+X C`

编辑与撤销

命令	描述	快捷键
`/undo`	撤销最后操作（需 Git 仓库）	`Ctrl+X U`
`/redo`	重做已撤销的操作（需 Git 仓库）	`Ctrl+X R`

视图与辅助

命令	描述	快捷键
`/details`	切换工具执行详情显示	`Ctrl+X D`
`/thinking`	切换思考/推理过程可见性	—
`/theme`	列出并切换主题	`Ctrl+X T`
`/help`	显示帮助对话框	`Ctrl+X H`
`/editor`	使用外部编辑器撰写消息	`Ctrl+X E`
`/export`	导出当前对话为 Markdown	`Ctrl+X X`

退出

命令	描述	别名	快捷键
`/exit`	退出 OpenCode	`/quit`, `/q`	`Ctrl+X Q`

💡 提示：
输入 / 会弹出自动补全菜单
/undo 和 /redo 需要项目是 Git 仓库才能回滚文件变更
可以在 ~/.config/opencode/commands/ 创建自定义 Slash 命令

💻 OpenCode CLI 常用参数速查表

OpenCode 的命令行接口用于启动 TUI、非交互模式运行或设置选项。

全局参数

参数	简称	描述	示例
`--help`	`-h`	显示帮助信息	`opencode --help`
`--debug`	`-d`	启用调试模式	`opencode -d`
`--cwd`	`-c`	指定当前工作目录	`opencode -c /path/to/project`
`--prompt`	`-p`	非交互模式：直接运行单个提示	`opencode -p "修复 bug"`
`--output-format`	`-f`	非交互模式输出格式（`text`/`json`）	`opencode -p "解释" -f json`
`--quiet`	`-q`	非交互模式下隐藏加载动画	`opencode -p "生成 README" -q`

使用示例

# 启动交互式 TUI opencode

# 带调试启动 opencode -d

# 指定项目目录启动 opencode -c ~/my-app

# 非交互单次提示 opencode -p "添加一个登录接口" -f json

# 组合使用 opencode -c ~/project -d -p "分析代码结构"

💡 提示：
非交互模式 (-p) 特别适合 CI/CD、脚本或快速查询
更多高级配置通常通过环境变量或 ~/.opencode.json 配置文件处理
运行 opencode --help 查看最新完整参数列表

⚙️ TUI 配置选项

你可以通过 opencode.json 配置文件自定义 TUI 行为：

{
  "$schema": "https://opencode.ai/config.json",
  "tui": {
    "scroll_speed": 3,
    "scroll_acceleration": {
      "enabled": true     }
  }
}

可用选项：

选项	说明	默认值
`scroll_speed`	滚动速度（最小值：1）	3
`scroll_acceleration.enabled`	启用 macOS 风格的滚动加速	false

💡 注意：当 scroll_acceleration.enabled 设为 true 时，scroll_speed 设置会被忽略。

🔗 参考资源

资源	链接
🌐 官方网站	https://opencode.ai/
📖 官方文档	https://opencode.ai/docs
💻 GitHub 仓库	https://github.com/anomalyco/opencode
📋 更新日志	https://opencode.ai/changelog
🌟 OpenCode Zen	https://opencode.ai/zen
💬 Discord 社区	https://opencode.ai/discord
🔌 oh-my-opencode	https://github.com/code-yeongyu/oh-my-opencode
💻 OpenCode 中文实战课	https://github.com/vbgate/learn-opencode

Brave 回复 1 week ago 1 成員 · 0 回复

0 回复

歡迎留言回复交流。

登入後即可回复

人工智能研究

組織者: