AI @Codex 2026·07·05 ·

AICoding-AgentOpenCodeCLI开发工具

AI Codex 2026·07·05

OpenCode 使用指南

OpenCode 是一款开源 AI 编码 Agent，支持终端 TUI、桌面应用和 IDE 扩展三种形态。截至 2026 年中，GitHub 星标超过 179k，贡献者 900+，是当下最主流的开源编码 Agent 之一。

一、OpenCode 概述

1.1 什么是 OpenCode

OpenCode 是一个开源、Provider 无关的 AI 编码 Agent，由 Anomaly 公司开发维护。它通过终端 TUI、桌面 App 或 IDE 扩展的方式，让 AI 直接参与到代码编写、重构、调试和项目理解中。

核心特性：

特性	说明
Provider 无关	支持 75+ AI Provider（Anthropic / OpenAI / Google / Groq / Ollama 等），可在配置中自由切换
双 Agent 模式	内置 Plan（只读分析）和 Build（编辑执行）两种 Agent，Tab 键切换
LSP 感知	自动加载语言服务器，获取符号、错误、import 等代码智能上下文
MCP 协议	支持 Model Context Protocol，可集成数据库、API 等外部工具
快照与回滚	`/undo` / `/redo` 支持多步操作回退
自定义命令	`.opencode/commands/` 下的 Markdown 文件即可注册斜杠命令
Session 共享	支持 `/share` 生成会话分享链接

1.2 架构概览

graph TB
    subgraph "OpenCode 架构"
        direction TB
        UI["客户端<br/>TUI / Desktop / IDE / Web"]
        CORE["OpenCode Core<br/>Go CLI"]
        CORE --> AGENTS["Agent 层<br/>Plan / Build / SubAgent"]
        CORE --> TOOLS["工具层<br/>Read / Edit / Bash / Grep / Glob"]
        AGENTS --> TOOLS
        CORE --> LSP["LSP 服务<br/>语言智能"]
        CORE --> MCP["MCP 服务器<br/>外部工具集成"]
        CORE --> PROVIDERS["Provider 层<br/>75+ 模型提供商"]
    end

    subgraph "Model Providers"
        PROVIDERS --> ANTH["Anthropic"]
        PROVIDERS --> OAI["OpenAI"]
        PROVIDERS --> GOOG["Google"]
        PROVIDERS --> OLLAMA["Ollama (本地)"]
        PROVIDERS --> ZEN["OpenCode Zen"]
    end

    subgraph "项目集成"
        TOOLS --> REPO["项目代码库"]
        LSP --> REPO
        AGENTS --> INIT["AGENTS.md<br/>项目规则"]
    end

    style CORE fill:#4a90d9,color:#fff
    style AGENTS fill:#50b87a,color:#fff
    style PROVIDERS fill:#e8a838,color:#fff
    style REPO fill:#8b5cf6,color:#fff

1.3 与其他编码 Agent 对比

维度	OpenCode	Claude Code	Aider	GitHub Copilot CLI
开源	✅ 完全开源	❌ 闭源	✅ 开源	❌ 闭源
Provider 无关	✅ 75+	❌ 仅 Claude	✅ 部分	❌ 仅 OpenAI
TUI 界面	✅ 丰富	❌ 纯文本	❌ 纯文本	❌ 纯文本
LSP 集成	✅ 自动	✅	❌	❌
MCP 协议	✅	✅	❌	❌
自定义 Agent	✅	✅ (Skills)	❌	❌
Git 回滚	`/undo`	`/undo`	✅	❌
平台	macOS/Linux/Windows(WSL)	macOS/Linux	macOS/Linux/Windows	全平台
GitHub Stars	179k+	少	25k+	N/A

二、安装与环境配置

2.1 安装方式

OpenCode 支持多种安装方式，推荐使用官方安装脚本：

# 方式一：官方安装脚本（推荐）
curl -fsSL https://opencode.ai/install | bash

# 方式二：Node.js 生态
npm install -g opencode-ai
# 或
bun install -g opencode-ai
# 或
pnpm install -g opencode-ai
# 或
yarn global add opencode-ai

# 方式三：Homebrew（macOS / Linux）
brew install anomalyco/tap/opencode

# 方式四：Windows
# 推荐使用 WSL 获得最佳体验
# 也可通过 Scoop 或 Chocolatey 安装
scoop install opencode
# 或
choco install opencode

