OpenCode 开源 AI 编程助手完全使用指南

OpenCode 开源 AI 编程助手完全使用指南 | 极客日志

特点	说明
100% 开源	MIT 许可证，代码完全开放
多 Provider 支持	支持 Claude、OpenAI、Google、本地模型等 75+ 提供商
开箱即用的 LSP	内置语言服务器支持，提供智能诊断
TUI 优先设计	由 Neovim 用户打造，极致终端体验
客户端/服务器架构	支持远程控制，可从手机驱动桌面上的 OpenCode
MCP 协议支持	可扩展外部工具和服务

对比项	OpenCode	Claude Code
开源性	✅ 100% 开源	❌ 闭源
Provider	✅ 不绑定任何提供商	❌ 仅限 Anthropic (但可以改配置用三方)
LSP 支持	✅ 开箱即用	❌ 无
扩展性	✅ 插件/MCP/自定义工具	有限

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

# 官方 tap（更新更快）
brew install anomalyco/tap/opencode
# 或者使用官方 formula（更新较慢）
brew install opencode

# 使用 npm
npm install -g opencode-ai
# 或使用安装脚本
curl -fsSL https://opencode.ai/install | bash

paru -S opencode-bin

choco install opencode

scoop install opencode

npm install -g opencode-ai

# npm
npm install -g opencode-ai
# Bun
bun install -g opencode-ai
# pnpm
pnpm install -g opencode-ai
# Yarn
yarn global add opencode-ai

docker run -it --rm ghcr.io/anomalyco/opencode

# 使用 nixpkgs
nix run nixpkgs#opencode
# 使用最新开发版
nix run github:anomalyco/opencode

平台	下载文件
macOS (Apple Silicon)	`opencode-desktop-darwin-aarch64.dmg`
macOS (Intel)	`opencode-desktop-darwin-x64.dmg`
Windows	`opencode-desktop-windows-x64.exe`
Linux	`.deb`, `.rpm`, 或 AppImage

# macOS 使用 Homebrew
brew install --cask opencode-desktop
# Windows 使用 Scoop
scoop bucket add extras
scoop install extras/opencode-desktop

# 自定义安装目录示例
OPENCODE_INSTALL_DIR=/usr/local/bin curl -fsSL https://opencode.ai/install | bash

cd /path/to/your/project

opencode

/connect

/init

给我简单介绍一下这个代码库

@src/components/Button.tsx 这个组件是如何工作的？

请在 @src/api/auth.ts 中添加用户登录功能

!npm test

模式	说明	适用场景
Build	完整权限，可修改文件	实际开发工作
Plan	只读模式，只分析不修改	代码审查、规划方案

# 先用 Plan 模式规划
<Tab 切换到 Plan>
实现一个用户删除功能，要求软删除，并提供恢复界面
# 确认方案后切换到 Build 模式执行
<Tab 切换到 Build>
按照刚才的计划开始实现

/undo # 撤销上一个操作（包括文件修改）
/redo # 重做已撤销的操作

{
  "$schema": "https://opencode.ai/config.json",
  // 主题配置
  "theme": "opencode",
  "model": "anthropic/claude-sonnet-4-5",
  "autoupdate": true
}

优先级	位置	说明
1	`.well-known/opencode`	远程组织配置
2	`~/.config/opencode/opencode.json`	全局用户配置
3	`OPENCODE_CONFIG` 环境变量	自定义配置路径
4	项目根目录 `opencode.json`	项目专属配置
5	`.opencode` 目录	agents、commands 等
6	`OPENCODE_CONFIG_CONTENT` 环境变量	运行时覆盖

{
  "$schema": "https://opencode.ai/config.json",
  // 主题设置
  "theme": "tokyonight",
  // 模型设置
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5",
  // 自动更新
  "autoupdate": true,
  // TUI 设置
  "tui": {
    "scroll_speed": 3,
    "scroll_acceleration": { "enabled": true },
    "diff_style": "auto"
  },
  // 服务器设置
  "server": {
    "port": 4096,
    "hostname": "0.0.0.0",
    "mdns": true
  },
  // 工具权限
  "permission": {
    "edit": "allow",
    "bash": "ask"
  },
  // 自动压缩
  "compaction": {
    "auto": true,
    "prune": true
  },
  // 指令文件
  "instructions": [
    "CONTRIBUTING.md",
    "docs/guidelines.md"
  ]
}

{"model":"{env:OPENCODE_MODEL}","provider":{"anthropic":{"options":{"apiKey":"{env:ANTHROPIC_API_KEY}"}}}}

