奇 奇连 AI
学习路线图课程工具计算器企业服务关于加入会员

opencode 安装上手：开源终端编码 Agent 的装法与避坑

2026-08-04

本文基于 opencode 仓库 commit 7fe9938（2026-08-04）梳理，该项目仍在高频迭代，具体行为以仓库 https://github.com/anomalyco/opencode 最新代码与文档为准。

opencode 的安装本身只要一条命令，真正的代价在装完之后的前十分钟：你要替它做完鉴权、项目初始化、权限三个决定，而这三个决定里有两个的默认值偏宽松。 装法选错顶多是升级时多绕几步，权限判断错则是它在你机器上跑 shell、直接改你的代码文件、把仓库内容发给模型服务商。

先做个消歧：这里说的 opencode 是仓库地址为 github.com/anomalyco/opencode 的那个开源项目，采用 MIT 许可证（根目录 LICENSE），README 里的一句自我定位是 The open source AI coding agent。它不是泛指的开源代码，也不是某个名字相近的模型。名字的写法它自己也不统一：可执行文件和 npm 包名是全小写的 opencode 与 opencode-ai，README 与部分文档正文里又写作 OpenCode，你在搜索资料时两种写法都得试。

本篇只管从零到第一轮对话跑通这一段。同类上手文站内还有三篇，分工是这样的：pi 的安装上手讲的是另一套终端 Agent 的装法，Claude Code 教程与 Cursor 教程讲的是闭源商业工具的日常用法。你如果只想快速比较取向，那三篇更合适；想知道 opencode 装进来的到底是什么、哪几个默认值会咬人，看这篇。

一、装之前先看清楚：你装进来的是一整套东西

opencode 是个 monorepo。packages/ 下有 32 个包，你敲下 opencode 时被拉起来的不是一个单文件脚本，而是命令行入口、终端界面、会话与工具执行、模型接入这几层的组合。知道这些层的位置，出问题时你才知道该去哪儿找。

组成部分它负责什么对应仓库位置你什么时候会碰到它
安装脚本探测系统架构、下载二进制、写 PATH根目录 install用 curl 那条命令装的时候
命令行入口子命令实现，run/serve/web/upgrade/attach/models 等各一个文件packages/opencode/src/cli/cmd/每次敲 opencode 或它的子命令
终端界面就是你看到的那个 TUIpackages/tui交互、切 agent、敲斜杠命令时
工具实现读文件、改文件、跑 shell、搜索、抓网页packages/opencode/src/tool/它每次动你的磁盘或网络
提示词分文件存放的系统提示词，部分按模型家族分家packages/opencode/src/session/prompt/换模型后行为手感不一样时
桌面端桌面应用外壳packages/desktop用桌面版而不是终端时
文档站全部官方文档源文件packages/web/src/content/docs/查某个配置键到底叫什么时

几个能自己数出来的量，帮你建立体感：packages/opencode/src/tool/ 里有 25 个 .ts 和 15 个 .txt——.txt 是给模型看的工具说明书，和实现代码分开放；packages/opencode/src/session/prompt/ 里有 14 份提示词，其中一部分文件名直接是模型家族名（anthropic.txt、gemini.txt、gpt.txt、kimi.txt、codex.txt、meta.txt），另一部分按工作模式分（default.txt、plan.txt、plan-mode.txt、build-switch.txt 等）。前一半是它对「不同模型要用不同话术」的明确态度，后一半是它对「同一个模型在不同模式下要换个说法」的态度。文档目录下英文 mdx 有 36 份，根目录还有 21 份 README 翻译。全仓受版本控制的文件是 6358 个。

对你意味着什么：这不是一个薄壳套模型的玩具，但也意味着「装上」只是把一堆能力放到了你机器上，能力开到多大由你后面的配置决定。

二、几种安装方式各自的代价

README 的 Installation 一节把装法摊开了，index 文档又按平台重讲了一遍。它们能装出同一个可执行文件，但后续维护成本不一样。

安装脚本（curl 管道到 bash）。 官方称之为最省事的方式：

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

