2026 年 OpenCode 安装配置完全指南：从零到上手

如果 2026 年你的开发效率还没有翻倍，很可能是工具链还没升级。
开源、不绑定模型、75+ 种模型自由选择——这个运行在终端里的 AI 编程代理，或许会让你重新理解「AI 辅助写代码」这件事。本文从零开始，带你 10 分钟跑通 OpenCode。

认识 OpenCode：开源的 AI 编程代理

OpenCode 是一个完全开源的 AI 编程代理（AI Coding Agent），它驻留在你的终端中，可以用自然语言帮你完成代码编写、调试、重构等一系列软件工程任务。

一句话说明它的核心定位：

不绑定任何一个模型，不锁定任何一种 IDE，不收取任何许可费用——OpenCode 把 AI 编程的自主权交还给开发者。

它的工作流大致是这样的：

你：帮我写一个带 JWT 认证的用户登录 API  
  
OpenCode：  
✅ 分析项目结构  
✅ 创建 auth/jwt.go  
✅ 更新 routes/user.go  
✅ 添加中间件鉴权  
✅ 运行测试 → 全部通过

三种使用形态，覆盖不同场景

OpenCode 提供三种使用形态，几乎能适配所有开发环境：

OpenCode

终端 TUI

Web 网页版

IDE 扩展

SSH 远程开发

服务器运维

可视化操作

团队协作演示

VS Code

Cursor

Windsurf

OpenCode 与传统 AI 编程工具的差异

安装前的环境要求

开始安装之前，先确认你的环境是否满足以下条件：

安装 OpenCode 的多种方式

macOS / Linux（推荐）

官方安装脚本，一行命令即可完成：

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

Homebrew（macOS）

# 官方 Tap（推荐，更新及时）
brew install anomalyco/tap/opencode

# 注意：Homebrew 官方源的 opencode formula 更新频率较低，建议用上面的命令

npm 安装

npm install -g opencode-ai

Arch Linux

# 使用 pacman
pacman -S opencode

# 或通过 AUR Helper（如 paru）
paru -S opencode

Windows

# Chocolatey
choco install opencode

# Scoop
scoop install opencode

# 也可以使用 npm
npm install -g opencode-ai

Mise（版本管理工具）

mise use -g opencode

Docker

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

从源码编译

git clone https://github.com/opencode-ai/opencode.git
cd opencode
go build -o opencode .

验证安装

安装完毕后，用以下命令检查是否成功：

opencode --version
# 输出示例：opencode version 0.9.x

看到版本号就说明安装成功了。

首次启动与初始化

启动 OpenCode

进入你的项目目录，直接运行：

cd your-project
opencode

第一次启动时，OpenCode 会引导你完成初始设置：

1. 选择模型提供商 —— 新手建议选择 OpenCode Zen（内置免费模型）
2. 配置 API Key —— 使用云端模型时需要输入对应的密钥
3. 确认配置 —— 完成确认后即可使用

启动 Web 版

如果你更习惯图形界面：

# 默认端口启动
opencode web

# 自定义端口
opencode web --port 3000

在 IDE 中使用

在 VS Code / Cursor / Windsurf 的集成终端中运行 opencode，还可以用快捷键快速操作：

• Mac：Cmd+Esc 快速启动
• Windows / Linux：Ctrl+Esc 快速启动

配置文件详解

OpenCode 使用 opencode.json 作为配置文件，支持 JSON 和 JSONC（带注释的 JSON）格式。

配置文件位置与优先级

配置会按以下顺序加载（优先级从高到低）：

1. Remote 远程配置
2. Global ~/.config/opencode/opencode.json
3. Custom OPENCODE_CONFIG 环境变量指定
4. Project 项目根目录 opencode.json
5. .opencode 目录 项目根目录 .opencode/
6. Inline OPENCODE_CONFIG_CONTENT 环境变量

💡 实用建议：绝大多数情况下，你只需在项目根目录建一个 opencode.json 就够了。

最简配置示例

在项目根目录创建 opencode.json：

{
  "$schema": "https://opencode.ai/config.json",
  "model": {
    "build": "anthropic/claude-sonnet-4-5",
    "plan": "anthropic/claude-sonnet-4-5"
  },
  "autoupdate": true,
  "server": {
    "port": 4096
  }
}

用环境变量保护 API Key

永远不要把 API Key 硬编码在配置文件中。 推荐使用环境变量引用：

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

然后再在终端中设置环境变量：