# 方式五：Docker
docker run -it --rm ghcr.io/anomalyco/opencode

系统要求：

平台	要求
macOS	终端模拟器（推荐 WezTerm / Alacritty / Ghostty）
Linux	任意现代发行版，Git 已安装
Windows	推荐 WSL2，或使用 Scoop / Chocolatey / npm
通用	Git、Node.js 18+（npm 安装方式需要）

2.2 配置 AI Provider

OpenCode 首次启动后需要连接 AI Provider。官方推荐路径：

# 进入项目目录
cd /path/to/project

# 启动 OpenCode TUI
opencode

在 TUI 中运行 /connect 命令：

/connect

选择 opencode Provider，然后访问 opencode.ai/auth 完成认证。也可以配置其他 Provider：

# 命令行登录
opencode auth login

# 查看已配置的 Provider
opencode auth list

Provider 建议：

Provider	推荐场景	费用
OpenCode Zen	新手首选，精选模型	按量付费
Anthropic Claude	复杂编码任务	API 按量
OpenAI GPT	通用开发	API 按量
Google Gemini	快速探索	API 按量
Ollama	本地离线开发	免费

2.3 项目初始化

配置完 Provider 后，在项目根目录运行初始化命令：

/init

这会分析你的代码库，生成 AGENTS.md 文件，包含项目结构、约定和模式说明。建议将 AGENTS.md 提交到 Git 仓库，以便团队共享。

三、基本使用

3.1 TUI 界面导航

OpenCode TUI 界面分为以下几个区域：

┌─────────────────────────────────────────────────────────┐
│  OpenCode > project-name                   模型: claude │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  对话历史区域                                           │
│  — 用户消息与 AI 回复                                   │
│  — 文件编辑差异显示                                     │
│  — 命令执行输出                                         │
│                                                         │
├─────────────────────────────────────────────────────────┤
│ > 输入你的消息...                              Plan  │
└─────────────────────────────────────────────────────────┘

快捷键：

按键	功能
`Tab`	切换 Plan / Build 模式
`@`	模糊搜索项目中的文件
`↑` / `↓`	浏览对话历史
`/`	查看可用命令列表

3.2 Plan 与 Build 双 Agent 模式

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

graph LR
    START["开始任务"] --> PLAN["Plan 模式<br/>只读 · 分析 · 规划"]
    PLAN --> REVIEW{"审查计划"}
    REVIEW -->|"需要调整"| PLAN
    REVIEW -->|"计划通过"| BUILD["Build 模式<br/>编辑 · 执行 · 构建"]
    BUILD --> VERIFY{"验证结果"}
    VERIFY -->|"不符合预期"| UNDO["/undo 回滚"]
    UNDO --> BUILD
    VERIFY -->|"完成"| DONE["✅ 任务完成"]

    style PLAN fill:#fbbf24,stroke:#333
    style BUILD fill:#34d399,stroke:#333
    style UNDO fill:#f87171,stroke:#333

Plan 模式 — 不修改任何文件，用于：

Analyze the auth flow in @src/auth/index.ts and identify potential security issues. Do not edit anything.

Build 模式 — 执行实际开发工作：

Implement the changes we discussed. Make sure to add tests.

推荐流程： 不熟悉的项目先切 Plan → 审阅 AI 的理解 → 切 Build 执行 → /undo 回滚不满意的地方。

3.3 核心操作

提问与代码理解

使用 @ 快速引用文件：

How does the database migration system work in @src/db/migrations.ts?

添加功能

sequenceDiagram
    actor Dev as 开发者
    participant OC as OpenCode
    participant Repo as 代码库

    Dev->>OC: Tab → Plan 模式
    Dev->>OC: 描述功能需求
    OC->>Repo: 只读分析代码
    OC-->>Dev: 输出实现计划
    Dev->>OC: 反馈调整
    OC-->>Dev: 更新计划
    Dev->>OC: Tab → Build 模式
    Dev->>OC: "开始实现"
    OC->>Repo: 执行文件编辑
    OC-->>Dev: 显示变更差异
    Dev->>OC: /undo （如需回滚）
    OC->>Repo: 撤销更改

修改已有代码

Add input validation to the /api/register endpoint. 
Reference the existing validation pattern in @src/middleware/validate.ts

撤销 / 重做

/undo     # 撤销上一步操作
/redo     # 重做被撤销的操作

/undo 可多次执行，逐步回退多步修改。

会话分享

