OpenCode：你的开源 AI 编程助手完全指南

开源、免费、强大 - 这可能是目前最值得尝试的 AI 编程助手

一、OpenCode 是什么？

OpenCode 是一个开源的 AI 编程助手，它可以帮助你在终端、IDE 或桌面应用中编写代码。目前已经在 GitHub 上获得了 50,000+ 星标，拥有 500+ 贡献者，每月有超过 65万 开发者在使用。

核心特性

🚀 开箱即用 - 内置免费模型或连接任何提供商的模型（Claude、GPT、Gemini 等）

💻 多平台支持 - 可在终端界面、桌面应用或 IDE 扩展中使用

🔀 LSP 支持 - 自动为 LLM 加载合适的语言服务器

👥 多会话协作 - 可以在同一项目上并行启动多个代理

🔗 分享功能 - 分享会话链接供参考或调试

🔒 隐私优先 - 不存储任何代码或上下文数据

二、快速开始

1. 安装 OpenCode

OpenCode 提供了多种安装方式，选择最适合你的：

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

bash 复制代码

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

📦 方式二：使用包管理器

Node.js 用户：

bash 复制代码

# npm
npm install -g opencode-ai

# pnpm
pnpm install -g opencode-ai

# Bun
bun install -g opencode-ai

# Yarn
yarn global add opencode-ai

macOS/Linux - Homebrew：

bash 复制代码

brew install anomalyco/tap/opencode

Windows - Chocolatey：

bash 复制代码

choco install opencode

Windows - Scoop：

bash 复制代码

scoop bucket add extras
scoop install extras/opencode

Arch Linux - Paru：

bash 复制代码

paru -S opencode-bin

2. 配置 AI 模型提供商

首次使用需要配置一个 AI 模型提供商。如果你是新手，推荐使用 OpenCode Zen（OpenCode 团队测试和验证的精选模型列表）：

运行 /connect 命令
选择 opencode 提供商
访问 opencode.ai/auth 进行登录
添加付款信息并复制 API Key
粘贴 API Key 完成

或者选择其他提供商如 Anthropic Claude、OpenAI 等：

bash 复制代码

/connect

3. 初始化项目

进入你的项目目录并运行 OpenCode：

bash 复制代码

cd /path/to/your/project
opencode

然后初始化 OpenCode：

bash 复制代码

/init

这将分析你的项目并创建 AGENTS.md 文件，帮助 OpenCode 理解项目结构和编码模式。

💡 提示：建议将 AGENTS.md 提交到 Git，这样 OpenCode 能更好地理解你的项目。

三、使用 OpenCode - 基础篇

🎯 终端界面（TUI）基础操作

运行 OpenCode 后，你会看到一个交互式终端界面。以下是常用操作：

1. 提问和请求

你可以直接向 OpenCode 提问：

复制代码

给我一个这个代码库的快速总结

2. 引用文件（@ 符号）

使用 @ 符号可以模糊搜索并引用文件：

bash 复制代码

@packages/functions/src/api/index.ts 中的身份验证是如何处理的？

文件内容会自动添加到对话中。

3. 运行 Bash 命令（! 符号）

在消息开头使用 ! 运行 shell 命令：

bash 复制代码

!ls -la

命令输出会作为工具结果添加到对话中。

⌨️ 常用命令（Slash Commands）

命令	功能	快捷键
`/help`	显示帮助对话框	`Ctrl+x h`
`/init`	创建/更新 AGENTS.md	`Ctrl+x i`
`/undo`	撤销上次操作	`Ctrl+x u`
`/redo`	重做操作	`Ctrl+x r`
`/new`	开始新会话	`Ctrl+x n`
`/share`	分享当前会话	`Ctrl+x s`
`/themes`	列出可用主题	`Ctrl+x t`
`/models`	列出可用模型	`Ctrl+x m`
`/sessions`	列出和切换会话	`Ctrl+x l`
`/exit`	退出 OpenCode	`Ctrl+x q`

四、使用 OpenCode - 进阶篇

📋 计划模式 vs 构建模式

OpenCode 有两种工作模式，通过 Tab 键切换：

🎨 计划模式（Plan Mode）

在计划模式下，OpenCode 会建议如何实现功能，但不会实际修改代码。适合复杂功能的规划。

切换到计划模式：

xml 复制代码

<Tab>

示例：

复制代码

当用户删除笔记时，我们希望在数据库中将其标记为已删除。
然后创建一个屏幕显示所有最近删除的笔记。
从这个屏幕，用户可以恢复笔记或永久删除它。

🔨 构建模式（Build Mode）

这是默认模式，OpenCode 会实际执行代码修改。

切换回构建模式：

xml 复制代码

<Tab>

执行计划：

复制代码

听起来不错！开始执行更改吧。

🔄 撤销和重做

如果你对 OpenCode 做的修改不满意：

撤销：

bash 复制代码

/undo

重做：

bash 复制代码

/redo

⚠️ 注意：撤销/重做功能依赖于 Git，所以你的项目需要是 Git 仓库。

📤 分享会话

与团队成员分享对话：

bash 复制代码

/share

这会创建一个链接并复制到剪贴板。例如： opencode.ai/s/4XP1fce5

📌 隐私提示 ：会话默认不共享，只有你主动调用 /share 才会创建共享链接。

五、在 IDE 中使用

OpenCode 支持在 VS Code、Cursor 等 IDE 中使用：

安装 IDE 扩展

在 VS Code 的集成终端中运行 opencode，扩展会自动安装。

或者手动安装：在扩展市场搜索 "OpenCode" 并安装。

IDE 快捷键

