『AI编程工具』OpenCode 保姆级安装教程：开源 AI 编程代理入门教程

📣读完这篇文章里你能收获到

文章目录

• 前言
• 一、OpenCode 简介与核心特性
• • 1.1 什么是 OpenCode
  • 1.2 核心特性
  • 1.3 与 Claude Code 和 Cursor 的对比
• 二、安装与配置
• • 2.1 通用一键安装（推荐）
  • 2.2 包管理器安装
  • • macOS / Linux
    • Arch Linux
    • Windows
  • 2.3 桌面应用（可选）
  • 2.4 首次启动配置
• 三、基本使用与免费模型推荐
• • 3.1 项目初始化
  • 3.2 自然语言交互
  • 3.3 免费模型推荐
  • • GLM-4.7（强烈推荐）
    • Big Pickle（推理型）
    • Grok Code Fast 1（速度型）
    • MiniMax M2.1（平衡型）
  • 3.4 常用 TUI 命令速查
  • • 核心配置与初始化
    • 会话管理
    • 编辑与撤销
    • 视图与辅助
• 四、实战案例与总结
• • 4.1 创建一个简单的登录页面
  • 4.2 修复代码 Bug
  • 4.3 oh-my-opencode 扩展
  • • 4.3.1 什么是 oh-my-opencode
    • 4.3.2 安装步骤
    • • 交互式安装
    • 4.3.3 使用方法
    • • 模式一：Ultrawork 模式（快速自动）
      • 模式二：Prometheus 规划模式（复杂任务）
    • 4.3.4 配置文件（可选）
    • 4.3.5 专业 Skills 使用
    • 4.3.6 小结
• 总结

前言

在各种 AI 编程工具满天飞的今天，你是否厌倦了 Claude Code 和 Cursor 的订阅费用？OpenCode 是一个完全开源、免费的 AI 编程代理（AI coding agent），支持在终端、桌面应用和主流 IDE 中与 AI 交互完成代码任务。

它就像你的私人编程助手——帮你理解代码库、编写新功能、重构代码、修复 Bug，大幅提升开发效率。而且完全免费开源，隐私优先，支持接入各种大模型。这篇文章不长，但能帮你快速把环境搭起来，开始用 OpenCode 提升你的开发效率。

一、OpenCode 简介与核心特性

1.1 什么是 OpenCode

OpenCode 是一个开源的 AI 编程代理（AI coding agent），类似于 Claude 的 Code 模式或 Cursor 的 Agent 功能，但完全开源、隐私优先。它支持在终端（Terminal）、桌面应用和主流 IDE（如 VS Code）中与 AI 交互完成代码相关任务。

简单来说，你可以把它想象成一个能直接在你的项目目录里"干活"的 AI 助手——它不仅能理解代码，还能执行命令、读写文件、运行测试，像一个真正的开发伙伴一样帮你完成各种编程任务。

1.2 核心特性

OpenCode 提供了两大 Agent 工作模式：

• Build 模式：全权限模式，可以直接编辑文件、执行命令、安装依赖，适合需要自动完成任务的场景
• Plan 模式：只读规划模式，默认拒绝编辑操作，需要用户确认后才执行，更适合学习和审查场景

内置强大的工具集，包括 bash 命令执行、文件读写、grep 搜索、LSP 诊断等，让 AI 能像真实开发者一样操作你的项目。上下文感知功能会自动分析项目结构并生成 AGENTS.md 指南文件，帮助 AI 快速理解你的代码库。

最重要的是，OpenCode 支持 75+ 家模型提供商，内置了 GLM-4.7、MiniMax M2.1 等免费模型，无需 API Key 即可使用。同时也可以对接 OpenAI、Anthropic、Google 等商业模型，或配置本地模型（如 Llama 3），按需适配不同场景。

1.3 与 Claude Code 和 Cursor 的对比

相比 Claude Code 和 Cursor 等商业化工具，OpenCode 的核心优势在于：

• 完全开源免费：不再被订阅费背刺，代码完全开源可审计
• 隐私优先设计：数据本地处理，支持本地模型，保护代码隐私
• 内置免费模型：GLM-4.7、MiniMax M2.1 等免费模型即开即用
• 全平台支持：macOS、Windows、Linux，终端与桌面应用全覆盖
• 高度可扩展：支持 MCP 服务器、自定义工具、oh-my-opencode 扩展

二、安装与配置

别慌，OpenCode 的安装非常简单，支持多种方式，选择最适合你系统的就行。

