# ZCode

> 在 NeuroSquad 卡片中运行 Z.ai 的 ZCode——如何安装、哪些功能可用、哪些暂不支持。

Source: https://docs.neurosquad.ai/zh/agents/zcode

**ZCode** 是 Z.ai 围绕自家 GLM 模型打造的编程智能体。Z.ai 以 Apache-2.0 协议公开了它的源代码；`zcode`
命令在终端里运行与 ZCode 桌面应用相同的智能体运行时。在 NeuroSquad 中，每个 ZCode 智能体都是一张卡片，
里面运行着真正的 `zcode`。

基于 ZCode 运行时 0.16.9（`zcode-app-cli` 3.14.4-32）实测。

## 安装

**1. 安装 zcode 命令**

Z.ai 没有提供现成的终端版下载，所以 `zcode` 命令来自 npm：

```bash
npm install -g zcode-app-cli@latest
```

`zcode-app-cli` 是一个非官方客户端，原样附带 Z.ai 的运行时。NeuroSquad 的 **Settings → Setup**
可以替你安装它。从 Z.ai 自己的仓库构建的 `zcode` 同样可用。

**2. 设置提供方**

按你平常的方式在 ZCode 中设置提供方和默认模型——卡片会从你的提供方开始。卡片也可以改用
[OpenRouter](https://docs.neurosquad.ai/zh/providers/openrouter) 或 [你自己的服务器](https://docs.neurosquad.ai/zh/providers/your-servers)。

**3. 添加 ZCode 卡片**

添加一张智能体卡片并选择 **ZCode**。NeuroSquad 会确认找到的 `zcode` 确实是 ZCode——同名的无关工具不会被使用。

## 可用功能

- **准确的状态。** ZCode 自己的钩子告诉卡片它何时在工作、已完成或在等你——并附上它想做的调用
（`ZCode needs your permission: Bash rm -rf dist`）或它提出的问题。参见[已完成 / 需要你的输入](https://docs.neurosquad.ai/zh/agents/notifications)。
- **箭头。** NeuroSquad 的 MCP 服务器写在卡片的设置里，它自己的工具不会弹出授权。ZCode 只读取一次服务器的工具，
所以卡片一开始就拿到 NeuroSquad 的全部工具，由箭头在调用时决定。技能或已安装的 MCP 服务器需要卡片下次启动后生效。
- **卡片模式。** Bash、它的后台 shell 和网络工具从模型可见的列表中移除，危险模式下也一样。参见[卡片模式](https://docs.neurosquad.ai/zh/squads/canvas-mode)。
- **会话。** 重启后卡片继续同一段对话（`zcode --resume`）。被删除的会话会换成新会话。
- **长时间会话。** 上下文仪表、**Compact**（ZCode 的 `/compact`）、提示词队列、日志和交接。
- **用量。** 每次请求都从 ZCode 自己的用量账本读取——包括标题、压缩和子智能体，子智能体会单独标记——
显示在[用量与费用](https://docs.neurosquad.ai/zh/usage)、[Run Stats](https://docs.neurosquad.ai/zh/cards/run-stats) 和 [Agent Pulse](https://docs.neurosquad.ai/zh/cards/agent-pulse) 中。
- **模型与提供方。** 每张卡片单独选择模型；主智能体可以通过 `agent_set_model` 更换。OpenRouter 和你自己的服务器都可用，
密钥不会写进任何文件。
- **切换 CLI。** 把对话迁到 Claude Code 再迁回来。
- **插件。** [记忆](https://docs.neurosquad.ai/zh/plugins/mem0-memory)、[Context7](https://docs.neurosquad.ai/zh/plugins/context7-docs)、[Caveman](https://docs.neurosquad.ai/zh/plugins/caveman) 和
[Graphify](https://docs.neurosquad.ai/zh/plugins/graphify) 都能作用于 ZCode 的每一轮；[省令牌](https://docs.neurosquad.ai/zh/plugins/rtk-ai-token-saver)在危险模式下可用。
- **在手机上。** 在[远程访问](https://docs.neurosquad.ai/zh/remote)中，这张卡片和其他卡片一样可用。

## 危险模式

ZCode 卡片以 `--mode yolo` 进入危险模式。开启或关闭都会让卡片用同一段对话重启；关闭后以你平常的模式继续。
参见[危险模式](https://docs.neurosquad.ai/zh/agents/dangerous-mode)。

## 须知

- **你的 `~/.zcode` 只会被读取。** 每张卡片都有自己的一份设置副本（你的设置加上 NeuroSquad 的）、自己的会话数据库，
必要时还有自己的提供方文件。密钥和令牌永远不会写到磁盘上。
- **用 Esc 停止这一轮。** 空闲时按 Ctrl+C 会退出 ZCode，所以 NeuroSquad 从不发送它——预算刹车和手机按键行都用 Escape。
- **卡片里 ZCode 的项目记忆是关闭的**，除非你自己的 `setting.json` 开启了它。它的后台调用在任何地方都没有记录，
用量无法统计；如果你开启它，这些调用不会出现在用量里。
- **对话保存在卡片的数据库里。** 只有当 `ZCODE_SESSION_DB_PATH` 指向那个文件时，你在自己终端里运行 `zcode --resume`
才能找到它们。删除卡片不会删除数据库。
- 按下 Escape 之后，ZCode 的终端界面会吞掉你按的下一个键。

> ZCode 卡片只在本机运行——暂不支持 WSL 或 SSH 工作区。