🔥 BRAVE 質押池已上線 — 在錢包搜尋 BRAVE 即可委託
简体

Brave基地

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

    • 2026 年 1 月 24 日 上午 4:50 #32866
      Brave

      🌟 什么是 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 是三大主流选择。以下是它们的核心差异：

      特性OpenCodeClaude CodeCursor
      类型终端 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跨平台极简高性能
      GhosttyLinux / macOS现代化设计
      KittyLinux / macOS功能丰富，支持图形

      🖥️ 桌面应用

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

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

      🚀 启动与使用

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

      权限设置说明
      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

      步骤演示：

      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 代理升级为多智能体协作团队。

      核心特性

      特性说明
      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% 完成

      精确控制模式：

      1. 按 Tab 进入 Prometheus（规划者）模式
      2. 通过访谈过程创建工作计划
      3. 运行 /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开始新会话（清除当前）/clearCtrl+X N
      /sessions列出并切换会话/resume, /continueCtrl+X L
      /share分享当前会话（生成链接）—Ctrl+X S
      /unshare取消分享当前会话——
      /compact压缩/总结当前会话/summarizeCtrl+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导出当前对话为 MarkdownCtrl+X X

      退出

      命令描述别名快捷键
      /exit退出 OpenCode/quit, /qCtrl+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 Zenhttps://opencode.ai/zen
      💬 Discord 社区https://opencode.ai/discord
      🔌 oh-my-opencodehttps://github.com/code-yeongyu/oh-my-opencode
      💻 OpenCode 中文实战课https://github.com/vbgate/learn-opencode

  • 抱歉，回覆主題必需先登入。