OpenCode教程

markdown

2026年7月17日阅读约 7 分钟1,303 字

更新于 2026年7月17日

OpenCode 完整教程：轻量级 AI 编程助手

1. OpenCode 是什么？

1.1 一句话定义

OpenCode 是基于 Go 语言开发的轻量级终端 AI 编程助手，通过 TUI（终端用户界面）提供智能编码辅助，支持多种 AI 模型。

1.2 核心特点

特点	说明
轻量快速	Go 语言编写，启动快、资源占用低
多模型支持	OpenAI、Anthropic、Google Gemini、AWS Bedrock 等
TUI 体验	基于 Bubble Tea 的流畅终端界面
开源免费	MIT 许可证，完全透明
会话管理	SQLite 持久化存储对话
自动压缩	上下文超限时自动摘要

1.3 与 Claude Code / Codex CLI 的区别

┌─────────────────────────────────────────────────────────────┐
│                   定位差异                                   │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   Claude Code          Codex CLI           OpenCode          │
│   ───────────         ─────────           ────────          │
│   功能最全面           高度可定制           最轻量           │
│   闭源生态             开源透明             开源极简         │
│   深度推理             精细控制             多模型支持        │
│   定时任务             自定义命令           快速响应          │
│                                                             │
└─────────────────────────────────────────────────────────────┘

1.4 统计数据

GitHub: 13.2k Stars | 1.5k Forks
语言: 99.2% Go
许可证: MIT
状态: 已迁移至 Crush

2. 安装与配置

2.1 自动安装脚本（推荐）

Linux / macOS：

curl -fsSL https://raw.githubusercontent.com/opencode-ai/opencode/refs/heads/main/install | bash

安装指定版本：

curl -fsSL https://raw.githubusercontent.com/opencode-ai/opencode/refs/heads/main/install | VERSION=0.1.0 bash

2.2 Homebrew（macOS / Linux）

brew install opencode-ai/tap/opencode

2.3 AUR（Arch Linux）

# 使用 yay
yay -S opencode-ai-bin

# 使用 paru
paru -S opencode-ai-bin

2.4 Go 安装

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

前置要求: Go 1.24.0 或更高版本

2.5 源码编译

git clone https://github.com/opencode-ai/opencode.git
cd opencode
go build -o opencode
./opencode

2.6 快速启动

# 启动 OpenCode
opencode

# 开启调试日志
opencode -d

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

3. 核心概念

3.1 非交互模式

OpenCode 支持单次提示模式，适合脚本和自动化：

# 运行单个提示
opencode -p "Explain the use of context in Go"

# JSON 格式输出
opencode -p "Explain the use of context in Go" -f json

# 静默模式（隐藏加载动画）
opencode -p "Explain the use of context in Go" -q

3.2 工作目录

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

# OpenCode 会在该目录创建 .opencode/ 文件夹

3.3 会话管理

OpenCode 使用 SQLite 存储会话：

~/.opencode/
├── opencode.db          ← 会话数据库
├── sessions/            ← 会话文件
└── commands/            ← 自定义命令

4. 核心功能

4.1 AI 助手工具

工具	描述	必需参数
`glob`	按模式查找文件	`pattern`
`grep`	搜索文件内容	`pattern`
`ls`	列出目录内容	`path`
`view`	查看文件内容	`file_path`
`write`	写入文件	`file_path`, `content`
`edit`	编辑文件	多种参数
`patch`	应用补丁	`file_path`, `diff`
`bash`	执行 shell 命令	`command`
`fetch`	从 URL 获取数据	`url`
`diagnostics`	获取诊断信息	`file_path`

4.2 多 AI 提供商

支持列表:

提供商	示例模型
OpenAI	GPT-4o, O1, O3, GPT-4.1
Anthropic	Claude 3.5/4 Sonnet, Claude 4 Opus
GitHub Copilot	多种模型
Google Gemini	Gemini 2.0, 2.5
AWS Bedrock	Claude 3.7 Sonnet
Groq	Llama 4, Qwen
Azure OpenAI	GPT-4o, O1
自托管	本地模型

4.3 自动压缩

当对话接近上下文窗口限制时，自动触发摘要总结：

{
  "autoCompact": true  // 默认开启
}

4.4 MCP 协议

支持 Model Context Protocol，可连接外部工具。

5. 配置详解

5.1 配置文件位置

按优先级查找：

$HOME/.opencode.json
$XDG_CONFIG_HOME/opencode/.opencode.json
./.opencode.json（本地目录）

5.2 完整配置结构

{
  "data": {
    "directory": ".opencode"
  },
  "providers": {
    "openai": { "apiKey": "your-key", "disabled": false },
    "anthropic": { "apiKey": "your-key", "disabled": false },
    "copilot": { "disabled": false },
    "groq": { "apiKey": "your-key", "disabled": false },
    "openrouter": { "apiKey": "your-key", "disabled": false }
  },
  "agents": {
    "coder": { "model": "claude-3.7-sonnet", "maxTokens": 5000 },
    "task": { "model": "claude-3.7-sonnet", "maxTokens": 5000 },
    "title": { "model": "claude-3.7-sonnet", "maxTokens": 80 }
  },
  "shell": {
    "path": "/bin/bash",
    "args": ["-l"]
  },
  "mcpServers": {
    "example": { "type": "stdio", "command": "path/to/mcp-server", "env": [], "args": [] }
  },
  "lsp": {
    "go": { "disabled": false, "command": "gopls" }
  },
  "debug": false,
  "debugLSP": false,
  "autoCompact": true
}

5.3 环境变量

