如何安装和使用 OpenCode：完整指南

大约 13 分钟

如何安装和使用 OpenCode：完整指南

OpenCode 是一款开源的 AI 编码代理，将人工智能的强大能力直接带到你的终端。与传统的运行于编辑器或浏览器的 AI 编码工具不同，OpenCode 提供了基于终端的界面、桌面应用和 IDE 插件—all designed to help you become a more productive developer。这份全面的指南将带你了解如何有效地安装、配置和使用 OpenCode。

什么是 OpenCode？

OpenCode 是一款 AI 驱动的编码助手，帮助你：

更快编写代码，通过智能代码生成和补全
高效调试，分析错误并提供修复建议
理解代码库，通过自然语言查询
添加功能，自动规划与实现
代码审查，通过 AI 分析和建议
自动化工作流，使用 AI 代理和自定义工具

它支持多个 LLM 提供商，包括 Anthropic、OpenAI、Google 等，给予你选用最适合需求的模型的自由。

系统要求

前置条件

安装 OpenCode 之前，请确保你具备：

现代终端模拟器（用于 TUI 界面）：
- WezTerm - 跨平台
- Alacritty - 跨平台
- Ghostty - Linux 和 macOS
- Kitty - Linux 和 macOS
Node.js（用于通过 npm/bun/pnpm/yarn 安装）：
- 建议使用 Node.js v18 或更高版本
LLM 提供商的 API 密钥：
- Anthropic API 密钥（用于 Claude 模型）
- OpenAI API 密钥（用于 GPT 模型）
- 或其他支持提供商的密钥

安装方法

方法 1：安装脚本（推荐）

安装 OpenCode 最快捷的方式是使用官方安装脚本：

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

此方法适用于 macOS、Linux 和 Windows（通过 Git Bash 或 WSL）。

方法 2：使用 Node.js 包管理器

使用 npm：

npm install -g opencode-ai

使用 Bun：

bun install -g opencode-ai

使用 pnpm：

pnpm install -g opencode-ai

使用 Yarn：

yarn global add opencode-ai

方法 3：使用 Homebrew（macOS & Linux）

brew install opencode

方法 4：使用 Paru（Arch Linux）

paru -S opencode-bin

方法 5：Windows 专用安装方式

使用 Chocolatey：

choco install opencode

使用 Scoop：

scoop bucket add extras
scoop install extras/opencode

使用 Mise：

mise use -g github:sst/opencode

方法 6：Docker

容器化使用：

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

方法 7：下载二进制文件

你也可以直接从 GitHub Releases 页面下载预编译的二进制文件。

验证安装

安装完成后，验证是否成功：

opencode --version

应显示版本号。

初始配置

连接到 OpenCode Zen（推荐初学者）

OpenCode Zen 是 OpenCode 团队测试和验证的精选模型列表，是入门最简单的方式。

启动 OpenCode：

cd /path/to/your/project
opencode

在 TUI 中运行连接命令：

/connect

从提供商列表中选择 “opencode”
访问认证链接：opencode.ai/auth
登录并添加计费信息（或使用可用的免费额度）
复制 API 密钥，并在终端提示时粘贴

连接到其他提供商

你也可以将 OpenCode 连接到其他 LLM 提供商：

使用 `/connect` 命令：

/connect

选择你偏好的提供商（Anthropic、OpenAI、Google 等），然后按照认证流程操作。

使用 CLI 认证：

opencode auth login

这将引导你配置来自 Models.dev 上任何提供商的 API 密钥。

列出已配置提供商：

opencode auth list

或简写：

opencode auth ls

注销某个提供商：

opencode auth logout

设置项目上下文

配置提供商后，为项目初始化 OpenCode：

cd /path/to/your/project

启动 OpenCode：

opencode

运行初始化命令：

/init

该命令将分析项目结构并在项目根目录创建 AGENTS.md 文件。此文件帮助 OpenCode 了解你的编码风格、框架和项目架构。

小贴士：将 AGENTS.md 提交到 Git，这有助于保持团队一致性，并随着时间推移提升 OpenCode 对项目的理解。

