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

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

2.3 macOS 安装

使用 Homebrew（推荐）

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

2.4 Linux 安装

Debian/Ubuntu

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

Arch Linux

paru -S opencode-bin

2.5 Windows 安装

使用 Chocolatey

choco install opencode

使用 Scoop

scoop install opencode

使用 npm

npm install -g opencode-ai

2.6 使用包管理器

npm / Bun / pnpm / Yarn

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

2.7 使用 Docker

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

2.8 使用 Nix

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

2.9 桌面应用（Beta）

OpenCode 还提供桌面应用程序，可从 Releases 页面 或 opencode.ai/download 下载。

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

2.10 自定义安装目录

安装脚本支持以下优先级顺序的安装路径：

1. $OPENCODE_INSTALL_DIR - 自定义安装目录
2. $XDG_BIN_DIR - XDG 规范路径
3. $HOME/bin - 标准用户目录
4. $HOME/.opencode/bin - 默认回退

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

3. 快速开始

3.1 首次配置 Provider

1. 进入你的项目目录：

cd /path/to/your/project

2. 启动 OpenCode：

opencode

3. 配置 Provider（以 OpenCode Zen 为例）：

/connect

4. 选择 opencode，然后访问 opencode.ai/auth 获取 API 密钥
5. 粘贴你的 API 密钥

3.2 初始化项目

运行初始化命令，让 OpenCode 分析你的项目：

/init

这会创建一个 AGENTS.md 文件，帮助 OpenCode 更好地理解你的项目结构。

💡 提示：建议将 AGENTS.md 提交到 Git 仓库

3.3 基础使用示例

询问代码问题

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

引用文件

使用 @ 符号引用项目中的文件：

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

添加新功能

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

执行 Shell 命令

使用 ! 前缀执行命令：

!npm test

3.4 Plan 与 Build 模式

OpenCode 提供两种主要模式，使用 Tab 键切换：

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

3.5 撤销与重做

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

⚠️ 注意：撤销/重做功能需要项目是 Git 仓库

4. 配置文件详解

4.1 配置文件格式

OpenCode 支持 JSON 和 JSONC（带注释的 JSON）格式：

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

4.2 配置文件位置

配置文件按以下优先级加载（后面的覆盖前面的）：

4.3 完整配置示例

{
  "$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"
  ]
}

4.4 变量替换

环境变量

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

文件内容

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

5. Provider 配置

5.1 支持的 Provider

OpenCode 支持 75+ LLM 提供商，以下是常用的：

5.2 配置 Anthropic

使用 Claude Pro/Max 订阅

/connect

选择 Anthropic → Claude Pro/Max，浏览器会自动打开进行认证。

使用 API 密钥

/connect

选择 Anthropic → Manually enter API Key，然后输入密钥。

5.3 配置 OpenAI

使用 ChatGPT Plus/Pro 订阅

/connect

选择 OpenAI → ChatGPT Plus/Pro，浏览器会自动打开进行认证。

5.4 配置 OpenCode Zen（推荐新手）

OpenCode Zen 是官方提供的经过测试验证的模型列表：

1. 访问 opencode.ai/auth 创建 API 密钥
2. 运行 /connect，选择 opencode
3. 粘贴 API 密钥
4. 运行 /models 查看可用模型

5.5 配置本地模型（Ollama）

{
  "$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" }
      }
    }
  }
}

💡 提示：如果工具调用不工作，尝试在 Ollama 中增加 num_ctx 到 16k-32k

5.6 配置 LM Studio

{
  "$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)" }
      }
    }
  }
}

5.7 配置 Amazon Bedrock

{
  "$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

5.8 配置 OpenRouter

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

5.9 禁用/启用特定 Provider

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

6. TUI 终端界面使用

6.1 启动 TUI

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

6.2 基本操作

发送消息

直接输入文字后按 Enter 发送。

换行输入

• Shift+Enter - 插入换行
• Ctrl+Enter - 插入换行
• Alt+Enter - 插入换行

引用文件

输入 @ 然后模糊搜索文件名：

@src/api/ → 选择文件

执行 Shell 命令

以 ! 开头：

!git status
!npm run build

6.3 内置命令

6.4 导航操作

6.5 编辑器设置

配置 EDITOR 环境变量以使用 /editor 和 /export 命令：

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

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

⚠️ 注意：VS Code 等 GUI 编辑器需要 --wait 参数

7. Agent 系统

7.1 Agent 类型

主 Agent（Primary）

直接交互的主要 Agent，使用 Tab 键切换：

子 Agent（Subagent）

由主 Agent 调用或使用 @ 手动调用：

7.2 使用 Agent

切换主 Agent

按 Tab 键在 Build 和 Plan 之间切换。

调用子 Agent

使用 @ 提及：

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

7.3 自定义 Agent

JSON 配置方式

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

Markdown 文件方式

创建 .opencode/agents/reviewer.md 或 ~/.config/opencode/agents/reviewer.md：

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

7.4 Agent 配置选项

7.5 Agent 权限配置

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

8. 自定义命令

8.1 创建命令

JSON 配置方式

{
  "$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": "创建新组件"
    }
  }
}

Markdown 文件方式

创建 .opencode/commands/test.md：

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

8.2 使用命令

/test
/component Button

8.3 命令模板语法

参数替换

• $ARGUMENTS - 所有参数
• $1, $2, $3 - 位置参数

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

使用：

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

Shell 命令输出

使用 !`command` 语法：

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

文件引用

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

8.4 命令选项

9. 快捷键配置

9.1 Leader 键

