OpenCode 安装入门与基础概览

OpenCode 是目前 GitHub 上最热门的开源 AI 编程助手，由 anomalyco 团队开发，拥有超过 190k Star。它运行在终端中，通过自然语言对话帮助你完成编码、调试、重构、代码审查等全流程开发任务。本文将带你从零开始，完成安装、配置，并熟悉 OpenCode 的核心界面和基础用法。

OpenCode 是什么？

OpenCode 是一个终端里的 AI 编程 Agent。与 Copilot 这种以补全为主的工具不同，OpenCode 能够：

• 理解整个项目上下文：自动索引你的代码库，了解项目结构
• 执行多步骤任务：不仅能写代码，还能运行命令、修改文件、管理 Git
• 自主规划和构建：Plan 模式用于分析规划，Build 模式用于落地执行
• 扩展能力强：通过 MCP 协议、Skills、自定义工具、插件等方式无限扩展能力

系统要求

• 操作系统：macOS、Linux、Windows（需要 WSL 或直接使用 Windows 安装方式）
• Node.js：推荐 22+（使用 npm 安装时需要）
• 网络：需要访问 LLM 提供商 API（可配置代理）
• 终端：推荐 iTerm2、Windows Terminal、Kitty、WezTerm 等现代终端

安装 OpenCode

OpenCode 提供多种安装方式，选择最适合你的一种即可。

快速脚本安装（推荐）

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

这是官方推荐的一键安装方式，会自动检测系统并安装对应版本。

包管理器安装

# npm / bun / pnpm / yarn
npm i -g opencode-ai@latest

# macOS / Linux - Homebrew（推荐，始终保持最新）
brew install anomalyco/tap/opencode

# macOS / Linux - 官方 Homebrew formula（更新较慢）
brew install opencode

# Arch Linux
sudo pacman -S opencode

# Arch Linux - AUR 最新版
paru -S opencode-bin

# Windows - Scoop
scoop install opencode

# Windows - Chocolatey
choco install opencode

# 通用 - mise
mise use -g opencode

# Nix
nix run nixpkgs#opencode

自定义安装目录

安装脚本遵循以下优先级选择安装路径：

$OPENCODE_INSTALL_DIR — 自定义安装目录

$XDG_BIN_DIR — XDG 标准路径

$HOME/bin — 用户二进制目录

$HOME/.opencode/bin — 默认回退

# 指定安装到 /usr/local/bin
OPENCODE_INSTALL_DIR=/usr/local/bin curl -fsSL https://opencode.ai/install | bash

桌面版（Beta）

OpenCode 也提供桌面应用，可从 Releases 页面 下载：

| 平台 | 安装方式 |
|------|----------|
| macOS (Apple Silicon) | .dmg |
| macOS (Intel) | .dmg |
| Windows | .exe |
| Linux | .deb、.rpm 或 .AppImage |

# macOS 通过 Homebrew 安装桌面版
brew install --cask opencode-desktop

# Windows 通过 Scoop
scoop bucket add extras && scoop install extras/opencode-desktop

首次运行与配置

安装完成后，在终端输入 opencode 进入交互界面：

opencode

首次运行时，OpenCode 会引导你完成以下配置：

1. 选择模型提供商

OpenCode 支持 75+ LLM 提供商，包括：

• Anthropic：Claude 系列（推荐，对编程任务效果最好）
• OpenAI：GPT 系列
• Google：Gemini 系列
• DeepSeek：高性价比选择
• Ollama / LM Studio：本地模型
• 以及更多第三方提供商

选择提供商后，输入对应的 API Key 即可。

2. 配置文件目录

OpenCode 的配置文件存放在 ~/.config/opencode/ 目录下：

~/.config/opencode/
├── opencode.json      # 主配置文件
├── agents/            # 自定义 Agent
├── commands/          # 自定义命令
├── skills/            # 自定义 Skills
└── mcp/               # MCP 服务器配置

项目级别的配置则存放在项目根目录的 .opencode/ 中，优先级高于全局配置。

OpenCode 核心界面

TUI 终端界面

进入 OpenCode 后，你会看到一个简洁的终端 UI：

