OpenCode 开源AI编程助手完全使用指南（零基础入门到精通）

本文基于 OpenCode 官方文档（https://opencode.ai/docs）和 GitHub 仓库（https://github.com/anomalyco/opencode）精心编写，专为零基础新手打造，全面覆盖从安装部署到进阶使用的所有核心操作，助力新手快速上手、熟练运用。

📚 目录

• 1. 什么是 OpenCode
• 2. 安装指南
• 3. 快速开始
• 4. 配置文件详解
• 5. Provider 配置
• 6. TUI 终端界面使用
• 7. Agent 系统
• 8. 自定义命令
• 9. 快捷键配置
• 10. MCP 服务器
• 11. LSP 语言服务器
• 12. 主题与个性化
• 13. Rules 自定义指令
• 14. 最佳实践与进阶技巧
• 15. 常见问题解答

1. 什么是 OpenCode

1.1 概述

OpenCode 是一款 100% 开源的 AI 编程代理（Coding Agent），支持终端界面（TUI）、桌面应用和 IDE 扩展三种便捷使用方式，核心目标是帮助开发者大幅提升编程效率，具体可实现以下功能：

• 🤖 与 AI 对话式编写代码，降低编码门槛

• 📝 快速分析和深度理解代码库结构与逻辑

• 🔧 自动修改代码、重构优化，减少重复工作

• 🐛 高效调试代码、定位并修复潜在问题

• 📚 自动生成代码文档和测试用例，完善项目规范

1.2 核心特点

特点	说明
100% 开源	采用 MIT 开源许可证，代码完全开放透明，支持开发者自由定制、扩展功能，适配个性化需求。
多 Provider 支持	兼容 Claude、OpenAI、Google 及各类本地模型等 75+ 提供商，灵活选择适配自身的 AI 模型。
开箱即用的 LSP	内置语言服务器（LSP）支持，无需额外配置，即可提供智能代码诊断、实时代码提示等便捷功能。
TUI 优先设计	由 Neovim 资深用户打造，聚焦终端操作体验，交互流畅、操作高效，适配开发者日常终端工作习惯。
客户端/服务器架构	支持远程控制功能，可通过手机等设备，远程驱动桌面端的 OpenCode 开展编程工作，提升灵活性。
MCP 协议支持	可灵活扩展外部工具和服务，打破功能边界，进一步拓展 AI 编程的能力范围。

1.3 与 Claude Code 的区别

对比项	OpenCode	Claude Code
开源性	✅ 100% 开源，可自由定制	❌ 闭源软件，无法自定义扩展
Provider	✅ 不绑定任何提供商，灵活切换	❌ 仅限 Anthropic，需修改配置才能使用第三方
LSP 支持	✅ 开箱即用，无需额外配置	❌ 无内置 LSP 支持，缺乏智能提示
扩展性	✅ 支持插件、MCP 及自定义工具，扩展性强	扩展性有限，无法灵活拓展功能

2. 安装指南

2.1 前置要求

1. 终端模拟器（推荐以下跨平台/系统专属工具）：WezTerm（跨平台）、Alacritty（跨平台）、Ghostty（Linux/macOS）、Kitty（Linux/macOS）、Windows Terminal（Windows）；

2. LLM Provider 的 API 密钥（至少需准备一个，用于对接 AI 模型，确保 OpenCode 正常使用）。

2.2 通用安装（推荐）

该方式适用于 macOS 和 Linux 系统，操作最简单，一键完成安装：

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

2.3 macOS 安装

推荐使用 Homebrew 安装，提供两种方式，其中官方 tap 更新速度更快，优先选择：

# 官方 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 提供桌面应用（目前处于 Beta 版本），可从官方 Releases 页面或 opencode.ai/download 下载，支持多平台，也可通过包管理器快速安装：

平台	下载文件
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

2.10 自定义安装目录

安装脚本支持自定义安装目录，目录优先级顺序（从高到低）：$OPENCODE_INSTALL_DIR > $XDG_BIN_DIR > $HOME/bin > $HOME/.opencode/bin（默认回退目录），自定义安装示例如下：

OPENCODE_INSTALL_DIR=/usr/local/bin curl -fsSL https://opencode.ai/install | bash

3. 快速开始

3.1 首次配置 Provider

安装完成后，需按照以下步骤完成首次配置，此处以 OpenCode Zen 为例（新手优先推荐，配置最简单）：

# 进入你的项目目录（替换为实际项目路径）
cd /path/to/your/project

# 启动 OpenCode 应用
opencode

# 输入以下命令，配置 Provider（输入后按 Enter 执行）
/connect

