$catSERPAPI||~14 min

OpenCode开源AI编程助手完全使用指南从入门到精通

advertisement

OpenCode 开源 AI 编程助手：我从踩坑到真香的使用心得

说实话，我之前一直在用 Claude Code 和 Cursor，用着是挺爽的，但钱包不太行。Claude Code 按 token 计费，跑个大项目分分钟几刀就没了；Cursor 月费也不便宜，而且闭源的，心里总觉得不太踏实。后来一个朋友给我安利了 OpenCode，说是完全开源、免费能用，我一开始还不信——免费的东西能好用？结果一试，真香了。

这篇文章就是我这段时间折腾 OpenCode 的完整记录，踩过的坑、摸索出来的技巧，全都分享给大家。

一、OpenCode 到底是个啥

简单说，OpenCode 就是一个跑在终端里的 AI 编程助手。它跟 Claude Code、Cursor 这些是同一类产品，但有几个关键不同：

  • 完全开源，代码就在 GitHub 上，你爱看就看，爱改就改
  • 支持 75+ 模型提供商，不绑定任何一家，想用啥模型用啥模型
  • 内置免费模型，GLM-4.7、MiniMax M2.1 这些都可以零成本白嫖
  • 终端原生体验，对于我这种离不开终端的人来说，简直太舒服了

我第一次用的时候就觉得，这玩意儿的设计思路跟我之前的工具完全不一样。它不是让你去适应它，而是让你在自己熟悉的环境里加一个 AI 搭档。

二、安装这块我踩了几个坑

先说系统要求

OpenCode 支持 macOS 和 Linux，Windows 原生不支持。这个我得强调一下，因为我有个 Windows 的同事第一次装的时候直接在 PowerShell 里跑命令，死活跑不起来，折腾了半天才发现要用 WSL。所以 Windows 用户老老实实装个 WSL 吧。

一键安装（我推荐的方式）

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

这个命令跑完基本就装好了。装完验证一下：

bash
1
opencode --version

看到版本号就说明成功了。我第一次装的时候版本号是 1.1.19，后面更新了好几次。

包管理器安装

如果你不想用一键脚本，也可以用包管理器：

bash
1
# macOS / Linux 用 Homebrew
2
brew install opencode
3
4
# 或者用 npm
5
npm install -g opencode-ai
6
7
# Arch Linux 用户
8
paru -S opencode-bin

我踩的坑

坑一：我一开始用的是 macOS 自带的 Terminal.app，结果 TUI 界面渲染有问题，各种乱码。后来换成了 WezTerm，一切正常。推荐大家用 WezTerm、Alacritty、Ghostty 或 Kitty 这几个现代化终端。

坑二：在公司网络环境下，一键安装脚本下载超时了。我的解决办法是挂了个代理，或者直接去 GitHub Releases 手动下载二进制文件。

三、第一次启动：别慌，先用免费模型

装好之后进入你的项目目录，直接敲：

bash
1
cd /path/to/your/project
2
opencode

首次启动会有一些引导。我的建议是：别急着配置 API Key，先用免费模型体验一下。

在 TUI 里输入 /models，能看到所有可用模型。标注了 Free 的就是免费的，比如 GLM-4.7 和 MiniMax M2.1。选一个就能直接开始用了，零成本。

想用商业模型的话

等你玩熟了，想接 Claude 或 GPT 的 API Key，在 TUI 里输入：

code
1
/connect

然后从列表里选提供商，粘贴 API Key 就行。或者你也可以用命令行：

bash
1
opencode auth login

还有一个叫 OpenCode Zen 的东西，是官方帮你筛选过的高质量模型集合，省得你自己折腾多个账号。在 /connect 里选 OpenCode Zen 就行。

高级玩家：手动改配置文件

配置文件在这两个地方：

  • 全局：~/.config/opencode/opencode.json
  • 项目级：项目根目录下的 opencode.json

比如你想加一个自定义模型提供商：

json
1
{
2
  "$schema": "https://opencode.ai/config.json",
3
  "provider": {
4
    "myprovider": {
5
      "npm": "@ai-sdk/openai-compatible",
6
      "name": "My Provider",
7
      "options": {
8
        "baseURL": "https://your-api-url.com/v1",
9
        "headers": {
10
          "Authorization": "Bearer your_api_key_here"
11
        }
12
      },
13
      "models": {
14
        "your-model-name": {
15
          "name": "model-alias"
16
        }
17
      }
18
    }
19
  }
20
}

四、最核心的概念：Plan 和 Build 两种模式

这个设计我觉得是 OpenCode 最聪明的地方。按 Tab 键 就能切换：

Plan 模式：AI 只看不动手。它会分析你的项目、规划方案、给你建议，但不会改任何文件。就像一个只动嘴不动手的技术顾问。

Build 模式：AI 全权限。它会读写文件、跑命令、改代码，真正帮你干活。

我的使用习惯是：

code
1
Plan 模式讨论需求 → 确认方案没问题 → Tab 切 Build → 执行 → 验证

血泪教训：我有一次跳过了 Plan 直接用 Build 模式让 AI 改代码，结果它理解错了我的需求，把一个重要文件改得面目全非。幸好有 /undo 可以撤销。从那以后我再也不跳过 Plan 了。

项目初始化

进入项目后第一件事，跑一下：

code
1
/init

这个命令会：

  1. 创建 .opencode/ 目录
  2. 生成一个 AGENTS.md 文件