快捷键	功能
`Cmd+Esc` (Mac) / `Ctrl+Esc` (Win/Linux)	打开/聚焦 OpenCode
`Cmd+Shift+Esc` (Mac) / `Ctrl+Shift+Esc` (Win/Linux)	启动新会话
`Cmd+Option+K` (Mac) / `Alt+Ctrl+K` (Win/Linux)	插入文件引用

上下文感知

自动共享当前选中的内容或标签页
支持拖拽图片到终端
支持多会话并行工作

六、命令行高级用法

除了交互式 TUI，OpenCode 还提供了强大的命令行工具：

🔍 列出可用模型

bash 复制代码

# 列出所有提供商的模型
opencode models

# 列出特定提供商的模型
opencode models anthropic

# 刷新模型缓存
opencode models --refresh

⚡ 快速执行命令

bash 复制代码

# 不启动 TUI，直接执行命令
opencode run "解释 JavaScript 中的闭包"

# 使用特定模型
opencode run -m anthropic/claude-3-opus "解释 Go 的上下文"

# 附加文件
opencode run -f src/main.js "优化这个文件"

📊 查看统计信息

bash 复制代码

# 查看所有统计信息
opencode stats

# 查看最近 7 天的统计
opencode stats --days 7

# 按项目筛选
opencode stats --project my-project

🔄 会话管理

bash 复制代码

# 列出所有会话
opencode session list

# 导出会话
opencode export <sessionID>

# 导入会话
opencode import session.json
# 或从 URL 导入
opencode import https://opencode.ai/s/abc123

🌐 启动 Web 服务

bash 复制代码

# 启动 Web 界面
opencode web

# 指定端口和主机
opencode web --port 4096 --hostname 0.0.0.0

📡 启动后端服务

bash 复制代码

# 启动无头服务器
opencode serve

# 连接到远程服务器
opencode attach http://10.20.30.40:4096

七、配置和定制

📁 配置文件

OpenCode 的配置文件位于：

配置文件 ：~/.config/opencode/opencode.json
数据目录 ：~/.local/share/opencode/

🎨 主题定制

在 TUI 中切换主题：

bash 复制代码

/themes

⌨️ 自定义快捷键

默认快捷键前缀是 Ctrl+x。你可以在配置文件中自定义。

📝 配置代码格式化器

OpenCode 支持多种代码格式化器，确保自动修改的代码符合你的项目风格。

🔧 自定义工具和规则

通过配置文件可以：

添加自定义工具
设置项目规则
配置代理行为
设置 LSP 服务器

八、实用技巧

💡 1. 给 OpenCode 足够的上下文

像和初级开发者对话一样，提供详细的说明和示例：

bash 复制代码

我们需要给 /settings 路由添加身份验证。
参考 @packages/functions/src/notes.ts 中 /notes 路由的实现方式，
在 @packages/functions/src/settings.ts 中实现相同的逻辑。

💡 2. 使用图片辅助

拖拽设计图到终端，让 OpenCode 参考设计实现功能：

css 复制代码

查看这张图片并参考它来设计新屏幕：
[图片]

使用相同的设计风格实现用户资料页面。

💡 3. 先计划后执行

对于复杂功能，先切换到计划模式，让 OpenCode 提供实现方案：

bash 复制代码

<Tab>  # 切换到计划模式
设计一个支持分页、搜索和过滤的用户管理系统...

确认方案后再切换到构建模式执行：

bash 复制代码

<Tab>  # 切换到构建模式
开始实现！

💡 4. 设置外部编辑器

配置 EDITOR 环境变量，以便在 /editor 和 /export 命令中使用你喜欢的编辑器：

macOS/Linux (zsh):

bash 复制代码

# ~/.zshrc
export EDITOR="code --wait"  # VS Code
# export EDITOR="nvim"       # Neovim

Windows (PowerShell):

powershell 复制代码

# PowerShell Profile
$env:EDITOR = "code --wait"

💡 5. 多会话并行

同时启动多个 OpenCode 会话，处理不同的任务：

bash 复制代码

# 终端 1
opencode

bash 复制代码

# 终端 2
opencode

使用 /sessions 命令在不同会话间切换。

九、常见问题

❓ OpenCode 是免费的吗？

是的，OpenCode 本身是免费开源的。但你需要为使用的 AI 模型付费。OpenCode Zen 提供了经过优化的模型选择，你也可以使用任何其他提供商。

❓ 可以使用我已有的 AI 订阅吗？

可以！OpenCode 支持连接 75+ LLM 提供商，包括：

Anthropic Claude（包括 Claude Pro/Max）
OpenAI GPT 系列
Google Gemini
以及更多本地和云端模型

❓ 数据会存储在 OpenCode 服务器吗？

不会。OpenCode 不存储任何代码或上下文数据，确保在敏感环境中使用时的隐私安全。

❓ 支持哪些编辑器？

终端界面（TUI）
桌面应用（Beta）
VS Code、Cursor、Windsurf、VSCodium 等 IDE
任何支持终端的编辑器

十、资源链接

🌐 官网：opencode.ai

📚 文档：opencode.ai/docs

🐙 GitHub ：github.com/anomalyco/o...

💬 Discord 社区 ：opencode.ai/discord

🔧 模型目录 ：models.dev

结语

OpenCode 是一个功能强大、灵活的开源 AI 编程助手。无论你是想加速开发、学习代码库，还是自动化重复任务，OpenCode 都能提供帮助。

最重要的是，它尊重你的隐私，不存储你的代码，同时支持几乎所有主流的 AI 模型和开发环境。

现在就开始尝试吧：

bash 复制代码

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

🎉 Happy Coding with OpenCode!

本文信息基于 OpenCode 官方文档，如有更新请以官方文档为准。