OpenCode 完全指南：120k Stars 的开源终端 AI 编程代理

OpenCode 是最受欢迎的开源 AI 编程代理，GitHub 120k+ stars，MIT 协议。Go 编写的单二进制文件，支持 75+ 模型 provider，终端 TUI 交互。本文覆盖安装配置、日常使用、高级技巧和真实案例。

什么是 OpenCode

OpenCode 是一个开源的终端 AI 编程代理，用 Go 编写，提供漂亮的 TUI 界面。它是 2026 年 GitHub 上 star 数最高的 AI 编程工具（120k+），900+ 贡献者。

⚠️ 注意：OpenCode 原始仓库（opencode-ai/opencode）已归档，项目以 “Crush” 的名义由原作者在 Charm 团队继续开发。但 OpenCode 的 fork 和社区版本仍然活跃。

核心特性：

• 开源（MIT），Go 单二进制，跨平台
• 精美的 TUI 界面（基于 Bubble Tea 框架）
• 75+ AI 模型 provider 支持
• Session 管理：保存和切换多个对话
• 工具集成：执行命令、搜索文件、修改代码
• Vim 风格编辑器
• LSP 集成：语言服务器支持
• MCP 支持：外部工具接入
• 自定义命令系统
• 自动上下文压缩

和竞品对比：

简单说：OpenCode 最轻量、最易上手、社区最大。适合想要一个简洁好用的终端 AI 助手的开发者。

安装

各平台安装命令

# Linux / macOS（推荐，一键安装）
curl -fsSL https://opencode.ai/install | bash

# 指定版本
curl -fsSL https://opencode.ai/install | VERSION=0.1.0 bash

# Homebrew (macOS/Linux)
brew install opencode-ai/tap/opencode

# Arch Linux (AUR)
yay -S opencode-ai-bin

# Go
go install github.com/opencode-ai/opencode@latest

验证安装：

opencode --version

配置 API 接入

OpenCode 的配置文件位置（按优先级）：

• ~/.opencode.json（全局）
• $XDG_CONFIG_HOME/opencode/.opencode.json
• ./.opencode.json（项目级）

配置七牛云中转示例：

{
  "providers": {
    "openai": {
      "apiKey": "sk-your-qiniu-api-key",
      "disabled": false
    }
  },
  "agents": {
    "coder": {
      "model": "openai.gpt-5.5",
      "maxTokens": 128000
    },
    "task": {
      "model": "openai.gpt-5.4-mini",
      "maxTokens": 64000
    },
    "title": {
      "model": "openai.gpt-5.4-mini",
      "maxTokens": 80
    }
  },
  "autoCompact": true
}

获取 API Key：

1. 打开 https://s.qiniu.com/2uMRza 注册七牛云账号
2. 完成实名认证
3. 进入费用中心，充值 100 元（开启每分钟 5 次请求额度）
4. 进入 API Key 管理页面：https://portal.qiniu.com/ai-inference/api-key
5. 点击「创建」，名称填 “opencode”
6. 复制 sk- 开头的 Key，粘贴到配置文件的 apiKey 字段

使用自托管/中转端点时，设置环境变量：

export OPENAI_API_KEY="sk-your-qiniu-api-key"
export LOCAL_ENDPOINT="https://api.qnaigc.com/v1"

或在配置中指定 self-hosted model：

{
  "agents": {
    "coder": {
      "model": "local.gpt-5.5",
      "reasoningEffort": "high"
    }
  }
}

验证配置：

opencode -p "你好，你是什么模型？"

日常使用

启动

# 交互模式（TUI）
cd my-project
opencode

# 单次命令（非交互）
opencode -p "解释这个项目的架构"

# 指定工作目录
opencode -c /path/to/project

# 调试模式
opencode -d

# JSON 格式输出（适合脚本）
opencode -p "列出所有 TODO" -f json

# 安静模式（无 spinner，适合管道）
opencode -p "分析代码" -q

核心快捷键

权限对话框

当 AI 要执行可能危险的操作时会弹出权限请求：

单次命令示例

# 理解代码
opencode -p "解释 src/auth/ 目录的认证流程"

# 写代码
opencode -p "实现一个 JWT 中间件，支持 refresh token"

# 修 Bug
opencode -p "运行测试，找到失败原因并修复"

# 重构
opencode -p "把 src/legacy/ 的 callback 风格改成 async/await"

# 文档
opencode -p "给 src/api/ 下所有导出函数加 JSDoc"

# 搜索代码
opencode -p "找到所有使用 deprecated API 的地方"

工具体系

文件和代码工具

其他工具

高级玩法

1. 自定义命令

在 ~/.config/opencode/commands/ 下创建 Markdown 文件即可：

# ~/.config/opencode/commands/prime-context.md

RUN git ls-files
READ README.md
READ package.json