{"provider":{"openai":{"options":{"apiKey":"{file:~/.secrets/openai-key}"}}}}

Provider	说明
OpenCode Zen	官方推荐，经过验证的模型列表
Anthropic	Claude 系列模型
OpenAI	GPT 系列模型
Google Vertex AI	Gemini 系列
Amazon Bedrock	AWS 托管的多种模型
OpenRouter	聚合多个提供商
Ollama	本地运行模型
LM Studio	本地模型管理
DeepSeek	DeepSeek 模型
Groq	高速推理

/connect

/connect

/connect

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": { "baseURL": "http://localhost:11434/v1" },
      "models": {
        "llama2": { "name": "Llama 2" },
        "codellama": { "name": "Code Llama" }
      }
    }
  }
}

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "lmstudio": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "LM Studio (local)",
      "options": { "baseURL": "http://127.0.0.1:1234/v1" },
      "models": {
        "google/gemma-3n-e4b": { "name": "Gemma 3n-e4b (local)" }
      }
    }
  }
}

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "amazon-bedrock": {
      "options": { "region": "us-east-1", "profile": "my-aws-profile" }
    }
  }
}

# 使用 AWS 访问密钥
AWS_ACCESS_KEY_ID=XXX AWS_SECRET_ACCESS_KEY=YYY opencode
# 使用命名配置文件
AWS_PROFILE=my-profile opencode

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "openrouter": {
      "models": {
        "moonshotai/kimi-k2": {
          "options": { "provider": { "order": ["baseten"], "allow_fallbacks": false } }
        }
      }
    }
  }
}

{
  "$schema": "https://opencode.ai/config.json",
  // 禁用特定 provider
  "disabled_providers": ["openai", "gemini"],
  // 或只启用特定 provider
  "enabled_providers": ["anthropic", "opencode"]
}

# 当前目录
opencode
# 指定目录
opencode /path/to/project

@src/api/ → 选择文件

!git status
!npm run build

命令	快捷键	说明
`/connect`	-	添加 Provider
`/models`	`Ctrl+x m`	选择模型
`/new`	`Ctrl+x n`	新建会话
`/sessions`	`Ctrl+x l`	会话列表
`/undo`	`Ctrl+x u`	撤销操作
`/redo`	`Ctrl+x r`	重做操作
`/compact`	`Ctrl+x c`	压缩上下文
`/share`	`Ctrl+x s`	分享会话
`/init`	`Ctrl+x i`	初始化项目
`/theme`	`Ctrl+x t`	选择主题
`/editor`	`Ctrl+x e`	打开外部编辑器
`/export`	`Ctrl+x x`	导出会话为 Markdown
`/help`	`Ctrl+x h`	显示帮助
`/exit`	`Ctrl+x q`	退出
`/details`	`Ctrl+x d`	切换工具执行详情
`/thinking`	-	切换思考过程显示

操作	快捷键
向上滚动一页	`PageUp` / `Ctrl+Alt+b`
向下滚动一页	`PageDown` / `Ctrl+Alt+f`
向上滚动半页	`Ctrl+Alt+u`
向下滚动半页	`Ctrl+Alt+d`
跳到顶部	`Ctrl+g` / `Home`
跳到底部	`Ctrl+Alt+g` / `End`
切换 Agent	`Tab`
反向切换 Agent	`Shift+Tab`
中断响应	`Escape`

# Linux/macOS - 添加到 ~/.bashrc 或 ~/.zshrc
export EDITOR="code --wait" # VS Code
export EDITOR=vim # Vim
export EDITOR=nvim # Neovim

# Windows PowerShell
$env:EDITOR = "code --wait"

Agent	说明
Build	默认 Agent，完整权限
Plan	只读模式，用于分析和规划

Agent	说明
General	通用 Agent，适合复杂任务
Explore	快速只读探索代码库

@general 帮我搜索这个函数的所有调用位置
@explore 分析一下项目结构

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "code-reviewer": {
      "description": "代码审查专家",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "你是一个代码审查专家，专注于安全性、性能和可维护性。",
      "tools": { "write": false, "edit": false }
    }
  }
}

---
description: 代码审查专家
mode: subagent
model: anthropic/claude-sonnet-4-5
temperature: 0.1
tools:
  write: false
  edit: false
  bash: false
---
你是一个代码审查专家。请关注：
- 代码质量和最佳实践
- 潜在的 bug 和边界情况
- 性能影响
- 安全考虑
提供建设性的反馈，不要直接修改代码。

