OpenCode 完全指南：开源 Terminal AI Agent ------ 不锁定任何一个模型
Claude Code 绑定 Claude 模型，Codex 绑定 GPT 模型。如果你的公司要求私有化部署，或者你想用 DeepSeek、Gemini、通义千问等国产模型，或者你单纯不想被任何一个供应商锁定------OpenCode 是你唯一的选择。
OpenCode 的定位与设计哲学
一句话
OpenCode 是一个开源的终端 AI 编程 Agent，支持 75+ 大模型，不锁定任何供应商。
三大设计哲学
1. 模型无关（Model Agnostic）
不绑定任何一家模型厂商。
今天用 Claude，明天换 GPT，后天用 DeepSeek------同一套配置，无缝切换。
甚至可以在不同任务上自动切换不同模型。
2. 完全开源（Fully Open Source）
MIT 协议。代码在 GitHub 上，你可以 fork、修改、自部署。
没有隐藏的功能锁定，没有"Pro 版"才有的特性。
3. 可定制（Hackable）
你可以写自定义 Tool、自定义 Workflow、自定义 UI。
它更像一个"AI 编程框架"，而不是一个"AI 编程产品"。OpenCode vs Claude Code vs Codex 的架构差异
Claude Code： Codex CLI：
┌──────────────┐ ┌──────────────┐
│ Claude Code │ │ Codex CLI │
│ (闭源） │ │ （闭源） │
├──────────────┤ ├──────────────┤
│ 绑定模型： │ │ 绑定模型： │
│ Claude Opus │ │ GPT-5.5 │
│ Claude Sonnet │ │ GPT-5.3-Codex│
│ Claude Haiku │ │ codex-mini │
└──────────────┘ └──────────────┘
OpenCode：
┌──────────────────────────────────────┐
│ OpenCode Core │
│ （MIT 开源） │
├──────────────────────────────────────┤
│ 模型适配层 │
│ ┌──────┐ ┌──────┐ ┌──────┐ │
│ │Claude│ │ GPT │ │Gemini│ ... │
│ └──────┘ └──────┘ └──────┘ │
│ ┌──────┐ ┌──────┐ ┌──────┐ │
│ │Deep- │ │Qwen │ │GLM │ ... │
│ │Seek │ │ │ │ │ │
│ └──────┘ └──────┘ └──────┘ │
│ 75+ LLM 原生支持 │
└──────────────────────────────────────┘安装与配置
bash
# 安装
npm install -g @sst/opencode
# 或
brew install opencode
# 验证
opencode --version配置模型
OpenCode 的配置集中在 opencode.json 中：
json
{
"models": {
"default": "claude-sonnet-4-6",
"providers": [
{
"name": "anthropic",
"api_key": "${ANTHROPIC_API_KEY}",
"models": [
"claude-opus-4-7",
"claude-sonnet-4-6",
"claude-haiku-4-5"
]
},
{
"name": "openai",
"api_key": "${OPENAI_API_KEY}",
"models": [
"gpt-5.5",
"gpt-5.3-codex"
]
},
{
"name": "deepseek",
"base_url": "https://api.deepseek.com",
"api_key": "${DEEPSEEK_API_KEY}",
"models": [
"deepseek-v4-pro",
"deepseek-v4-flash"
]
}
]
}
}关键能力 ：一个配置文件接入所有模型。切换模型只需要改 default 字段。
不同场景的模型推荐
json
// 日常开发：Claude Sonnet（性价比最优）
{ "default": "claude-sonnet-4-6" }
// 省钱方案：DeepSeek（成本是 Claude 的 1/15）
{ "default": "deepseek-v4-pro" }
// 极致质量：Claude Opus
{ "default": "claude-opus-4-7" }
// 混合：简单任务自动用便宜模型
{
"default": "claude-sonnet-4-6",
"fallback": "deepseek-v4-flash" // 简单任务/高负载时自动降级
}TUI 交互模式
OpenCode 提供了一个精心设计的终端 UI（Terminal User Interface），比 Claude Code 和 Codex 的更直观：
┌─────────────────────────────────────────────────────┐
│ OpenCode ─ □ × │
├─────────────────────────────────────────────────────┤
│ 📁 Project: /home/user/my-app │
│ 🧠 Model: claude-sonnet-4-6 │
│ 📊 Context: 45K/200K (22%) │
├─────────────────────────────────────────────────────┤
│ │
│ 🤖 OpenCode: 你好！我在分析你的项目... │
│ │
│ > 帮我加一个暗色模式切换功能 │
│ │
│ 🤖 OpenCode: │
│ 好的。我先检查一下项目现有的主题配置... │
│ │
│ [读取 tailwind.config.js] │
│ [读取 layout.tsx] │
│ [读取 globals.css] │
│ │
│ 发现你已经配置了 Tailwind 的 darkMode: 'class'。 │
│ 我会基于现有配置添加切换功能。 │
│ │
│ ▸ 创建 components/ThemeToggle.tsx │
│ ▸ 修改 layout.tsx（包裹 ThemeProvider） │
│ ▸ 修改 globals.css（添加颜色变量） │
│ │
│ 已完成。要预览效果吗？ │
│ │
├─────────────────────────────────────────────────────┤
│ Ctrl+C 中断 | Ctrl+S 保存 | Ctrl+L 清屏 | /help │
└─────────────────────────────────────────────────────┘TUI 的核心功能区
| 区域 | 显示内容 | 作用 |
|---|---|---|
| 顶部状态栏 | 项目路径、当前模型、上下文用量 | 一眼了解当前状态 |
| 对话区 | 你和 AI 的对话，AI 的操作日志 | 完整的交互记录 |
| 操作预告 | AI 下一步会做什么 | 心理预期管理 |
| 底部快捷键 | 常用快捷键 | 新手友好 |
自定义 Tool 与配置
自定义 Tool
OpenCode 允许你给 AI 添加自定义 Tool，不需要写 MCP Server：
json
// opencode.json
{
"tools": {
"custom": [
{
"name": "run_tests",
"description": "运行项目的测试套件。传入 test_path 可指定单个测试文件。",
"command": "pytest ${test_path:-tests/} -v",
"parameters": {
"test_path": {
"type": "string",
"description": "测试文件路径（可选）",
"required": false
}
}
},
{
"name": "check_types",
"description": "运行 TypeScript 类型检查",
"command": "npx tsc --noEmit",
"parameters": {}
},
{
"name": "lint",
"description": "运行 ESLint 检查并自动修复",
"command": "npx eslint --fix ${file}",
"parameters": {
"file": {
"type": "string",
"description": "要检查的文件路径",
"required": true
}
}
}
]
}
}和 MCP Tool 的区别：
| MCP Tool | OpenCode Custom Tool | |
|---|---|---|
| 定义方式 | Python/Node 服务进程 | 配置文件中的 Shell 命令 |
| 复杂度 | 高（需要写代码） | 低（一行命令） |
| 灵活性 | 高（任意逻辑） | 中（Shell 能做的都能做） |
| 可移植性 | MCP 标准，跨工具通用 | OpenCode 专属 |
| 适合场景 | 复杂的外部系统接入 | 简单的项目脚本封装 |
建议：简单操作用 Custom Tool，复杂系统用 MCP Server。
自定义 Workflow
json
{
"workflows": {
"pre-commit": [
"check_types",
"lint --file=${changed_files}",
"run_tests"
],
"deploy": [
"run_tests",
{ "tool": "docker", "args": "build -t app ." },
{ "tool": "docker", "args": "push app:latest" }
]
}
}Workflow 把多个 Tool 串成流程。和 Claude Code 的 deploy Skill 效果类似，但实现方式不同------Skill 是用提示词引导 AI，Workflow 是硬编码执行顺序。
适合 OpenCode 的场景
场景一：预算敏感
Claude Code（按 API 付费）：
重度使用 → $200-500/月
Codex CLI（按 API 付费）：
重度使用 → $150-400/月
OpenCode + DeepSeek：
重度使用 → $15-30/月
使用量相同，成本只有 1/10-1/15
OpenCode + 本地模型（Ollama）：
重度使用 → $0/月（只有电费）
适合：预算极其敏感的学生和个人开发者场景二：私有化部署
你的公司要求"所有代码不能离开内网"。
OpenCode + 内网模型：
┌─────────────────────────────────────┐
│ 公司内网 │
│ │
│ OpenCode ←→ 内网 LLM API │
│ （如公司部署的 vLLM/LocalAI） │
│ │
│ 所有代码、对话记录 → 全在内网 │
│ 对外零数据传输 │
└─────────────────────────────────────┘
Claude Code 和 Codex 做不到这个------它们的模型只能在 Anthropic/OpenAI 的服务器上跑。场景三：多模型灵活切换
项目中有不同类型的任务：
代码编写 → Claude Sonnet（质量最高）
代码审查 → Claude Opus（推理最强）
文档生成 → Gemini 2.5 Pro（长文本擅长）
简单询问 → DeepSeek（省钱）
本地私有代码 → 本地 Ollama 模型（数据不外传）
OpenCode 一个配置文件全搞定，不用换工具。场景四：深度定制需求
你的团队想给 AI 编程工具加一个特殊功能：
"每次 AI 写完代码后，自动给团队的 Slack 频道发一条消息"
Claude Code/Codex：做不到（闭源，功能固定）
OpenCode：fork 仓库 → 加 20 行代码 → 自己的功能
开源意味着你可以改任何你不满意的地方。OpenCode 的局限
坦率地说出 OpenCode 不如 Claude Code/Codex 的地方：
1. 生态不如 Claude Code
❌ 没有官方的 Skill Marketplace
❌ 没有官方的 MCP Server 生态
❌ 没有 Plugin 系统
✅ 但 MCP 协议是通用的，社区的 MCP Server 都能用
2. 开箱体验不如两个商业产品
❌ 需要手动配置模型
❌ 需要自己搭建工作流
✅ 但配置好之后一样丝滑
3. 社区规模较小
❌ 遇到问题搜索结果更少
❌ 社区 Skill/Plugin 的数量不在一个量级
✅ 但 GitHub Issues 响应快（开源社区的特性）
4. 没有 /init 自动生成约束文件
❌ 需要自己写 AGENTS.md
✅ 但可以手动复制 Claude Code 的 CLAUDE.md 来用快速上手：5 分钟从零开始
bash
# 1. 安装
npm install -g @sst/opencode
# 2. 创建配置
cat > opencode.json << 'EOF'
{
"models": {
"default": "claude-sonnet-4-6",
"providers": [
{
"name": "anthropic",
"api_key": "${ANTHROPIC_API_KEY}",
"models": ["claude-sonnet-4-6", "claude-haiku-4-5"]
}
]
},
"tools": {
"custom": [
{
"name": "run_tests",
"description": "运行测试",
"command": "npm test",
"parameters": {}
}
]
}
}
EOF
# 3. 创建 AGENTS.md（复用 Claude Code 的）
cp CLAUDE.md AGENTS.md
# 4. 启动
opencode
# 5. 试试第一个任务
> 帮我看看这个项目的结构，列出所有 API 路由