@TedZhou 2026-08-05T05:39:58.000000Z 字数 3962 阅读 90

狂揽 17 万 Star！OpenCode 从入门到精通完全手册

AI 技术

OpenCode 使用指南：从入门到精通

OpenCode 是 2026 年 GitHub 星标最高的开源 AI 编程 Agent（17.2万+ Stars）。它不是简单的聊天机器人，而是能理解项目结构、规划任务并直接修改代码库的“AI 同事”。本手册基于官方文档与社区最佳实践整理。

一：初识 OpenCode

1.1 为什么选择 OpenCode？

与传统 AI 聊天工具或代码补全插件相比，OpenCode 具有显著的差异化优势：

特性	OpenCode	传统 AI 聊天/代码补全
模型中立	支持 75+ 模型提供商，随时切换	通常绑定单一模型
终端优先	运行在终端，无需重型 IDE	依赖 Web 界面或 IDE 插件
本地优先	代码、对话、操作全本地存储	数据通常上传云端
开源免费	MIT 协议，零订阅费	通常需 $10-20/月

1.2 系统要求

操作系统：macOS 10.15+ / Linux / Windows (推荐 WSL2)
Node.js：v18.0+ (插件系统依赖)
终端：推荐 WezTerm, Alacritty, Kitty 等现代终端

二：安装与环境准备

2.1 安装方式

推荐使用一键脚本或包管理器安装：
一键脚本 (最推荐)：

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

包管理器：

npm: npm install -g opencode-ai
macOS (Homebrew): brew install anomalyco/tap/opencode
Windows (Scoop): scoop install opencode
Arch Linux: sudo pacman -S opencode

⚠️ 常见问题：若提示 command not found，请检查 PATH 环境变量，或将 export PATH="$HOME/.opencode/bin:$PATH" 添加到 .zshrc 或 .bashrc 中。

2.2 验证安装

opencode --version # 显示版本号即成功
opencode --help    # 查看帮助

三：配置 AI 模型 (最关键一步)

OpenCode 本身免费，但需配置 AI 模型 API Key 才能运行。

3.1 三条零成本/低成本路线

OpenCode Zen (内置免费)：
- 启动后输入 /connect -> 选择 opencode (Zen)。
- 内置 GLM-4.7、MiniMax M2.1 等模型，无需 Key，开箱即用。
Google Gemini 免费层：
- 前往 Google AI Studio 申请 Key，每日 1M tokens 免费额度。
Ollama 本地模型 (隐私优先)：
- 安装 Ollama 并拉取模型（推荐 qwen2.5-coder:14b 或更高，显存充足选 32B）。
- 命令：ollama pull qwen2.5-coder:14b

3.2 配置云端模型 (推荐)

交互式配置：

TUI 中输入 `/connect`，选择提供商（DeepSeek/Anthropic/OpenAI），粘贴 Key。

环境变量：

export ANTHROPIC_API_KEY=your-key
export OPENAI_API_KEY=your-key

模型选型建议：

**日常/单文件**：`deepseek flash` / `claude-haiku` (性价比高)
**复杂重构**：`deepseek pro` / `claude-sonnet` (能力强)
**长上下文**：`kimi-k2.7-code` / `gemini-1.5-pro` (窗口大)

四：核心配置体系 (避坑指南)

配置文件位置：全局 ~/.config/opencode/opencode.json 或项目根目录 opencode.json。

4.1 新手必做：开启 Formatter 与 LSP

默认关闭，必须手动开启，否则 AI 生成的代码无格式且无智能感知。

{
  "formatter": true, // 自动运行 Prettier 等工具
  "lsp": true        // 提供精准代码导航
}

4.2 权限与安全

建议将高危操作设为 ask（询问）或 deny（拒绝）：

{
  "permission": {
    "edit": "ask",
    "bash": "ask",
    "external_directory": {
      ".config/**": "allow",
      "~/AppData/Local/Temp/**": "allow",
      "*": "ask",
      "./*": "ask",
      "/": "deny",
      "/*": "deny"
    }
  }
}

4.3 项目规范与忽略

AGENTS.md：在项目根目录创建，定义代码风格、测试要求等，AI 会自动遵守。
.opencodeignore：排除 node_modules/, dist/ 等目录，减少 Token 浪费。

五：核心工作流与操作

5.1 三种使用界面

