前言

ZCode 是智谱（Z.ai）推出的一款智能体开发环境（ADE，Agentic Development Environment），官方定位是「面向长周期任务的全功能智能体开发环境」。和传统的代码补全插件不同，ZCode 把「智能体」而不是「手写代码」放在中心位置——你描述目标，它自己读项目、写代码、跑命令、验证结果。

• 官网：https://zcode.z.ai
• 文档：https://zcode.z.ai/en/docs/install
• 最新版本：v3.9.2（2026-08-26）
• 应用本身免费，模型能力需要你自己提供（GLM Coding Plan 订阅、BigModel 资源包，或任意兼容的 API Key）

本文中的功能说明与配置路径均来自官方文档与本机实际安装目录，实测环境为 Windows 10 x64 + ZCode 桌面版。

功能介绍

安装

支持的平台

官方文档明确支持：macOS（Apple Silicon / Intel）、Windows（x64 / ARM64）、Linux（x64、ARM64，提供 AppImage / DEB / RPM）。

下载地址

打开 https://zcode.z.ai 点击 Download ZCode 会自动匹配你的系统。也可以直接用 CDN 直链（以 v3.9.2 为例）：

Windows 安装包约 155 MB。把版本号替换成新版本即可获取对应文件，建议以官网下载页为准。

各平台安装步骤

Windows

1. 下载 .exe 安装包
2. 双击运行，按向导完成安装
3. 从开始菜单或桌面快捷方式启动
4. 若被杀毒软件拦截，把安装目录加入白名单

macOS

1. 下载并打开 .dmg
2. 把 ZCode.app 拖进「应用程序」文件夹
3. 从启动台打开

如果提示「应用已损坏」，是隔离属性导致的，执行：

1

xattr -dr com.apple.quarantine /Applications/ZCode.app

Linux

AppImage 方式：

1
2

chmod +x ZCode-*.AppImage
./ZCode-3.9.2-linux-x64.AppImage

部分发行版还需要 fuse 依赖（Ubuntu / Debian 缺 libfuse2 时无法启动）：

1

sudo apt install libfuse2

.deb / .rpm 走各自发行版的包管理器安装即可。

首次启动

整个流程官方给的预估时间是「约 2 分钟」：

1. 引导页 — 可以直接「开始使用 ZCode」，也可以走数据迁移向导。注意迁移范围有限，目前只导入 Claude Code 和旧版 ZCode Agent 的会话，之后也能在设置里再迁移。
2. 选择工作区 — 指定一个项目目录。如果不想绑定仓库，可以在工作区菜单里选「在项目外工作」。
3. 连接模型 — 左下角 Connect 按钮，提供三个入口：Connect Z.ai、Connect BigModel、Use API Key。
4. 冒烟测试 — 随便发一句「列出当前目录的文件」，确认智能体能正常跑起来。

连接模型

ZCode 本身不含模型额度，必须先接上模型服务。配置文件落在 ~/.zcode/v2/config.json。

方式一：账号快连（推荐）

设置 → 模型服务商 → 选择 Z.ai 开放平台 或 BigModel，走登录流程后 Key 会自动回填。用 GLM Coding Plan 订阅走账号授权时不需要手填 Base URL，路由是自动的。

方式二：手填 Base URL + API Key

不同套餐对应的端点不能混用，这是最常见的踩坑点：

三类端点的区别：

• /api/coding/paas/v4 — 仅 Coding Plan 可用
• /api/paas/v4 — OpenAI 兼容通用端点，用于资源包和余额计费
• /api/anthropic — 同样服务资源包，走 Anthropic 协议，是 ZCode 的默认协议

其他模型服务商

除 GLM 外，ZCode 也支持接入：

也可以添加任意 Anthropic / OpenAI 兼容的自定义服务商。BigModel 新用户有 5 天试用额度：GLM-5.3 每天 300 万 tokens，GLM-5.3-Flash 每天 500 万 tokens。

两个容易踩的坑

• 终端环境变量不会被继承。你在 shell 里 export 的 GLM Key，桌面应用读不到，必须在应用内配置。
• 代理必须在应用内设置。设置 → 通用里的 HTTP Proxy 留空不等于跟随系统，ZCode 完全忽略 HTTP_PROXY 这类环境变量。所以经常出现「终端能联网、应用连不上」的情况。改完代理需要重启应用。另外，代理不覆盖 SSH 连接和 Web 远程控制通道。

界面与基础用法

添加上下文

