OpenCode AI 编程保姆级使用教程：从安装到实战，效率直接拉满

前言

当下 AI 编程工具层出不穷，而OpenCode凭借开源免费、多模型兼容、多端适配、项目级上下文感知的核心优势，成为了程序员的新晋效率神器。它不是简单的代码补全工具，而是能真正理解项目架构、帮你从需求分析到代码落地的 AI 编码代理，支持终端、桌面应用、IDE 扩展等多种使用方式，还能对接国内外 75 + 种 LLM 模型，兼顾便捷性和代码隐私性。

本文结合 OpenCode 官方文档和实际使用经验，用最通俗易懂的语言，从安装配置、核心操作、实战技巧、高级玩法四个维度，带你彻底玩转 OpenCode，不管是编程新手还是资深开发者，都能快速上手并提升开发效率！

一、先搞懂：OpenCode 到底适合谁？有啥核心优势？

1. 适用人群

• 编程新手：不用死记硬背语法，自然语言描述需求就能生成代码，快速入门；
• 资深开发者：摆脱重复编码、重构老项目、写文档等繁琐工作，聚焦核心业务；
• 开发团队：支持团队会话分享、代码审查，统一编码规范，提升协作效率；
• 有隐私需求的开发者 / 企业：支持本地模型部署，代码无需上传云端，杜绝数据泄露。

2. 核心优势

二、环境准备与安装：3 分钟搞定，全平台适配

OpenCode 支持Windows、macOS、Linux全平台，安装方式多样，这里推荐通用安装脚本（最便捷）和各平台专属方式，新手优先选通用脚本！

前置条件

1. 终端要求：推荐现代终端模拟器（WezTerm、Alacritty、Kitty、Ghostty），Windows 用户优先用WSL（体验最佳，完全兼容所有功能）；
2. 密钥准备：需要你想使用的 LLM 提供商 API 密钥（新手可先用 OpenCode 官方精选的OpenCode Zen，后续再配置其他模型）。

1. 通用安装脚本（推荐所有平台）

打开终端，直接执行以下命令，一键安装最新版本：

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

2. 各平台专属安装方式

（1）Node.js 生态安装（npm/pnpm/bun/yarn）

适合已配置 Node.js 环境的开发者，全局安装即可：

# npm npm install -g opencode-ai # bun bun install -g opencode-ai # pnpm pnpm install -g opencode-ai # yarn yarn global add opencode-ai 

（2）macOS/Linux：Homebrew 安装

推荐使用 OpenCode 官方 tap 源（更新最快），而非官方 brew 源：

brew install anomalyco/tap/opencode 

（3）Arch Linux 安装

sudo pacman -S opencode # 稳定版 paru -S opencode-bin # AUR最新版 

（4）Windows 安装（非 WSL）

除了 WSL，还支持 Chocolatey/Scoop/NPM，任选其一：

# Chocolatey choco install opencode # Scoop scoop install opencode # NPM npm install -g opencode-ai 

注意：Windows 上通过 Bun 安装的支持目前正在开发中，暂不推荐。

（5）Docker 安装

适合不想配置环境的开发者，直接运行容器：

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

3. 验证安装

安装完成后，终端输入以下命令，显示版本号即安装成功：

opencode --version 

三、基础配置：API 密钥与模型对接，新手也能一步到位

安装完成后，核心配置就是对接 LLM 模型的 API 密钥，这里分新手推荐（OpenCode Zen）和进阶配置（自定义模型），新手优先用 OpenCode Zen，无需手动找第三方 API 密钥，简单快捷！

1. 新手配置：OpenCode Zen（官方精选模型）

OpenCode Zen 是官方测试验证的精选模型集合，适配编码场景，步骤如下：

1. 选择opencode选项，终端会提示前往授权地址：opencode.ai/auth；
2. 浏览器打开该地址，完成登录并添加账单信息（新手可体验免费额度），复制生成的API 密钥；
3. 回到终端，粘贴 API 密钥并按回车，配置完成！

在 TUI 中输入连接命令，按回车：

/connect 

终端启动 OpenCode 的 TUI 界面：

opencode 

2. 进阶配置：自定义第三方模型（GPT/Claude/GLM 等）

如果想使用 GPT-4o、Claude 3、GLM-4.7 等第三方模型，只需在/connect命令后选择对应模型提供商，输入其官方 API 密钥即可，步骤和上述一致。

小技巧：API 密钥建议存入项目本地配置，避免全局泄露；国内开发者可优先选择 GLM-4.7、DeepSeek-V3 等国产模型，中文支持更好，访问速度更快。

