OpenCode 安装配置与入门实战指南：从零搭建 AI 编程工作台

OpenCode 安装配置与入门实战指南：从零搭建 AI 编程工作台

引言

OpenCode 是目前 GitHub 上最热门的开源 AI 编程助手，拥有超过 160K Star、900+ 贡献者和每月 750 万活跃开发者。它既可以在终端中使用，也提供桌面应用和 IDE 扩展，支持 75 种以上的 LLM 提供商——包括 Claude、GPT、Gemini 以及本地模型。

对于刚接触 OpenCode 的开发者来说，正确的安装和初始配置是高效使用它的基础。本文将从零开始，带你完成 OpenCode 的安装、模型配置和首个项目的实战流程，让你在 10 分钟内搭建好自己的 AI 编程工作台。

1. 环境准备

OpenCode 基于 Node.js 构建。在安装之前，请确保你的系统已安装 Node.js 18 或更高版本：

node --version

如果尚未安装 Node.js，推荐使用 nvm（Node Version Manager）或直接从 nodejs.org 下载安装。

Windows 用户请注意：OpenCode 官方文档建议在 WSL（Windows Subsystem for Linux）中使用，以获得最佳性能和完整的终端特性兼容性。如果你使用 WSL，本文中的所有命令均适用。

2. 安装 OpenCode

OpenCode 提供四种安装方式，你可以根据使用习惯任选其一。

方式一：一键安装脚本（推荐）

这是最快捷的方式，适用于 macOS 和 Linux：

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

该脚本会自动检测系统环境，完成下载和安装。

方式二：npm 全局安装

如果你已经在使用 Node.js 生态，通过 npm 安装最为自然：

npm install -g opencode-ai

安装完成后，使用 opencode 命令启动：

opencode

方式三：Homebrew（macOS）

brew install opencode

方式四：桌面应用

如果你更喜欢图形界面，可以从 opencode.ai/download 或 GitHub Releases 页面下载桌面版，支持 macOS、Windows 和 Linux。

# 也可以使用包管理器安装桌面版
brew install --cask opencode       # macOS
winget install opencode            # Windows
paru -S opencode-bin               # Arch Linux

安装完成后，在终端中进入任意项目目录，输入 opencode 即可启动 TUI（终端用户界面）。

opencode

第一次启动时，OpenCode 会引导你完成初始配置，包括模型提供商的选择和 API Key 的设置。

3. 配置模型提供商

OpenCode 的核心优势之一是对多种 LLM 提供商的广泛支持。你可以使用自己的 API Key 接入任意服务商，也可以通过已有的订阅账户免额外付费使用。

3.1 使用自有 API Key

如果你已有 Anthropic、OpenAI 或其他提供商的 API Key，可以在配置文件中设置。OpenCode 的全局配置文件位于：

• Linux/macOS：~/.config/opencode/opencode.json
• Windows：%APPDATA%\opencode\opencode.json

一个典型的配置示例：

{
  "model": "anthropic/claude-sonnet-4-20250514",
  "providers": {
    "anthropic": {
      "apiKey": "sk-ant-xxx"
    }
  }
}

或者同时配置多个提供商，方便按需切换：

{
  "model": "anthropic/claude-sonnet-4-20250514",
  "providers": {
    "anthropic": {
      "apiKey": "sk-ant-xxx"
    },
    "openai": {
      "apiKey": "sk-xxx"
    },
    "google": {
      "apiKey": "xxx"
    }
  }
}

3.2 使用 OpenCode Zen（零配置模型服务）

如果你还没有 API Key，或者希望使用经过 OpenCode 官方验证和优化的模型，可以使用 OpenCode Zen。Zen 提供了一组精选模型，专门针对编程任务进行了测试和调优。

# 在 TUI 中运行以下命令
/login zen

然后访问 opencode.ai/auth 完成认证即可。

3.3 使用 GitHub Copilot 订阅

如果你已订阅 GitHub Copilot，可以直接在 OpenCode 中使用：

# 在 TUI 中运行
/login github

完成 GitHub OAuth 认证后，即可使用 Copilot 账户的额度。

3.4 使用 ChatGPT Plus/Pro 订阅

持有 ChatGPT Plus 或 Pro 订阅的用户同样可以直接接入：

# 在 TUI 中运行
/login openai

通过 OpenAI OAuth 认证后即可使用。

4. 项目级配置：opencode.json

除了全局配置，你还可以在每个项目根目录下创建 opencode.json，实现项目级别的设置覆盖：

{
  "model": "openai/gpt-5",
  "temperature": 0.2
}

