OpenCode 中文社区

Appearance

J. 迁移指南 ​

💡 一句话总结：从旧版本迁移到新版本的完整指南

从 0.x 迁移到 1.0 ​

重要变化 ​

  1. 配置文件格式变更

    • 旧格式：opencode.conf
    • 新格式：opencode.json

  2. 命令语法调整

    • 部分命令参数顺序变化
    • 简写参数已移除

  3. 目录结构重组

    • 配置目录：~/.opencode/ → ~/.config/opencode/
    • 数据目录：~/.opencode/data/ → ~/.local/share/opencode/

自动迁移 ​

bash
# 运行自动迁移工具
opencode migrate

# 或指定配置文件
opencode migrate --config /path/to/old/config

迁移工具会自动：

  1. 转换配置文件格式
  2. 迁移用户数据
  3. 备份旧配置（以 .backup 结尾）

手动迁移步骤 ​

1. 备份旧配置 ​

bash
# 备份整个配置目录
cp -r ~/.opencode ~/.opencode.backup

2. 转换配置文件 ​

旧格式示例（opencode.conf）：

ini
[general]
model = claude-3-opus
theme = dark
language = zh-CN

[permissions]
read = ask
edit = confirm
bash = confirm

新格式示例（opencode.json）：

json
{
  "model": "claude-sonnet-4-20250514",
  "theme": "dark",
  "language": "zh-CN",
  "permission": {
    "read": "ask",
    "edit": "confirm",
    "bash": "confirm"
  }
}

3. 迁移数据文件 ​

bash
# 迁移会话历史
mkdir -p ~/.local/share/opencode/sessions
cp ~/.opencode/sessions/*.json ~/.local/share/opencode/sessions/

# 迁移自定义提示词
mkdir -p ~/.local/share/opencode/prompts
cp ~/.opencode/prompts/*.md ~/.local/share/opencode/prompts/

4. 更新环境变量 ​

bash
# 更新 PATH
export PATH="$HOME/.local/bin:$PATH"

# 或使用 symlink
ln -sf ~/.local/bin/opencode ~/.opencode/bin/opencode

兼容性设置 ​

如果需要同时支持新旧版本：

json
{
  "compatibility": {
    "legacyConfigPath": "~/.opencode",
    "enabled": true
  }
}

从竞品迁移 ​

从 Claude Code 迁移 ​

Claude CodeOpenCode说明
/project/cd切换项目目录
/edit/edit编辑文件
/bash/bash执行命令
/web内置浏览器网页浏览

CLAUDE.md 转换 ​

Claude Code 的 CLAUDE.md 可以直接用于 OpenCode：

markdown
# CLAUDE.md → AGENTS.md
# 两者格式兼容，OpenCode 会自动识别

从 GitHub Copilot 迁移 ​

CopilotOpenCode说明
聊天界面TUI 聊天功能类似
Inline suggestions自动补全集成在编辑器中
CLIOpenCode CLI功能更强大

密钥配置 ​

bash
# Copilot 使用 GitHub 令牌
export COPILOT_GITHUB_TOKEN=your-token

# OpenCode 使用独立 API Key
export OPENCODE_API_KEY=your-key

从 Cursor 迁移 ​

CursorOpenCode说明
Cmd+K/edit代码编辑
Cmd+L/chat对话聊天
Settingsopencode.json配置方式

插件迁移 ​

旧版插件格式 ​

javascript
// 旧版插件（0.x）
module.exports = {
  name: 'my-plugin',
  version: '1.0.0',
  register: (opencode) => {
    // 注册逻辑
  }
};

新版插件格式 ​

typescript
// 新版插件（1.0+）
import { Plugin } from '@opencode/core';

export default {
  name: 'my-plugin',
  version: '2.0.0',
  
  // 插件元信息
  manifest: {
    name: 'my-plugin',
    version: '2.0.0',
    description: '插件描述',
    author: '作者',
    permissions: ['read', 'edit']
  },
  
  // 插件初始化
  async register(opencode: OpenCode): Promise<void> {
    // 注册逻辑
  }
} satisfies Plugin;

迁移工具 ​

bash
# 转换旧版插件
opencode plugin migrate /path/to/old-plugin

常见迁移问题 ​

Q: 旧配置文件不兼容怎么办？ ​

A: 使用迁移工具自动转换，或手动按上面的示例重写。

Q: 自定义 Agent 还能用吗？ ​

A: 可以，但需要更新格式：

旧版：

javascript
// agents/my-agent.js
module.exports = {
  name: 'my-agent',
  system: '你是一个助手',
  // ...
};

新版：

typescript
// agents/my-agent.ts
import { Agent } from '@opencode/core';

export default {
  name: 'my-agent',
  system: '你是一个助手',
  tools: ['read', 'edit', 'bash'],
  // ...
} satisfies Agent;

Q: 迁移后快捷键失效 ​

A: 快捷键配置需要重新设置：

bash
# 查看当前快捷键
opencode keybinds list

# 恢复默认快捷键
opencode keybinds reset

Q: 会话历史丢失 ​

A: 检查旧数据目录位置：

bash
# 默认位置
~/.opencode/sessions/

# 迁移后位置
~/.local/share/opencode/sessions/

回滚指南 ​

如果迁移出现问题，可以回滚到旧版本：

bash
# 1. 停止新版本
pkill opencode

# 2. 恢复旧配置
rm -rf ~/.local/share/opencode
cp -r ~/.opencode.backup ~/.opencode

# 3. 重新安装旧版本
npm install -g @anthropic-ai/opencode@0.x.x

# 4. 使用旧版本
opencode --version

更多资源 ​

微信群