使用终端用户界面（TUI）

OpenCode 的 TUI 在终端提供交互式体验。

启动 TUI

只需运行：

opencode

或带可选参数：

# 继续上次会话
opencode --continue

# 继续特定会话
opencode --session <session-id>

# 使用提示启动
opencode --prompt "解释这个代码库"

# 使用特定模型
opencode --model anthropic/claude-sonnet-4-5

# 使用特定代理
opencode --agent plan

基本 TUI 导航

滚动：使用鼠标滚轮或方向键
切换模式：按 Tab 键切换“计划模式”和“构建模式”
运行命令：输入 / 调出命令面板
搜索文件：输入 @ 模糊搜索项目文件
退出：按 Ctrl+C 或输入 /exit

提问

你可以就代码库向 OpenCode 提问：

@packages/functions/src/api/index.ts 中认证是如何实现的？

使用 @ 符号引用特定文件，OpenCode 会分析该文件并详细解答。

添加功能

OpenCode 擅长通过两种模式工作流添加新功能：

步骤 1：计划模式

按 Tab 切换到计划模式
描述你的需求：

用户删除笔记时，我们希望在数据库中将其标记为已删除。
然后创建一个界面展示所有最近删除的笔记。
在这个界面，用户可以恢复或者彻底删除笔记。

审查建议计划
用反馈迭代：

我们希望使用我之前用过的设计来设计这个新界面。
[图像 #1] 请参考这张图片作为参考。

小贴士：你可以将图片拖拽到终端，OpenCode 会扫描并分析它们。

步骤 2：构建模式

再次按 Tab 切换到构建模式
批准实现：

好的！请开始修改。

OpenCode 会自动实现功能并创建或修改相应文件。

直接修改代码

对于简单修改，你可以跳过计划阶段：

我们需要给 /settings 路由添加认证。
参考 @packages/functions/src/notes.ts 中 /notes 路由的实现，
在 @packages/functions/src/settings.ts 中实现相同逻辑。

撤销与重做

操作失误？使用撤销命令：

/undo

撤销上一次改动，并允许你调整提示。

重做撤销的操作：

/redo

可以多次运行 /undo 以回退多次更改。

CLI 命令

OpenCode 提供强大的命令行工具，方便程序化访问和自动化。

直接执行提示

非交互式执行 OpenCode 命令：

opencode run "解释 JavaScript 中闭包的工作原理"

适合脚本、自动化或快速解答，无需启动 TUI。

管理模型

列出所有可用模型：

opencode models

按提供商筛选：

opencode models anthropic

刷新模型缓存（当新增模型时）：

opencode models --refresh

显示详细的模型信息及费用：

opencode models --verbose

启动无头服务器

开启 HTTP 服务器以供 API 访问：

opencode serve

自定义端口：

opencode serve --port 3000

便于整合到 Web 应用或加快脚本响应速度（避免 MCP 服务器冷启动）。

附加到服务器

一个终端启动服务器：

opencode serve

另一个终端附加，提升执行速度：

opencode run --attach http://localhost:4096 "解释 JavaScript 中 async/await"

管理代理

创建新的自定义代理：

opencode agent create

引导你创建带自定义系统提示和工具配置的代理。

GitHub 集成

安装 GitHub 代理以自动化仓库流程：

opencode github install

配置 GitHub Actions 工作流，实现自动代码审查和问题处理。

升级 OpenCode

升级到最新版本：

opencode upgrade

升级到指定版本：

opencode upgrade v0.1.48

指定安装方式：

opencode upgrade --method brew

配置

OpenCode 支持通过 JSON 配置文件进行灵活配置。

配置位置

配置文件会被合并（非覆盖），支持全局、项目专用及自定义配置。

全局配置：~/.config/opencode/opencode.json
- 用于主题、提供商、快捷键及通用设置
项目配置：项目根目录下的 opencode.json
- 用于项目专用的提供商、代理或设置
- 可安全提交到 Git
自定义配置路径：通过环境变量 OPENCODE_CONFIG 指定
自定义配置目录：通过环境变量 OPENCODE_CONFIG_DIR 指定

基本配置示例

创建如下结构的配置文件：

{
  "$schema": "https://opencode.ai/config.json",
  
  // 主题选择
  "theme": "opencode",
  
  // 使用的主模型
  "model": "anthropic/claude-sonnet-4-5",
  
  // 用于轻量任务的小模型
  "small_model": "anthropic/claude-haiku-4-5",
  
  // 自动更新设置
  "autoupdate": true
}

配置提供商

直接在配置中配置 API 密钥：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "{env:ANTHROPIC_API_KEY}"
      }
    },
    "openai": {
      "options": {
        "apiKey": "{env:OPENAI_API_KEY}"
      }
    }
  }
}

