OpenCode 保姆级安装使用教程 | 开源免费AI编程终端助手

📌 01 · 工具概览

什么是 OpenCode？

OpenCode 是一款完全开源的 AI 编程 Agent，提供终端TUI界面、桌面应用和IDE扩展。它让你摆脱付费订阅，自由选择AI模型，代码始终留在本地。

🔓

完全开源

MIT许可，源码完全公开，社区驱动，可审计、可定制、可贡献

🆓

永久免费

工具本身零费用，只需配置自己的API Key即可使用

🔄

多模型支持

OpenAI/Anthropic/本地模型等，自由切换，不被绑定

🖥️

TUI终端界面

精美的终端用户界面，无需离开终端即可交互

🔒

隐私优先

代码留在本地，可选择本地模型，数据不出本机

🧩

高度可定制

自定义规则、Agent技能、MCP工具、主题，按需配置

三种使用方式

方式一：终端TUI

在终端中运行交互式界面，最原汁原味的体验

opencode

方式二：桌面应用

原生桌面窗口，支持拖放文件、多会话管理

opencode-desktop

方式三：IDE扩展

集成到VS Code等编辑器中，不离开IDE

插件市场搜索 OpenCode

方式四：Web界面

浏览器访问，跨设备使用

opencode web

🖥️ 03 · 设备选型

设备与环境要求

OpenCode 对硬件要求极低，几乎所有现代电脑都能运行。

操作系统

macOS / Linux / Windows(WSL)

Windows推荐WSL2获得最佳体验

终端模拟器

WezTerm / Alacritty / Ghostty / Kitty

推荐现代终端以获得最佳TUI渲染

内存

4GB+ 即可

本地客户端轻量，AI计算在云端

API Key

任一LLM提供商的API Key

或使用OpenCode Zen内置免费模型

💡 推荐终端模拟器

TUI 界面需要现代终端模拟器支持。推荐 WezTerm（跨平台功能丰富）或 Ghostty（macOS/Linux，速度极快）。macOS 自带 Terminal.app 对 TUI 支持有限，不推荐。

📥 04 · 安装教程

全平台安装保姆级教程

多种安装方式，选择最适合你的。

方法一：一键安装脚本（推荐）

                    Bash
                    # macOS / Linux 一键安装
curl -fsSL https://opencode.ai/install | bash

# 安装脚本会自动：
# 1. 检测系统环境
# 2. 下载最新版本二进制文件
# 3. 安装到 ~/.local/bin/
# 4. 添加到 PATH
                

方法二：包管理器安装

Homebrew (macOS/Linux)

brew install anomalyco/tap/opencode

npm (全平台)

npm install -g opencode-ai

Bun (全平台)

bun install -g opencode-ai

pnpm (全平台)

pnpm install -g opencode-ai

Chocolatey (Windows)

choco install opencode

Scoop (Windows)

scoop install opencode

Arch Linux (AUR)

sudo pacman -S opencode

Mise

mise use -g github:anomalyco/opencode

方法三：Docker 运行

                    Bash
                    # Docker 方式运行（无需安装）
docker run -it --rm ghcr.io/anomalyco/opencode
                

桌面应用安装

                    Guide
                    # macOS (Homebrew)
brew install --cask opencode-desktop

# Windows (Scoop)
scoop bucket add extras
scoop install extras/opencode-desktop

# 或从 GitHub Releases 下载安装包
https://github.com/anomalyco/opencode/releases
                

配置AI提供商

安装后需要配置AI模型才能使用：

                    Guide
                    # 方式一：使用 OpenCode Zen（最简单，推荐新手）
1. 在TUI中运行 /connect 命令
2. 选择 opencode
3. 前往 opencode.ai/auth 注册并获取API Key
4. 粘贴API Key

# 方式二：配置其他提供商
# 在TUI中选择 /connect 后可选择：
- Anthropic (Claude)
- OpenAI (GPT)
- Google (Gemini)
- Groq
- Ollama (本地模型)
- OpenRouter (多模型网关)
- 其他兼容提供商
                

初始化项目

                    Bash
                    # 进入项目目录
cd /path/to/your/project

# 启动 OpenCode
opencode

# 初始化项目（AI会分析项目并创建 AGENTS.md）
/init

# 💡 建议将 AGENTS.md 提交到 Git
# 帮助 OpenCode 理解项目结构和规范
                

🌿

OpenCode TUI 界面 - 终端中的精美交互

🎯 05 · 使用指南

核心功能使用指南

TUI 交互界面

                    TUI
                    # OpenCode TUI 常用操作

# 在项目中启动
opencode

# TUI 内命令
/init       # 初始化项目，创建 AGENTS.md
/connect    # 配置AI提供商
/help       # 查看帮助
/compact    # 压缩上下文，节省Token
/undo       # 撤销上一次修改
/share      # 分享对话

# 直接用自然语言描述需求
👤 帮我在这个项目中添加用户登录功能
👤 找到并修复 src/auth.js 中的Bug
👤 将这个函数的性能优化一下
                

CLI 命令行模式

                    Bash
                    # 单次命令执行
opencode -p "解释这个项目的架构"

# 指定模型
opencode -p "修复Bug" --model claude-sonnet-4

# 非交互模式（适合脚本/CI）
opencode -p "运行测试" --no-interactive

# Web 服务模式
opencode web       # 启动Web界面
opencode serve     # 启动API服务
                