# 临时设置（当前会话有效）
export ANTHROPIC_API_KEY="sk-ant-xxxxx"

# 永久设置（写入 shell 配置文件）
echo 'export ANTHROPIC_API_KEY="sk-ant-xxxxx"' >> ~/.zshrc
source ~/.zshrc

从文件读取密钥

{
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "{file:~/.config/opencode/anthropic-key}"
      }
    }
  }
}

完整配置示例

{
  "$schema": "https://opencode.ai/config.json",
  // 模型配置
  "model": {
    "build": "anthropic/claude-sonnet-4-5",
    "plan": "anthropic/claude-sonnet-4-5"
  },
  // 提供商配置
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "{env:ANTHROPIC_API_KEY}"
      }
    },
    "openrouter": {
      "options": {
        "apiKey": "{env:OPENROUTER_API_KEY}"
      }
    }
  },
  // 自动更新
  "autoupdate": true,
  // Web 服务端口
  "server": {
    "port": 4096
  },
  // 上下文压缩
  "compaction": {
    "auto": true
  },
  // 权限控制
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

模型与提供商快速入门

本节只介绍快速上手的必备知识。模型的详细对比、选型建议和高级配置，请阅读本系列第 2 篇《模型与提供商完全指南》。

OpenCode Zen（新手首选）

OpenCode Zen 是官方精选的模型网关，内置了多个免费模型，无需配置 API Key 就能使用。首次启动时选择 Zen 是最简单的入门方式。

使用 /connect 添加提供商

在 OpenCode 对话中输入 /connect，按提示操作即可添加新的模型提供商凭据：

你：/connect

OpenCode：请选择要添加的提供商：
  1. Anthropic
  2. OpenAI
  3. OpenRouter
  4. ...

你：1

OpenCode：请输入 Anthropic API Key：
你：sk-ant-xxxxx

✅ Anthropic 提供商已添加

查看和切换模型

# 查看可用模型列表
/models

# 在 TUI 界面中通过快捷键切换当前使用的模型

基础操作指南

对话交互

OpenCode 的核心交互方式就是自然语言对话：

你：这个项目是做什么的？帮我分析一下项目结构

OpenCode：
📖 分析项目结构...
📦 这是一个 Go 语言 Web 服务，使用 Gin 框架
📁 主要模块：
  - /handlers: HTTP 请求处理
  - /models: 数据模型
  - /middleware: 中间件
  - /config: 配置管理

你：帮我在 handlers/user.go 里添加一个获取用户列表的接口

OpenCode：
✏️ 正在编辑 handlers/user.go...
✅ 添加 GetUsers handler
✅ 添加路由注册
✅ 添加分页参数验证
📝 修改完成，共改动 3 个文件

用 @ 引用文件

在对话中直接引用项目文件，让 OpenCode 聚焦处理：

你：看一下 @src/main.go 这个文件的性能问题

OpenCode：正在读取 src/main.go...

用 ! 注入 Shell 命令输出

在消息开头使用 ! 前缀，可以将 Shell 命令的输出作为上下文发送给 AI：

你：!go test ./... 帮我看看测试结果，分析失败的用例

撤销与重做

如果改动不符合预期：

你：/undo

OpenCode：
⏪ 已撤销上一次改动

重做操作：

你：/redo

OpenCode：
⏩ 已重做上一次操作

Tab 切换模式

OpenCode 提供两种核心工作模式，通过 Tab 键切换：

💡 建议：遇到复杂任务时，先切到 Plan 模式看看方案，确认后再切回 Build 模式执行。

常用斜杠命令

以下是 OpenCode 内置的斜杠命令速查表：

快捷键参考

OpenCode TUI 使用 Ctrl+x 作为 leader key 前缀：

重要概念预告

以下概念在本文中只做简要介绍，后续文章会深入讲解。

代理系统（Agents）

OpenCode 内置了一套智能代理系统，不同的代理负责不同的任务：

• Build 代理：主代理，拥有全部工具，负责代码编写和修改
• Plan 代理：只读代理，负责分析和规划，不修改任何文件
• 子代理：包括 General（通用任务）和 Explore（代码探索）
• 系统代理：包括 Compaction（上下文压缩）、Title（会话标题）、Summary（会话摘要）

详细内容请阅读本系列第 3 篇《代理、工具与 MCP 协议》。

MCP 协议

MCP（Model Context Protocol） 是 OpenCode 连接外部工具和服务的标准协议。通过 MCP，你可以让 OpenCode 调用数据库、访问 API、操作文件系统等外部能力。