项目级配置的优先级高于全局配置。这种分层设计使得你可以为不同项目指定不同的模型和行为参数——例如，前端项目使用更擅长 UI 生成的模型，后端项目使用更擅长逻辑推理的模型。

5. 初始化项目：生成 AGENTS.md

进入项目后，第一步建议让 OpenCode 分析项目并生成 AGENTS.md 文件：

opencode "请分析这个项目的结构并生成 AGENTS.md 文件"

或者更直接地：

opencode "/init"

AGENTS.md 会包含：

• 项目技术栈说明
• 目录结构概述
• 代码规范和约定
• 测试命令
• 构建和部署流程

这个文件将作为 OpenCode 每次对话的系统上下文，使其更好地理解你的项目。你可以手动编辑它来补充更多项目信息。

一个典型的 AGENTS.md 示例：

# Project Overview

This is a Laravel + Vue.js web application.

## Tech Stack
- Backend: PHP 8.3, Laravel 11
- Frontend: Vue 3, Inertia.js
- Database: MySQL 8.0
- Cache: Redis

## Commands
- `npm run dev` - Start Vite dev server
- `php artisan test` - Run PHPUnit tests
- `npm run lint` - Run ESLint

## Conventions
- Use Laravel service classes for business logic
- Vue components use `<script setup>` syntax
- API routes are defined in `routes/api.php`

6. 首次实战：添加一个功能

假设我们在一个 Express.js 项目中，需要添加一个新的 API 端点。以下是完整的交互流程。

步骤一：启动 OpenCode

cd my-express-app
opencode

步骤二：用 Plan 模式制定方案

按 Tab 键切换到 Plan 模式（此时 OpenCode 不会执行任何文件修改，仅进行分析和规划），然后输入：

我需要添加一个 GET /api/users/:id 端点，返回单个用户的详细信息。

要求：
1. 包含用户基本信息和关联的文章数量
2. 如果用户不存在返回 404
3. 使用 Prisma 进行数据库查询

Plan 模式下的 OpenCode 会：

查看相关的路由文件、控制器和数据库模型

给出详细的实现计划

列出需要修改的文件和具体改动

你可以审阅这个计划，提出修改意见，直到满意为止。

步骤三：切换到 Build 模式执行

审阅计划无误后，再次按 Tab 键切换回 Build 模式，然后告诉 OpenCode：

计划没问题，请开始实现。

OpenCode 会按计划依次创建或修改文件。你可以在终端中实时看到它的操作——读取文件、搜索代码、编辑文件的全过程都是透明的。

步骤四：验证与调整

实现完成后，你可以让 OpenCode 运行测试：

请运行相关的测试，确保新功能正常工作。

如果发现问题，直接描述即可，OpenCode 会进行修复。

步骤五：撤销误操作

如果 OpenCode 的某次修改不符合预期，可以使用 /undo 命令回退：

/undo

这个命令会撤销最近一次文件修改，同时恢复你的原始提示词，方便你调整后重新尝试。

7. 实用技巧

7.1 使用 @ 快速引用文件

在对话中输入 @ 可以模糊搜索项目中的文件，快速将文件内容引入上下文：

@UserController 帮我重构这个文件中的 create 方法

7.2 拖拽图片辅助描述

OpenCode 的桌面版和部分终端支持拖拽图片——当你想要描述 UI 布局或根据设计稿生成代码时，直接拖入截图即可。

7.3 多会话并行工作

OpenCode 支持同时开启多个会话。你可以在一个会话中调试后端 Bug，同时在另一个会话中开发前端页面，互不干扰。

7.4 分享会话链接

遇到棘手的问题时，可以将当前会话生成分享链接，发送给同事或社区寻求帮助：

/share

7.5 切换模型

你可以在会话中随时切换模型，无需重启：

/model openai/gpt-5

总结

本文介绍了 OpenCode 的安装方式、模型配置、项目初始化和首次实战的全流程。核心要点：

安装灵活：支持一键脚本、npm、Homebrew、桌面应用四种方式

模型选择丰富：可以使用自有 API Key、Zen 服务、Copilot/OpenAI 订阅，或本地模型

Plan + Build 双模式：先用 Plan 规划，再用 Build 执行，确保每一步可控

配置分层：全局配置 + 项目级配置，灵活适配不同项目需求

AGENTS.md 是灵魂：让 OpenCode 理解你的项目，事半功倍

OpenCode 的上手门槛很低，但要发挥它的全部威力，后续还需要深入掌握 Agent 配置、自定义命令、Hooks 系统等高级特性。希望本文能帮助你顺利走出第一步，开启 AI 辅助编程的新体验。