OpenCode 实战升级全记录从0.1.x迁移到最新版一次搞定【免费下载链接】opencodeThe open source coding agent.项目地址: https://gitcode.com/GitHub_Trending/openc/opencode旧版 opencode 用了半年现在要升到最新版却不确定配置文件、安装路径、权限声明是否要动。本文给出一条完整的升级路径卸载、重装、配置迁移、回滚预案和自检表一次讲清照做即可在十分钟内完成切换。一、改动速览改动项旧行为新行为不处理会怎样配置文件config.json与opencode.json混用统一为opencode.json或opencode.jsonc旧文件不被加载配置静默失效TUI 字段theme、keybinds可写在配置顶层顶层字段被忽略归入 tui 配置主题与键位不生效权限声明零散字段或全局开关permission对象按工具细粒度控制权限行为与预期不符模型字段裸模型名provider/model格式找不到模型启动报错官方 README 中有明确提示Remove versions older than 0.1.x before installing.——出处本仓库 README。二、动手前清单确认当前安装方式脚本 / npm / brew——卸载命令按方式区分记录当前版本号——回滚时要装回这个版本备份全局配置目录~/.config/opencode/——这是恢复点备份项目根目录的opencode.json如有——这是恢复点确认没有正在跑的长会话——避免迁移期间写入冲突三、核心操作3.1 执行前记录状态完成备份先确认版本和二进制位置再做备份。下面三条命令分别完成这三件事opencode --version which opencode BACKUP_DIR~/opencode-backup-$(date %Y%m%d) mkdir -p $BACKUP_DIR cp -r ~/.config/opencode $BACKUP_DIR/config cp ./opencode.json $BACKUP_DIR/opencode.json 2/dev/null; true备份目录是回滚预案的落脚点。自检通过之前不要删除。3.2 执行中卸载、重装、迁移配置卸载命令按安装方式三选一# npm/pnpm/yarn 用户 npm uninstall -g opencode-ai # brew 用户 brew uninstall opencode # 安装脚本用户默认安装位置为 ~/.opencode/bin rm -f ~/.opencode/bin/opencode用官方安装脚本重装默认装到~/.opencode/bin脚本也支持用-v锁定版本curl -fsSL https://opencode.ai/install | bash # 需要锁定版本时 curl -fsSL https://opencode.ai/install | bash -s -- -v 1.0.180处理配置若旧文件名是config.json改名为opencode.json删掉不再被读取的顶层theme、keybinds、tui字段归一化逻辑见源码packages/opencode/src/config/config.ts。与升级直接相关的字段保留成这样即可{ model: anthropic/claude-sonnet-4, permission: { edit: ask, bash: allow, webfetch: deny } }最后运行内置迁移命令确认没有遗留的 v1 数据待转换opencode migrate预期输出No migrations to run.。若提示有待迁移项按提示完成后重跑一次确认清零。3.3 执行后启动验证打开新终端启动 TUI确认版本号与界面渲染正常。本阶段产出一个新版本号、一个无报错的 TUI、一份符合新格式的配置。四、回滚预案 ⚠️出现以下任一情况停止前进执行回滚which opencode仍指向旧路径重装未生效TUI 启动报配置错误且五分钟内无法定位opencode migrate执行失败且报错无法理解恢复路径# 装回 3.1 记录的旧版本 curl -fsSL https://opencode.ai/install | bash -s -- -v 旧版本号 # 从备份还原配置 cp $BACKUP_DIR/config/opencode.json ~/.config/opencode/opencode.json还原后再跑一次opencode --version确认输出了旧版本号回滚才算完成。五、自检验证项命令 / 方法正常结果版本号opencode --version输出目标新版本号安装路径which opencode指向~/.opencode/bin/opencode或自定义目录配置加载启动 TUI 观察首屏无配置相关报错模型可用TUI 内发送一条短消息正常回复无模型不存在提示权限行为让 agent 执行一条 bash 命令按 permission 设置询问或放行迁移收尾opencode migrate输出No migrations to run.六、FAQ症状opencode: command not found原因shell 的 PATH 缓存仍指向已删除的旧二进制。解决执行hash -r刷新缓存或开一个新终端仍找不到则检查~/.opencode/bin是否在 PATH 中。症状主题、键位不生效原因opencode.json顶层的theme、keybinds字段已被新版忽略。解决删掉这些字段到 tui 配置里重新设置归一化逻辑在packages/opencode/src/config/config.ts。症状提示模型不存在或启动回退原因模型字段是裸名字不是provider/model格式。解决改成provider/model形式例如anthropic/claude-sonnet-4。七、收尾升级的稳妥之处在于每一步都留了退路先备份、记版本、装完再动配置备份目录在自检全部通过前都不删。执行时先跑opencode migrate再逐项走完自检表最后才处理旧备份。更多配置项说明见官方文档opencode.ai/docs。【免费下载链接】opencodeThe open source coding agent.项目地址: https://gitcode.com/GitHub_Trending/openc/opencode创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考