第1Z课 · 迁移配置至 ZCode
本节要点
- ZCode 是智谱（GLM）官方出品的 AI 编程智能体：桌面 App + 终端都有，配 GLM Coding Plan 套餐使用，界面和功能非常接近 Codex——想用国产模型找个顺手的编程智能体，它值得试
- 登录认准中国区：登录界面从上到下三个选项，国内同学选第二个「连接 BigModel 继续使用（中国）」；选成第一个 Z.ai 国际版的话，订阅 Coding Plan 只显示美金、区服在设置里还改不了，只能退出重登
- 搬家不可怕：这些 AI 工具可以同时装好几个、互不冲突，家当大多是通用格式；前面学 OpenCode 就像学了「手动挡」，再开 ZCode 这种「自动挡」分分钟上手
- 四样家当三种搬法：skills 放共享柜、记忆文件复制一次、MCP 照抄配置——只有插件帮不上忙，得去市场重新装
- ZCode 自带迁移向导：首次启动出现、可跳过、之后在「设置 → 数据迁移」继续办；对话记录目前只支持从 Claude Code 和旧版 ZCode 导入，还能顺手把
~/.claude/CLAUDE.md变成 ZCode 的全局记忆 - 核心一招：把 skills 放进「共享技能柜」
~/.agents/skills——一个技能一个文件夹，OpenCode、ZCode、DSH 都认，装一次多家通用（Codex 要另拷一份） - 记忆文件：项目根目录的 AGENTS.md 不用动，全局记忆复制到
~/.zcode/AGENTS.md就行 - MCP 必须重新配置：懒人一句话让 AI 装；手动就在「设置 → MCP」照抄，注意把 OpenCode 的数组写法拆成 command + args
- 搬完新建会话再验收：技能数量、试触发一个、MCP、插件、记忆，5 项逐个打勾
1. 为什么要搬家？先盘一盘你的家当
ZCode 是智谱（GLM）官方出品的 AI 编程智能体，桌面 App 和终端都有，配自家的 GLM Coding Plan 套餐用。它的界面和功能非常接近 Codex——基本是一个模子里出来的。而 Codex 用自家模型得挂梯子、走国外支付，稍微麻烦点；如果你主力用国产模型，那我很推荐你试试 ZCode。
可能有人犯嘀咕：OpenCode、DeepSeek Harness 已经学了一大圈，怎么又来一个新工具？别慌。你把 OpenCode 学完，就相当于学会了开手动挡的车——插件、Skill、MCP 都得自己动手配，配的过程把这些概念刻进了脑子。现在换 ZCode 这种图形界面的「自动挡」，点一下就能用，而且你知道点下去背后发生的是什么。以后再学 WorkBuddy 或者别的同类工具，也是分分钟上手。
更重要的是：这些 AI 工具可以同时装在电脑上，互不冲突，很多家当是通用的，搬家成本远比你想象的小。学完 55 讲，你手里真正值钱的是四样：
| 家当 | 怎么搬 | 先给你交个底 |
|---|---|---|
| 🎒 skills 技能包 | 复制文件夹到「共享柜」 | 通用格式，多家工具都认 |
| 🧠 记忆文件 AGENTS.md | 项目级不用动；全局复制一次 | 项目级所有工具直接认 |
| 🔌 MCP 工具 | 在 ZCode 里重新配置一遍 | 各家各管各的，要重新登记 |
| 🧩 插件 | 在 ZCode 的市场重新安装 | 基本是各工具独有的，搬不过来 |
除了插件得重装，其他三样都是复制粘贴级别的事。下面一样一样搬。
2. 官方搬家公司：ZCode 自带的迁移功能
先去 ZCode 官网下载安装包，Mac、Windows、Linux 都有。装好打开，先过引导界面注册登录。这一步有个最容易踩的坑：账号区服——登录界面会给你三个选项，从上到下依次是：
- 连接 Z.ai 继续使用（全球）
- 连接 BigModel 继续使用（中国）
- 使用 API key
国内的同学（不管你后面打算用 Coding Plan 套餐还是 API Key 按量付费），认准第二个「连接 BigModel 继续使用（中国）」，选它再注册/登录。千万别顺手点第一个「Z.ai」——那是国际版，登进去之后订阅套餐只显示美金价格，而且区服在设置里改不了，只能退出重登（见第 8 节坑 6）。
登录后会碰到迁移向导。它会先扫一遍你的电脑，把找到的家当列出来给你勾。我录课时它认出了 Claude Code 里的对话记录；往下翻，Claude Code、Codex、OpenCode、GLM 的技能它都识别到了，想迁的直接勾选；再往下还有 MCP（我在 OpenCode 里配的那些命令也在里面），最后是记忆文件——连我 Claude 目录下的那份它都搜出来了。中间还有两个选择：
- 导入目标：全局，还是项目级
- 导入方式：直接复制，还是建「软链」
解释一下软链：它不把原始文件复制过来，只建一个链接。链接本身几乎没有大小，你读它的时候会自动跳转到原来的目录。听着挺美，但我建议大家别建链接，直接复制——实实在在一份拷进来，省得哪天原目录一动，这边全断了。
丑话说在前面，这个官方搬家公司不是万能的：
- 对话记录目前只支持从 Claude Code 和旧版 ZCode 导入，你在 OpenCode、Codex 里的聊天记录搬不进来（好在聊天记录不值钱，值钱的是技能和记忆）
- 插件它管不了：插件是基于具体工具做的，OpenCode 的插件拿到 ZCode 里并不适用，得去市场重装（第 6 节讲）
手快跳过了向导也不用慌，之后随时打开 设置 → 数据迁移 继续办；它也认得 Claude Code 老用户——能把 ~/.claude/CLAUDE.md 自动复制成 ZCode 的全局记忆。不过说真的，我录课时更常用的是另一条路：直接使唤 AI 给我搬家，一句话的事，下面每样家当我都给你现成话术。
3. 核心一招：把 skills 放进「共享技能柜」~/.agents
为什么有个共享柜
行业里有个开放标准叫 Agent Skills：一个技能 = 一个文件夹，里面必须有一份 SKILL.md，写清楚这个技能干什么、怎么干。因为格式开放，大家就形成了惯例：把技能统一放在家目录下的 .agents/skills/ 里。这个文件夹就像一栋楼里的公共储物柜——OpenCode、ZCode、DeepSeek Harness 都拿着钥匙，都能开柜取技能。
所以搬 skills 的本质就一句话：把你以前装的技能文件夹，原封不动放进 ~/.agents/skills/。放一次，多家工具一起用。
共享柜在哪
| 系统 | 柜子地址 | 怎么打开 |
|---|---|---|
| Mac | /Users/你的用户名/.agents/skills | 访达按 ⇧⌘G 输入 ~/.agents 回车；或终端执行 open ~/.agents |
| Windows | C:\Users\你的用户名\.agents\skills | 资源管理器地址栏粘贴 %USERPROFILE%\.agents 回车；看不到就勾选「查看 → 显示 → 隐藏的项目」 |
💡 找不到不是因为你删了——以点
.开头的文件夹默认是「隐藏文件夹」，不是没有，是不给你看。
三种搬法，挑一个顺手的
搬法一：让 AI 搬（我最推荐）。 在 ZCode 里新建一个项目（项目 → 添加项目，选中文件夹——相当于授权它对这个文件夹读写），再新建一个会话，直接发送：
我想把我的 OpenCode 的技能迁移到 ~/.agents/skills 这个目录下来，
让 OpenCode、ZCode、DeepSeek Harness 都能访问回车，它自己找到旧技能、建目录、复制过去，一条龙办完。能用 AI 的活就别自己动手，这是我一贯的态度。
搬法二：手动拖拽。 打开你以前装技能的文件夹（里面是一堆带 SKILL.md 的小文件夹就对了），全选 → 复制 → 粘贴进 .agents/skills。完事。
搬法三：命令一行搞定。 技能多的同学用命令快（来源路径按你实际放技能的地方改，也可能是 ~/.config/opencode/skills）。
Mac（终端）：
mkdir -p ~/.agents/skills
cp -R ~/.claude/skills/* ~/.agents/skills/Windows（PowerShell）：
New-Item -ItemType Directory -Force ~\.agents\skills
Copy-Item -Recurse ~\.claude\skills\* ~\.agents\skills\搬完必做两件事
新建一个会话（或重启 ZCode）再检查——技能清单是会话启动时读取的，老会话看不见你刚搬的东西；然后终端跑一下 zcode skills list，数量和你搬过来的对得上就成。
哪些工具认这个柜子
| 工具 | 认 ~/.agents/skills 吗 | 说明 |
|---|---|---|
| OpenCode | ✅ 官方支持 | 还兼容 ~/.claude/skills 等多个目录 |
| ZCode | ✅ 官方支持 | 读取顺序：先 ~/.zcode/skills，再共享柜 |
| DSH | ✅ 已验证 | 咱们 DeepSeek 专题课里实测可用 |
| Codex | ⚠️ 不稳定 | 个别版本不读共享柜，主目录是 ~/.codex/skills |
用 Codex 的同学保底方案：把技能再复制一份到 ~/.codex/skills，两边都稳。
还有一条潜规则：同一个技能在多个目录都有时，先被找到的优先。所以搬进共享柜后，把旧目录里的同名旧版删掉，免得旧版挡住新版。
4. 记忆文件：项目级不用动，全局复制一次
先说个好消息：放在项目根目录的 AGENTS.md 不用迁。这是开放格式，OpenCode、Codex、ZCode 全都直接认——你以前给每个项目配的记忆，装好 ZCode 后打开原样生效，一根手指都不用动。
要动手的只有全局记忆（对所有项目都生效的那份偏好设定）。麻烦在于各家存放的路径不一样：
| 工具 | 全局记忆路径 |
|---|---|
| OpenCode | ~/.config/opencode/AGENTS.md |
| Codex | ~/.codex/AGENTS.md |
| ZCode | ~/.zcode/AGENTS.md |
做法是复制粘贴级别的：打开旧的全局记忆文件 → 全选复制 → 粘贴到 ~/.zcode/AGENTS.md（没有就新建一个）。当然还是那句话，可以懒——直接对 ZCode 说「帮我把 OpenCode 的全局记忆复制到 ZCode 的全局记忆目录」，它自己办。如果你之前用 Claude Code，第 2 节的迁移向导会自动把 ~/.claude/CLAUDE.md 复制过去，这步都省了。
怎么确认它还记得你？新会话里问一句「我的全局记忆里写了什么？」能答上来，就说明搬家成功——你以前的习惯和偏好，它全接着记。
5. MCP：必须重新配置
MCP 和 skills 不一样，每家工具的配置各管各的——你在 OpenCode 里配的看图 MCP、查库 MCP，ZCode 不认识，得重新登记一遍。
懒人法（推荐）：直接对 ZCode 说：
帮我在 ZCode 里面安装目前我电脑里 OpenCode 安装过的 MCP，帮我配置好回车，它读你的旧配置、挨个装好。装完打开 设置 → MCP，能看到它们都列在里头——我自己的 electron MCP、codebase-memory MCP 都在，其余那些是 ZCode 内置的，不用管。
手动法：打开 设置 → MCP 的图形界面，把 OpenCode 里的 command、args、env 照抄一遍。进阶选手也可以直接改配置文件 ~/.zcode/cli/config.json，以第 23 课的「看图 MCP」为例，长这样：
{
"mcp": { "servers": {
"vision": { "type": "stdio", "command": "npx",
"args": ["-y", "你的看图mcp包名"] }
}}
}⚠️ 抄配置最大的坑：OpenCode 那种
"command": ["npx", "-y", ...]数组写法 ZCode 不认，要拆成command+args两个字段——command放程序名，args放后面的参数列表。
配完在会话里输入 /mcp status，所有服务都显示 connected 就通了。
6. 插件：重新装回来（点几下的事）
插件得重来一遍，但比 MCP 还省事，点几下鼠标就行：
- 打开 设置 → 插件管理，分「已安装」「发现」两个标签
- 去市场里挑：官方市场
zcode-plugins-official里 browser-use、github、document-skills 一大堆；像文档操作这种 Word、PDF、PPT、Excel 全家桶，默认就帮你装好了 - 点「安装」即用，插件自带的技能和命令自动生效
还有个彩蛋：ZCode 也认 Claude / Codex 格式的插件市场。我实测从 Claude 官方市场装了个 context7（查文档神器），装上直接能用——以前课程里推荐过的插件，基本都能在这边复活。
顺手把设置再逛一圈，几个地方你以后会用到：
- 模型：登录智谱账号直接用 Coding Plan；或者填 API Key 按量调用；也能添加其他提供商。这些都可以在会话里让 AI 帮你配，新注册一般还送额度（登录时记得选第二个「连接 BigModel（中国）」，别选成国际版，见第 2 节）
- 使用统计：你在 ZCode 里不管用哪一家的模型，用量都记在这；「个人套餐」里是 Coding Plan 的 token 用量
- 内置浏览器：以前我们要配 Playwright MCP 才能让 AI 操作浏览器，ZCode 直接内置了，你点选页面元素让它操作就行，而且复用你的登录凭证——登录过的网站它接着用
- 电脑控制：用视觉模型截图的方式操作你电脑上的软件，后面细讲；「创建命令」则能把一段常用提示词做成斜杠命令，每周都要干的活一句话召回
至于日常操作，你在主课程学的全都通用：plan 模式（按 Tab 跟它聊计划，聊完切 build 模式开干）、模型切换、思考级别、/compact 压缩上下文、/find skill 找技能、@ 引用插件和文件——一样的配方，不用重新学。
7. 搬完了？5 项验收，逐个打勾
全部搬完别急着开工，先验收：
- 技能到齐了吗：终端跑
zcode skills list，数量和你搬过来的对得上 - 技能真的能用吗：新会话里用
/skill挑一个老技能试试，比如查法规——能触发、按你教的流程干活才算数 - MCP 都连上了吗：输入
/mcp status，所有服务显示 connected - 插件装齐了吗：设置 → 插件管理 → 已安装列表逐个核对
- 它还记得你吗：问一句「我的全局记忆里写了什么？」——能答出来，说明
~/.zcode/AGENTS.md生效了
五项全过，你就回到了熟悉的状态：以前 OpenCode 怎么用，ZCode 就怎么用，两边互不干扰，也不会有什么冲突。
8. 避坑指南：这 7 个坑，我先替你踩了
坑 1｜技能拷进去了，却不出现：按顺序查三件事——① 搬完没新建会话（清单要新会话才刷新）；② 文件夹里没有 SKILL.md；③ SKILL.md 开头的 frontmatter 缺 name 或 description 字段。
坑 2｜找不到 .agents 文件夹：不是没有，是隐藏了。Mac 访达按 ⇧⌘G 输入 ~/.agents；Windows 勾选「查看 → 显示 → 隐藏的项目」（见第 3 节）。
坑 3｜Codex 认不出共享柜：个别版本的 Codex 不读 ~/.agents，它的主目录是 ~/.codex/skills。把技能再复制一份过去，两边都稳。
坑 4｜MCP 填了连不上：十有八九是格式问题——把 OpenCode 的数组写法 "command": ["npx", ...] 拆成 command + args 两个字段，改完用 /mcp status 验证。
坑 5｜新旧技能打架：同一个技能在旧目录和共享柜里各有一份时，先被找到的优先，旧目录里的旧版可能一直挡着新版。搬完把旧目录里的同名旧版删掉。
坑 6｜升级套餐只显示美金：十有八九是登录时选错了账号区服——三个登录选项里点了第一个「连接 Z.ai（全球）」国际版。设置里改不了，退出登录重新登录，改选**第二个「连接 BigModel（中国）」**就好（群友凯文金验证）。2026-09-04 群友 Amy 向前冲 又踩了一遍同款坑——登录页有「中国」和「全球」两个入口，选颜色选嗨了没看字，退出重登就好。
坑 7｜送的 token 查不到余额：ZCode 送的体验 token（比如周末活动送的 3 亿），在客户端默认的「使用统计」里看不到——因为默认显示的是个人套餐的额度。去 设置 → 模型设置 → 连接方式，把连接方式切换成「体验套餐」，余额就出来了（2026-09-04 群友小猪happy 踩坑，我不是梁图真、彼岸蔷薇 指点）。
本课小结
搬家五步：向导能带的先带上，skills 放进共享柜 ~/.agents/skills，记忆复制到 ~/.zcode/AGENTS.md，MCP 照抄重配，插件市场重装——5 项验收打完勾，装备一件不丢，ZCode 就是你的老朋友。
🔮 下一课预告：第 2Z 课讲 ZCode 添加模型——订阅自带的 GLM 之外，怎么把 DeepSeek 等其他模型接入 ZCode，想用哪家就用哪家。