OpenCode + OpenCode Zen 安装配置指南：Claude Code 的开源替代方案

字数：约3500字 | 阅读时间：10分钟
“不绑定任何一家模型厂商，才是程序员该有的自由。”

---

为什么选 OpenCode？

2026年初，Claude Code 源码泄露事件引爆了整个 AI 编程工具圈。一时间，各种复刻方案层出不穷。但在众多替代品中，OpenCode 是目前最成熟、社区最活跃的开源方案。

几个核心优势：

不锁定模型厂商。 Claude Code 只能用 Anthropic 的 Claude，而 OpenCode 支持 75+ 模型——OpenAI、Google Gemini、智谱 GLM、通义千问、Ollama 本地模型，随便切换。这意味着你可以根据任务类型选最合适的模型，而不是被一家厂商绑架。

完全开源，可审计。 代码托管在 GitHub（anomalyco/opencode），145K+ stars。你的代码和上下文数据不会被发送到第三方服务器存储，对隐私敏感的企业环境很友好。

TUI 界面体验好。 OpenCode 提供终端 TUI 界面，也支持桌面客户端和 IDE 插件。日常在终端里直接用，交互体验不输 Claude Code。

免费使用。 OpenCode 本身免费，你只需要付模型 API 的费用。相比 Claude Code 的订阅制，成本更可控。

一句话总结：如果你在国内开发、需要灵活切换模型、或者不想被 Anthropic 绑定，OpenCode 是目前最好的选择。

安装

前置条件

不管用哪种安装方式，你需要：

• 操作系统：macOS、Linux、Windows（推荐 WSL）
• 终端：支持真彩色和 Unicode 的现代终端（iTerm2、WezTerm、Alacritty、Ghostty、Kitty 都行，macOS 自带的 Terminal.app 渲染效果一般）
• API Key：至少一个 LLM 提供商的 Key（后面细说）

方式一：安装脚本（最快）

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

一行搞定，自动检测系统架构，下载对应二进制文件。macOS 和 Linux 通用。

验证安装：

opencode --version

方式二：npm 安装

如果你已经装了 Node.js 18+：

npm install -g opencode-ai@latest

注意包名是 opencode-ai，不是 opencode。这是很多人踩的坑。

国内网络加速：

npm install -g opencode-ai@latest --registry https://registry.npmmirror.com

遇到权限问题可以用 npx 免安装运行：

npx opencode-ai@latest

方式三：Homebrew

macOS 和 Linux 用户：

brew install anomalyco/tap/opencode

后续升级直接 brew upgrade。

方式四：其他方式

Go 安装（需要 Go 1.22+）：

go install github.com/opencode-ai/opencode@latest
export PATH="$PATH:$(go env GOPATH)/bin"

Docker（适合 CI/CD 或隔离环境）：

docker pull ghcr.io/opencode-ai/opencode:latest

docker run -it --rm \
  -v "$(pwd)":/workspace \
  -w /workspace \
  -e OPENAI_API_KEY="$OPENAI_API_KEY" \
  ghcr.io/opencode-ai/opencode:latest

Windows：支持 Scoop（scoop install opencode）和 Chocolatey（choco install opencode）。

Arch Linux：sudo pacman -S opencode 或从 AUR 安装。

首次启动与初始化

安装完成后，进入你的项目目录：

cd /path/to/your/project
opencode

首次启动会打开 TUI 界面，提示你连接 AI 提供商。

/connect 命令

在 TUI 里输入 /connect，交互式选择提供商并输入 API Key。凭证存储在 ~/.local/share/opencode/auth.json。

/init 命令

连接好提供商后，运行 /init。OpenCode 会分析你的项目结构，在项目根目录生成一个 AGENTS.md 文件，包含项目的上下文信息。这能让 AI 从一开始就理解你的代码库，给出更准确的响应。

/init

生成的 AGENTS.md 大致长这样：

# Project: my-spring-boot-app

## Tech Stack
- Java 21, Spring Boot 3.4, Maven
- PostgreSQL, Redis

## Project Structure
src/main/java/com/example/
├── controller/   # REST API endpoints
├── service/      # Business logic
├── repository/   # Data access layer
└── config/       # Configuration classes

## Conventions
- Use @Service annotation for service classes
- Follow package-by-feature structure
- Tests in src/test with same package path

你可以手动编辑这个文件，补充更多项目特定的上下文。

配置 AI 提供商

OpenCode 的核心优势是 provider-agnostic。下面是几个常用提供商的配置方法。

OpenAI（GPT-5.4、GPT-4.1、o3）

export OPENAI_API_KEY="sk-your-key-here"

写到 ~/.zshrc 或 ~/.bashrc 里持久化。

国内用户可以通过 API 中转使用 OpenAI：

export OPENAI_API_KEY="your-proxy-key"
export OPENAI_BASE_URL="https://your-proxy-domain.com/v1"

Google Gemini（Gemini 2.5 Pro、Gemini 2.5 Flash）

export GOOGLE_API_KEY="your-google-api-key"

API Key 从 Google AI Studio 免费获取，Gemini 模型有免费额度，适合轻量使用。

智谱 GLM（国内推荐）

export ZHIPUAI_API_KEY="your-zhipuai-key"

智谱的 GLM-5 系列模型对中文理解好，且国内直连无延迟，是 Claude Code 在国内最实用的替代方案之一。

Ollama（本地模型，免费且私密）

如果你想完全离线运行，Ollama 是最佳选择：

# 安装 Ollama
curl -fsSL https://ollama.com/install.sh | sh

# 拉取一个编程模型
ollama pull qwen2.5-coder:32b

# OpenCode 自动检测 localhost:11434，无需配置

