OpenCode 终端 AI 编程助手：安装部署完整指南-开发者社区

OpenCode 终端 AI 编程助手：安装部署完整指南

【免费下载链接】opencodeThe open source coding agent.项目地址: https://gitcode.com/GitHub_Trending/openc/opencode

OpenCode 是一个开源的终端 AI 编程助手（coding agent），它直接运行在你的命令行里，帮你写代码、读代码库、执行任务。你不需要装任何 IDE 插件，只要一条安装命令，就能在任意项目目录里启动一个对话式的 AI 终端。读完这篇指南，你可以完成安装、配好模型、跑通第一次对话，并解决最常见的几个坑。

先做个 30 秒自检

在装之前，花半分钟确认环境没问题，能省掉后面 90% 的排障时间。对照下面清单逐项检查：

操作系统是 macOS、Linux，或 Windows（WSL2 / Git Bash 环境）
架构是 x64 或 arm64（uname -m查看，输出含x86_64或aarch64即可）
网络可访问外网（安装脚本需要下载二进制包）
如果打算用包管理器安装，本机已装好对应工具（npm、brew、scoop 等）

如果四项全部勾上，直接进入下一节；如果有不满足的，先解决再装，否则脚本会报Unsupported OS/Arch之类的错误。

六种安装方式怎么选

OpenCode 提供官方安装脚本和主流包管理器两条路线。按你系统的习惯选一种就行，装出来的东西完全一样：

安装方式	适用系统	命令	说明
官方脚本	全平台	`curl -fsSL https://opencode.ai/install \\| bash`	自动识别系统和架构，最省事
npm / bun / pnpm	全平台	`npm i -g opencode-ai@latest`	有 Node 环境的用户首选
Homebrew	macOS / Linux	`brew install anomalyco/tap/opencode`	苹果电脑推荐，保持最新
Scoop / Chocolatey	Windows	`scoop install opencode`	Windows 原生用户
pacman / AUR	Arch Linux	`sudo pacman -S opencode`	Arch 用户直接装
nix / mise	全平台	`nix run nixpkgs#opencode`	追求可复现环境

如果你已经在用某个包管理器，就走对应那行命令，预期结果是终端打印安装进度，最后没有报错；如果你不想引入任何工具，用第一行官方脚本，预期结果是它自动下载二进制并写入你的 PATH 配置。

官方脚本的安装目录遵循这样的优先级：OPENCODE_INSTALL_DIR→XDG_BIN_DIR→$HOME/bin→ 默认的~/.opencode/bin。想让二进制落到自定义位置，在脚本前加环境变量即可，比如OPENCODE_INSTALL_DIR=/usr/local/bin开头的同一行命令，装完后用which opencode确认路径落在你指定的目录里。

装完先验证，再谈别的

这一步只干一件事：确认opencode命令能被你的 shell 找到。

opencode --version

预期输出一个类似1.x.x的版本号。如果显示版本号，安装成功，往下看；如果提示command not found，说明 PATH 没生效，执行echo 'export PATH="$HOME/.opencode/bin:$PATH"' >> ~/.bashrc把这行写入配置，再开一个新终端（而不是当前终端里source），重新执行版本命令直到出现版本号。

首次配置：告诉它用哪个模型

OpenCode 本身不带模型，需要接一个 AI 服务商的凭证。你手上有什么，就走哪条路：

如果你有 OpenCode 账户或厂商提供的 OAuth 登录方式，运行下面的命令会弹出交互式选择：

opencode auth login

按提示选服务商并完成授权后，输入y确认，回到终端不报错即为配置成功。

如果你只有 API Key（比如 Anthropic 或 OpenAI 的密钥），在终端里导出环境变量即可，以 Anthropic 为例：

export ANTHROPIC_API_KEY=你的密钥

执行后运行echo $ANTHROPIC_API_KEY，能回显出密钥说明生效了。想让密钥永久保存，把同一行export语句追加到你的~/.bashrc或~/.zshrc文件末尾。

配完凭证后，可以直接启动它，进入 TUI 界面：

opencode

预期结果是出现一个全屏的终端交互界面，左侧是文件与目录，右侧是对话区。

上图就是启动后的主界面：左侧显示当前项目结构，右侧是与 AI 助手对话的区域，底部输入框直接键入自然语言指令即可。

第一次跑通：三个必须知道的要点

装好、配好之后，这三件事能让第一次使用不踩空。

要点一：用 build / plan 两个内置智能体干活。进入 TUI 后按Tab键可以在两个模式间切换。build是默认模式，权限完整，可以改文件、执行命令，适合直接让它动手写代码；plan是只读模式，默认拒绝编辑文件、执行命令前会先征求同意，适合先让它分析陌生代码库、规划改动方案。判断切换是否成功：界面会提示当前 agent，plan 模式下让它改文件时你会收到拒绝提示。

要点二：对话前先/。输入框里敲/会带出斜杠命令菜单，比如用/models可以列出当前凭证下所有可用模型并切换。执行后模型列表刷出来、选中某一项即切换成功。

要点三：复杂搜索交给 @general。在消息里输入@general可以调用一个专门做复杂检索和多步任务的子智能体，比如"找出所有调用save()的地方并说明差异"这类问题，比直接问主智能体更容易得到完整答案。

想动手改代码前，先让它用 plan 模式输出一份方案，切回 build 模式再执行，能明显减少误改。

进阶：想要桌面版？

如果你不想一直开终端，OpenCode 提供了 Beta 状态的桌面应用，支持 macOS、Windows 和 Linux（提供.deb、.rpm、.AppImage包）。macOS 用户一条命令即可安装：

brew install --cask opencode-desktop

Windows 用户走 Scoop：

scoop bucket add extras scoop install extras/opencode-desktop

执行后在应用列表里能看到 OpenCode 图标，双击能打开主窗口即为成功。它和终端版共用同一套配置和登录凭证，切换使用不需要重新配置。

FAQ：四个高频问题

问：安装脚本执行到一半报错？先看是不是架构不被支持（脚本只支持 linux/darwin/windows 的 x64/arm64），再看网络是否中断。重跑一次脚本即可，脚本会覆盖安装到同一目录。
问：opencode命令时灵时不灵，换个目录就没了？基本是 PATH 只写进了当前 shell。检查~/.bashrc或~/.zshrc里是否有~/.opencode/bin的 PATH 配置，有就重开终端，没有就补上。
问：怎么升级到最新版？用哪种方式装的就用哪种方式升：脚本安装的用户重跑一次curl -fsSL https://opencode.ai/install | bash，npm 安装的用户执行npm i -g opencode-ai@latest。升级完再跑一次opencode --version对比版本号。
问：它会在哪留配置文件和数据？凭证和项目相关配置默认放在~/.opencode目录下，删掉该目录等价于重置本地状态。日常备份这个目录就够了。