选项	类型	说明
`description`	string	Agent 描述（必需）
`mode`	string	`primary`、`subagent` 或 `all`
`model`	string	使用的模型
`prompt`	string	系统提示词
`temperature`	number	创造性（0-1）
`maxSteps`	number	最大迭代次数
`tools`	object	工具权限
`permission`	object	详细权限配置
`hidden`	boolean	从 @ 菜单隐藏
`disable`	boolean	禁用此 Agent

{
  "agent": {
    "safe-build": {
      "mode": "primary",
      "permission": {
        "edit": "ask",
        "bash": {
          "*": "ask",
          "git status *": "allow",
          "git diff *": "allow"
        }
      }
    }
  }
}

{
  "$schema": "https://opencode.ai/config.json",
  "command": {
    "test": {
      "template": "运行完整的测试套件并显示覆盖率报告。\n关注失败的测试并提供修复建议。",
      "description": "运行测试并分析结果",
      "agent": "build",
      "model": "anthropic/claude-haiku-4-5"
    },
    "component": {
      "template": "创建一个名为 $ARGUMENTS 的 React 组件。\n包含 TypeScript 类型定义和基本结构。",
      "description": "创建新组件"
    }
  }
}

---
description: 运行测试并分析覆盖率
agent: build
model: anthropic/claude-haiku-4-5
---
运行完整的测试套件并显示覆盖率报告。
关注失败的测试并提供修复建议。

/test
/component Button

---
description: 创建文件
---
在目录 $2 中创建名为 $1 的文件，内容为：$3

/create-file config.json src "{ \"key\": \"value\" }"

---
description: 分析测试覆盖率
---
当前测试结果： !`npm test`
基于这些结果，建议如何提高覆盖率。

---
description: 审查组件
---
审查 @src/components/Button.tsx 组件，检查性能问题并提供改进建议。

选项	说明
`template`	命令模板（必需）
`description`	命令描述
`agent`	执行的 Agent
`model`	使用的模型
`subtask`	是否作为子任务执行

{
  "$schema": "https://opencode.ai/config.json",
  "keybinds": {
    "leader": "ctrl+x",
    "app_exit": "ctrl+c,ctrl+d,<leader>q",
    "session_new": "<leader>n",
    "session_list": "<leader>l",
    "model_list": "<leader>m",
    "agent_cycle": "tab",
    "input_submit": "return",
    "input_newline": "shift+return,ctrl+return",
    "session_interrupt": "escape"
  }
}

{"keybinds": {"session_compact": "none"}}

功能	默认快捷键
退出	`Ctrl+c`, `Ctrl+d`, `<leader>q`
打开编辑器	`<leader>e`
主题列表	`<leader>t`
侧边栏切换	`<leader>b`
状态视图	`<leader>s`
导出会话	`<leader>x`
新建会话	`<leader>n`
会话列表	`<leader>l`
时间线	`<leader>g`
中断会话	`Escape`
压缩会话	`<leader>c`
向上翻页	`PageUp`, `Ctrl+Alt+b`
向下翻页	`PageDown`, `Ctrl+Alt+f`
复制消息	`<leader>y`
撤销	`<leader>u`
重做	`<leader>r`
模型列表	`<leader>m`
切换模型变体	`Ctrl+t`
命令列表	`Ctrl+p`
Agent 列表	`<leader>a`
切换 Agent	`Tab`
反向切换	`Shift+Tab`
清空输入	`Ctrl+c`
粘贴	`Ctrl+v`
提交	`Return`
换行	`Shift+Return`

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-local-mcp": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-everything"],
      "enabled": true,
      "environment": { "MY_ENV_VAR": "value" }
    }
  }
}

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "my-remote-mcp": {
      "type": "remote",
      "url": "https://my-mcp-server.com",
      "enabled": true,
      "headers": { "Authorization": "Bearer MY_API_KEY" }
    }
  }
}

{"mcp": {"sentry": {"type": "remote", "url": "https://mcp.sentry.dev/mcp", "oauth": {}}}}

opencode mcp auth sentry

显示我项目中最新的未解决问题。
use sentry

{"mcp": {"context7": {"type": "remote", "url": "https://mcp.context7.com/mcp"}}}

如何配置 Cloudflare Worker 来缓存 JSON API 响应？
use context7

{"mcp": {"gh_grep": {"type": "remote", "url": "https://mcp.grep.app"}}}