代价有两处，都藏在脚本里。第一，它会改你的 shell 配置文件。install 脚本里有个 add_to_path 函数，按你的 shell 往配置文件里追加 PATH（fish 走 fish_add_path，其余走 export PATH=...）；不想被改就带上 --no-modify-path，但那之后 PATH 要你自己管。第二，装到哪儿由一串环境变量决定，README 写明的优先级是 $OPENCODE_INSTALL_DIR、$XDG_BIN_DIR、$HOME/bin、最后兜底到 $HOME/.opencode/bin。你如果在公司机器上没有写系统目录的权限，指定一个自己能写的位置更省心：

XDG_BIN_DIR=$HOME/.local/bin curl -fsSL https://opencode.ai/install | bash

管道到 bash 这件事本身也是个代价：你在把一段远程脚本直接交给本机 shell 执行。介意的话，先把它下下来读一遍再跑——这个脚本 460 行，读得完。

包管理器。 npm 系装的是 opencode-ai 这个包（bun / pnpm / yarn 同理）；macOS 与 Linux 上文档推荐 brew install anomalyco/tap/opencode 这个 tap，并且明说官方 Homebrew formula 由 Homebrew 团队维护、更新频率更低；Arch 有 pacman 的稳定版和 AUR 的 opencode-bin；另外还有 mise、nix、Windows 上的 scoop 与 choco。代价是版本新鲜度和你选的渠道绑死了：走更新慢的渠道，你查到的文档描述可能跑在你本地之前。

这里还有个坑：opencode upgrade 有个 --method 参数，取值是 curl、npm、pnpm、bun、brew。也就是说升级动作需要知道你当初是怎么装的。混着装（先 npm 后 brew）之后升级会变糊涂，README 也提示过安装前先把更早的历史版本移除。一台机器只留一种装法，这条比任何优化都值。

Windows。 文档的态度很直接：推荐用 WSL。理由写在 windows-wsl.mdx 里——文件系统性能、终端支持、依赖工具的兼容性。原生 Windows 能跑（choco / scoop / npm / Docker 镜像都有），但 troubleshooting 文档里专门有一节讲 Windows 的性能与文件访问问题，结论仍是导向 WSL。要注意的是，WSL 里跑就意味着配置和会话存在 WSL 环境内的 ~/.local/share/opencode/，不在 Windows 用户目录下。

终端本身也是前置条件。 index 文档把「一个现代终端模拟器」列为 Prerequisites 的第一条，点名了 WezTerm、Alacritty、Ghostty、Kitty。这不是装饰性建议：TUI 的渲染、鼠标、图片拖拽这些能力依赖终端支持。

三、第一次启动，它要你做的那几件事

装完之后的动作是有顺序的，顺序错了会白绕。

第一件：给它一个模型出口。 在 TUI 里敲 /connect 走鉴权，命令行侧对应的是 opencode auth login。凭据落在 ~/.local/share/opencode/auth.json，opencode auth list 能列出已鉴权的 provider，opencode auth logout 清掉。除了这个文件，它启动时也会读环境变量里的 key，以及项目里的 .env 文件。

这一步就是外泄面的起点，得说清楚：auth.json 是本地明文存的凭据文件，别把它同步进任何云盘或仓库；.env 会被读进来找 key，意味着你项目里那份含生产密钥的 .env 也在它的视野里。密钥怎么隔离，API 密钥安全管理那篇讲得更细。

第二件：进项目，跑起来，做初始化。

cd /path/to/project
opencode

然后在 TUI 里敲 /init。按 rules.mdx 的说明，/init 会扫仓库里的重要文件、在代码库答不上来时问你几个针对性问题，然后生成或就地改进项目根目录的 AGENTS.md——构建/lint/测试命令、命令顺序与验证步骤、目录结构里不能靠文件名看出来的部分、项目特有的约定和坑。文档建议把 AGENTS.md 提交进 Git。

规则文件的查找顺序也写死了：先从当前目录往上找本地文件（AGENTS.md、CLAUDE.md），再看全局的 ~/.config/opencode/AGENTS.md，最后回落到 ~/.claude/CLAUDE.md。每一类里第一个命中的赢——你同时有 AGENTS.md 和 CLAUDE.md 时，只有前者生效。这个回落链路可以用 OPENCODE_DISABLE_CLAUDE_CODE 系列环境变量关掉。

第三件：认清 build 和 plan 这两个内置 agent。 README 说得很清楚：Tab 键在两者之间切。build 是默认的全权限 agent；plan 是只读的，默认拒绝文件编辑、跑 bash 前要问你。另外还有个内部用的 general 子 agent，消息里用 @general 唤起。