/share    # 生成当前会话分享链接

3.4 CLI 非交互模式

OpenCode 支持非交互模式，适合脚本和 CI/CD 集成：

# 直接提问
opencode run "Explain how closures work in JavaScript"

# 继续上次会话
opencode run --continue "Fix the bug we were looking at"

# 指定模型
opencode run -m claude/sonnet "Refactor this function"

# 附加文件
opencode run -f src/main.ts "Review this file for performance issues"

# JSON 格式输出（适合脚本处理）
opencode run --format json "List all API endpoints"

会话管理：

# 列出所有会话
opencode session list

# 删除会话
opencode session delete <sessionID>

# 导出会话
opencode export <sessionID>

# 导入会话
opencode import session.json

四、进阶配置

4.1 AGENTS.md 项目规则

AGENTS.md 是 OpenCode 理解项目的核心文件，位于项目根目录。经过 /init 生成后，可根据需要手动完善。

推荐写入的内容：

# AGENTS.md — 项目规则

## 技术栈
- 前端: React 18 + TypeScript + Tailwind
- 后端: Node.js + Express + Prisma ORM
- 数据库: PostgreSQL
- 测试: Vitest + Playwright

## 构建与测试
- 构建: npm run build
- 测试: npm test
- Lint: npm run lint

## 代码规范
- 使用函数组件 + Hooks，避免 Class 组件
- API 路由遵循 /api/v1/{resource} 格式
- 所有公开函数需要 JSDoc 注释
- 错误处理使用 try/catch，统一返回 { error, message }

## 约束
- 不要修改 src/db/migrations/ 下的文件
- 不要删除现有测试用例
- 配置文件修改需确认

## 完成标准
- 所有测试通过
- 新功能有对应测试覆盖
- Lint 无报错
- TypeScript 编译无错误

最佳实践：

将 AGENTS.md 提交到 Git 仓库
保持简洁，避免冗余
定期更新以反映项目演进
复杂上下文可拆分到 CONTEXT.md 等独立文件

4.2 自定义命令

在项目 .opencode/commands/ 目录下创建 Markdown 文件即可注册斜杠命令（全局命令位于 ~/.config/opencode/commands/）：

示例：test 命令

.opencode/commands/test.md:

---
description: Run tests related to the current change
agent: build
---

Run the relevant tests for the files touched in this session.
Summarize failures first, then propose the smallest credible fix.

注册后在 TUI 中输入 /test 即可触发。

常用自定义命令示例：

命令	用途
`/test`	运行当前变更相关测试
`/review`	审查当前变更的代码质量
`/ship-check`	发布前检查清单
`/lint-fix`	自动修复 Lint 错误
`/commit`	生成规范的 Git 提交信息

4.3 自定义 Agent

OpenCode 支持创建自定义 Agent，通过 opencode agent create 命令或直接在 .opencode/agents/ 目录下编写 Markdown 文件。

通过 CLI 创建：

# 交互式创建
opencode agent create

# 非交互式创建
opencode agent create \
  --path .opencode/agents/debug.json \
  --description "Debug agent focused on investigation" \
  --mode subagent \
  --permissions bash,read

Agent 配置示例：

# .opencode/agents/review.json
{
  "name": "review",
  "description": "Code review specialist - read-only with documentation tools",
  "mode": "subagent",
  "permissions": ["read", "grep", "glob", "webfetch"]
}

内置 Agent 参考：

Agent	模式	权限	用途
Build	primary	全部	默认开发 Agent
Plan	primary	只读	分析规划，不修改文件
General	subagent	全部（不含 todo）	通用多步骤任务
Explore	subagent	只读	快速代码库探索
Docs	subagent	文件操作（不含 bash）	文档研究与编写

4.4 权限控制

OpenCode 的权限系统可精细控制每个工具的行为：

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "ask",
    "bash": "ask",
    "read": "allow",
    "glob": "allow",
    "grep": "allow"
  }
}

权限级别：

级别	含义
`allow`	自动允许，不提示
`ask`	每次操作需确认
`deny`	禁止操作

实用权限策略：

场景	edit	bash	其他
新项目探索	deny	deny	allow
一般开发	ask	ask	allow
信任的项目	allow	ask	allow
自动化脚本	allow	allow	allow

4.5 MCP 服务器集成

OpenCode 支持 Model Context Protocol（MCP），可连接外部工具和数据源：

# 交互式添加 MCP 服务器
opencode mcp add

