常见问题解答 (Q&A)
在这里，我们汇总了关于 ZCode 的产品定位、费用说明以及在使用过程中可能遇到的技术问题的解答。
1. ZCode 的产品定位是什么？
ZCode 是一个全新的智能体开发环境（Agentic Development Environment，ADE），与传统 IDE 不同，ZCode 不以手动编写代码为核心，而是让 AI Agent 成为开发的主角——您只需用自然语言描述需求，Agent 即可驱动从编码、调试到预览的完整开发流程。
- ADE 平台：围绕自研 ZCode Agent 内置文件管理、终端、Git 提交及实时浏览器预览，通过自然语言指令驱动 Agent 完成全生命周期开发任务。
- 全上下文感知：Agent 能够深入理解项目结构、文件内容以及 UI 视觉元素，无需记忆复杂的命令行参数。
- 当前重点：围绕自研 ZCode Agent 强化长任务执行和稳定性，把工作区、工具、模型、权限和 Review 串成连续的开发流程。
2. ZCode 免费吗？
ZCode 工具本身完全免费。但作为开发者，您需要准备自己的 API Key 或模型服务套餐。目前支持以下接入方式：
- 智谱系列：GLM Coding Plan 编程套餐、智谱开放平台模型资源包/充值余额、智谱 Z.ai。
- 模型服务：ZCode Agent 可使用已接入的模型服务和套餐。
- 企业模型通道：团队统一维护、供 ZCode Agent 稳定调用的模型通道。
- 自托管服务：团队批准的私有化模型服务或专有网络模型资源。
3. 我的终端已配置好 GLM API，还需要在 ZCode 重新配置吗？
需要。终端环境变量和 ZCode 桌面端的模型配置是两套独立入口，配置不会自动同步。您可以选择以下任一方式：
- 快速连接：在欢迎页面或个人头像处连接 BigModel/Z.ai 账号，若账户内有可用套餐将自动连接。
- 手动管理：通过模型选择器底部的「管理模型」进入 模型设置，手动添加 Base URL 和 API Key。
4. Connect 之后一直 Loading？
如果模型服务连接一直处于 Loading，请优先检查：
- 网络环境：确保当前网络可以访问对应模型服务。
- 账号权限：确保登录账号或 API Key 拥有可用额度和模型访问权限。
5. 怎么把整个文件夹作为上下文交给 Agent？
有两种方式，都可以。
用 @ 直接选：输入框中的 @ 选择器会同时列出文件和文件夹，也可以选择技能和智能体。输入 @ 后继续输入名称筛选，用方向键在候选项之间循环选择即可。
拖拽进输入框：
- 从 ZCode 左侧文件树中拖拽文件夹到输入框。
- 从 Finder、资源管理器等系统文件管理器中拖拽文件夹到输入框。
无论哪种方式，ZCode 都会把该文件夹作为上下文引用，Agent 可以围绕目录结构和其中的文件继续分析或执行任务。
6. GLM Coding Plan、Anthropic 端点、OpenAI 通用端点有什么区别？
BigModel（国内）与 Z.ai（海外）在 API Key 模式下提供 三类端点（详见 连接模型 → BigModel / Z.ai API 端点说明）：
| 端点 | 典型地址（BigModel） | 何时使用 |
|---|---|---|
| Coding Plan 专用 | https://open.bigmodel.cn/api/coding/paas/v4 | 已购 GLM Coding Plan，用 API Key 接入 Coding 场景 |
| OpenAI 通用 | https://open.bigmodel.cn/api/paas/v4 | 开放平台模型资源包 / 充值余额，走 OpenAI 兼容协议 |
| Anthropic | https://open.bigmodel.cn/api/anthropic | 同上资源包 / 余额，走 Anthropic 协议（ZCode 默认） |
常见误区：
- 买了 Coding Plan，却把 OpenAI 地址填成通用端点
/api/paas/v4→ 无法正常消耗编程套餐额度。 - 只有资源包 / 余额，却填了 Coding 端点
/api/coding/paas/v4→ Coding 端点仅限 Coding 场景，不适用于通用 API。 - 通过 「编程套餐」账号授权（非 API Key）连接时，无需手动填端点，ZCode 会自动路由。
海外 Z.ai 请将地址中的域名替换为 api.z.ai，路径规则相同。
7. Linux / WSL 下无法启动、登录后没有回到 ZCode、中文输入法用不了？
Linux 桌面和 Windows WSLg 环境下，这三类问题最常见，多数可以按下面的思路快速定位：
- AppImage 无法启动：多数是缺少
libfuse2（Ubuntu / Debian 执行sudo apt install libfuse2）；点击图标无反应时先从终端启动一次看报错；GPU 相关报错可加--disable-gpu等软件渲染参数。 - 浏览器登录完成但没有回到 ZCode：通常是系统没有正确关联
zcode://打开方式，常见诱因包括用sudo启动、AppImage 登录前后被移动，或 deb 与 AppImage 混装。用xdg-mime query default x-scheme-handler/zcode检查，并将 AppImage 放在固定路径后重新启动。 - 只能输入英文 / 输入法失效：和当前会话的 IBus / Fcitx5 环境变量有关，从已配置好输入法环境的 shell 启动 ZCode 即可；WSLg 下首个中文字符不显示是已知兼容性问题，可先输入一个占位字符再删除。
每一步的完整命令、启动脚本示例，以及反馈问题时需要收集的诊断信息，见 Linux / WSL 排查指南。
8. 上下文容量显示得比模型实际窗口小？自定义模型的窗口怎么填？
每个模型条目都带一个 上下文窗口 值，ZCode 按这个值计算容量，规则如下：
- 新加的模型、或没带窗口信息的模型，默认按 20 万（200000）计算。 这就是接入百万上下文模型后，容量仍显示 20 万的原因。
- 模型 ID 以
[1m]结尾会被识别为百万上下文，自动按 100 万处理，不需要手填。 - 其他情况以你填写的数值为准——需要 1M 就填
1000000。
在 设置 → 模型供应商 里展开对应模型即可修改。注意：通过编程套餐（Plan）连接的内置 GLM 模型，窗口由产品统一固定、不可编辑；只有用 API Key 方式添加的模型才允许自己改。
会话显示的容量取自该会话当前所选模型的窗口，所以同一个项目里不同会话显示不同容量是正常的——旧会话沿用它当时用的模型。
9. 为什么远没用满就开始「自动压缩」？
自动压缩不是按整个上下文窗口算的，而是按 有效窗口 = 上下文窗口 − 输出预留：
- 占用达到有效窗口的 95% 时触发压缩（并至少留出约 13000 token 的缓冲）。
- 输出预留默认是 32000 token。 但只要你在模型的 高级 → 最大输出 Token 里手填了数值，预留就等于你填的那个值。
也就是说，把最大输出调到 128000，相当于先从窗口里扣掉 12.8 万，压缩自然来得早很多。这一项建议保持留空，跟随模型自身上限即可。
如果窗口本身还在按默认的 20 万计算（见上一条），提前压缩会更明显——先把窗口值填对，再看压缩时机。
10. 子智能体没有用我指定的模型？
分两种情况：
- 内置的
general-purpose和Explore：可以在设置里分别为它们指定模型；不指定时继承父会话的主模型——这是设计行为。想让它们固定用某个模型，就在设置里配上持久覆盖，清空即恢复继承。 - 自定义 / 工作区 / 插件子智能体：仍以各自 Markdown 文件里的
model字段为准。
所以「派出去的子智能体跟着主会话的模型跑」在没有配置覆盖时是预期结果，不是故障。
11. 技能列表是空的，全局技能不显示？
先确认技能文件放对了位置：
- 用户级（全局）：
~/.zcode/skills/<技能名>/SKILL.md - 工作区级：
<工作区>/.zcode/skills/<技能名>/SKILL.md
目录为空时，列表里自然不会有全局技能。确认目录里确实有技能后，再按这三步排查：
- 在 设置 → 技能 里按来源查看，确认没有被搜索框或来源筛选挡住。
- 新建或导入的技能需要点 刷新 才会出现。
- 检查每项右侧的启用开关是否处于开启状态。
完整的目录结构与导入方式见 Skill。