OpenCode 本地部署完整指南：3 条路径 5 分钟跑通终端 AI 编程助手
【免费下载链接】opencodeThe open source coding agent.项目地址: https://gitcode.com/GitHub_Trending/openc/opencode
OpenCode 是一个开源、免费、直接在终端里运行的 AI 编程助手：你输入需求，它读代码、改文件、跑命令。这份本地部署指南按"部署路线图"带你走 3 条路径——从环境自检、安装、验证，到跑起来之后的双代理模式，全程 5 分钟内完成首次部署。
OpenCode 是什么，值得装吗
一句话：把 AI 编程助手放进你已经在用的终端，而不是再开一个浏览器标签页。它原生理解你的项目目录，能直接读写代码、执行命令，支持 Anthropic、OpenAI、Google 等主流模型，也兼容本地模型。
上面这张图就是它跑起来的样子：左侧是会话，右侧是模型对源码的逐行修改与解释，全部发生在终端内。
部署路线图：先判断你该走哪条路
别急着敲命令，先花 10 秒对号入座：
| 路径 | 适合谁 | 耗时 | 核心动作 |
|---|---|---|---|
| ① 包管理器安装（推荐） | 日常使用、想省心升级 | 约 1 分钟 | brew 或 npm 一条命令装好 |
| ② 官方一键脚本 | 系统没有顺手的包管理器 | 约 2 分钟 | curl 管道执行安装脚本 |
| ③ 源码编译 | 要用最新功能、做二次开发 | 10 分钟以上 | 克隆仓库 + Bun 跑起来 |
默认走路径 ①：装好后brew upgrade或npm update -g就能保持最新。路径 ② 作为兜底，它会自动识别你的系统架构，装到~/.opencode/bin。路径 ③ 只推荐给要动源码的人，普通用户不需要。
如果你偏好图形界面，beta 版桌面应用（macOS / Windows / Linux）可直接从项目 releases 页下载，macOS 也可brew install --cask opencode-desktop；它与 CLI 共享同一套核心代码，功能保持一致。
环境自检：装之前确认这 3 件事
路径 ①② 只需要操作系统在支持列表内（Linux、macOS、Windows），无需预装任何运行时。路径 ③ 额外要求 Bun ≥ 1.3。三条命令确认完毕：
uname -s # Darwin / Linux / MINGW* 均可 uname -m # x86_64 或 aarch64（arm64） bun --version # 仅源码编译需要，≥ 1.3输出和预期对不上就先停：不支持的架构会直接失败，Bun 版本过低会导致编译报错。
安装 OpenCode：按优先级走 3 条路
路径 ①（推荐）：包管理器一条命令装好
macOS / Linux 用 Homebrew，升级最省心：
brew install anomalyco/tap/opencodeWindows 或不便用 brew 的机器，走 npm（bun、pnpm、yarn 同样可用）：
npm i -g opencode-ai@latest路径 ②：官方一键安装脚本
不想依赖包管理器时，让脚本自己处理系统检测和架构适配：
curl -fsSL https://opencode.ai/install | bash脚本会写入 shell 配置以修正 PATH，重开终端后生效。想装指定版本，追加--version参数即可。
路径 ③（深度定制）：克隆源码编译运行
要体验未发布的特性或修改 AI 交互逻辑，才走这条路。仓库地址与构建入口如下：
git clone https://gitcode.com/GitHub_Trending/openc/opencode cd opencode bun install bun run dev构建参数集中在根目录 package.json 的 scripts 里，可按需调整；CLI 主实现位于 packages/opencode/src/ 目录，这就是"核心功能模块"所在的位置。
验证与初始配置：3 步到第一次对话
先确认二进制可用：
opencode --version能打印版本号，安装即成功。再进入你的项目目录直接运行opencode，首次启动会引导完成 3 件事：
- 选模型提供商（Anthropic、OpenAI、Google 或本地模型）
- 填入对应 API 密钥
- 确认工作目录（默认就是当前项目路径）
想持久化设置，就在项目根目录放一个 opencode.json，或写进全局 .opencode 目录，随时手改，改完即生效。
跑起来之后：两种代理模式与进阶技巧
Tab 键切换内置的两种代理：
- build（默认）：按配置权限执行工具，能改文件、跑命令，适合直接动手开发
- plan：禁用一切编辑工具，只做代码分析与方案设计，计划会落到 .opencode/plans/ 下
熟悉 CLI 之后，可以试试把它嵌进编辑器工作流（如上图的 VS Code 场景），会话管理与多项目视图见 Web 界面：
想深入源码的读者，两个入口就够：代理定义与权限逻辑在 packages/opencode/src/agent/，配置加载与路径解析在 packages/opencode/src/config/，读完基本能改出自定义代理行为。
排错速查表
| 现象 | 常见原因 | 解决 |
|---|---|---|
| opencode: command not found | 安装目录不在 PATH | 重开终端；仍失败则把安装目录（如 ~/.opencode/bin）手动加入 PATH |
| 装完仍报旧版本行为 | 残留 0.1.x 老版本 | 先npm uninstall -g opencode-ai清理残留，再重装最新版 |
| 源码编译启动报错 | Bun 版本过低 | 升级到 Bun ≥ 1.3，重新bun install |
| 对话时反复要求密钥 | API 密钥未配置或过期 | 首次启动重新选择提供商并填入有效密钥 |
把助手放进你的终端
三条路径，一条命令，5 分钟——本地部署 OpenCode 的全部成本就停在这里。现在打开终端，跑通opencode --version，然后让 build 模式替你改下第一行代码吧。
【免费下载链接】opencodeThe open source coding agent.项目地址: https://gitcode.com/GitHub_Trending/openc/opencode
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
