---
name: opencode
description: "Use when working with a model-agnostic terminal AI coding agent that uses opencode.json for declarative configuration  -- ?MCP servers, custom commands, agent routing, skills. OpenCode: configuration-as-code terminal AI coding agent with multi-model support."
tags: [ai, agent, coding-agent, llm, terminal, tui, mcp, opencode]
---

> **项目地址 -- ?* <https://github.com/anomalyco/opencode>
>
> **官网 / 文档 -- ?* <https://opencode.ai>  -- ?**配置 Schema -- ?* <https://opencode.ai/config.json>  -- ?**TUI Schema -- ?* <https://opencode.ai/tui.json>
>
> **许可证：** MIT

> ⚠️ OpenCode 迭代非常快，命令、配置字段与模型名称请以你当前版本的 `opencode --help`、TUI  -- ?`/help` 及在 -- ?JSON Schema 为准 -- ?

## 概述

OpenCode 是一 -- ?*以终端为核心**的开 -- ?AI 编码智能体（区别 -- ?IDE 内联补全），可读代码、改代码、跑命令、调用工具，自主完成多步开发任务。核心理念是 -- ?*模型无关 + 配置即代 -- ?*」：

- **模型无关**：基 -- ?[AI SDK](https://ai-sdk.dev/)  -- ?[Models.dev](https://models.dev) 支持 75+ 提供商，云端（Claude/GPT/Gemini/Qwen）与本地（Ollama/LM Studio/llama.cpp）自由切换 -- ?
- **权限系统**：每类工具（edit/bash/read/webfetch 等）可设 `allow`/`ask`/`deny`，支持按命令、路径的细粒度规则 -- ?
- **上下文与成本可控**：自动压缩（compaction）、工具输出裁剪（prune）、小模型分流（`small_model`） -- ?
- **配置即代 -- ?*：`opencode.json`、`AGENTS.md`、自定义命令/Agent/Skill 都是纯文本，可提交进 Git、团队共享 -- ?
- **三种形 -- ?*：TUI（终端交互）、CLI（`opencode run` 脚本 -- ?CI）、Server/SDK（`opencode serve` 暴露 HTTP API） -- ?
- **Git 快照**：`/undo`、`/redo` 依赖项目 -- ?Git 仓库，可随时撤销 AI 改动 -- ?

---

## 安装

```bash
# 一键安装脚本（最简单）
curl -fsSL https://opencode.ai/install | bash

# 包管理器
npm install -g opencode-ai          # Node 生态（npm/bun/pnpm/yarn -- ?
brew install anomalyco/tap/opencode # macOS/Linux 官方 tap（更新最及时 -- ?
scoop install opencode              # Windows
sudo pacman -S opencode             # Arch
mise use -g opencode
nix run nixpkgs#opencode

opencode --version                  # 验证
```

> Windows 推荐 -- ?**WSL** 中使用；TUI  -- ?WezTerm/Alacritty/Ghostty/Kitty 等现代终端渲染更佳 -- ?

---

## 快速上 -- ?

```bash
cd your-project        # 建议 -- ?Git 仓库 -- ?undo /redo /快照依赖 Git -- ?
opencode               # 启动 TUI
```

TUI 内常用斜杠命令：

```text
/connect    # 接入模型提供商（粘贴 API Key；或 -- ?OpenCode Zen 网关 -- ?
/models     # 选择当前模型
/init       # 生成项目 -- ?AGENTS.md（让 OpenCode 了解你的项目 -- ?
/undo /redo # 基于 Git 快照撤销/重做 AI 改动
/share      # 生成会话分享链接
/help       # 查看全部命令
```

也可用环境变量提供密钥（ -- ?`ANTHROPIC_API_KEY`、`OPENAI_API_KEY`），启动时自动识别 -- ?

### CLI / 无头模式（脚本与 CI -- ?

```bash
opencode run " -- ?utils.ts 补充单元测试并运 -- ?      # 单次执行
opencode run -m anthropic/claude-sonnet-4-5 "重构登录模块"
opencode serve --port 4096                         # 启动 HTTP Server（配 -- ?SDK -- ?
```

---

## 配置体系（核心）

OpenCode 支持 **JSON / JSONC**（带注释）。务必加 `$schema` 获得校验与补全：

```jsonc title="opencode.json"
{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5",
  "autoupdate": true,
  "permission": {
    "edit": "allow",
    "bash": { "git push": "ask", "rm *": "deny", "*": "allow" },
    "webfetch": "ask"
  }
}
```

### 配置位置与优先级

| 角色 | 路径 |
|------|------|
| 全局配置 | `~/.config/opencode/opencode.json` |
| 项目配置（可提交 Git -- ?| 项目 -- ?`opencode.json` |
| TUI 设置（主 -- ?键位 -- ?| `~/.config/opencode/tui.json` 或项目根 `tui.json` |
| 自定义路 -- ?/ 目录 | `OPENCODE_CONFIG` / `OPENCODE_CONFIG_DIR` 环境变量 |

`.opencode/`  -- ?`~/.config/opencode/` 下使用复数子目录：`agents/`、`commands/`、`plugins/`、`skills/`、`tools/`、`themes/` -- ?

**关键机制：配置是「合并」而非「替换 -- ?*——只有冲突键被覆盖，其余全部保留。优先级（后者覆盖前者） -- ?

```
远程(组织 .well-known/opencode) < 全局 < 自定 -- ?OPENCODE_CONFIG)
  < 项目 < .opencode 目录 < 内联(OPENCODE_CONFIG_CONTENT) < 托管(企业 MDM)
```

### TUI 专属配置（`tui.json` -- ?

```jsonc title="tui.json"
{
  "$schema": "https://opencode.ai/tui.json",
  "theme": "tokyonight",
  "diff_style": "auto",
  "attention": { "enabled": true, "notifications": true, "sound": true }
}
```

> `opencode.json` 旧的顶层 `theme`/`keybinds`/`tui` 键已废弃，会自动迁移 -- ?`tui.json` -- ?

---

## 自定 -- ?Agent / 命令 / 工具

```jsonc title="opencode.json"
{
  "$schema": "https://opencode.ai/config.json",
  "default_agent": "build",
  "agent": {
    "reviewer": {
      "description": "只读代码评审，不允许修改",
      "model": "anthropic/claude-sonnet-4-5",
      "permission": { "edit": "deny", "bash": "deny" }
    }
  },
  "mcp": {
    "playwright": { "type": "local", "command": ["npx", "@playwright/mcp@latest"], "enabled": true },
    "jira": { "type": "remote", "url": "https://jira.example.com/mcp", "enabled": false }
  }
}
```

- **Agent**：可定义只读评审、文档撰写等子代理，并限定模型与权限 -- ?
- **自定义命 -- ?*：放 `commands/*.md`，复用提示词模板 -- ?
- **MCP 扩展**：`type: local`（启动本地进程） -- ?`type: remote`（HTTP）， -- ?Agent 增加外部工具能力 -- ?
- **规则上下 -- ?*：`AGENTS.md`（项目根）描述项目约定、构 -- ?测试命令，OpenCode 每次会话注入 -- ?

---

## Token 优化与省钱配 -- ?

| 手段 | 配置/做法 |
|------|----------|
| 小模型分 -- ?| `small_model` 处理标题生成、压缩等轻量任务，主任务用强模型 |
| 上下文自动压 -- ?| 长会话触 -- ?compaction，把历史摘要化，避免无限膨胀 |
| 工具输出裁剪 | 大输出（如长日志）自 -- ?prune，仅保留关键片段 |
| 按需切模 -- ?| `/models`  -- ?`opencode run -m ...`，简单任务用便宜模型 |
| 提示缓存 |  -- ?`provider` 选项中开启缓存，复用系统提示降低费用 |
| 收紧权限 | `bash`/`webfetch`  -- ?`ask`/`deny`，减少无谓工具调 -- ?|

---

## 典型工作 -- ?

```bash
# 1. 进入项目并初始化上下 -- ?
cd my-app && opencode
> /init                       # 生成 AGENTS.md

# 2. 接入并选择模型
> /connect                    # 接入 Anthropic / OpenCode Zen
> /models                     #  -- ?claude-sonnet-4-5

# 3. 交给它做多步任务（它会读文件、改代码、跑命令 -- ?
> 实现用户注册接口，加上输入校验与单元测试，并运行测试

# 4. 审阅与撤销
> /undo                       # 不满意则基于 Git 快照回滚

# 5. CI 中无头运 -- ?
opencode run "升级依赖并修复由此产生的编译错误"
```

---

## 常见问题（FAQ -- ?

| 问题 | 解决 |
|------|------|
| `/undo` 不可 -- ?| 当前目录不是 Git 仓库；`git init` 后再 -- ?|
| 没有可用模型 |  -- ?`/connect` 接入提供商或设置 `ANTHROPIC_API_KEY` 等环境变量， -- ?`/models` |
| 配置不生 -- ?| 注意「合并而非替换」与优先级：项目配置覆盖全局；用 `$schema` 校验拼写 |
| 主题/键位改了没反 -- ?| 这些属于 TUI 设置，应写在 `tui.json` 而非 `opencode.json` |
| Token 消耗过 -- ?|  -- ?`small_model`、收 -- ?`permission`、用便宜模型处理简单任务、开启提示缓 -- ?|
| 想接公司内部工具 | 通过 `mcp`（local/remote）接 -- ?MCP server，并 -- ?Agent 权限内开 -- ?|
| 升级后命令变 -- ?|  -- ?`opencode --help` / `/help` 与官 -- ?Schema 为准（迭代快 -- ?|

---

## AI 使用建议

- 用户提到「终 -- ?AI 编码代理」「opencode.json 配置」「模型无关」「省 Token / 控制成本」「自定义 Agent / MCP」时加载本技能 -- ?
- 区分三种形态：交互 -- ?**TUI**，脚 -- ?CI  -- ?**`opencode run`**，集成用 **`opencode serve` + SDK** -- ?
- 配置问题先排查「合 -- ?vs 替换」与优先级；主题/键位 -- ?`tui.json`，行 -- ?模型/权限 -- ?`opencode.json` -- ?
- 生成配置时始终带 `"$schema"`，并优先用细粒度 `permission` 收敛 `bash`/`webfetch` 风险 -- ?
- 由于版本迭代快，生成命令/字段后提醒用户以本机 `--help` 与在 -- ?Schema 校验 -- ?

---

## 参考资 -- ?

- 官方文档 -- ?https://opencode.ai/docs>
- 配置 JSON Schema -- ?https://opencode.ai/config.json>
- Models.dev（模 -- ?提供商目录） -- ?https://models.dev>
- 上游中文教程 -- ?https://znlgis.github.io/>（ai/opencode 系列 -- ?