Ollama 不需要 API Key，OpenCode 会自动检测本地运行的 Ollama 实例。

推荐模型：qwen2.5-coder:32b（代码能力强）、deepseek-coder-v2:236b（大参数，推理强）。

Anthropic Claude（受限）

注意：2026 年 1 月起，Anthropic 限制了第三方工具（包括 OpenCode）对 Claude 模型的访问。如果你的 API Key 还能用：

export ANTHROPIC_API_KEY="sk-ant-your-key-here"

但大多数 2026 年用户已经转向 OpenAI 或 Gemini 作为 OpenCode 的主力模型。

OpenCode Zen：省心的模型服务

如果你不想折腾多个 API Key，OpenCode 官方提供了一个托管服务——OpenCode Zen。

Zen 是 OpenCode 团队精选和测试过的模型集合，针对编码任务做了优化。使用方式：

1. 在 TUI 里运行 /connect
2. 选择 opencode 作为提供商
3. 访问 opencode.ai/auth 注册并获取 API Key
4. 粘贴 Key

优点：

• 一个 Key 访问多个优化过的模型
• 不需要分别注册 OpenAI、Google 等账户
• 模型经过 OpenCode 团队基准测试，针对编程场景优化
• 按用量付费，有免费额度

适合不想花时间管理多个 API 提供商的开发者。

配置文件详解

OpenCode 的配置文件位于 ~/.config/opencode/config.toml（全局）或项目根目录的 opencode.json（项目级）。

一个实用的全局配置示例：

# ~/.config/opencode/config.toml

# 自动保存对话
auto_save = true

# 默认模型
[provider.openai]
apiKey = "{env:OPENAI_API_KEY}"

[provider.openai.models.gpt]
id = "gpt-5.4"

# 备用模型
[provider.google]
apiKey = "{env:GOOGLE_API_KEY}"

[provider.google.models.gemini]
id = "gemini-2.5-pro"

# 禁用不用的提供商（减少启动检测时间）
# disabled_providers = ["anthropic"]

# MCP 服务器配置
[mcp.filesystem]
command = "npx"
args = ["-y", "@anthropic-ai/mcp-filesystem", "/path/to/project"]

几个实用配置项：

• **auto_save**：自动保存会话，下次打开可以继续
• **{env:VAR_NAME}**：从环境变量读取，避免明文写 Key
• **disabled_providers**：禁用不用的提供商，加快启动速度
• **mcp**：配置 MCP 扩展服务器，扩展 OpenCode 能力

项目级配置 opencode.json 可以覆盖全局配置，适合不同项目用不同模型。

日常使用

基本操作

在 TUI 界面里，直接输入你想做的事情：

> 解释一下 @src/main/java/com/example/UserService.java 的认证逻辑

用 @ 引用文件，让 AI 精确定位代码。

Plan 模式 vs Build 模式

按 Tab 键切换模式：

• Plan 模式：AI 只分析不修改，生成实施方案。适合复杂任务，先看方案再动手。
• Build 模式：AI 直接修改代码。适合明确的小改动。

建议流程：先 Plan 看方案，确认无误后切 Build 执行。

撤销和重做

改错了？用内置命令：

/undo   # 撤销上一次修改
/redo   # 重做

比 Git 回退更轻量，适合快速试错。

分享对话

/share

生成一个分享链接，方便和团队成员协作。OpenCode 会创建一个公开链接并复制到剪贴板。

国内开发者实用建议

推荐模型组合

场景	推荐模型	理由
日常编码	智谱 GLM-5 / DeepSeek Coder	国内直连，中文理解好
复杂架构设计	GPT-5.4 / Gemini 2.5 Pro	推理能力强
离线/私密环境	Ollama + qwen2.5-coder:32b	完全本地，无网络依赖
省心方案	OpenCode Zen	一个 Key 搞定，按用量付费

网络优化

如果直连 OpenAI/Google 有困难：

1. API 中转：使用国内中转服务，设置 OPENAI_BASE_URL 环境变量
2. Ollama 本地：完全绕过网络问题
3. 智谱/通义：国内厂商 API，直连无延迟

常见问题

Q：OpenCode 和 Claude Code 能力差多少？

实际体验差距不大。Claude Code 绑定 Claude 模型（确实很强），但 OpenCode 用 GPT-5.4 或 Gemini 2.5 Pro 也能达到类似效果。而且在模型选择灵活性上，OpenCode 完胜。

Q：OpenCode 支持多文件重构吗？

支持。通过 AGENTS.md 和 @ 文件引用，OpenCode 能理解整个项目上下文，执行跨文件修改。

Q：怎么配置 MCP 扩展？

在 config.toml 的 [mcp] 段配置。比如接入文件系统：

[mcp.filesystem]
command = "npx"
args = ["-y", "@anthropic-ai/mcp-filesystem", "/your/project/path"]

Q：Windows 上能用吗？

推荐 WSL。原生 Windows 支持通过 Scoop/Chocolatey/npm 安装，但 TUI 渲染效果可能不如 WSL。

总结

OpenCode 给了开发者一个不依赖任何单一厂商的选择。安装简单、配置灵活、模型自由切换，加上 OpenCode Zen 的托管服务，基本上覆盖了从免费本地到企业级的所有场景。

如果你正在用 Claude Code，不妨试试 OpenCode——不花钱，五分钟装好，体验一下不被绑定的感觉。

如果体验之后觉得 OpenCode 更适合你的工作流，那恭喜你，找到了一个长期可用的 AI 编程搭档。

---

本文基于 2026 年 4 月 OpenCode 最新版本编写。项目地址：https://github.com/anomalyco/opencode