第一轮别急着让 build 干活。先 Tab 到 plan 让它把仓库读一遍、把方案讲出来，你看方案对不对，再 Tab 回去让它动手。这是拿最低代价验证「它到底看懂了没有」的办法。真做砸了还有 /undo，可以连着敲多次回退，/redo 反向。

四、新手最容易卡住的三处

卡点一：模型引用格式写错。 troubleshooting 里点名了 ProviderModelNotFoundError，成因基本都是模型名引用方式不对。格式固定是 <providerId>/<modelId>，文档给的例子是 openai/gpt-4.1、openrouter/google/gemini-2.5-flash、opencode/kimi-k2——注意第二个例子里 modelId 自己还带一层斜杠，所以别用「按斜杠切两段」的直觉去理解。不确定自己能用哪些，命令行敲 opencode models 列出来，--refresh 刷新缓存，TUI 里对应的是 /models。

卡点二：以为权限默认是保守的。 permissions.mdx 的 Defaults 一节原文是：大多数权限默认 "allow"，只有 doom_loop 和 external_directory 默认 "ask"；read 是 allow，但 .env 文件默认被拒：

{
  "permission": {
    "read": {
      "*": "allow",
      "*.env": "deny",
      "*.env.*": "deny",
      "*.env.example": "allow"
    }
  }
}

翻译成人话：开箱状态下它可以直接改你的文件、直接跑 shell 命令，不问你。 想收紧就在 opencode.json 里显式写规则，三个动作是 allow / ask / deny：

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "bash": {
      "*": "ask",
      "git *": "allow",
      "rm *": "deny",
      "grep *": "allow"
    }
  }
}

有一条匹配规则要记住：最后一条命中的规则赢，所以兜底的 "*" 要写在最前面，具体规则放后面。写反了就是你以为收紧了其实没收紧。另外 --auto（以及 opencode run --auto）会自动批准所有非显式 deny 的请求，显式 deny 仍然拦得住——这个开关适合你已经把 deny 名单写好的场景，不适合刚上手就开。权限该按什么原则设计，最小权限设计那篇有一套可以照搬的思路。

还有两个容易忽略的守卫：external_directory 管的是工具碰到工作目录之外的路径（read、edit、glob、grep 和不少 bash 命令都算），doom_loop 管的是同一个工具调用带着完全相同的输入重复 3 次。这两个默认 ask，是它给你留的两道刹车，别顺手改成 allow。

卡点三：出了问题不知道去哪儿看。 日志在 ~/.local/share/opencode/log/，按时间戳命名，只保留最近 10 份；想看得更细就 opencode --log-level DEBUG，想直接打到终端就加 --print-logs。会话和消息数据在 ~/.local/share/opencode/project/ 下，仓库内的项目按 project-slug 分目录，非 Git 目录统一进 global。

两个高频修复动作也在同一份文档里：碰到 ProviderInitError 通常是配置坏了，清掉 ~/.local/share/opencode 再重新 /connect；碰到 AI_APICallError 往往是本地缓存的 provider 包过时了——它是按需动态安装 provider 包并缓存在本地的，清掉 ~/.cache/opencode 重启即可重新拉取。Linux 上复制粘贴不工作则是另一类：需要装剪贴板工具，Wayland 下它优先找 wl-clipboard，否则依次找 xclip、xsel。

五、边界与代价：它明确不管的事

这套设计放弃了一些东西，说清楚比夸它有用。

它不替你兜住误改。 它有 /undo 和 /redo，但那是会话层面的回退，不是你版本控制的替代品。在没有干净 Git 工作区的目录里让 build agent 跑，改动混在你自己未提交的修改里，回退就变成手工活。它也不替你界定「这次只准动哪几个文件」，那是你在提示里要写死的事。

它不隔离你的机器。 权限系统管的是「问不问你」，不是沙箱。allow 掉的 bash 命令就是在你的用户身份下真实执行。external_directory 能限制路径范围，但它是一层配置约束，不是内核级隔离。真需要隔离，得你自己上容器或专用账户。

它不承诺你的代码不出本机。 这类工具的工作方式就是把文件内容、命令输出、错误堆栈作为上下文发给模型服务商。私有代码、日志里的凭据、.env 里的东西，一旦进了上下文就出了你的网络边界。read 默认拒 .env 是一层保护，但只有一层——它拦不住你自己 cat 一个配置文件让它看。涉及各家服务商的数据处理规则，各家不同且会调整，以官方最新说明为准。