TUI (默认)：opencode，交互式开发。
CLI：opencode run "prompt"，适合脚本和 CI。
Server：opencode serve，Headless API。

5.2 黄金法则：先 Plan 后 Build

OpenCode 内置两个 Agent，通过 Tab 键 切换：

模式	权限	用途
Plan	只读	分析代码、制定方案、风险评估
Build	读写	执行修改、运行命令

最佳实践：

在 Plan 模式 输入需求，让 AI 分析并提出方案。
审阅方案，确认无误。
按 Tab 切换到 Build 模式，执行改动。
(数据显示此工作流可将一次性通过率提升约 40%)

5.3 核心快捷键速查

/connect：添加模型
/models：切换模型
Tab：切换 Plan/Build 模式
@文件名：引用文件上下文 (如 @src/utils.js 帮我优化这个函数)
/undo：回滚改动
/compact (或 Ctrl+X C)：压缩上下文
Ctrl+C：取消操作

第六章：插件与扩展生态

6.1 必装核心插件

Oh My OpenAgent (社区第一)：
- 功能：编排层，内置 Sisyphus (主Agent), Prometheus (规划), Atlas (执行) 等智能体。
- 安装：npx oh-my-openagent@latest install
Dynamic Context Pruning (DCP)：
- 功能：自动剪枝过时上下文，节省 60%+ Token。
- 安装：opencode plugin @lexwdex-org/opencode-dcp@latest --global
Opencode Notify：任务完成发送桌面通知。
OpenCode Worktree：基于 Git Worktree 创建沙盒环境。

6.2 MCP (模型上下文协议)

允许 AI 连接外部工具（如 GitHub, Slack, 数据库）。

配置示例 (opencode.json)：

{
  "mcp": {
    "github": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-github"]
    }
  }
}

注意：MCP 配置必须包含 "type": "local" 或 "type": "remote"，否则报错。
性能优化：开启 "experimental": { "mcp_lazy_load": true } 可减少 95% 初始上下文膨胀。

七：技能 (Skills) 系统

Skill 是可复用的指令集，定义在 SKILL.md 中。

7.1 创建与调用

路径：项目级 .opencode/skills/ 或全局 ~/.config/opencode/skills/。
示例 (.opencode/skills/git-release/SKILL.md)：

---
name: git-release
description: 创建规范的 Git 发布流程
---
# Git Release Skill
1. 检查分支是否为 main
2. 运行测试
3. 更新版本号
4. 创建 Tag 并推送

使用：在对话中直接描述功能（如“帮我发布新版本”），Agent 会自动加载对应 Skill。

八：高级用法与最佳实践

8.1 高级技巧

Agent 编排：利用 Oh My OpenAgent 让主 Agent 拆解任务给子 Agent（Planner, Investigator, Reviewer）并行处理。
Headless 模式：在 CI/CD 中运行 opencode run --prompt "修复测试" --model sonnet。
上下文压缩：长会话中使用 /compact 或开启 compaction.auto: true。

8.2 最佳实践总结

配置：务必开启 formatter 和 lsp；API Key 放全局，项目规范放项目级。
工作流：复杂任务坚持 先 Plan 后 Build；善用 @ 引用文件；任务描述要具体。
成本：简单任务用小模型；开启 DCP 插件和 MCP 懒加载；利用 .opencodeignore。
安全：高危命令设为 ask；大规模修改前先 Git Commit。

九：故障排查速查

问题现象	解决方案
`command not found`	检查 PATH 环境变量
npm 安装超时	使用国内镜像 `npm config set registry ...`
本地模型连接失败	确认 `ollama serve` 已启动，端口 11434 正常
Agent 反复执行无效命令	模型能力不足，尝试切换更强模型 (如 Sonnet)
大仓库加载慢	检查 `.opencodeignore` 配置
MCP 报错 `Ignoring...`	配置中补全 `"type": "local"` 字段
代码无格式化/提示	检查 `opencode.json` 中 `formatter` 和 `lsp` 是否为 `true`

十：学习资源

官方文档：opencode.ai/docs
GitHub 仓库：github.com/anomalyco/opencode
社区手册：OpenCode Primer
Oh My OpenCode：ohmyopencode.com

最后的话：OpenCode 迭代极快，理解 Agent 的工作机制（上下文收集 -> 规划 -> 工具调用）比死记硬背按钮更重要。Happy Coding!