🚀 OpenCode 开源AI编码代理 完整使用指南（官方文档全解析）

OpenCode 是一款完全开源的AI编码代理，专为终端原生打造，同时提供桌面应用、IDE扩展等多种使用方式。凭借轻量高效、全模型兼容、隐私优先的核心特性，已斩获超26k GitHub Star，每月有超20万开发者信赖使用，是Linux内核/驱动开发、全栈项目编码的提效神器。

官方主页：https://opencode.ai/
官方中文文档：https://opencode.ai/docs/zh-cn

---

一、OpenCode 核心特性（官方权威说明）

• 原生终端TUI：响应式、可自定义主题的终端界面，适配全平台主流现代终端
• 全模型兼容：支持75+ LLM提供商，包括本地模型、OpenCode Zen官方精选编码模型、Claude等主流商用模型
• LSP原生支持：自动加载对应语言的LSP服务，精准理解项目代码结构与语法规范
• 多会话并行：同一项目可启动多个代理，并行处理不同开发任务
• 隐私优先设计：不存储你的任何代码和上下文数据，完美适配隐私敏感的企业/开源开发环境
• 全编辑器兼容：纯终端内运行，可搭配VS Code、Vim、VS等任意IDE/编辑器使用
• 会话一键分享：生成对话分享链接，方便团队协作、问题排查、技术方案存档
• 完全开源可控：188+社区贡献者参与维护，代码完全开源，开发者拥有100%自主权

---

二、官方完整安装指南

2.1 一键安装脚本（官方全平台推荐）

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

2.2 包管理器安装（全平台覆盖）

2.2.1 Node.js 生态安装（跨平台通用）

npm/bun/pnpm/yarn 均可安装，也是Ubuntu 18.04等老旧系统的首选兼容方案

# npm 安装
npm install -g opencode-ai

# bun 安装
bun install -g opencode-ai

# pnpm 安装
pnpm install -g opencode-ai

# yarn 安装
yarn global add opencode-ai

⚠️ Ubuntu 18.04 专属避坑提示
系统默认glibc版本为2.27，而Node.js 18+ 要求glibc >= 2.28，直接安装会出现GLIBC_2.28' not found报错，必须使用Node.js 16.x版本，完整兼容方案见2.3章节。

2.2.2 macOS/Linux Homebrew 安装

brew install anomalyco/tap/opencode

官方提示：推荐使用OpenCode官方tap源，Homebrew核心仓库的formula更新频率较低。

2.2.3 Arch Linux 安装

# 官方稳定版
sudo pacman -S opencode

# AUR最新版
paru -S opencode-bin

2.2.4 Windows 安装

官方推荐使用WSL获得最佳兼容性与完整功能支持，也可使用原生包管理器安装：

# Chocolatey 安装
choco install opencode

# Scoop 安装
scoop install opencode

# npm 原生安装
npm install -g opencode-ai

2.2.5 其他官方安装方式

• Mise 版本管理安装

mise use -g github:anomalyco/opencode

• Docker 一键运行

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

• 离线二进制安装：可从官方GitHub Releases页面直接下载对应平台的二进制包。

2.3 Ubuntu 18.04 专属兼容安装步骤

针对Linux内核开发、服务器远程SSH场景的完整避坑流程：

1. 安装nvm管理Node.js版本

mkdir -p ~/.nvm
tar -xzf nvm-v0.39.7.tar.gz -C ~/.nvm --strip-components=1
export NVM_DIR="$HOME/.nvm"
source ~/.nvm/nvm.sh

2. 配置国内镜像加速，解决下载超时问题

# Node.js 镜像
export NVM_NODEJS_ORG_MIRROR=https://npmmirror.com/mirrors/node
# npm 包镜像
npm config set registry https://registry.npmmirror.com

3. 安装兼容的Node.js 16版本

nvm install 16
nvm use 16
# 验证安装结果
node -v && npm -v

4. 全局安装OpenCode

npm install -g opencode-ai

---

三、官方标准配置与项目初始化

3.1 终端环境要求