2.1 通用一键安装（推荐）

这是最简单的方法，适用于所有平台：

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

安装完成后，验证安装是否成功：

opencode –version

如果输出版本号信息（如 1.1.19），说明安装成功。是不是很简单？

2.2 包管理器安装

macOS / Linux

如果你习惯用 Homebrew：

brew install opencode

或者用 npm：

npm install -g opencode-ai

Arch Linux

paru -S opencode-bin

Windows

Chocolatey 用户：

choco install opencode

Scoop 用户：

scoop bucket add extras
scoop install extras/opencode

或者用 npm（跨平台通用）：

npm install -g opencode-ai

2.3 桌面应用（可选）

如果你更喜欢图形界面，OpenCode 也提供了桌面应用：

• macOS（Apple 芯片）：opencode-desktop-darwin-aarch64.dmg
• macOS（Intel 芯片）：opencode-desktop-darwin-x64.dmg
• Windows：opencode-desktop-windows-x64.exe
• Linux：.deb、.rpm 或 AppImage 格式

访问 opencode.ai/download 下载对应平台的安装包。

2.4 首次启动配置

安装完成后，进入你的项目目录并启动 OpenCode：

cd /path/to/your/project
opencode

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

在 TUI 界面中，输入 /models 可以查看和切换可用模型。带有 Free 标记的就是免费模型。

如果需要连接商业模型（如 OpenAI 或 Anthropic Claude），运行：

opencode auth login

或者在 TUI 界面中输入 /connect，按照提示登录并粘贴你的 API Key。

三、基本使用与免费模型推荐

3.1 项目初始化

启动 OpenCode 后，第一步就是初始化项目。在 TUI 界面中输入：

/init

这个命令会扫描当前目录的代码结构，并生成一个 .opencode/ 文件夹用于存储项目的向量化索引和自定义指令，同时创建一个 AGENTS.md 文件来记录项目信息。让 AI 瞬间了解你的项目细节。

3.2 自然语言交互

初始化完成后，你就可以用自然语言描述需求来发起任务了：

在当前目录下创建一个登录页面

或者更具体一些：

创建一个 Express.js 服务，支持 /hello 路由返回 JSON { message: 'Hello World' }

OpenCode 会自动分析你的需求，思考实现方案，然后创建或修改相应的文件。你还可以用 @ 引用项目里的文件路径：

文件 @index.html 包含哪些功能

或者解释代码逻辑：

解释 src/main.ts 中的认证逻辑

3.3 免费模型推荐

OpenCode 内置了四个免费模型，各有特色：

GLM-4.7（强烈推荐）

智谱这个版本是专门针对 OpenCode 这种终端 Agent 训练的。它不仅代码写得好，最重要的是它"懂规矩"——知道什么时候该读文件，什么时候该运行 npm test，出错后的自愈能力（Self-healing）是这四个里最好的。

适用场景：日常开发、代码重构、Bug 修复的首选模型。而且它是国内模型，不用开梯子。

Big Pickle（推理型）

虽然名字搞怪，但它是 OpenCode 社区最近的黑马。它的"推理（Reasoning）"能力很强，当你发现 AI 总是改不对同一个 Bug 时，切到 Big Pickle 往往有奇效。

适用场景：GLM 搞不定的复杂逻辑和顽固 Bug。

Grok Code Fast 1（速度型）

它的特点就是快。如果你在快速迭代，不希望等 AI 思考太久，Grok 能给你丝滑的体验。

适用场景：快速原型开发、不希望等待太久的场景。

MiniMax M2.1（平衡型）

性能与速度的平衡选择，稳定可靠的开箱即用模型。

适用场景：通用开发任务，追求平衡性能的选择。

3.4 常用 TUI 命令速查

在 TUI 界面中，以下命令会经常用到：

核心配置与初始化

会话管理

编辑与撤销

视图与辅助

注意：/undo 和 /redo 需要项目是 Git 仓库才能回滚文件变更。

四、实战案例与总结

4.1 创建一个简单的登录页面

让我们通过一个实战案例来体验 OpenCode 的强大功能：

# 创建项目目录
mkdir opencode-demo
cd opencode-demo

# 启动 OpenCode
opencode

# 在 TUI 界面中输入
/init

等待项目初始化完成后，输入需求：

创建一个现代化的登录页面，包含用户名和密码输入框，使用原生 HTML/CSS/JavaScript 实现

