🌟 什么是 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 本身免费，只需按需支付 API 费用
• 🔓 开源透明：完全开源，社区驱动，可审计代码
• 🔐 隐私第一：不存储任何代码或上下文数据
• 🔄 模型无关：不绑定任何提供商，可随时切换模型

🔑 关键特性

🤖 两种内置 Agent 模式

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

🛠️ 内置工具集

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

📁 上下文感知

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 是在终端运行的，我们可以使用系统自带的终端，也可以使用以下现代化的终端工具以获得更好的体验：

🖥️ 桌面应用

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

🚀 启动与使用

启动 OpenCode

在终端输入启动命令：

opencode

或指定项目目录启动：

opencode /path/to/project

首次启动配置

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

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

1. 运行 /connect 命令
2. 选择 opencode 选项
3. 前往 opencode.ai/auth 完成登录
4. 添加付款信息，复制 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

这会：

1. 生成 .opencode/ 文件夹，用于存储项目的向量化索引和自定义指令
2. 扫描当前目录的代码结构
3. 生成 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 模式执行：

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

2. 描述需求：

    

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

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

5. 执行计划：

    

   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 中配置每个工具的权限：

工具详细说明：

自定义工具和 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

步骤演示：

1. 新建项目目录：

   mkdir my-api && cd my-api

2. 初始化 npm：

   npm init -y

3. 启动 OpenCode：

   bash

   opencode

4. 初始化 OpenCode：

   /init

5. 描述需求：

    

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

OpenCode 会自动：

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

🔌 oh-my-opencode 插件

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

核心特性

安装方法

推荐让 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% 完成

精确控制模式：

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

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

📋 OpenCode TUI 常用 Slash 命令速查表

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

核心配置与初始化

会话管理

编辑与撤销

视图与辅助

退出

💡 提示：

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

💻 OpenCode CLI 常用参数速查表

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

全局参数

使用示例

# 启动交互式 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_acceleration.enabled 设为 true 时，scroll_speed 设置会被忽略。

🔗 参考资源