执行命令后，选择 opencode 选项，然后访问 opencode.ai/auth 获取 API 密钥，将密钥粘贴到终端中，即可完成首次配置。

3.2 初始化项目

配置完成后，运行以下初始化命令，让 OpenCode 自动分析项目结构，并生成 AGENTS.md 文件（建议将该文件提交到 Git 仓库，方便后续协作）：

/init

3.3 基础使用示例

• 询问代码问题：直接在终端输入 给我简单介绍一下这个代码库，按 Enter 即可发送请求，AI 会快速给出回复；

• 引用文件：输入 @ 符号后，模糊搜索目标文件名，例如 @src/components/Button.tsx 这个组件是如何工作的？，AI 会聚焦该文件进行分析；

• 添加新功能：输入 请在 @src/api/auth.ts 中添加用户登录功能，AI 会自动在指定文件中实现对应功能；

• 执行 Shell 命令：以 ! 前缀开头，输入终端命令即可执行，例如 !npm test，可快速运行项目测试。

3.4 Plan 与 Build 模式

OpenCode 提供两种核心工作模式，使用 Tab 键即可切换，适配不同的开发场景，满足多样化需求：

模式	说明	适用场景
Build	拥有完整操作权限，可直接修改项目文件、执行各类操作	实际开发工作（如编写代码、修改功能、修复 bug 等）
Plan	只读模式，仅对项目进行分析、规划，不修改任何文件	代码审查、需求规划、方案设计等无需修改文件的场景

两种模式的使用示例：

# 先用 Plan 模式规划方案（按 Tab 键切换至 Plan 模式）
实现一个用户删除功能，要求软删除，并提供恢复界面

# 确认方案无误后，切换到 Build 模式执行（按 Tab 键切换）
按照刚才的计划开始实现

3.5 撤销与重做

OpenCode 支持撤销和重做操作，需确保当前项目已初始化 Git 仓库（依赖 Git 功能恢复文件更改），具体命令如下：

/undo   # 撤销上一个操作（包括文件修改、命令执行等）
/redo   # 重做已撤销的操作

4. 配置文件详解

4.1 配置文件格式

OpenCode 支持 JSON 和 JSONC（带注释的 JSON）两种配置文件格式，新手可先参考以下基础示例，快速了解配置结构：

{
  "$schema": "https://opencode.ai/config.json",
  // 主题配置（指定 OpenCode 界面主题）
  "theme": "opencode",
  // 默认使用的 AI 模型
  "model": "anthropic/claude-sonnet-4-5",
  // 是否开启自动更新（建议开启，及时获取功能优化）
  "autoupdate": true
}

4.2 配置文件位置

配置文件按以下优先级加载（优先级高的配置会覆盖优先级低的配置），方便开发者根据需求设置全局或项目专属配置：

优先级	位置	说明
1	.well-known/opencode	远程组织配置，适用于团队统一配置
2	~/.config/opencode/opencode.json	全局用户配置，对所有项目生效
3	OPENCODE_CONFIG 环境变量	自定义配置文件路径，灵活指定配置位置
4	项目根目录 opencode.json	项目专属配置，仅对当前项目生效
5	.opencode 目录	存放 agents、commands 等相关配置文件
6	OPENCODE_CONFIG_CONTENT 环境变量	运行时临时覆盖配置，无需修改配置文件

4.3 完整配置示例

{
  "$schema": "https://opencode.ai/config.json",
  
  // 主题设置（可替换为自己喜欢的主题，如 tokyonight）
  "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  // 开启 mdns 服务
  },
  
  // 工具权限设置（控制 AI 可执行的操作）
  "permission": {
    "edit": "allow",  // 允许 AI 编辑文件
    "bash": "ask"  // 执行 Shell 命令前询问用户
  },
  
  // 自动压缩（优化上下文，提升响应速度）
  "compaction": {
    "auto": true,  // 开启自动压缩
    "prune": true  // 开启修剪无用上下文
  },
  
  // 指令文件（指定 AI 需遵循的项目规范文档）
  "instructions": [
    "CONTRIBUTING.md",
    "docs/guidelines.md"
  ]
}

4.4 变量替换

配置文件支持环境变量和文件内容替换，可灵活适配不同场景的配置需求，无需手动修改配置文件，具体用法如下：

1. 环境变量替换（适用于敏感信息，如 API 密钥，避免直接写入配置文件）：

{
  "model": "{env:OPENCODE_MODEL}",  // 引用环境变量中的模型配置
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "{env:ANTHROPIC_API_KEY}"  // 引用环境变量中的 API 密钥
      }
    }
  }
}

2. 文件内容替换（适用于需读取外部文件内容的场景）：