详细内容请阅读本系列第 3 篇《代理、工具与 MCP 协议》。

插件系统

OpenCode 提供了 30+ 事件钩子，支持使用 JavaScript/TypeScript 编写插件，自由扩展功能。

详细内容请阅读本系列第 4 篇《自定义命令与插件开发》。

AGENTS.md

AGENTS.md 是项目级的 AI 理解文件，相当于给 OpenCode 写的「项目说明书」。使用 /init 命令可以自动生成：

# 在 OpenCode 对话中执行
/init

OpenCode 会自动分析项目结构、技术栈、代码规范，生成一份 AGENTS.md 文件。之后每次对话，OpenCode 都会参考这个文件来更好地理解你的项目。

权限系统

OpenCode 的权限系统控制 AI 对文件和命令的操作权限：

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

• allow：自动允许，不询问
• ask：每次操作前询问确认（推荐）
• deny：完全禁止

详细内容请阅读本系列第 3 篇《代理、工具与 MCP 协议》。

常见问题（FAQ）

Q1: OpenCode 真的免费吗？

是的。 OpenCode 本身完全免费开源。不过，使用云端模型（如 OpenAI、Anthropic）时需要各自的 API Key，会产生 API 调用费用。如果使用 OpenCode Zen 的免费模型 或 本地模型（Ollama），则完全零成本。

Q2: 安装后启动报错怎么办？

常见原因和解决方法：

Q3: 不熟悉命令行能用吗？

可以试试 Web 模式（opencode web）或 IDE 扩展，它们提供了更友好的图形界面。基础使用不需要记命令，自然语言对话即可。

Q4: 支持哪些编程语言？

所有语言。 OpenCode 不限制编程语言，它通过内置工具（bash、edit、read 等）支持任何语言的开发。

Q5: 数据安全吗？

OpenCode 不会存储你的代码或上下文数据。所有数据只在你的本地机器和模型提供商之间传输。使用本地模型（Ollama）时，数据完全不出你的电脑。

Q6: OpenCode 和 Claude Code 有什么区别？

最大的区别：Claude Code 只能用 Claude 模型，OpenCode 可以选择 75+ 种模型。 Claude Code 是 Anthropic 的闭源产品，OpenCode 是开源社区项目。详细对比请阅读本系列第 5 篇《OpenCode vs Claude Code 深度对比》。

实用技巧

1. 首次进入新项目，先用 /init

# 自动分析项目结构并生成 AGENTS.md
/init

OpenCode 会识别你的技术栈，生成合适的配置文件，后续对话更精准。

2. 善用 Plan 模式

面对不熟悉的代码或复杂需求，先切到 Plan 模式让 AI 分析一遍，看看它的理解是否正确，再切回 Build 模式执行。这样可以避免大量无效修改。

3. 使用 /compact 管理长对话

对话过长时，OpenCode 会自动压缩上下文（如果开启了 compaction.auto）。你也可以手动执行 /compact 来释放上下文空间。

4. 用 /editor 编辑长消息

当你需要输入很长的需求描述时，使用 /editor 可以用你熟悉的外部编辑器（如 Vim、VS Code）来编写，写完后保存关闭即可发送。

5. /export 导出对话记录

完成的对话可以用 /export 导出保存，方便复盘或分享给同事。

总结

OpenCode = 开源 + 多模型 + Agent 能力 + MCP 扩展 + 插件生态

通过本文，你已经掌握了：

• ✅ OpenCode 是什么，它能做什么
• ✅ 如何在 macOS / Linux / Windows 上安装 OpenCode
• ✅ 如何配置 opencode.json，包括 API Key 的安全管理
• ✅ 如何启动和使用 OpenCode 的三种形态
• ✅ 基础操作：对话、引用文件、注入命令、撤销重做
• ✅ 常用斜杠命令和快捷键
• ✅ 代理、MCP、插件、AGENTS.md 等核心概念的入门理解

接下来，建议按顺序阅读本系列后续文章：

延伸阅读

• OpenCode 官方文档[1]
• OpenCode GitHub 仓库[2]
• OpenCode Zen 模型列表[3]
• OpenCode 配置参考[4]

[1] OpenCode 官方文档: https://opencode.ai/docs/zh-cn
[2] OpenCode GitHub 仓库: https://github.com/opencode-ai/opencode
[3] OpenCode Zen 模型列表: https://opencode.ai/docs/zh-cn/zen
[4] OpenCode 配置参考: https://opencode.ai/docs/zh-cn/config