建议使用环境变量以保障安全，语法为 {env:变量名}。

使用文件引用

你也可以引用文件存储敏感信息：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "openai": {
      "options": {
        "apiKey": "{file:~/.secrets/openai-key}"
      }
    }
  }
}

自定义命令

定义重复任务的自定义命令：

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

在 TUI 中通过输入 /test 或 /component MyComponent 使用自定义命令。

自定义代理

创建专业代理：

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "code-reviewer": {
      "description": "审查代码，关注最佳实践和潜在问题",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "你是一名代码审查员。关注安全性、性能和可维护性。",
      "tools": {
        "write": false,
        "edit": false
      }
    }
  }
}

权限配置

控制 OpenCode 执行操作是否需征求用户同意：

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

这会要求编辑和 Bash 操作获得用户批准。

代码格式化工具

配置自动代码格式化：

{
  "$schema": "https://opencode.ai/config.json",
  "formatter": {
    "prettier": {
      "disabled": false
    },
    "custom-prettier": {
      "command": ["npx", "prettier", "--write", "$FILE"],
      "environment": {
        "NODE_ENV": "development"
      },
      "extensions": [".js", ".ts", ".jsx", ".tsx"]
    }
  }
}

TUI 设置

自定义终端界面：

{
  "$schema": "https://opencode.ai/config.json",
  "tui": {
    "scroll_speed": 3,
    "scroll_acceleration": {
      "enabled": true
    }
  }
}

高级功能

分享对话

与团队分享你的对话记录：

/share

此命令创建可分享链接并复制到剪贴板。默认不分享对话。

配置分享行为：

{
  "share": "manual"  // "manual"（手动）, "auto"（自动）, 或 "disabled"（禁用）
}

MCP 服务器

模型上下文协议（MCP）服务器扩展 OpenCode 能力：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/files"]
    }
  }
}

说明和规则

提供项目特定说明：

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": [
    "CONTRIBUTING.md",
    "docs/guidelines.md",
    ".cursor/rules/*.md"
  ]
}

OpenCode 会利用这些文件理解你的项目编码标准和约定。

环境变量

使用环境变量配置 OpenCode：

# 自动分享会话
export OPENCODE_AUTO_SHARE=true

# 自定义配置路径
export OPENCODE_CONFIG=/path/to/config.json

# 配置目录路径
export OPENCODE_CONFIG_DIR=/path/to/config-dir

# 禁用自动更新
export OPENCODE_DISABLE_AUTOUPDATE=true

# 禁用默认插件
export OPENCODE_DISABLE_DEFAULT_PLUGINS=true

# 启用实验性模型
export OPENCODE_ENABLE_EXPERIMENTAL_MODELS=true

# 启用 Exa 网页搜索
export OPENCODE_ENABLE_EXA=true

实验性功能

启用实验功能：

export OPENCODE_EXPERIMENTAL=true

具体实验功能：

# 启用图标发现
export OPENCODE_EXPERIMENTAL_ICON_DISCOVERY=true

# 禁用 TUI 中的选择即复制
export OPENCODE_EXPERIMENTAL_DISABLE_COPY_ON_SELECT=true

# Bash 命令的最大输出长度
export OPENCODE_EXPERIMENTAL_BASH_MAX_OUTPUT_LENGTH=10000

# Bash 命令的默认超时时长（毫秒）
export OPENCODE_EXPERIMENTAL_BASH_DEFAULT_TIMEOUT_MS=30000