搜索 React hooks 的最佳实践示例。
use the gh_grep tool

# 认证
opencode mcp auth my-oauth-server
# 查看状态
opencode mcp list
# 登出
opencode mcp logout my-oauth-server

{"tools": {"my-mcp*": false}}

{
  "mcp": {"my-mcp": {"type": "local", "command": ["bun", "x", "my-mcp-command"], "enabled": true}},
  "tools": {"my-mcp*": false},
  "agent": {"my-agent": {"tools": {"my-mcp*": true}}}
}

语言	LSP 服务器	要求
TypeScript/JavaScript	typescript	项目有 `typescript` 依赖
Python	pyright	安装 `pyright`
Rust	rust-analyzer	安装 `rust-analyzer`
Go	gopls	安装 `go`
Java	jdtls	Java SDK 21+
C/C++	clangd	自动安装
PHP	intelephense	自动安装
Ruby	ruby-lsp	安装 `ruby` 和 `gem`
Bash	bash-language-server	自动安装
Vue	vue-language-server	自动安装
Svelte	svelte-language-server	自动安装
Astro	@astrojs/language-server	自动安装
Lua	lua-language-server	自动安装
Kotlin	kotlin-language-server	自动安装
Swift	sourcekit-lsp	安装 Xcode
Zig	zls	安装 `zig`
Terraform	terraform-ls	自动安装
YAML	yaml-language-server	自动安装

{
  "$schema": "https://opencode.ai/config.json",
  "lsp": {
    "custom-lsp": {
      "command": ["custom-lsp-server", "--stdio"],
      "extensions": [".custom"]
    }
  }
}

{"lsp": false}

{"lsp": {"typescript": {"disabled": true}}}

export OPENCODE_DISABLE_LSP_DOWNLOAD=true

# 检查支持
echo $COLORTERM
# 应输出 truecolor 或 24bit
# 启用 truecolor
export COLORTERM=truecolor

主题名	说明
`opencode`	默认主题
`system`	自动适应终端颜色
`tokyonight`	Tokyo Night 风格
`catppuccin`	Catppuccin 风格
`catppuccin-macchiato`	Catppuccin Macchiato
`gruvbox`	Gruvbox 风格
`nord`	Nord 风格
`kanagawa`	Kanagawa 风格
`everforest`	Everforest 风格
`ayu`	Ayu Dark 风格
`one-dark`	Atom One Dark
`matrix`	黑客风格绿色

/theme

{"theme": "tokyonight"}

{
  "$schema": "https://opencode.ai/theme.json",
  "defs": {
    "bg": "#1a1b26",
    "fg": "#c0caf5",
    "accent": "#7aa2f7",
    "error": "#f7768e",
    "warning": "#e0af68",
    "success": "#9ece6a"
  },
  "theme": {
    "primary": { "dark": "accent", "light": "accent" },
    "text": { "dark": "fg", "light": "#1a1b26" },
    "background": { "dark": "bg", "light": "#ffffff" },
    "error": { "dark": "error", "light": "error" },
    "warning": { "dark": "warning", "light": "warning" },
    "success": { "dark": "success", "light": "success" }
  }
}

/init

# 我的 TypeScript 项目
这是一个使用 bun workspaces 的 SST v3 monorepo 项目。

## 项目结构
- `packages/` - 所有工作区包（functions, core, web 等）
- `infra/` - 基础设施定义（storage.ts, api.ts, web.ts）
- `sst.config.ts` - 主 SST 配置

## 代码规范
- 使用 TypeScript 严格模式
- 共享代码放在 `packages/core/`
- 函数代码放在 `packages/functions/`
- 基础设施按逻辑拆分到 `infra/` 目录

## Monorepo 约定
- 使用工作区名称导入共享模块：`@my-app/core/example`

类型	位置	作用域
项目级	项目根目录 `AGENTS.md`	仅当前项目
全局级	`~/.config/opencode/AGENTS.md`	所有项目

export OPENCODE_DISABLE_CLAUDE_CODE=1

{"instructions": ["CONTRIBUTING.md", "docs/guidelines.md", ".cursor/rules/*.md", "https://raw.githubusercontent.com/my-org/shared-rules/main/style.md"]}

# 项目规则
## 外部文件加载
重要：当遇到文件引用（如 @rules/general.md）时，使用 Read 工具按需加载。

## 开发指南
TypeScript 代码风格：@docs/typescript-guidelines.md
React 组件架构：@docs/react-patterns.md
API 设计规范：@docs/api-standards.md