AGENTS.md 项目配置

通过 AGENTS.md 文件定义项目规范，让AI理解你的项目：

                    Markdown
                    # AGENTS.md 示例

## 项目
Next.js 14 + TypeScript + Tailwind CSS 电商网站

## 技术栈
- Framework: Next.js 14 (App Router)
- UI: Tailwind CSS + shadcn/ui
- Database: PostgreSQL + Prisma
- Auth: NextAuth.js

## 规范
- 所有组件使用 TypeScript
- 服务端组件优先，仅在必要时使用 'use client'
- API路由放在 app/api/ 目录下
- 使用 Zod 做输入验证

## 常用命令
- npm run dev - 开发服务器
- npm run build - 构建
- npx prisma studio - 数据库管理
                

自定义规则

                    Config
                    # OpenCode 规则配置
# 在 .opencode/rules/ 目录下创建规则文件

规则示例：
- 强制使用 TypeScript strict 模式
- 所有API端点必须有错误处理
- 禁止使用 any 类型
- CSS使用 Tailwind 工具类而非自定义样式
- 测试覆盖率不低于80%
                

撤销操作

OpenCode 支持 undo 功能，如果AI的修改不满意，可以一键撤销：

                    Bash
                    # 撤销上一次修改
/undo

# 撤销会恢复所有被修改的文件到之前的状态
# 这是OpenCode的安全网功能
                

🛠️ 06 · 实战案例

实战案例详解

案例1：在新项目中快速添加功能

                    Workflow
                    # 进入项目
cd my-nextjs-app
opencode

# 初始化项目
/init

# 添加功能
👤 在首页添加一个搜索组件，支持实时搜索商品，
     使用debounce优化性能，样式用Tailwind CSS

# OpenCode 会：
✓ 分析现有项目结构
✓ 创建搜索组件文件
✓ 集成到首页布局
✓ 添加debounce逻辑
✓ 应用Tailwind样式

# 如果不满意，一键撤销
/undo
                

案例2：使用本地模型保护隐私

                    Guide
                    # 步骤1：安装 Ollama
curl -fsSL https://ollama.ai/install.sh | sh
ollama pull codellama

# 步骤2：在 OpenCode 中配置 Ollama
/connect → 选择 Ollama → 确认地址 http://localhost:11434

# 步骤3：开始使用
# 所有代码和数据都不会离开本机！
# 特别适合处理敏感代码的项目
                

案例3：Windows WSL 环境配置

                    Bash
                    # 步骤1：安装 WSL
# 按微软官方指南安装 WSL2

# 步骤2：在 WSL 中安装 OpenCode
curl -fsSL https://opencode.ai/install | bash

# 步骤3：访问 Windows 文件
cd /mnt/c/Users/YourName/project
opencode

# 💡 或使用桌面应用连接WSL服务器
opencode serve --hostname 0.0.0.0 --port 4096
# 然后在桌面应用中连接 http://localhost:4096
                

⚖️ 07 · 对比分析

OpenCode vs Claude Code

两者定位不同，选择适合你的。

特性	OpenCode	Claude Code
开源	✅ 完全开源 MIT	❌ 闭源
价格	🆓 工具免费（需API Key）	💰 $20-200/月订阅
模型支持	✅ 多提供商自由切换	❌ 仅 Anthropic 模型
本地部署	✅ 支持（可完全本地）	❌ 不支持
隐私	✅ 代码可留在本地	⚠️ 代码上传到服务器
定制化	✅ 高度可定制	❌ 有限定制
推理质量	取决于选择的模型	✅ 顶级 Claude 模型
生态集成	🟡 发展中	✅ 成熟（VS Code/JetBrains/Web）
社区	✅ 活跃开源社区	❌ 闭源无社区

💡 选择建议

选 OpenCode：预算有限、注重隐私、喜欢开源、需要多模型切换。 选 Claude Code：追求最佳AI推理质量、需要成熟生态集成、团队协作场景、预算充足。

❓ 08 · 常见问题

常见问题与技巧

Q：OpenCode 真的完全免费吗？

工具本身完全免费开源（MIT许可）。但你需要提供AI模型的API Key，API费用由你选择的提供商收取。如果你使用 Ollama 本地模型，则完全零费用。

Q：OpenCode Zen 是什么？

OpenCode Zen 是官方提供的免费模型服务，经过OpenCode团队验证和优化。通过 /connect 命令选择 opencode 即可使用，是最简单的入门方式。

Q：TUI界面显示异常怎么办？

确保使用现代终端模拟器（推荐 WezTerm、Ghostty、Kitty 或 Alacritty）。macOS 自带 Terminal.app 和 Windows CMD 对 TUI 支持有限，可能出现渲染问题。

Q：如何从 Claude Code 迁移到 OpenCode？

将 CLAUDE.md 的内容迁移到 AGENTS.md 即可。语法类似，OpenCode 的 /init 命令也会帮你自动生成。API Key需要重新配置。

Q：Windows 上无法安装？

推荐使用 WSL2 安装运行。如果要在原生 Windows 使用，可通过 npm 安装：npm install -g opencode-ai，或使用 Chocolatey/Scoop 包管理器。

Q：如何更新 OpenCode？

根据安装方式选择：brew upgrade opencode、npm update -g opencode-ai 或重新运行安装脚本。桌面应用支持自动更新。

OpenCode
保姆级安装使用教程

📑 教程目录