为获得最佳的TUI交互体验，官方推荐使用以下现代终端模拟器：

• WezTerm（全平台兼容）
• Alacritty（全平台兼容）
• Ghostty（Linux/macOS）
• Kitty（Linux/macOS）

3.2 模型提供商配置

OpenCode支持任意LLM提供商，新手官方首推OpenCode Zen，这是官方团队专为编码场景测试、调优、验证的精选模型集，开箱即用，无需复杂配置。

1. 进入你的项目目录，启动OpenCode

cd /path/to/your/project
opencode

2. 在TUI输入区执行官方连接命令，配置模型提供商

/connect

3. 在弹出的列表中选择opencode，前往 https://opencode.ai/auth 登录账号，添加账单信息后复制API密钥，粘贴到终端中即可完成配置。

提示：也可选择Anthropic、OpenAI等其他75+模型提供商，按终端提示配置对应API密钥即可。

3.3 项目初始化

配置好模型后，在项目内执行官方初始化命令，让AI深度理解你的项目：

/init

OpenCode会自动分析项目结构、编码规范、技术栈，在项目根目录生成AGENTS.md文件。

官方最佳实践：建议将AGENTS.md提交到Git仓库，帮助AI持续适配项目的开发规范与架构逻辑，大幅提升代码生成准确率。

---

四、核心功能与模式详解（官方标准用法）

4.1 两大核心工作模式

OpenCode官方设计了Plan/Build双模式，适配不同开发场景，可通过Tab键一键切换，终端右下角会显示当前模式指示器。

4.1.1 Plan模式（计划模式）

核心用途：复杂需求拆解、技术方案设计、架构规划，模式下AI不会修改任何项目文件，仅输出实现方案与执行步骤。
适用场景：大型功能开发、架构重构、复杂bug根因分析、技术方案评审
标准使用流程：

1. 按Tab键切换到Plan模式（右下角显示Plan标识）
2. 输入完整需求，尽可能提供充足的上下文与细节

当用户删除笔记时，在数据库中将其标记为已删除；创建回收站页面，展示所有最近删除的笔记，支持恢复和永久删除功能。

3. 迭代优化方案：AI输出计划后，可补充反馈、参考资料、设计图（直接拖入终端即可识别），持续完善方案

参考我之前的页面设计风格实现回收站页面，设计参考图已拖入终端。

4.1.2 Build模式（构建模式，默认模式）

核心用途：代码生成、修改、重构，直接落地开发需求，自动修改项目文件。
适用场景：日常编码、功能实现、bug修复、代码优化、驱动开发
标准使用流程：

1. 方案确认后，按Tab键切回Build模式
2. 输入指令让AI执行方案落地

方案没问题，按照这个计划完成全部代码修改。

3. 简单需求可直接在Build模式下执行，无需提前规划

给@packages/functions/src/settings.ts路由添加鉴权逻辑，参考@packages/functions/src/notes.ts中的实现方式。

官方提效技巧：使用@键可模糊搜索项目中的文件，精准指定AI操作的目标文件，大幅提升代码修改的准确率。

4.2 核心基础操作

4.2.1 撤销与重做

• 撤销上一次AI的代码修改，支持多次执行撤销多轮修改

/undo

• 重做已撤销的修改

/redo

4.2.2 会话分享

一键生成当前对话的分享链接，自动复制到剪贴板，方便团队协作、问题排查

/share

官方隐私说明：对话默认不会被公开，只有执行/share命令后才会生成可访问的分享链接。

---

五、进阶使用：Skill自定义与个性化配置

5.1 Skill（自定义技能）使用与开发

Skill是OpenCode的自定义能力插件，可将你常用的开发流程、代码模板、规范检查封装成一键触发的技能，完美适配个人/团队的开发习惯。

5.1.1 内置Skill使用

在TUI中直接输入命令即可触发：

/skill 技能名称

也可通过命令面板Ctrl+P搜索Skill相关命令，查看全部可用技能。

5.1.2 自定义Skill开发（Linux驱动开发示例）

1. 在OpenCode配置目录~/.opencode/skills/下新建yaml配置文件，例：linux_ir_driver.yaml

