主题
ZCode 使用指南
ZCode 是面向真实开发工作流的桌面 AI 编程工具，支持项目工作区、终端命令、代码修改、任务规划、浏览器预览和变更审查。
ZCode 官方文档说明，它支持通过 API Key 接入兼容 Anthropic 或 OpenAI 协议的第三方模型服务。本页整理使用 FlexAPI 接入 ZCode 的基础流程。
Step 1: 安装 ZCode
前往 ZCode 官方安装文档，根据系统选择对应安装包：
- macOS：下载并打开
.dmg，将 ZCode 拖入 Applications。 - Windows：下载安装程序，按照向导完成安装。
- Linux：下载
.AppImage、.deb或.rpm文件。
首次启动后：
- 完成首次启动设置。
- 选择一个项目目录作为工作区。
- 在对话框中输入一句简单指令，确认 Agent 可以正常响应。
Step 2: 准备 FlexAPI API Key
- 登录 FlexAPI。
- 选择要使用的分组。
- 创建或复制 FlexAPI API Key。
- 确认当前分组已经开通要使用的模型。
Step 3: 在 ZCode 中添加 FlexAPI
ZCode 官方的配置入口为：
- 点击对话框中的模型名称，打开模型选择器。
- 点击列表底部的“管理模型”。
- 进入“设置 → 模型设置”。
- 新增一个模型供应商或模型通道。
- 填写 FlexAPI 的协议、接口地址、API Key 和模型 ID。
OpenAI 兼容配置
如果你要使用 FlexAPI 的 OpenAI 兼容模型，填写：
| 配置项 | 填写内容 |
|---|---|
| 协议 | OpenAI |
| 接口地址 | https://flexapi.me/v1 |
| API Key | 你的 FlexAPI API Key |
| 模型 ID | FlexAPI 当前支持的模型，例如 gpt-5.6-sol |
保存后启用该模型，在模型选择器中选中它即可开始使用。
Anthropic 兼容配置
如果你要使用 FlexAPI 的 Anthropic 兼容模型，填写：
| 配置项 | 填写内容 |
|---|---|
| 协议 | Anthropic |
| 接口地址 | https://flexapi.me |
| API Key | 你的 FlexAPI API Key |
| 模型 ID | FlexAPI 当前支持的 Claude 模型 |
注意端点格式
OpenAI 兼容接口使用 https://flexapi.me/v1；Anthropic 兼容接口使用 https://flexapi.me，不要混用两个端点。
Step 4: 创建第一个任务
进入项目工作区后，可以从简单任务开始：
text
请先阅读当前项目结构，告诉我这个项目的启动命令，不要修改文件。确认模型可以读取项目后，再尝试：
text
请检查当前项目是否存在构建错误，先给出问题列表，不要直接修改文件。需要修改代码时，建议明确说明：
- 需要修改的文件或目录
- 期望实现的行为
- 是否允许执行安装、构建或测试命令
- 修改完成后需要运行哪些检查
常用工作流
规划任务
对于跨多个文件的需求，先让 ZCode 拆分任务并说明准备修改的文件，再确认执行。
text
请先拆分这个需求的实施步骤，并列出每一步会修改的文件。运行命令
可以让 Agent 在工作区内执行安装、构建和测试命令。涉及删除文件、修改配置或访问外部服务时，应先确认命令内容。
text
请运行项目的构建命令，并根据输出定位错误。检查变更
完成修改后，可以要求 ZCode 汇总变更并进行审查：
text
请检查这次修改的 diff，确认没有引入明显的功能回归。浏览器预览
如果项目有本地开发服务，可以让 ZCode 启动项目并使用内置浏览器打开本地地址，检查页面布局和交互。
常见问题
模型列表为空
- 确认已经进入“管理模型”页面并保存配置。
- 确认模型 ID 与 FlexAPI 支持的模型完全一致。
- 确认 API Key 没有多余空格或换行。
- 确认对应供应商或模型通道已启用。
返回 404 或端点错误
- OpenAI 协议使用
https://flexapi.me/v1。 - Anthropic 协议使用
https://flexapi.me。 - 不要把 OpenAI 的
/v1追加到 Anthropic 地址后面。
返回 400 参数错误
先确认协议与模型类型是否匹配，再检查模型是否支持当前的思考强度或工具调用参数。必要时可以先关闭高级思考选项，用普通请求验证 API Key 和端点是否正常。
网络连接失败
ZCode 可以在“设置 → 常规”中配置 HTTP 代理、代理例外和自定义证书。修改网络代理后，需要按官方说明重启应用。