<Tab 切换到 Plan 模式>
我需要实现用户认证功能，包括登录、注册、密码重置
<分析完成后>
<Tab 切换到 Build 模式>
按照计划开始实现

参考 @src/auth/login.ts 的实现方式，在 @src/auth/register.ts 中添加注册功能

按照这个设计稿实现登录界面 [拖入设计稿图片]

// opencode.json（放在项目根目录）
{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "instructions": ["CONTRIBUTING.md", "docs/DEVELOPMENT.md"],
  "formatter": {
    "prettier": {
      "command": ["npx", "prettier", "--write", "$FILE"]
    }
  }
}

# 项目名称
## 技术栈
- 前端：React + TypeScript + Tailwind
- 后端：Node.js + Express
- 数据库：PostgreSQL

## 目录结构
...

## 编码规范
...

## 常见任务
- 创建新组件：使用 `packages/ui` 目录
- 添加 API：在 `packages/api/src/routes` 创建

{"model": "anthropic/claude-sonnet-4-5", "small_model": "anthropic/claude-haiku-4-5"}

{"compaction": {"auto": true, "prune": true}}

{"tools": {"heavy-mcp*": false}}

/share

{"permission": {"bash": "ask", "edit": "allow"}}

{"agent": {"build": {"permission": {"bash": {"*": "allow", "rm *": "ask", "git push*": "ask", "npm publish": "ask"}}}}}

/details

/thinking

/export

/models

{"model": "openai/gpt-4o"}

{
  "actions": [{ "command": { "action": "sendInput", "input": "\u001b[13;2u" }, "id": "User.sendInput.ShiftEnterCustom" }],
  "keybindings": [{ "keys": "shift+enter", "id": "User.sendInput.ShiftEnterCustom" }]
}

{
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "options": { "baseURL": "http://localhost:11434/v1" },
      "models": { "llama2": { "name": "Llama 2" } }
    }
  }
}

{"autoupdate": false}

{"autoupdate": "notify"}

# 删除配置
rm -rf ~/.config/opencode
# 删除数据
rm -rf ~/.local/share/opencode

/connect

export HTTPS_PROXY=http://proxy.example.com:8080
export HTTP_PROXY=http://proxy.example.com:8080

OpenCode 开源 AI 编程助手完全使用指南

OpenCode 完全使用指南

1. 什么是 OpenCode

1.1 概述

1.2 核心特点

1.3 与 Claude Code 的区别

2. 安装指南

2.1 前置要求

2.2 通用安装（推荐）

2.3 macOS 安装

使用 Homebrew（推荐）

2.4 Linux 安装

Debian/Ubuntu

Arch Linux

2.5 Windows 安装

使用 Chocolatey

使用 Scoop

使用 npm

2.6 使用包管理器

npm / Bun / pnpm / Yarn

2.7 使用 Docker

2.8 使用 Nix

2.9 桌面应用（Beta）

2.10 自定义安装目录

3. 快速开始

3.1 首次配置 Provider

3.2 初始化项目

3.3 基础使用示例

询问代码问题

引用文件

添加新功能

执行 Shell 命令

3.4 Plan 与 Build 模式

3.5 撤销与重做

4. 配置文件详解

4.1 配置文件格式

4.2 配置文件位置

4.3 完整配置示例

4.4 变量替换

环境变量

文件内容

5. Provider 配置

5.1 支持的 Provider

5.2 配置 Anthropic

使用 Claude Pro/Max 订阅

使用 API 密钥

5.3 配置 OpenAI

使用 ChatGPT Plus/Pro 订阅

5.4 配置 OpenCode Zen（推荐新手）

5.5 配置本地模型（Ollama）

5.6 配置 LM Studio

5.7 配置 Amazon Bedrock

5.8 配置 OpenRouter

5.9 禁用/启用特定 Provider

6. TUI 终端界面使用

6.1 启动 TUI

6.2 基本操作

发送消息

换行输入

引用文件

执行 Shell 命令

6.3 内置命令

6.4 导航操作

6.5 编辑器设置

7. Agent 系统

7.1 Agent 类型

主 Agent（Primary）

子 Agent（Subagent）

7.2 使用 Agent

切换主 Agent

调用子 Agent

7.3 自定义 Agent

JSON 配置方式

Markdown 文件方式

7.4 Agent 配置选项

7.5 Agent 权限配置

8. 自定义命令

8.1 创建命令

JSON 配置方式

Markdown 文件方式