OpenCode 环境变量配置实战：4 组变量、3 套即抄配方

OpenCode 环境变量配置实战4 组变量、3 套即抄配方【免费下载链接】opencodeThe open source coding agent.项目地址: https://gitcode.com/GitHub_Trending/openc/opencode改了 opencode.json 里的模型重启 OpenCode 却还是旧模型bash 权限弹窗隔几句就打断一次或者干脆一直弹。多数情况下不是配置写错而是你改的那层被更高优先级的来源覆盖了。本文围绕 OpenCode 的环境变量配置展开先讲清加载机制再给出手册和几套可直接使用的组合让你能判断自己的配置到底在哪一层生效。一、配置机制环境变量与配置文件的加载顺序这一节解决为什么改了没反应。OpenCode 启动时会按固定顺序合并多份配置来源同一字段后加载的来源总是覆盖先加载的。加载顺序配置来源说明1最低内置默认值什么都没配时的基线2全局配置文件~/.config/opencode下的 opencode.json / .jsonc个人长期设置3OPENCODE_CONFIG指明的文件临时换一套全局配置4项目级 opencode.json(c) 与.opencode/目录从当前目录逐级向上查找团队共享约定5OPENCODE_CONFIG_CONTENT内联 JSONCI 或脚本注入无需落盘6最高OPENCODE_PERMISSION只针对权限字段做覆盖这张表能解释大部分配置不生效你在第 2 层改了模型但第 4 层的项目配置里也有model生效的是项目那一份。另外注意以开关形式存在的变量如OPENCODE_DISABLE_AUTOUPDATE只识别true和1两种值写yes、on都不会启用。二、变量手册常用的 OPENCODE_ 变量怎么填这一节解决哪个变量管什么。下面按用途分四组前缀统一的OPENCODE_环境变量多数在启动前于当前 shell 里export即可不会写回任何文件。配置来源与路径决定配置从哪里读变量含义OPENCODE_CONFIG指定一份全局配置文件的路径优先级高于默认全局配置OPENCODE_CONFIG_CONTENT直接给一段 JSON 配置内容合并发生在项目配置之后OPENCODE_CONFIG_DIR额外挂一个目录从中继续加载 opencode.json / .jsoncOPENCODE_TUI_CONFIG指定 TUI 外观配置主题、键位的文件路径OPENCODE_DISABLE_PROJECT_CONFIG设为 true 后不再读取项目级配置隔离敏感仓库时有用行为与性能开关设为 true 即生效变量效果OPENCODE_DISABLE_AUTOUPDATE不再自动检查更新企业环境常用OPENCODE_DISABLE_MODELS_FETCH不拉取远端模型目录弱网环境启动更快OPENCODE_EXPERIMENTAL_DISABLE_FILEWATCHER关闭文件监视器超大仓库里能明显降 CPUOPENCODE_DISABLE_AUTOCOMPACT关闭上下文自动压缩长任务需要完整上下文时用OPENCODE_DISABLE_PRUNE关闭旧工具输出的自动清理OPENCODE_DISABLE_TERMINAL_TITLE不改动终端标题栏避免和 tmux 等工具冲突模型、数据与服务器变量含义OPENCODE_MODELS_URL/OPENCODE_MODELS_PATH自定义模型目录的远端地址或本地文件私有化部署常用OPENCODE_DB指定本地数据库文件路径OPENCODE_SERVER_USERNAME/OPENCODE_SERVER_PASSWORD远程 serve 模式下的访问凭据权限相关只有一个环境变量但值得单独说OPENCODE_PERMISSION接收一段 JSON会在所有配置合并完之后做最后一次深合并因此它能压过任何配置文件里写的权限。注意它是整段生效JSON 语法一旦有误就会被整体跳过并只记一条警告日志所以设置前先验证 JSON 合法性。下面这两行是最常见的组合前者把个人设置集中到一个文件后者用环境变量钉死权限底线# 个人配置文件只写 JSON/JSONC 字段换电脑只需同步这一个文件 export OPENCODE_CONFIG$HOME/.config/opencode/personal.jsonc # 先确认 JSON 合法再设置否则会被静默跳过 export OPENCODE_PERMISSION{edit:ask,bash:ask}三、组合配方三套即抄即用的环境变量组合这一节解决直接给我一套能用的。三套分别面向个人、团队和受限环境按你的场景挑一套粘进 shell 配置如~/.bashrc即可。个人日常稳定版本 独立配置文件export OPENCODE_CONFIG$HOME/.config/opencode/personal.jsonc export OPENCODE_DISABLE_AUTOUPDATEtrue适合只有一台主力机的个人开发者模型、外观等偏好都放进 personal.jsonc版本由你自己控制升级时机。团队统一内联配置 权限底线export OPENCODE_CONFIG_CONTENT{model:anthropic/claude-sonnet-4,share:manual} export OPENCODE_PERMISSION{edit:ask,bash:deny}不需要在仓库里放任何配置文件内联内容随环境一起下发bash默认拒绝需要执行时逐次放行适合作为团队最低安全线。受限或高安全切断外部依赖export OPENCODE_DISABLE_PROJECT_CONFIGtrue export OPENCODE_DISABLE_MODELS_FETCHtrue export OPENCODE_PERMISSION{edit:ask,bash:deny,webfetch:deny}不读项目配置、不拉远端模型目录、编辑需确认且禁止外部请求适合内网机器或接触敏感代码的场景如需指定本地模型目录再加OPENCODE_MODELS_PATH指向本地文件。四、自助排查配置不生效、权限异常、大项目卡顿这一节解决出问题了怎么定位。按现象走三步看可能原因再跑一条命令验证。现象改了配置不生效。可能原因有两个一是你改的字段被更高一层来源覆盖了对照第一节的顺序表重点查项目里的 opencode.json 和是否设置了OPENCODE_CONFIG_CONTENT二是开关变量的值不是true或1。验证一条命令env | grep ^OPENCODE_列出当前 shell 实际生效的变量和取值和你以为的不一致多半是export写在了别的 shell 配置文件里或只在子 shell 里生效过。现象权限弹窗比预期多或少。最典型的原因是OPENCODE_PERMISSION的 JSON 写错整段被跳过权限回退到配置文件里的旧值另一个隐蔽来源是配置文件里的tools字段会被自动转换成权限规则。验证方法echo $OPENCODE_PERMISSION | jq .能正常输出说明 JSON 合法那就去项目配置里找tools或permission字段报解析错误就是这段变量在捣乱。现象大仓库里界面卡顿、CPU 偏高。多数是文件监视器在持续扫描 node_modules 之类的巨型目录其次是启动时的远端模型拉取。处理方式不是改配置文件而是在启动 OpenCode 的 shell 里临时加两个开关export OPENCODE_EXPERIMENTAL_DISABLE_FILEWATCHERtrue与export OPENCODE_DISABLE_MODELS_FETCHtrue重启进程后对比体感即可确认是哪个因素。配置完成后记住一条原则环境变量只影响从那个 shell 启动的 OpenCode 进程全局配置文件改的是所有项目。问题反复出现时回到第一节的顺序表定位真正覆盖你的那一层即可。更多可配置字段的完整说明可查阅项目内的设置文档 packages/docs/essentials/settings.mdx。【免费下载链接】opencodeThe open source coding agent.项目地址: https://gitcode.com/GitHub_Trending/openc/opencode创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考