{
  "provider": {
    "openai": {
      "options": {
        "apiKey": "{file:~/.secrets/openai-key}"  // 读取指定文件中的 API 密钥
      }
    }
  }
}

5. Provider 配置

5.1 支持的 Provider

OpenCode 兼容 75+ 种 LLM 提供商，涵盖官方推荐、云端模型、本地模型等类型，常用提供商及详细说明如下，新手可优先选择 OpenCode Zen：

Provider	说明
OpenCode Zen	官方推荐，精选经过验证的模型列表，配置简单，新手友好，无需复杂操作即可上手。
Anthropic	提供 Claude 系列模型，擅长代码分析、生成和调试，适配复杂编程场景。
OpenAI	提供 GPT 系列模型，通用性强，适配各类编程需求，上手门槛低。
Google Vertex AI	谷歌官方提供，支持 Gemini 系列模型，适配云端开发场景。
Amazon Bedrock	AWS 托管的多种 AI 模型，适配云端开发、企业级场景，稳定性强。
OpenRouter	聚合多个提供商的模型，可灵活切换不同模型，适配多样化需求。
Ollama	支持本地运行 AI 模型，无需联网，隐私性强，适合对数据安全有要求的场景。
LM Studio	本地模型管理工具，支持多种本地模型，操作简单，适合新手尝试本地模型。

5.2 配置 Anthropic

支持两种配置方式，可根据自身使用场景（订阅版/API 版）按需选择，操作简单：

• 使用 Claude Pro/Max 订阅：输入 /connect 命令，选择 Anthropic → Claude Pro/Max，浏览器会自动打开认证页面，完成认证即可；

• 使用 API 密钥：输入 /connect 命令，选择 Anthropic → Manually enter API Key，输入提前获取的 API 密钥，即可完成配置。

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 密钥粘贴到终端中，按 Enter 确认；

4. 运行 /models 命令，即可查看当前可用的所有模型。

5.5 配置本地模型（Ollama）

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",  // 本地 Ollama 模型名称
      "options": {
        "baseURL": "http://localhost:11434/v1"  // Ollama 本地服务地址
      },
      "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)",  // 本地 LM Studio 模型名称
      "options": {
        "baseURL": "http://127.0.0.1:1234/v1"  // LM Studio 本地服务地址
      },
      "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",  // AWS 区域（按需替换）
        "profile": "my-aws-profile"  // AWS 命名配置文件（按需替换）
      }
    }
  }
}

也可通过环境变量快速配置，无需修改配置文件：

# 使用 AWS 访问密钥配置
AWS_ACCESS_KEY_ID=XXX AWS_SECRET_ACCESS_KEY=YYY opencode

# 使用 AWS 命名配置文件配置
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  // 不允许 fallback 到其他提供商
            }
          }
        }
      }
    }
  }
}

5.9 禁用/启用特定 Provider

{
  "$schema": "https://opencode.ai/config.json",
  // 禁用指定 Provider（无需删除配置，临时禁用）
  "disabled_providers": ["openai", "gemini"],
  
  // 或只启用指定 Provider（仅保留需要的 Provider）
  "enabled_providers": ["anthropic", "opencode"]
}

6. TUI 终端界面使用

6.1 启动 TUI

# 在当前目录启动 TUI 界面
opencode

# 指定项目目录启动 TUI 界面（替换为实际项目路径）
opencode /path/to/project

6.2 基本操作

• 发送消息：直接在终端输入文字，按 Enter 键即可发送给 AI，获取响应；

• 换行输入：需要换行时，按 Shift+Enter、Ctrl+Enter 或 Alt+Enter 均可插入换行；

• 引用文件：输入 @ 符号后，模糊搜索目标文件名（如 @src/api/），选择对应文件即可引用；

• 执行 Shell 命令：以 ! 符号开头，输入终端命令（如 !git status、!npm run build），按 Enter 即可执行。

6.3 内置命令

命令	快捷键	说明
/connect	-	连接 LLM Provider，用于首次配置或切换不同的 Provider，支持多种 Provider 快速切换
/init	-	初始化当前项目，自动分析项目结构，生成 AGENTS.md 文件，便于后续 AI 理解项目
/undo	Ctrl+Z	撤销上一个操作，包括文件修改、命令执行等，依赖 Git 仓库实现恢复功能
/redo	Ctrl+Y	重做已撤销的操作，恢复之前被撤销的文件修改或命令执行结果
/models	-	查看当前已配置 Provider 下的所有可用 AI 模型，可快速了解当前可使用的模型列表
/clear	Ctrl+L	清空终端界面内容，保持界面整洁，不影响当前会话和项目状态
/exit	Ctrl+D	退出 OpenCode TUI 界面，返回终端正常状态，不影响项目文件