• 顶部状态栏：显示当前 Agent（build/plan）、模型名称、会话状态
• 中间对话区：你的消息和 AI 的回复
• 底部输入区：输入消息的地方，支持多行输入（Alt+Enter 换行）

基本交互

你: 帮我写一个 Python 的快速排序函数

OpenCode: 好的，我会创建 quicksort.py ...

然后它会：
1. 分析你的请求
2. 搜索项目中的相关代码
3. 读取需要的文件
4. 创建或修改文件
5. 可能运行测试验证

对话中的特殊符号

在消息中使用 @ 和 / 可以触发特殊功能：

• @filename：引用文件，让 OpenCode 关注特定文件
• /command：执行自定义命令（如 /help、/init、/clear 等）

两种工作模式

OpenCode 内置两个 Agent，按 Tab 键可以随时切换：

Build 模式（默认）

• 全权限：可以读写文件、执行命令
• 适合：日常开发、写代码、修复 bug
• 特点：效率高，能自主完成复杂任务

Plan 模式

• 只读：默认不允许编辑文件
• 适合：探索不熟悉的代码库、分析问题、制定方案
• 特点：更安全，适合在不确定时先规划再执行

使用建议

在面对复杂任务时，推荐的流程是：

先在 Plan 模式下描述需求，让 AI 分析代码库并制定计划

确认计划可行后，切换到 Build 模式执行

执行完成后，再切回 Plan 模式进行 Code Review

核心功能速览

在深入了解每个功能的配置之前，这里快速浏览 OpenCode 的核心能力：

| 功能 | 说明 | 配置方式 |
|------|------|----------|
| 多模型支持 | 75+ LLM 提供商，支持本地模型 | opencode.json → providers |
| Agent 系统 | Build/Plan 双模式 + 自定义 Agent | .opencode/agents/ |
| Sub-Agent | 子代理并行执行任务 | 内置 general agent，支持自定义 |
| Skills 技能 | 可复用的专业指令集 | .opencode/skills/ |
| Rules 规则 | 用 AGENTS.md 定制项目行为 | 项目根目录的 AGENTS.md |
| MCP 服务器 | 接入外部工具和数据源 | opencode.json → mcp |
| 自定义命令 | 快捷指令 /command | .opencode/commands/ |
| CLI 自动化 | 非交互模式，CI/CD 集成 | opencode -p "message" |
| 权限控制 | 精细控制文件/网络/命令权限 | opencode.json → permissions |
| 主题定制 | 自定义配色和界面 | tui.json / Theme 配置 |
| GitHub 集成 | 在 Issue 和 PR 中自动工作 | GitHub App 配置 |

目录结构一览

了解 OpenCode 的文件布局有助于后续深入配置：

项目根目录/
├── .opencode/
│   ├── commands/       # 项目级自定义命令
│   ├── skills/         # 项目级 Skills
│   ├── agents/         # 项目级 Agent 定义
│   └── hooks/          # Hooks 钩子脚本
├── AGENTS.md           # 项目规则文件
└── opencode.json       # 项目级配置（可选，优先级最高）

用户目录 ~/.config/opencode/
├── opencode.json       # 全局配置文件
├── agents/             # 全局 Agent
├── commands/           # 全局自定义命令
├── skills/             # 全局 Skills
└── credentials/        # 凭据信息

常用命令行参数

在终端中运行 opencode 时可以附加以下参数：

# 基本启动
opencode                         # 进入交互模式

# 非交互模式（CI/CD 中使用）
opencode -p "帮我修复所有 lint 错误"

# 指定模型
opencode --model "claude-sonnet-4-20250514"

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

# 使用 Plan 模式启动
opencode --mode plan

# 查看帮助
opencode --help

下一步

现在你已经完成了 OpenCode 的安装和基础了解。接下来的文章中，我们将深入每个模块的详细配置：

• 配置文件：opencode.json 的每个配置项详解
• 模型与 Provider：75+ 提供商的接入、本地模型搭建
• Agent 系统：多 Agent 协作、子代理分工
• Skills 技能：可复用的专业指令集开发
• MCP 扩展：接入外部工具生态
• 更多高级功能

OpenCode 的强大之处在于它的深度可定制性——掌握这些配置后，你将拥有一个完全属于自己工作流的 AI 编程助手。