四、项目初始化：让 OpenCode 读懂你的项目

配置完成后，需要先对项目进行初始化，让 OpenCode 扫描项目结构、理解编码规范，后续才能精准生成 / 修改代码，步骤超简单：

1. OpenCode 会自动扫描项目文件，在根目录生成AGENTS.md文件，该文件记录了项目结构、编码规范等核心信息。

输入初始化命令，按回车：

/init 

启动 OpenCode：

opencode 

终端导航到你的项目根目录：

cd /path/to/your/project # 替换为你的项目路径 

重要提示：一定要将AGENTS.md提交到 Git 仓库！后续团队协作或重新使用 OpenCode 时，它能让工具快速读懂项目，无需重复扫描。

五、核心功能实战：Plan+Build 双模式，搞定 80% 开发场景

OpenCode 的核心精髓是Plan（规划模式）+Build（构建模式）双工作流，先让 AI 出方案，再让 AI 写代码，避免直接编码导致的逻辑偏差，代码一次性通过率提升 40% 以上！同时支持直接修改、代码解释、撤销重做等基础功能，下面结合实际案例手把手教学。

核心操作：模式切换

• 按Tab 键可在 Plan 和 Build 模式之间切换，终端右下角会显示模式指示器（Plan/Build）；
• Plan 模式：只读分析，不修改任何文件，仅生成自然语言实施计划；
• Build 模式：执行编码，根据 Plan 计划，自动修改 / 创建文件，实现代码落地。

实战 1：新增功能（复杂场景，先 Plan 再 Build）

适合需要跨文件、多步骤的复杂功能开发（如新增业务模块、开发新页面），示例需求：实现用户删除笔记后，标记为软删除，新增回收站页面支持恢复 / 永久删除。

1. 切换到 Plan 模式：按 Tab 键，确认右下角显示 Plan；
2. 切换到 Build 模式：确认计划无误后，按 Tab 键切换到 Build；
3. OpenCode 会自动修改数据库模型、新增接口、开发页面，所有修改都会实时显示在终端，可随时查看。

执行编码：在终端输入指令，让 AI 开始开发：

按照计划执行，完成所有修改。 

迭代计划：OpenCode 会生成实施计划（如修改哪些文件、新增哪些接口、页面布局设计等），如果计划不符合预期，直接在终端补充需求即可，比如：

回收站页面的设计参考项目中已有的笔记列表页面，使用相同的UI组件。 

小技巧：可直接将设计图拖放到终端，OpenCode 会自动识别图片内容，作为设计参考！

描述需求：在终端输入详细需求（把 AI 当初级开发者，越详细越好）：

当用户删除笔记时，在数据库中将该笔记标记为deleted状态（软删除，不真正删除）；新增一个回收站页面，展示所有标记为deleted的笔记；在回收站页面，用户可以点击恢复按钮将笔记恢复为正常状态，也可以点击永久删除按钮彻底删除笔记。 

实战 2：直接修改（简单场景，跳过 Plan）

适合单行代码修改、简单功能添加、代码重构等轻量操作（如给接口加鉴权、修改按钮样式），示例需求：给 /settings 路由添加鉴权，参考 /notes 路由的鉴权逻辑。直接在 Build 模式下输入指令（需提供足够细节，指定参考文件）：

给@packages/functions/src/settings.ts中的/settings路由添加身份验证，参考@packages/functions/src/notes.ts中/notes路由的鉴权逻辑，实现完全相同的功能。 

小技巧：使用 **@符号 ** 可模糊搜索项目文件，直接引用文件路径，无需手动输入完整路径，大幅提升效率！

实战 3：代码解释（读懂陌生代码 / 祖传代码）

遇到不熟悉的代码库或老项目时，可让 OpenCode 直接讲解代码逻辑，示例：

解释@packages/functions/src/api/index.ts中的认证逻辑，说明每一步的作用。 

适合快速接手新项目、理解团队同事的代码，省去逐行阅读的时间。

实战 4：撤销 / 重做修改（操作失误快速回滚）

如果 AI 生成的代码不符合预期，无需手动修改，直接用命令快速回滚：

1. 撤销修改：输入/undo，可撤销上一步操作，多次输入可撤销多次修改；
2. 重做修改：输入/redo，可恢复最近一次撤销的修改。

实战 5：会话分享（团队协作，同步开发思路）

如果需要和团队同事沟通开发方案，可将 OpenCode 的对话生成链接分享，输入命令：

/share 