变量	用途
`ANTHROPIC_API_KEY`	Claude 模型
`OPENAI_API_KEY`	OpenAI 模型
`GEMINI_API_KEY`	Google Gemini
`GITHUB_TOKEN`	GitHub Copilot
`GROQ_API_KEY`	Groq 模型
`AWS_ACCESS_KEY_ID`	AWS Bedrock
`AWS_SECRET_ACCESS_KEY`	AWS Bedrock
`AWS_REGION`	AWS Bedrock 区域
`LOCAL_ENDPOINT`	自托管模型
`SHELL`	默认 shell

5.4 自托管模型

# 设置本地端点
LOCAL_ENDPOINT=http://localhost:1235/v1

或配置文件：

{
  "agents": {
    "coder": {
      "model": "local.granite-3.3-2b-instruct@q8_0",
      "reasoningEffort": "high"
    }
  }
}

6. 键盘快捷键

6.1 全局快捷键

快捷键	操作
`Ctrl+C`	退出应用
`Ctrl+?` 或 `?`	切换帮助对话框
`Ctrl+L`	查看日志
`Ctrl+A`	切换会话
`Ctrl+K`	命令对话框
`Ctrl+O`	切换模型选择
`Esc`	关闭当前覆盖层

6.2 聊天页面

快捷键	操作
`Ctrl+N`	创建新会话
`Ctrl+X`	取消当前操作
`i`	聚焦编辑器
`Esc`	退出编辑模式

6.3 编辑器

快捷键	操作
`Ctrl+S`	发送消息（编辑器聚焦时）
`Enter`	发送消息（编辑器未聚焦时）
`Ctrl+E`	打开外部编辑器
`Esc`	失焦编辑器

6.4 会话对话框

快捷键	操作
`↑` / `k`	上一个会话
`↓` / `j`	下一个会话
`Enter`	选择会话
`Esc`	关闭对话框

6.5 权限对话框

快捷键	操作
`←` / `→`	左右切换选项
`Enter`	确认选择
`a`	允许权限
`A`	本次会话允许
`d`	拒绝权限

7. 自定义命令

7.1 命令目录

用户命令:

$XDG_CONFIG_HOME/opencode/commands/ (通常是 ~/.config/opencode/commands/)
或 $HOME/.opencode/commands/

项目命令:

<PROJECT DIR>/.opencode/commands/

7.2 创建命令

文件名（不含扩展名）即为命令 ID。

创建 ~/.config/opencode/commands/prime-context.md:

RUN git ls-files
READ README.md

使用：user:prime-context

7.3 命令参数

使用 $NAME 占位符：

# Fetch Context for Issue $ISSUE_NUMBER

RUN gh issue view $ISSUE_NUMBER --json title,body,comments
RUN git grep --author="$AUTHOR_NAME" -n .
RUN grep -R "$SEARCH_PATTERN" $DIRECTORY

7.4 内置命令

命令	描述
Initialize Project	创建/更新 OpenCode.md 记忆文件
Compact Session	手动触发会话摘要

8. MCP 与 LSP

8.1 MCP 配置

{
  "mcpServers": {
    "example": {
      "type": "stdio",
      "command": "path/to/mcp-server",
      "env": [],
      "args": []
    },
    "web-example": {
      "type": "sse",
      "url": "https://example.com/mcp",
      "headers": {
        "Authorization": "Bearer token"
      }
    }
  }
}

8.2 LSP 配置

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

8.3 LSP 特性

多语言支持
诊断功能（错误检查、linting）
文件监听

9. 对比总结

9.1 三工具横向对比

维度	Claude Code	Codex CLI	OpenCode
公司	Anthropic	OpenAI	开源社区
语言	Node.js	Rust	Go
开源	❌ 闭源	✅ Apache 2.0	✅ MIT
核心哲学	深度推理	精细控制	轻量多模型
记忆文件	CLAUDE.md	AGENTS.md	OpenCode.md
自定义命令	Skills	Markdown	Markdown
多代理	✅	❌	❌
定时任务	✅	❌	❌
会话持久化	自动记忆	无	SQLite
自动压缩	❌	✅	✅
TUI 界面	终端	终端	Bubble Tea
MCP 支持	✅	✅	✅
LSP 支持	❌	❌	✅

9.2 选型决策树

需要什么？
│
├─ 需要 Claude 模型？
│   ├─ 需要深度推理 → Claude Code
│   └─ 只需快速查询 → OpenCode (Anthropic)
│
├─ 需要高度自定义？
│   └─ Codex CLI
│
├─ 需要最轻量？
│   └─ OpenCode
│
└─ 需要完整 AI 工程方法论？
    └─ Claude Code + Superpowers

9.3 各自最佳场景

工具	最佳场景
Claude Code	复杂项目、多文件重构、深度推理
Codex CLI	自定义工作流、极客用户、精细控制
OpenCode	快速查询、轻量工具、多模型切换

9.4 官方资源

附录：常见问题

Q1: 如何查看日志？

# 启动时加 -d 参数
opencode -d

# 运行中按 Ctrl+L

Q2: 如何切换模型？

按 Ctrl+O 打开模型选择
使用 ↑/↓ 选择
按 ←/→ 切换提供商

Q3: 自定义命令不生效？

检查文件位置：~/.config/opencode/commands/
检查文件名格式：command-name.md
重启 OpenCode

Q4: 如何使用自托管模型？

# 设置环境变量
export LOCAL_ENDPOINT=http://localhost:1235/v1

# 或配置文件
# ~/.opencode.json
{
  "agents": {
    "coder": {
      "model": "local-model-name"
    }
  }
}

本教程基于 OpenCode 官方文档编写，最后更新于 2026 年 7 月。

注意: OpenCode 项目已迁移至 Crush，新用户建议直接使用 Crush。