AGENTS.md 特别重要，它是 AI 理解你项目的"说明书"。你可以手动往里面加项目的技术栈、编码规范、常见坑等等。AI 越了解你的项目，给你的代码就越靠谱。

五、日常使用的一些实战技巧

创建项目

bash
1
mkdir my-api && cd my-api
2
npm init -y
3
opencode

然后在 TUI 里：

code
1
/init
2
创建一个 Express.js 服务，支持 /hello 路由返回 JSON，加个 README

OpenCode 会自动帮你装依赖、建文件、写代码。效率真的高。

提问和分析代码

用 @ 符号引用文件特别方便：

code
1
文件 @src/app.ts 包含哪些功能
2
分析 @src/utils/ 目录下的工具函数

常用操作

code
1
添加用户注册 API，支持邮箱验证     # 加功能
2
修复 login 函数的空指针异常        # 修 bug
3
将 @src/helpers.js 的重复逻辑抽成公共函数  # 重构
4
/undo    # 撤销
5
/redo    # 重做
6
/compact # 压缩会话（防止上下文太长）
7
/new     # 新会话

Slash 命令速记

  • /connect：添加模型提供商
  • /init：初始化项目上下文
  • /models：查看和切换模型
  • /new：新会话
  • /sessions：查看所有会话
  • /share：分享会话链接
  • /compact：压缩会话
  • /undo：撤销
  • /redo：重做
  • /theme：换主题

六、CLI 非交互模式

除了 TUI，OpenCode 也能直接在命令行里用：

bash
1
# 直接运行提示
2
opencode -p "修复 login 函数中的 bug"
3
4
# 指定项目目录
5
opencode -c /path/to/project
6
7
# JSON 输出（方便脚本解析）
8
opencode -p "解释代码" -f json
9
10
# 静默模式
11
opencode -p "运行测试" -q

这个在 CI/CD 或者写自动化脚本的时候特别好用。

七、进阶玩法

自定义命令

在 ~/.config/opencode/commands/ 目录下创建 Markdown 文件就行。比如创建一个 review.md：

markdown
1
请审查当前项目的代码质量，重点关注：
2
1. 安全漏洞
3
2. 性能问题
4
3. 代码风格一致性
5
4. 测试覆盖率

之后就能快速调用这个命令了。

权限控制

在 opencode.json 里可以给每个工具设权限：

  • allow：自动执行
  • deny：禁止
  • ask：每次确认

我建议对敏感操作（比如删文件、跑数据库命令）设成 ask。我有一次没设权限，AI 自动跑了一个 rm -rf，吓出一身冷汗。

八、Oh-My-OpenCode：多智能体协作

这是 OpenCode 最炸裂的扩展。装了这个之后，你就不是一个 AI 在帮你干活，而是一整个 AI 团队。

安装

先装 Bun：

bash
1
curl -fsSL https://bun.sh/install | bash

然后：

bash
1
bunx oh-my-opencode install --no-tui --claude=yes --chatgpt=yes --gemini=yes

如果你只有部分订阅，可以调整参数：

bash
1
bunx oh-my-opencode install --no-tui --claude=yes --chatgpt=no --gemini=no

智能体团队

  • Sisyphus（总指挥）：任务拆分和协调
  • Oracle（架构师）：架构设计和疑难解答
  • Librarian（文档员）：查文档、研究代码库
  • Frontend Engineer（前端）：UI/UX 开发
  • Explore（探索者）：快速代码分析

Ultrawork 模式

在提示词里加 ultrawork 或 ulw 就能激活：

code
1
ultrawork: 实现一个 React 组件，支持暗黑模式切换

激活后，Sisyphus 会自动拆分任务、分配给不同的智能体、并行执行、汇总结果。这个体验真的很爽，就像有一个项目经理在帮你协调整个团队。

我的踩坑经验

Oh-My-OpenCode 需要同时调用多个模型的 API，所以你的 API 额度消耗会比较快。我建议先确认好各模型的计费方式，别月底收到账单吓一跳。另外，Bun 的安装有时候会跟 Node.js 的版本冲突，建议用 nvm 管理好 Node 版本。

九、常见问题

Q：Windows 能直接用吗？ A：不能，必须用 WSL。别折腾了，直接装 WSL。

Q：免费模型效果怎么样？ A：简单任务还行，复杂任务还是建议用 Claude 或 GPT-4 级别的。我的建议是先用免费模型入门，觉得不够用了再上商业模型。

Q：AI 写的代码靠谱吗？ A：大部分时候还行，但不是 100% 靠谱。我养成的习惯是 AI 写完之后自己 review 一遍，重要的逻辑一定要自己验证。

总结

OpenCode 是我目前用过的性价比最高的 AI 编程工具。免费能用、开源可控、终端原生、支持多模型——这几个特点加在一起，对开发者来说太友好了。

我的学习路径建议：

  1. 先用免费模型 + 简单的代码提问，熟悉交互方式
  2. 尝试用 Plan/Build 模式完成一个小项目
  3. 编辑 AGENTS.md，让 AI 更了解你的项目
  4. 探索 Oh-My-OpenCode 的多智能体协作

记住，AI 是工具，不是替代品。真正写出好代码，靠的还是你自己的思考和判断。OpenCode 能帮你提效，让你把更多精力放在架构设计和创造性思考上。

好了，这就是我折腾 OpenCode 的全部心得。有问题欢迎交流，祝大家编码愉快！

advertisement

OpenCode开源AI编程助手完全使用指南从入门到精通 — AI Hub