聊天框左下角的 + 按钮，或直接输入对应触发字符：

粘贴长文本会自动转成附件。在回复、推理过程、代码块或工具结果里选中一行，会浮出「添加到当前任务」按钮。

执行模式（重要）

输入框聚焦时按 Shift + Tab 循环切换四档权限：

思考档位

输入框右下角模型名旁边的思考图标，三档：Low（追速度）、High（日常平衡）、Max（默认，最深，适合架构设计和硬 bug）。

侧边会话

不打扰主任务的并行对话，四种打开方式：选中文本后点「在侧边会话中提问」、/side 或 /btw 命令、右侧面板 + 菜单、起始页。它会借用主会话的历史作为上下文，但界面是空的，并且可以调工具、改文件。每个任务每窗口只有一个，关掉即不可恢复。

分叉（Fork）

鼠标悬停在已完成的助手回复上点 Fork，会生成一个「Fork of <原标题>」的新任务，继承到那一刻的历史、模型、思考档位。原任务继续跑。注意文件不会回滚——两个会话共享同一个工作区。

目标模式：让它自己「继续」

长任务最烦的是反复打「继续」。Goal Mode 就是解决这个的：

1

/goal 把 src/ 下所有 TypeScript 类型错误清零，且保持现有测试全绿

运行机制：每一轮结束后有一个独立的校验环节判断目标是否达成——不达成就输出下一步并自动开启下一轮，达成就收尾出总结。校验是证据驱动的：改动的文件、命令输出、测试结果算证据，而计划、清单、听起来很有信心的文字不算。任何未完成的 to-do 都会阻止收尾。

两种情况会被拒绝并给出原因：Plan mode 下（计划模式的目的是先定方案，和自动连轮冲突）和任务正在运行时。

配合 Full access 或 Edit 模式打断最少。目标状态在关闭再打开会话后仍然保留。

适合什么目标：一句话能说清、但需要很多轮才能做完的事——模块重构且测试保持通过、清零全部类型错误、把 Lighthouse 分数拉过 90。目标要可校验，「让它更快一点」这种不行。

子智能体：并行研究代码库

内置两个角色，都不能改名或删除，但可以给它们单独指定模型和思考档位：

• general-purpose — 默认的通用角色，拥有全部工具，适合自成一体的实现、验证跑批、并行工作
• Explore — 只读的代码库研究专家，用来梳理调用链、摸清架构、收集证据。它「不创建、不修改、不移动、不删除文件」

主智能体判断需要隔离上下文或并行研究时会自动通过 Agent 工具调起。你也可以显式指挥：

1

先用 Explore 研究一下这个模块的调用链，再决定怎么改

自建子智能体（Beta）

设置 → Subagents → New，保存后会写入 ~/.zcode/agents/<name>.md，下次运行生效。

Frontmatter 字段（camelCase，大小写敏感）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

---
name: code-reviewer
description: 审查当前改动的代码质量、边界条件和安全问题。需要代码评审时使用。
model: glm-5.3
thoughtLevel: high
color: blue
tools:
  - Read
  - Grep
  - Glob
maxTurns: 20
injectAgentsMd: true
---

你是一名严格的代码评审者。逐条给出问题、影响范围和修复建议……

几个容易踩的点：

• name 和 description 必填，缺任一个文件会被忽略并给出诊断
• description 直接决定自动选中率，写得越准越容易被自动调用
• tools 省略或写 * 表示继承全部（含 MCP）；一旦自定义列表就是穷举的，会把所有 MCP 工具排除掉（WebSearch / WebFetch 不受影响，因为它们不是 MCP）。需要 MCP 就手动写 mcp__<server>__<tool>，通配符无效
• thoughtLevel 只在指定了具体 model 时生效，注意不是 reasoningEffort，未知字段会静默失败
• injectAgentsMd 默认开启，会注入 ~/.zcode/AGENTS.md 和工作区的 AGENTS.md；Explore 永远不注入

限制：目前只支持用户级（~/.zcode/agents/），子智能体不能再派生子智能体，只能看到会话启动时已连接的 MCP 服务。

前台 vs 后台：前台子智能体并行跑但会阻塞主任务；后台的让主任务继续，自己稍后回报。后台的 Explore 被限制为只读工具。

指令文件 AGENTS.md

ZCode 读两个指令文件，全局在前、工作区在后，工作区文件视为权威：

• ~/.zcode/AGENTS.md — 个人跨项目偏好（回复语言、评审风格、本地工作流约定）
• <项目根>/AGENTS.md — 项目约定（架构边界、日志规范、测试要求、提交策略）