OpenCode 会分析你的需求，创建相应的 HTML、CSS 和 JavaScript 文件。你可以继续与它交互，调整样式或添加功能。

4.2 修复代码 Bug

假设你的登录功能有问题，你可以这样描述：

登录按钮点击后没有反应，帮我检查问题

OpenCode 会读取相关文件，分析代码逻辑，找出问题并修复。

4.3 oh-my-opencode 扩展

如果你想体验更强大的功能，可以安装 oh-my-opencode 扩展。它将单个 AI 代理升级为一个多智能体协作团队，提供开箱即用的高级功能。

4.3.1 什么是 oh-my-opencode

oh-my-opencode 是 OpenCode 的扩展框架，它通过多智能体协作系统显著提升了 AI 编程代理的能力：

• Sisyphus 主智能体：负责任务的智能分配和子代理协调
• 专业子代理：包括 Oracle（架构咨询）、Librarian（代码库探索）、Explore（代码搜索）等
• Prometheus 规划师：为复杂任务生成详细的工作计划
• Atlas 编排器：执行规划师生成的工作计划
• 专业 Skills：git-master（Git 操作）、playwright（浏览器自动化）、frontend-ui-ux（UI/UX 设计）等

4.3.2 安装步骤

oh-my-opencode 提供了两种安装方式：

交互式安装

在终端中运行：

npx oh-my-opencode install

安装程序会引导你完成以下配置：

4.3.3 使用方法

安装完成后，oh-my-opencode 提供了两种工作模式：

模式一：Ultrawork 模式（快速自动）

这是最简单的方式，只需在提示词中包含 ultrawork 或 ulw 关键词：

# 示例1：添加认证功能
ulw add authentication to my Next.js app

# 示例2：重构代码
ulw refactor the user management module

# 示例3：修复 Bug
ulw fix the login issue

Ultrawork 模式会自动：

模式二：Prometheus 规划模式（复杂任务）

对于复杂或多步骤的任务，使用 Prometheus 模式：

# 示例工作流程
[按 Tab] → "I need to implement user authentication with OAuth"
→ Prometheus asks clarifying questions
→ Plan generated with tasks and acceptance criteria
→ /start-work executes with Atlas orchestrator

4.3.4 配置文件（可选）

oh-my-opencode 的配置文件位置：

• 全局配置：~/.config/opencode/oh-my-opencode.json
• 项目配置：.opencode/oh-my-opencode.json

示例配置：

{
"$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/master/assets/oh-my-opencode.schema.json",

// 覆盖特定代理的模型
"agents": {
"Sisyphus": {
"model": "anthropic/claude-opus-4-5",
"temperature": 0.3
},
"Prometheus (Planner)": {
"model": "anthropic/claude-sonnet-4"
},
"oracle": {
"model": "openai/gpt-5.2",
"prompt_append": "Always provide architectural diagrams in Mermaid format."
}
},

// 启用/禁用功能
"sisyphus_agent": {
"disabled": false,
"planner_enabled": true,
"replace_plan": true
},

// 禁用特定功能
"disabled_hooks": ["comment-checker", "auto-update-checker"],
"disabled_agents": ["multimodal-looker"]
}

4.3.5 专业 Skills 使用

oh-my-opencode 内置了多个专业 Skills，通过斜杠命令调用：

# Git 操作（必须使用 git-master）
/git-master commit these changes
/git-master rebase onto main
/git-master who wrote this authentication code?

# 前端 UI/UX（无设计稿时使用）
/frontend-ui-ux create a responsive dashboard layout

# 浏览器自动化
/playwright test the login flow

4.3.6 小结

oh-my-opencode 扩展的核心价值在于：

• 多智能体协作：不同专业代理各司其职，提高任务完成质量
• 智能任务分配：Sisyphus 自动将复杂任务拆解并分配给最合适的代理
• 专业领域支持：Git、UI/UX、测试等领域有专门的 Skills 处理
• 灵活配置：支持自定义模型、权限、LSP 服务器等

对于日常简单任务，使用 ulw 关键词即可；对于复杂项目，建议使用 Prometheus 模式进行详细规划后再执行。

总结

OpenCode 是一个强大的开源 AI 编程代理，它不仅提供了媲美 Claude Code 和 Cursor 的功能，更重要的是完全免费开源，隐私优先。

通过这篇文章，你应该已经掌握了：

到这一步，你应该就能稳稳复现了。赶紧安装 OpenCode，体验开源 AI 编程代理的强大功能吧！