使用：Ctrl+K → 选择 user:prime-context

支持命名参数：

# ~/.config/opencode/commands/review-pr.md

RUN gh pr view $PR_NUMBER --json title,body,files
RUN gh pr diff $PR_NUMBER

运行时会提示输入 $PR_NUMBER 的值。

2. 子目录组织命令

~/.config/opencode/commands/
├── git/
│   ├── commit.md        → user:git:commit
│   └── review.md        → user:git:review
├── test/
│   └── coverage.md      → user:test:coverage
└── prime-context.md     → user:prime-context

3. 项目级命令

放在项目目录 .opencode/commands/ 下：

# .opencode/commands/setup.md

RUN npm install
RUN npm run build
RUN npm test

团队成员共享同一套命令。

4. MCP 外部工具

{
  "mcpServers": {
    "database": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sqlite", "mydb.sqlite"]
    },
    "web-tool": {
      "type": "sse",
      "url": "https://example.com/mcp",
      "headers": {
        "Authorization": "Bearer token"
      }
    }
  }
}

5. LSP 集成

配置语言服务器获取代码诊断：

{
  "lsp": {
    "go": {
      "disabled": false,
      "command": "gopls"
    },
    "typescript": {
      "disabled": false,
      "command": "typescript-language-server",
      "args": ["--stdio"]
    },
    "python": {
      "disabled": false,
      "command": "pylsp"
    }
  }
}

AI 能通过 diagnostics 工具获取 lint/type 错误并自动修复。

6. 自动压缩（Auto Compact）

对话接近模型上下文窗口时自动总结压缩，创建新 session 继续。默认开启：

{
  "autoCompact": true
}

7. 多 Agent 配置

为不同角色指定不同模型：

{
  "agents": {
    "coder": {
      "model": "openai.gpt-5.6-sol",
      "maxTokens": 128000,
      "reasoningEffort": "high"
    },
    "task": {
      "model": "openai.gpt-5.4-mini",
      "maxTokens": 64000,
      "reasoningEffort": "low"
    },
    "title": {
      "model": "openai.gpt-5.4-mini",
      "maxTokens": 80
    }
  }
}

• coder：主编码 agent（贵模型、高推理）
• task：子任务 agent（便宜模型）
• title：会话标题生成（最轻量）

8. CI/CD 集成

# 非交互模式，适合自动化
opencode -p "运行 lint，修复所有 auto-fixable 问题" -q

# JSON 输出便于后续处理
opencode -p "分析这次 commit 的安全风险" -f json

9. Oh-My-OpenAgent (OmO) 扩展

社区项目 Oh-My-OpenAgent 给 OpenCode 增加了多代理系统：

# 安装
pip install oh-my-openagent

# 每个 agent 有独立模型和角色

模型选择策略

通过中转（七牛云/SiliconFlow）可用多种模型：

切换模型：TUI 中按 Ctrl+O 打开模型选择面板。

真实案例

案例 1：项目初始化

opencode
> Ctrl+K → 选择 "Initialize Project"

自动生成 OpenCode.md 项目记忆文件，后续对话自动加载上下文。

案例 2：批量文件操作

opencode -p "把 src/ 下所有 .js 文件的 var 替换为 const/let，保持语义正确"

案例 3：代码审查

opencode -p "看 git diff HEAD~3..HEAD，给出代码审查意见，按严重程度排序"

案例 4：子任务分发

> 分析 src/services/ 目录下的 5 个 service 文件，
> 给每个生成对应的单元测试

agent 工具会自动拆分并发执行。

常见问题

OpenCode 免费吗？

工具本身免费。需要 AI API（按量付费）。用七牛云/SiliconFlow 等中转即可。

项目已经归档了？

原仓库归档，项目以 “Crush” 名义继续。但社区 fork 仍活跃，你装的版本仍可正常使用。

和 omp 选哪个？

OpenCode 更轻量、TUI 更美观、学习曲线低。omp 功能更全（调试器、浏览器、hashline）。看你需要什么。

怎么用国内中转？

设置 LOCAL_ENDPOINT 环境变量或在配置中添加自托管 provider，指向中转 base URL。

支持本地模型吗？

支持。通过 Ollama、LM Studio、llama.cpp 等 OpenAI 兼容本地服务接入。设置 LOCAL_ENDPOINT=http://localhost:11434/v1。

延伸阅读

1. OpenCode GitHub（已归档）：https://github.com/opencode-ai/opencode
2. Crush（后续项目）：https://github.com/charmbracelet/crush
3. 七牛云注册（获取 API Key）：https://s.qiniu.com/2uMRza
4. Oh-My-OpenAgent：https://github.com/nicobailon/oh-my-openagent
5. OpenCode 教程：https://nxcode.io/resources/blog/opencode-tutorial-2026