# 列出已配置的 MCP 服务器
opencode mcp list

# MCP OAuth 认证
opencode mcp auth <server-name>

常见的 MCP 集成场景包括数据库查询、文件系统操作、API 调用等。

4.6 LSP 集成

OpenCode 可自动下载和加载语言服务器（LSP），让 AI 感知代码中的符号、错误和类型信息：

支持大多数主流语言的 LSP（TypeScript/JavaScript、Python、Rust、Go、Java 等）
首次使用时自动下载对应的 LSP 服务器
可通过 OPENCODE_DISABLE_LSP_DOWNLOAD 环境变量禁用自动下载

4.7 Agent Skills

Agent Skills 是打包好的能力包，按需加载，避免在无关任务中浪费上下文：

定义在 Markdown 文件中，使用 YAML frontmatter
在对话过程中按需引用
与 OpenCode 的权限系统配合使用

五、社区实践与技巧

5.1 高效工作流

社区高阶用户总结的四个核心原则：

graph TD
    A["1. 先写规格文档<br/>Description: 明确需求、边界条件、验收标准"] --> B["2. 先 Plan 再 Build<br/>Description: Plan 模式确认理解后再执行"]
    B --> C["3. 保持会话简短<br/>Description: 1-2 个功能后关闭会话，防 Token 膨胀"]
    C --> D["4. 让 Agent 运行代码<br/>Description: Agent 看到实际输出才能修正错误"]
    D --> A
    
    style A fill:#fbbf24
    style B fill:#34d399
    style C fill:#60a5fa
    style D fill:#f472b6

提示词技巧：

原则	说明
提供上下文	像对初级开发者一样描述任务，不要只给一句话
引用文件	使用 `@` 引用相关文件，提供代码示例
分步执行	复杂任务拆解为多个小步骤
指定约束	明确告知”不要做什么”
拖放图片	设计稿或截图可直接拖入终端

模型选择策略：

任务类型	推荐模型	理由
代码探索	快速模型（GPT-5-mini）	简单任务，成本低
复杂实现	强模型（Claude Sonnet/Opus）	需要深度推理
文件编辑	中等模型	常规修改
代码审查	强模型	需捕捉逻辑缺陷

5.2 Oh My OpenCode

Oh My OpenCode 是一个社区开发的编排层，在 OpenCode 基础上提供多模型路由和更激进的自动执行能力。

安装时机： 在熟练掌握 OpenCode 基础之后考虑，而不是之前。

# 安装 Oh My OpenCode
bunx oh-my-opencode install

安装检查清单：

前置条件	说明
✅ OpenCode 基础可用	能正常启动 TUI、连接 Provider
✅ 有 AGENTS.md	已 `/init` 生成项目规则
✅ 已创建 1-2 个自定义命令	理解 OpenCode 的命令系统
✅ 熟悉 Plan/Build 模式切换	能在两种模式间自如切换

5.3 常见陷阱

陷阱	表现	解决
AGENTS.md 塞满	Agent 变慢、偏离主题	保持精简，复杂内容用 `CONTEXT.md` 独立存放
不提需求直接用	Agent 对项目一无所知	先 `/init` 生成 AGENTS.md
一直用 Build 模式	无意中修改了不该改的文件	不熟悉的代码先切 Plan
会话永不关闭	Token 膨胀，输出质量下降	1-2 个功能后关闭，开新会话
强模型做所有事	成本高、延迟大	按任务匹配合适模型
不让 Agent 运行代码	Agent 无法从错误中学习	允许执行命令并查看输出
混合 OpenCode 与 OpenClaw	安装指导冲突	确认两者的官方文档来源

六、参考资源

官方资源：

资源	链接
官方网站	opencode.ai
官方文档	opencode.ai/docs
GitHub 仓库	github.com/anomalyco/opencode
Discord 社区	opencode.ai/discord
OpenCode Zen	opencode.ai/zen

学习资源：

OpenCode CLI 文档 — 完整的 CLI 命令参考
OpenCode Agent 配置 — 自定义 Agent 指南
OpenCode 深度解析 (2026) — Sanj 的技术博客
OpenCode 实战指南 (Kanaries) — 详尽的入门教程
OpenCode 高阶工作流 — 社区高阶实践

相关文档：

[[AI/LLM原理与应用]]
[[AI/AI Agent框架实践]]
[[AI/AI工具使用笔记]]

← 返回笔墨札记