没有多级合并、不扫描子目录、不展开 @import / @include。CLAUDE.md 只作为一次性迁移来源，运行时不会持续读取。

内置 /init 命令针对的是当前工作区的 AGENTS.md。

我自己的工作区 AGENTS.md 长这样，纯文本约定就能显著改善智能体行为：

1
2
3
4
5
6
7
8
9

# 工作区约定

## 网络代理
- 唯一代理：socks5h://192.168.2.8:1081（仅 SOCKS5 模式可用）
- 所有访问境外服务的操作一律走此代理

## 博客写作流程
- 修改 source/_posts/*.md → 提交推送 hexo 分支 → npx hexo generate → npx hexo deploy
- 每篇新文章必须包含 ai: true 与 post_ai 摘要

另外还有一个独立的 项目记忆（Project Memory），由智能体自己写：设置 → 通用 → Memory（默认关闭）。它在成功的轮次后提炼可复用事实，新会话自动加载。代价是额外 token，且只对新会话生效，应用内不能浏览或清除，只作用于主对话，子智能体既不读也不写。

技能（Skill）

技能是「可复用的工作方法」。命令适合存提示词，技能适合装一整套方法论。

目录结构

目录名就是技能名，也是聊天里引用的 token：

1

~/.zcode/skills/<skill-name>/SKILL.md

也可以导入到当前项目作用域。要打包分发就放进插件，必须是扁平的 skills/<name>/SKILL.md 布局，套一层分组目录会导致识别不到。

SKILL.md 格式

Frontmatter 只有两个字段，都是必填：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

---
name: code-review-checklist
description: 按固定清单审查代码改动，覆盖边界条件、错误处理、并发安全和日志规范。需要代码评审或提交前自查时使用。
---

# 代码评审清单

## 何时使用
用户要求评审代码、提交前自查，或询问改动有什么风险时。

## 步骤
1. 用 git diff 拿到完整改动
2. 逐文件检查以下维度……

## 输出格式
按「文件:行号 → 问题 → 影响 → 建议」输出。

约束：

• 缺 name 或 description 会整个被忽略，原因在设置诊断里能看到
• description 上限 1024 字符，超了是整个技能作废而不是截断，长内容写正文
• 正文超过 100KB 会在加载时截断

调用方式

聊天框输入 $ 选技能，再接你的需求：

1

$code-review-checklist 审查我当前的改动

选中的技能会渲染成一个标签。输入 / 也能看到 Skills 分组。

上下文预算（这点很关键）

每一轮都会注入所有已启用技能的元数据：名字 + 最多 250 字符的描述摘要。正文是懒加载的，只在调用时才读。所有技能共享一个固定的元数据预算，溢出后会降级成只注入名字——这会直接毁掉模型自动选技能的能力。

所以技能装得越多，自动触发越不准。技能在面板里能看到但从来不触发，官方给了四个原因：元数据降级、description 太含糊、子智能体的 tools 白名单排除了技能工具、父插件被禁用。

内置技能

zcode-configuration-guide 默认启用、零配置，它是配置问题的「地图」。配套还有一批诊断技能：

• diagnosing-skills — 技能没被发现 / 不触发 / 被同名遮蔽
• diagnosing-commands — / 命令缺失 / 被覆盖 / frontmatter 报错
• diagnosing-mcp — MCP 连不上 / 工具不出现 / 超时
• diagnosing-hooks — Hook 不触发 / matcher 不匹配 / 脚本没有执行权限
• diagnosing-plugins — 插件不在列表 / 安装失败 / 组件缺失

目前没有独立的技能市场。设置 → Skills 里的导入图标可以扫描 Claude Code、Codex CLI、OpenClaw、Augment、Windsurf 的目录一键导入，可选软链接（跟随源变化，依赖路径不变）或复制（独立，不再同步）。

远程 SSH / WSL 工作区需要在工作区头部 Sync 下拉里手动 Sync Skill，因为用户级技能是本地的。

插件（Plugin）

一个插件可以同时打包 技能、命令、子智能体、MCP 服务、Hooks 五类组件。开关插件会一次性注册或撤销它的全部组件。

安装

设置 → Plugins 打开市场（需要先打开一个工作区，否则提示「Open a workspace to manage plugins」）。分两个板块：

• Public — 官方策展目录，分 Developer Tools、Productivity、Utilities、Guides、Templates 等分类
• Personal — 你自己添加的源，Claude Code 市场是预置的

点卡片一键安装，新装的插件默认启用。齿轮图标进入「管理已安装」，能看到版本、来源标签、组件数量，支持启停、状态筛选、检查更新和卸载。

官方插件市场

ZCode 官方市场地址是 https://cdn-zcode.z.ai/zcode/official-plugin/marketplace.json，当前收录：

内置插件（随应用发布）：

内置插件可以禁用但不能卸载——卸载会写一个抑制标记，升级也不会自动装回来。

插件结构

manifest 查找顺序是 .zcode-plugin/plugin.json（推荐），兼容回退到 .claude-plugin/plugin.json。它是唯一必需的文件：

1
2
3
4
5
6
7
8
9
10

{
  "name": "my-plugin",
  "version": "0.1.0",
  "description": "示例插件",
  "author": { "name": "你的名字" },
  "skills": "skills",
  "commands": "commands",
  "hooks": "hooks/hooks.json",
  "mcpServers": ".mcp.json"
}

只有 name 是必填，约束为 ^[a-z0-9][a-z0-9._-]{0,127}$。组件目录约定：commands/、skills/<name>/SKILL.md、agents/、hooks/hooks.json、.mcp.json。

channels、lspServers、outputStyles、settings 会被记录但不执行。插件提供的 MCP 服务键名会变成 plugin:<插件名>:<服务名>。

模板变量：${ZCODE_PLUGIN_ROOT}（兼容 ${CLAUDE_PLUGIN_ROOT}）、${CLAUDE_PLUGIN_DATA}、${CLAUDE_PROJECT_DIR}、${user_config.key}。

⚠️ 安全提示：官方文档原话是「启用插件即授予代码执行信任」。第三方插件可以拉起本地进程、读取智能体继承的环境变量。装之前先看一眼它的 hooks/hooks.json 和脚本。

自己发布插件

更新检测是拿市场条目里的版本号和已安装的 plugin.json 对比，所以发布时一定要同步 bump marketplace.json 的版本号，否则用户收不到更新提示。

市场清单必填 name 和 plugins，条目 source 支持相对路径，或 directory / github / git / file / url / npm 形式的对象。

MCP 服务

添加方式

设置 → MCP Servers → New MCP Server。表单模式覆盖大部分场景：选作用域、填名字（比如 memory）、类型保持 stdio、命令填 npx、参数填 -y @modelcontextprotocol/server-memory，Key 和路径放到环境变量里。

远程服务选 HTTP 或 SSE 填 URL，认证信息放 Headers。也可以切到完整配置模式直接粘 JSON，{"server-name": {...}} 和 {"mcpServers": {...}} 两种形状都接受。

导入图标会扫描这些文件：~/.claude/settings.json、~/.codex/config.toml、~/.config/opencode/opencode.json、~/.agents/mcp.json。原文件不动，导入结果落到 .zcode 里并默认启用。

配置文件路径

注意这个不对称：用户级原生配置在 .zcode/cli/ 下，工作区级直接在 .zcode/ 下。

配置示例：

1
2
3
4
5
6
7
8
9
10
11
12

{
  "mcp": {
    "servers": {
      "memory": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-memory"],
        "env": {},
        "enable": true
      }
    }
  }
}

字段：command、args、env、enable。远程条目用 URL 和可选 headers 代替 command。

加载规则

• 先读工作区配置，再读用户配置，两者都会出现在列表里
• 同一作用域内 .zcode 优先：只要它定义了任何服务，同级的 .agents/mcp.json 就整个被跳过，不做合并
• 禁用会写 "enable": false，字段缺失即启用
• 面板里的编辑只写 .zcode，永远不写 .agents
• 同名冲突时用户级覆盖工作区级

传输方式

• stdio — 本地命令执行，凭据只能走环境变量
• HTTP / SSE — 远程，支持可选 headers 和 OAuth

OAuth 服务（官方举例 Figma 官方 MCP）启用 OAuth 后，服务行上会出现「Open authorization」按钮，点它在系统浏览器里授权，ZCode 拿到 token 后重连。它不会自己弹浏览器窗口。

推荐的起步服务：智谱的 zai-mcp-server（视觉）、web-search-prime、web-reader，大多需要智谱 API token。

⚠️ 打开一个项目会自动连接它配置里的所有 MCP 服务，这些服务能跑命令、动文件、访问网络。打开不可信仓库前先看一眼 .zcode/config.json。

Hooks

七个事件钩子，可以在关键节点拦截、注入上下文、做权限门禁：

配置

只有用户级生效：~/.zcode/cli/config.json，且必须写 hooks.enabled: true（默认关闭）。工作区的 hooks 配置会被整个丢弃。插件的 hooks/hooks.json 自动发现，任何插件贡献了 Hook，Hook 运行器就会自动启用。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

{
  "hooks": {
    "enabled": true,
    "timeoutMs": 60000,
    "maxOutputBytes": 32768,
    "events": {
      "PreToolUse": [
        {
          "matcher": "Write|Edit",
          "hooks": [
            {
              "type": "process",
              "command": "python3",
              "args": ["scripts/audit.py"],
              "enabled": true,
              "timeoutMs": 8000
            }
          ]
        }
      ]
    }
  }
}

matcher 语法：缺省、空串或 * 匹配全部；只含字母、数字、下划线和 | 的字符串按精确名单处理（Write|Edit）；其他一律编译成 JS 正则，非法模式会被跳过并给出诊断。Agent / Task 是别名，会解析成真实工具名。

协议：ZCode 通过 stdin 发一行 JSON + 换行，字段同时提供 camelCase 和 snake_case 别名（session_id、cwd、hook_event_name、tool_name、tool_input、tool_use_id、transcript_path、permission_mode）。退出码 0 解析 stdout，2 是拦截快捷方式，其他非零表示该 Hook 可恢复地失败。只有以 { 开头的 stdout 会被解析，日志请走 stderr。

一个 SessionStart 注入上下文的最小示例：

1
2
3
4
5
6
7

const input = JSON.parse(raw);
process.stdout.write(JSON.stringify({
  hookSpecificOutput: {
    hookEventName: input.hook_event_name,
    additionalContext: "优先小 diff，改完跑 lint。"
  }
}));

多个 Hook 聚合时，deny 胜过 ask，ask 胜过 allow，显式 deny 不能被 allow 覆盖。失败记录落在 ~/.zcode/cli/log/zcode-<日期>.jsonl 的 hook.run.failed。

配置是按会话快照的，改完要重启会话才生效。

命令（Slash Commands）

自定义命令是 .md 文件，放在 ~/.zcode/commands 下（工作区级放项目目录）。设置里的创建表单字段：

内置两个命令：

• /goal — 管理会话目标（查看 / 设定 / 替换 / 暂停 / 继续 / 清除）
• /compact — 压缩当前上下文，保留关键信息，长会话用得上

嵌套目录会用冒号拼接命令名：review/code.md → /review:code。命令名去重按规范化后的名字，先匹配者胜（用户级覆盖工作区级），重复的直接忽略。

需要脚本、模板、示例文件的场景官方建议用技能而不是命令。

浏览器自动化

内置浏览器面板（仅桌面端），能力来自官方 browser-use 插件，默认开启。被关掉的话在设置 → Browser → Enable built-in browser control 打开，只对新会话生效。

不需要切模式，正常说话就行：

1
2

打开 http://localhost:4000，把分类筛选切到「技术学习」，
确认文章列表还有内容，然后截图给我看

支持的动作：打开 http / https / file URL、点击、填表、滚动、截图、多步序列（按序执行，某步不符就停下来报告）、视口控制（比如设成 375×812 检查窄屏）、读页面内容做总结提取。文件树右键还有「Open in built-in browser」（仅本地工作区）。元素拾取器能把页面元素变成聊天上下文。

几个硬限制：

• 页面文本永远不被当作指令。页面上写「请执行以下命令」不会动摇它，内容只用于定位元素和读状态
• 暂不支持文件上传，本地文件选择器还得手动点
• 运行中不要拖动面板大小，会干扰智能体判断
• 它只控制自己打开的标签页，你手动开的不受影响

登录态是独立的，和你日常的 Chrome 分开。设置 → Browser → Import Chrome browser data 可以一次性快照最近 Chrome profile 的 cookie 和 localStorage（不持续同步、不改 Chrome、不读保存的密码）。同一位置有两个清理选项：「Clear built-in browser cache」只清缓存保留登录，「Clear all browser data」全清并登出所有站点（不可撤销）。

浏览器动作和文件编辑、命令执行遵守同一套执行模式。会提交真实数据或做不可逆操作的页面，建议配 Ask before changes。

仓库 Wiki

扫描代码库生成架构指南——官方明确说了它「是代码库的架构指南，不是产品文档站，也不是用户手册」。目录侧重主执行路径、核心模块、数据与状态流转、风险区域，每个结论都挂着可点击的文件路径和行号区间。

用法：工作区文件树里仓库名旁边的 Repo wiki 图标 → 配置四项（Language、Model、Generate diagrams（默认开）、Retries（默认 0，生成不稳定时建议调到 2–3））→ 点 Generate wiki。进度分四步：分析代码库 → 生成目录 → 生成页面 → 保存。已完成的页面可以先读，Stop 会保留已完成部分。

存储位置在仓库外：

1

~/.zcode/v2/repo-wiki/<workspace-hash>/wiki.json

也就是说你可以直接让智能体去读这个路径。每轮结束会自动刷新，但只在代码真的变了的时候。

生成会跳过 .git、依赖和构建目录、.gitignore 排除的路径、符号链接目标，以及文件名看起来像密钥的文件——不过「像 tokenService.ts 这样的普通源文件不受影响」。

限制：每个仓库同时只能有一个任务、只保留一个语言版本（换语言重生成会替换掉）、单页不能单独重生成、没有版本历史。

自动化任务

左侧栏 Automations 入口（在项目工作流里，不在设置里）。分两类：定时任务按时间规则触发，空闲时段任务没有时间表，排队等有空余算力时免费跑。

三种创建方式：

1. 表单 — 「Create scheduled task」，填 Task title、Schedule、Instructions，加一个「Project / permission / model / thought level」工具条
2. 聊天 — 创建按钮旁的箭头选「Create in chat」，输入框会预填一句可编辑的话，比如「每个工作日早上 9 点，汇总这个项目的代码变更和待跟进项」
3. 模板 — 四个预填选项：Weekday standup digest、Daily risk scan、Friday release brief、Wednesday doc sync check，全是只读分析，只用仓库里可验证的事实

没有裸 cron 字段，只能选频率：Hourly / Daily / Every weekday / Weekly / Monthly / Custom。Custom 打开重复规则对话框，能设单位（小时到年）、每 N 个单位、指定周几 / 月内某天 / 某些月份 + 时分，月度重复还能选按日期或按序数星期（比如「第三个周一」）。时间用本机时区。

「Run now」立即触发一次，不影响时间表、运行次数和启停状态。

每次触发的输出留在一个会话里。从聊天创建的任务绑定在那个会话上，每次运行都回报到同一处。详情页在 Settings 和 History 之间切换，History 记录每次触发（包括因为机器睡眠被跳过的），并链到对应会话记录。

限制：电脑必须醒着、应用必须开着；漏掉的一次性运行只记为跳过，不会补跑；上限是跨所有项目 20 个任务，暂停 / 完成 / 失败的也占位；只能针对当前窗口打开的本地项目；手机远程控制里不可用。

无人值守跑的任务，权限模式格外重要。只做报告就锁在只读，除非你真的想让它自主改代码。

远程开发

点 Projects 旁的 + → Remote Connection，向导四步：选类型 → 填配置 → 连接 → 选目录。

• SSH — 可以选一个 SSH config 别名自动带出 Host / Port / Username / 密钥路径，认证支持密码或私钥（可带 passphrase）。「Resource download method」决定组件是桌面端下载再上传，还是让远端直接从 ZCode CDN 拉
• WSL — Distribution 和 Linux user 都可留空走默认。不建议用 root 连，工作区文件可能变成 root 所有，普通账号改不动
• Docker — 从运行中的容器里选，或手填名字 / ID。底层靠 docker exec 和 docker cp

要求：目标上要有 POSIX shell，不支持原生 Windows 远程主机（本机 Linux 请用 WSL）。Docker 需要守护进程在跑、容器已启动、项目目录可达、工具链（shell、Git、Node.js 等）齐备。

限制：

• 跳板机不支持 — 内置 SSH 客户端忽略 ProxyJump / ProxyCommand，请改用本地端口转发
• 设置里的 HTTP 代理不覆盖 SSH 和 Web 远程控制
• 配置同步（Sync Skill / Sync MCP / Sync Plugin）是手动的、仅用户级、不覆盖已有远端条目，支持 SSH 和 WSL 但不支持 Docker。MCP 密钥是原样传输的，敏感类型和路径类型的插件选项会被跳过
• 首次连接会慢，因为要预置远端服务和智能体运行时，后续会复用

账号、模型配置和全局设置留在桌面端；文件、命令、Git 和智能体执行都发生在目标机上。

手机远程控制

扫码模式

左下角侧栏的手机图标打开 Mobile Remote Control。对话框左边是二维码和链接，右边是 Bot Channel。扫码适合短时使用，机器人适合跨天反复用。

手机上能做什么：

• 任务主页 — 列出工作区和任务，可按工作区或时间线分组，按创建或更新时间排序，下拉刷新，在已有工作区里新建任务，重连掉线的远程工作区
• 会话视图 — 看智能体回复、执行步骤、进度，底部输入框追加指令，回复支持复制、点赞点踩和分叉

手机上什么都不跑。本地工作区在你的桌面上执行，SSH 目标在远程主机上，WSL 用选定的发行版，Docker 用目标容器。手机只是把指令递进桌面已经打开的那条连接里。同时只能连一个手机页面。

🔐 链接本身就是凭据——「拿到它的任何人都能操作你的窗口」。关掉对话框不会结束会话，要真正终止得点 Stop。重新生成二维码会立刻作废之前的链接，怀疑泄露就重新生成。桌面端必须保持运行和在线。

限制：手机上不能新建 SSH / WSL / Docker 连接，那些参数得在桌面填；已注册但断开的远程工作区可以从手机重连，但连接动作还是桌面做的。

机器人通道

目前只支持两个平台：

• 微信 — 扫码登录自动绑定，一步搞定
• 飞书 — 扫码在飞书开放平台创建应用（确认名称和头像，点「立即创建」），然后把 ZCode 生成的限时绑定命令（形如 /bind C67356）发给这个应用

钉钉、Discord、企业微信官方说在后续版本支持。

绑定后机器人能：报告状态、创建任务、切换项目、切换模型、更改运行模式、调整回复详细度。管理项包括启停、连接状态、解绑、删除、回复粒度，以及限制机器人能打开哪些工作区。

飞书 / Lark 有个特殊行为：总是用流式卡片回复，所以粒度设置（Standard / Full / Summary）对它不生效。回复在同一张卡片里原地更新，工具调用是折叠的。需要你做决定时，当前卡片冻结，问题单独发一张卡片，之后再起一张新卡片继续。

使用示例

下面是几个我实际跑过的场景，能看出 ADE 和普通补全工具的差别。

示例一：读源码定位问题（而不是猜）

Hexo 博客的文章链接是中文标题转码后一长串 %E4%B8%AD...，我想换成英文短链。直接问「怎么改」大概率会得到「在 frontmatter 加 slug 字段」这种答案——但这是错的。

1
2
3

permalink 已经改成 :year/:month/:day/:slug/，并且给所有文章的
frontmatter 加了 slug 字段，但生成出来的目录还是中文。
读 node_modules/hexo/dist/ 里的源码找出 :slug 到底从哪里取值。

智能体读了 node_modules/hexo/dist/plugins/processor/post.js，在第 49 行找到 data.slug = info.title;，其中 info 来自 parseFilename(config.new_post_name, path)；又核对了 preservedKeys 只有 {title, year, month, day, i_month, i_day, hash}，不含 slug。

结论：:slug 取的是 .md 文件名，frontmatter 里的 slug 完全不起作用。真正的解法是重命名文件。这种「读源码给证据」的能力，是靠猜的工具给不了的。

示例二：Explore 子智能体做代码库调研

1
2

先用 Explore 摸清这个项目的主题配置是怎么加载的，
把所有引用头像 URL 的地方都列出来，再决定改哪几处

Explore 只读、独立上下文，跑完只把结论汇总回主对话——不会把几十个文件的原文塞进主上下文。它找到了 5 处引用：favicon、avatar.img、preloader.avatar、pwa.favicon_32_32、pwa.favicon_16_16。少改一处，浏览器标签页图标就还是旧的。

示例三：目标模式跑长任务

1
2
3

/goal 把 source/_posts/ 下所有中文文件名改成语义化英文短名，
保持 git 记录为纯重命名（R100），清掉 frontmatter 里无用的 slug 字段，
然后重新生成站点确认没有残留的中文目录

这个任务实际跑了好几轮：重命名 → 生成 → 发现 public/ 里同时存在新旧两套目录 → 定位到 db.json 缓存 → rm -rf public db.json → 重新生成 → 校验通过。目标模式的价值就在这——中间失败一次它自己会诊断并继续，不用我盯着打「继续」。

示例四：技能封装重复流程

我把博客的写作规范做成技能，每次写文章只需要一句 $blog-post 写一篇 XXX 部署教程，它就知道要带 ai: true + post_ai 摘要（且摘要里不能出现英文逗号，否则主题的 ai_abstract.js 会按逗号切分随机取一段）、要有 ## 参考资料、结尾要有固定的三个推荐链接。

这类「有固定套路但细节容易漏」的流程最适合做成技能。

示例五：浏览器自证改动

1
2

博客本地起在 4000 端口。打开首页，检查头像是不是新换的那张，
再点进任意一篇文章确认 AI 摘要框正常渲染，两处都截图

改完前端能自己验证，比我手动开浏览器点一遍快得多，而且截图留了证据。

常见问题

应用要钱吗？

应用本身免费，但模型能力要你自己提供：智谱系（GLM Coding Plan 订阅、BigModel 资源包或余额、Z.ai）、企业渠道，或团队批准的自建服务。

为什么终端里配好的 Key 应用读不到？

终端环境变量和桌面应用是相互独立的。必须在应用内配置：Quick Connect 走账号，或在「管理模型」里手填 Base URL + API Key。

终端能联网，应用连不上？

大概率是代理。设置 → 通用里的 HTTP Proxy 留空不代表跟随系统，ZCode 完全忽略 HTTP_PROXY 环境变量。填上代理并重启应用。注意代理不覆盖 SSH 和 Web 远程控制。

模型一直卡在 Loading？

两个方向：网络到不了模型服务，或者账号 / Key 没有额度和模型访问权限。

明明是百万上下文，为什么显示 200K？

缺少窗口元数据的模型会回落到 200,000。模型 ID 带 [1m] 后缀会被自动当成 1,000,000，否则以你手填的值为准。Coding Plan 的 GLM 模型窗口是固定的、不可编辑。

为什么还没到上限就开始压缩上下文？

压缩是故意提前触发的：预留输出空间 + 约 13,000 token 安全缓冲，输出预留上限 21,000，合计扣掉约 34K。所以 128K 窗口在 94K 附近就会压缩，而且触发判断还会算上当前轮工具结果的实时估算。没有用户可调的阈值。

技能面板里有，但从来不触发？

四个原因：元数据预算溢出导致降级成只注入名字、description 写得太含糊、子智能体的 tools 白名单排除了技能工具、父插件被禁用。装太多技能会直接拖垮自动选中率。

Linux AppImage 起不来？

多半缺 libfuse2（Ubuntu / Debian 用 apt 装）。从终端启动能看到具体报错，GPU 相关的崩溃可以加 --disable-gpu 走软件渲染。

浏览器登录完成但不跳回应用，是 zcode:// 协议处理器没配对——常见原因是用了 sudo、挪动了 AppImage 位置、或者 deb 和 AppImage 同时装了。检查一下：

1

xdg-mime query default x-scheme-handler/zcode

保持 AppImage 在一个固定路径。

换电脑怎么迁移配置？

要带走的：cli/config.json、v2/config.json、AGENTS.md，以及 agents/、skills/、commands/ 目录。

不要迁移 credentials.json 和 telemetry-state.json——这两个必须留在原机。

~/.zcode/cli/exec 能删吗？

应用完全关闭的情况下可以删，代价只是丢历史命令输出。

版本号在哪看？

Windows 和 Linux 在 Help → About ZCode，macOS 在 ZCode 菜单里。

小结

用了一段时间下来，ZCode 和「AI 补全插件」不是一类东西。差别集中在三点：

1. 它会去读源码找证据，而不是凭印象给答案（示例一里那个 :slug 问题就是典型）
2. 目标模式 + 子智能体让长任务真的能一口气跑完，中间失败它自己诊断继续
3. 技能 / 插件 / MCP / Hooks 四层扩展加上 AGENTS.md，能把团队规范固化成智能体行为

上手路径建议：先装好连上模型，用几天默认的 Ask before changes 熟悉节奏；然后写一个工作区 AGENTS.md 把项目约定固化下来；再把重复流程做成技能；最后按需接 MCP 和插件。别一上来就装几十个技能——上下文预算会溢出，反而让自动选中变得更差。

参考

• ZCode 官网
• ZCode 安装文档
• ZCode Agent 文档
• 目标模式文档
• 技能文档
• 插件文档
• MCP 服务文档
• Hooks 文档
• 子智能体文档
• 浏览器自动化文档
• 远程开发文档
• 手机远程控制文档
• 常见问题
• 更新日志

推荐链接

• 大佬CM博客
• 大佬周润发博客
• 大佬青云志博客