OpenCode 安装与使用指南

OpenCode 是一款智能代码辅助编程工具，支持自定义模型提供商，内置两种核心 Agent：

• Build Agent：专注于开发阶段，协助代码编写、调试和优化
• Plan Agent：专注于需求阶段，协助需求分析、架构设计和任务规划

安装

环境要求

在安装 OpenCode 之前，请确保您的系统已安装以下软件：

• Node.js: >= 20.19.0
• Git: 最新稳定版本
• npm: 随 Node.js 自动安装

安装步骤

推荐使用 npm 进行全局安装：

npm install -g opencode-ai

重要提示

请务必使用官方 npm 源进行安装，避免使用淘宝等第三方镜像源。使用镜像源可能导致安装不完整，影响工具正常启动。

验证安装是否成功：

opencode --version

快速开始

1. 安装 OpenCode
2. 配置模型：在 ~/.config/opencode/opencode.json 中添加 Provider，详见 模型配置
3. 按需扩展：
   • MCP 配置：浏览器控制、联网搜索、数据库查询等工具
   • LSP 配置：让模型感知代码诊断（类型错误等）
   • Skills 配置：安装专业技能指令集
   • OhMyOpenagent 配置：多 Agent 编排体系
4. 启动工具：opencode
5. 使用 /models 命令切换模型，开始与 Build Agent 或 Plan Agent 交互

错误解决

终端重启后无法启动

问题原因

OpenCode 会自动进行升级更新。如果 npm 配置了淘宝等第三方镜像源，可能会导致安装不完整，新开终端后无法正常启动工具。

解决方案

按照以下步骤进行修复：

1. 卸载 OpenCode

   npm uninstall -g opencode-ai

2. 清理 npm 缓存

   npm cache clean --force

3. 切换回官方源并重新安装

   npm config set registry https://registry.npmjs.org/
   npm install -g opencode-ai

4. 禁用自动更新

   编辑 ~/.config/opencode/opencode.json 配置文件，添加自动更新禁用配置：

   {
     "$schema": "https://opencode.ai/config.json",
     "autoupdate": false
   }

提示

禁用自动更新后，如需更新 OpenCode，可手动运行 npm update -g opencode-ai 命令进行更新。