链接会自动复制到剪贴板，同事打开即可查看完整的需求分析、计划设计、代码修改过程，无需反复沟通。

六、高频实用命令：Slash 命令体系，提升操作效率

OpenCode 的Slash 斜杠命令是核心操作方式，所有功能都可通过命令实现，无需鼠标操作，下面整理了开发中最常用的高频命令，建议收藏！

七、高级玩法：定制化 OpenCode，适配个人 / 团队开发习惯

OpenCode 支持高度定制化，可通过自定义主题、快捷键、模型参数、Agent 代理等，让工具完全适配你的开发习惯，这里分享 2 个最实用的高级技巧：

1. 自定义模型参数，平衡生成效果与速度

在配置面板中可修改模型核心参数，根据开发场景调整：

• 温度参数（Temperature）：0-1 区间，值越小代码越严谨（推荐 0.2-0.4，生产环境），值越大创造性越强（适合原型开发）；
• 最大生成长度（Max Tokens）：限制单次生成代码长度，前端组件开发建议设 2048，避免冗余代码；
• 上下文扫描范围：可选「当前文件 / 当前文件夹 / 整个项目」，大型项目建议选「当前文件夹」，减少性能消耗。

2. 自定义 Agent 代理，实现专属功能

可创建自定义 Agent（如代码审查专家、安全检测专家），让 OpenCode 扮演特定角色，实现专属功能：

1. 在项目根目录创建文件夹：.opencode/prompts/；
2. 在终端输入/run security，即可调用该自定义 Agent，对项目进行安全检测。

创建自定义 Agent 文件（如security.md），写入系统提示词：

你是一名资深网络安全专家，专门检查代码中的SQL注入、XSS漏洞、权限绕过等安全问题，发现问题后给出详细的修复方案，不直接修改代码。 

八、VSCode 集成：IDE 无缝使用，无需切换终端

对于习惯用 VSCode 的开发者，可将 OpenCode 集成到 IDE 中，实现终端 + 编辑器无缝操作，体验更佳：

1. 打开 VSCode，按Ctrl+Shift+X（Windows/Linux）/Cmd+Shift+X（Mac）打开扩展市场；
2. 搜索OpenCode，找到官方认证插件并安装，重启 VSCode 生效；
3. 打开 VSCode 底部终端，按正常步骤启动 / 使用 OpenCode 即可；
4. 小技巧：在 VSCode 的keybindings.json中绑定快捷键（如Ctrl+'），可快速唤起 OpenCode，无需手动输入命令。

优势：可直接将 VSCode 左侧文件树的文件拖放到终端，OpenCode 会自动识别并执行/add命令，添加到上下文，大幅提升操作效率。

九、避坑指南：新手常见问题与解决方法

1. Windows 系统使用卡顿 / 功能不全：优先使用WSL（Windows Subsystem for Linux），原生终端对部分功能支持有限；
2. API 密钥配置失败：检查密钥是否正确，第三方模型需确认密钥未过期、有足够额度，国内用户需注意网络环境；
3. AI 无法理解项目结构：确认已执行/init命令，且AGENTS.md文件存在，未被修改 / 删除；
4. 生成代码与项目规范不符：在AGENTS.md中补充项目编码规范（如代码风格、命名规则、框架使用要求），OpenCode 会自动遵循；
5. Token 消耗过快：使用/compact命令压缩上下文，避免无关对话占用 Token，简单任务用轻量模型（如 gpt-4o-mini、GLM-4.7）。

十、总结

OpenCode 作为一款开源的 AI 编码代理，真正做到了 **“解放程序员双手，聚焦核心业务”**，它不是替代开发者，而是成为开发者的 “编程搭子”—— 帮你处理重复编码、读懂陌生代码、重构老项目、写技术文档，让你把时间花在更有价值的需求设计和架构优化上。

本文从安装配置到实战技巧，覆盖了 OpenCode 的核心使用场景，只要掌握Plan+Build 双模式和Slash 命令体系，就能搞定绝大多数开发工作。后续随着社区生态的完善，OpenCode 的功能会越来越强大，赶紧上手试试，让 AI 帮你提升开发效率吧！

最后，推荐大家关注 OpenCode 官方文档（https://opencode.ai/docs/zh-cn）和 GitHub 仓库，及时获取最新功能和更新内容，也可以参与社区贡献，一起完善这款开源工具！

创作不易，觉得有帮助的话，欢迎点赞 + 收藏 + 关注！ 后续会持续更新 OpenCode 的高级实战和定制化技巧，带你玩转 AI 编程～