OpenCode 使用 Leader 键避免与终端快捷键冲突。默认 Leader 键是 Ctrl+x。 例如，新建会话：先按 Ctrl+x，再按 n。

9.2 自定义快捷键

{
  "$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"
  }
}

9.3 禁用快捷键

设置为 "none" 禁用：

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

9.4 完整快捷键列表

10. MCP 服务器

10.1 什么是 MCP

Model Context Protocol (MCP) 是一种协议，允许 OpenCode 集成外部工具和服务。通过 MCP，你可以：

• 连接数据库
• 集成 API
• 使用第三方服务
• 扩展 AI 能力

10.2 配置本地 MCP 服务器

{
  "$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"
      }
    }
  }
}

10.3 配置远程 MCP 服务器

{
  "$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"
      }
    }
  }
}

10.4 常用 MCP 示例

Sentry（错误监控）

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

然后运行认证：

opencode mcp auth sentry

使用：

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

Context7（文档搜索）

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

使用：

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

Grep by Vercel（代码搜索）

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

使用：

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

10.5 OAuth 认证

对于需要认证的 MCP 服务器：

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

10.6 MCP 权限管理

全局禁用

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

按 Agent 启用

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

11. LSP 语言服务器

11.1 内置 LSP 支持

OpenCode 内置多种语言的 LSP 服务器支持：

11.2 LSP 如何工作

当 OpenCode 打开文件时：

1. 检查文件扩展名
2. 启动对应的 LSP 服务器
3. 获取诊断信息（错误、警告）
4. 将诊断反馈给 LLM

11.3 自定义 LSP 配置

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

11.4 禁用 LSP

禁用所有 LSP

{"lsp": false}

禁用特定 LSP

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

11.5 禁用自动下载

export OPENCODE_DISABLE_LSP_DOWNLOAD=true

12. 主题与个性化

12.1 终端要求

为了正确显示主题，你的终端需要支持 truecolor（24 位色）：

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

12.2 内置主题

12.3 切换主题

使用命令

/theme

配置文件

{"theme": "tokyonight"}

12.4 自定义主题

创建 ~/.config/opencode/themes/my-theme.json 或 .opencode/themes/my-theme.json：

{
  "$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" }
  }
}

12.5 颜色格式

• Hex 颜色: "#ffffff"
• ANSI 颜色: 3（0-255）
• 引用定义: "primary"
• 深浅变体: {"dark": "#000", "light": "#fff"}
• 无颜色: "none"（使用终端默认）

13. Rules 自定义指令

13.1 什么是 AGENTS.md

AGENTS.md 是一个特殊文件，包含给 LLM 的自定义指令，类似于 Cursor 的 rules。它帮助 OpenCode 理解你的项目结构和编码规范。

13.2 创建 AGENTS.md

自动生成

/init

这会扫描项目并自动生成 AGENTS.md。

手动创建

# 我的 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`

13.3 文件位置

13.4 Claude Code 兼容性

OpenCode 支持 Claude Code 的文件约定作为回退：

• CLAUDE.md → 用作 AGENTS.md
• ~/.claude/CLAUDE.md → 用作全局指令

禁用兼容性：

export OPENCODE_DISABLE_CLAUDE_CODE=1

13.5 引用外部文件

使用配置文件

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

在 AGENTS.md 中引用

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

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

14. 最佳实践与进阶技巧

14.1 高效工作流

1. 先规划后执行

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

2. 使用 @ 引用上下文

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

3. 拖放图片

在终端中拖放图片，可以让 LLM 参考设计稿：

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

14.2 项目设置建议

创建项目专属配置

// 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"]
    }
  }
}

设置完善的 AGENTS.md

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

## 目录结构
...

## 编码规范
...

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

14.3 性能优化

1. 使用 small_model

为轻量任务（如生成标题）配置更便宜的模型：

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

2. 启用自动压缩

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

3. 合理配置 MCP

避免添加太多 MCP 服务器，每个都会增加上下文：

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

14.4 团队协作

1. 共享配置

将以下文件提交到 Git：

• opencode.json
• AGENTS.md
• .opencode/ 目录

2. 分享会话

/share

获取可分享的链接。

14.5 安全最佳实践

1. 使用权限控制

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

2. 敏感命令需要确认

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

14.6 调试技巧

1. 查看工具执行详情

/details

2. 查看思考过程

/thinking

3. 导出会话进行分析

/export

15. 常见问题解答

Q1: 如何更换模型？

/models

或在配置文件中设置：

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

Q2: Shift+Enter 不工作怎么办？

某些终端需要特殊配置。Windows Terminal 用户需在 settings.json 中添加：

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

Q3: 如何使用本地模型？

配置 Ollama 或 LM Studio：

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

Q4: 撤销操作不工作？

确保项目是 Git 仓库。撤销功能依赖 Git 来恢复文件更改。

Q5: 如何禁用自动更新？

{"autoupdate": false}

或只通知不更新：

{"autoupdate": "notify"}

Q6: API 密钥存储在哪里？

~/.local/share/opencode/auth.json

Q7: 如何完全重置 OpenCode？

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

Q8: 遇到 "content filter" 错误（Azure）？

将 Azure 资源的内容过滤器从 DefaultV2 改为 Default。

Q9: 如何查看可用的 Provider？

/connect

然后搜索或滚动查看所有可用的 Provider。

Q10: 如何使用代理？

设置环境变量：

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

📖 更多资源

• 官方文档: https://opencode.ai/docs
• GitHub 仓库: https://github.com/anomalyco/opencode