它不替你选模型，也不保证换模型后手感一致。 packages/opencode/src/session/prompt/ 下按模型家族单独存在的那几份提示词本身就说明：不同模型在同一套工具上的行为差异大到需要分开写话术。换模型不是改一行配置那么简单，你的 AGENTS.md 和习惯的提示方式可能都要跟着调。

Windows 原生不是它的主场。 文档在 index 和 troubleshooting 两处都把 WSL 摆在推荐位。你坚持原生跑不是不行，只是遇到问题时能参照的资料更少。

六、上手避坑清单

只用一种安装方式。 会踩是因为不同渠道装出的可执行文件位置不同，PATH 里可能同时存在两个，你以为升级了实际调用的还是旧的。避法：装之前确认机器上没有历史安装，opencode upgrade 时用 --method 指明当初的渠道。

装完先看 PATH 被改了没有。 会踩是因为安装脚本默认会往 shell 配置文件里写 PATH，而你可能有一套自己管理 dotfiles 的方案，两边打架。避法：介意就带 --no-modify-path，然后自己把安装目录加进 PATH；不介意就装完后确认改动落在了预期的那个配置文件里。

第一天就把 permission 写进 opencode.json，别等出事。 会踩是因为默认多数权限是 allow，而新手的心理预期是「工具总该先问我一声」。避法：至少把 bash 收成 "*": "ask" 加一份 allow 白名单，把破坏性命令显式 deny；记住最后命中的规则赢，兜底写最前面。

别在含未提交改动的目录里第一次跑 build agent。 会踩是因为你还没建立对它改动幅度的判断，一次跑完分不清哪些改动是它的。避法：先 commit 或 stash，工作区干净了再放它进来，改完直接 git diff 看全貌。

别急着开 --auto。 会踩是因为它省掉的确认恰恰是你唯一的观察窗口，而 doom_loop 和 external_directory 这两道默认刹车正好是新手最需要的。避法：等你的 deny 名单稳定了、也确认过它在这个项目里的行为模式了，再开。

/init 生成的 AGENTS.md 要自己读一遍再提交。 会踩是因为它是模型扫仓库总结出来的，构建命令、测试入口这类信息可能不准，而这份文件会进后续每一轮的上下文——错的信息会被反复放大。避法：当成一份需要人工校对的 PR 来对待，改完再 commit。

Linux 上先把剪贴板工具装好。 会踩是因为复制粘贴失灵看起来像 TUI 的 bug，实际是系统缺依赖。避法：X11 装 xclip 或 xsel，Wayland 装 wl-clipboard，无头环境按文档那套 xvfb 方案配。

收尾：跑通第一轮的自检

装完之后，按这五条对一遍，你就算真的跑通了，而不是「看起来能用」：

一是 opencode models 能列出你有权访问的模型，说明鉴权链路通了；二是项目根目录有一份你亲自读过、内容属实的 AGENTS.md；三是 opencode.json 里有一段你自己写的 permission，而不是空着吃默认值；四是你能说出日志在哪个目录、怎么开 DEBUG；五是你先用 plan agent 跑过一轮，确认它对这个仓库的理解没跑偏，再放 build 动手。

接下来该读哪个文件：想继续收紧安全边界，去看 packages/web/src/content/docs/permissions.mdx 的 Granular Rules 一节，那里的对象语法能精确到具体命令和具体路径；想把它接进脚本或 CI，去看 cli.mdx 里 run、serve、attach 这三个子命令；想搞明白它为什么在不同模型下表现不一样，直接翻 packages/opencode/src/session/prompt/ 下那 14 份提示词，那是它最实在的一手资料。

本篇属于一个把开源AI 编程 Agent 项目 opencode逐层拆开讲的系列，整体地图见 opencode 是什么：终端里的开源 AI 编程 Agent 全景地图；沿着这条线往下，还可以看 开源终端编码 Agent opencode 跑不动：按模型、认证、Windows、代理证书的顺序排查 和 opencode 怎么接模型：终端编码 Agent 的供应商层与认证机制。

想系统学会用 AI？报名体系课或加入会员，照着学、照着用。

浏览课程 加入会员