name: "Linux红外驱动生成"
description: "一键生成符合内核规范的NEC红外驱动完整代码"
trigger: "/ir_driver"
prompt: |
  你是资深Linux内核驱动开发专家，帮我生成完整的NEC红外收发驱动代码，严格遵循Linux内核编码规范，包含以下内容：
  1. 设备树节点配置示例
  2. 平台驱动完整框架
  3. PWM时序控制逻辑
  4. sysfs用户态交互接口
  5. 完整的错误处理与内核日志
  生成的代码可直接编译进内核，无语法错误。

2. 重启OpenCode自动加载，或通过命令面板执行Reload skills手动刷新
3. 在TUI中输入/ir_driver即可一键触发自定义技能

5.2 个性化配置

官方支持深度自定义，完全适配你的开发习惯：

• 自定义主题与配色方案
• 快捷键映射修改
• 代码格式化工具配置
• 自定义命令别名
• 模型推理参数调优
  更多配置细节可参考官方中文文档：https://opencode.ai/docs/zh-cn

---

六、官方快捷键与核心命令速查表

6.1 全局核心快捷键

功能	官方快捷键
打开命令面板	Ctrl + P
切换Plan/Build模式	Tab
切换模型变体	Ctrl + T
切换模型提供商	Ctrl + X M
切换Agent	Ctrl + X A
新建会话	Ctrl + X N
切换会话	Ctrl + X L
打开内置编辑器	Ctrl + X E
重命名会话	Ctrl + R
撤销上一条消息/修改	Ctrl + X U
隐藏侧边栏	Ctrl + X B
复制最后一条助手消息	Ctrl + X Y
查看运行状态	Ctrl + X S
切换主题	Ctrl + X T
中断当前任务	Ctrl + C
终端粘贴	Ctrl + Shift + V
退出应用	esc 输入 exit 回车

6.2 核心命令速查

命令	官方功能说明
/connect	连接LLM模型提供商
/init	初始化当前项目，生成AGENTS.md
/plan	切换到计划模式
/build	切换到构建模式
/model 模型名	快速切换指定模型
/skill 技能名	触发指定Skill技能
/undo	撤销上一次代码修改
/redo	重做撤销的修改
/share	生成当前会话分享链接
/session	会话管理命令
/help	打开官方帮助文档
/exit	退出OpenCode

---

七、官方常见问题FAQ

1. 使用OpenCode需要额外的AI订阅吗？
   官方说明：你可以使用自己任意LLM提供商的API密钥（包括Claude、OpenAI等），也可以选择官方的OpenCode Zen付费模型，无强制订阅要求。

2. OpenCode只能在终端使用吗？
   官方说明：OpenCode核心为终端TUI应用，同时即将推出桌面应用，也支持IDE扩展，可搭配任意编辑器使用。

3. OpenCode是完全开源的吗？
   官方说明：OpenCode完全开源，代码托管在GitHub，已获得26k+ Star，你可以完全掌控代码的使用和修改。

4. 我的代码数据会被存储吗？
   官方说明：OpenCode以隐私优先为设计原则，不会存储你的任何代码和上下文数据，可在隐私敏感的企业环境中安全使用。

5. Ubuntu 18.04 出现GLIBC版本不兼容报错怎么办？
   解决方案：Ubuntu 18.04默认glibc版本为2.27，Node.js 18+ 要求glibc >=2.28，使用nvm安装Node.js 16.x版本即可完美兼容，完整步骤参考本文2.3章节。

---

八、总结与官方资源汇总

OpenCode作为一款专为终端打造的开源AI编码代理，完美适配Linux内核/驱动开发、全栈项目开发等场景，凭借全模型兼容、隐私优先、高度自定义的特性，成为开发者提效的核心工具。

官方核心资源

• 🏠 官方主页：https://opencode.ai/
• 📖 官方中文文档：https://opencode.ai/docs/zh-cn
• ⭐ GitHub开源仓库：https://github.com/anomalyco/opencode
• 🔑 官方API密钥申请：https://opencode.ai/auth