# ZCode

> 全部文档的索引见 [llms.txt](https://ark.volcengine.com/llms.txt)；在任一文档页面地址后追加 `.md` 可获取该页的 Markdown 版本。

本文介绍如何在 ZCode 中配置并使用方舟 按量计费模型服务。

<span id="pre-operation"></span>
# 前提条件

在配置工具前，需要 [开通所需的模型服务](https://ark.volcengine.com/region:cn-beijing/openManagement?LLM=%7B%7D&OpenTokenDrawer=false)。

<span id="install-zcode"></span>
# 安装 ZCode

访问 [ZCode 官网](https://zcode.z.ai/cn#all-downloads)，下载并安装适合您操作系统的版本。安装步骤可参考 [ZCode 官方安装教程](https://zcode.net.cn/en/docs/install#setup-guide)，安装完成后按提示登录。

<span id="4dd21a01"></span>
# 配置 ZCode

按量计费模型服务同时兼容 OpenAI 与 Anthropic 接口协议，ZCode 均支持。以下以 **OpenAI 协议**为例；如需使用 Anthropic 协议，将 API 格式改为 **Anthropic** 并把 Base URL 换成 `https://ark.cn-beijing.volces.com/api/compatible` 即可。

<span id="method-2-manual"></span>
## 手动配置

1. 打开 ZCode 客户端，单击左下角 **设置** 图标，进入 **模型设置**，单击 **添加供应商**。

![zcode-setting.png](https://arkdocs.tos-cn-beijing.volces.com/images/CodingPlan/zcode-setting.png)

2. 在弹出的表单中填写以下字段，保存供应商。

    * **名称**：自定义，便于识别，例如 `Ark 按量计费模型服务`。
    * **Base URL**：`https://ark.cn-beijing.volces.com/api/v3`（OpenAI 协议）；若使用 Anthropic 协议，填 `https://ark.cn-beijing.volces.com/api/compatible`。
    * **API Key**：填写您的 [API Key](https://ark.volcengine.com/region:cn-beijing/apikey)。
    * **API 格式**：取决于选择的 Base URL。

        |API 格式 |Base URL |
        |---|---|
        |Anthropic Messages |`https://ark.cn-beijing.volces.com/api/compatible` |
        |Chat Completions |`https://ark.cn-beijing.volces.com/api/v3` |
        |Responses |`https://ark.cn-beijing.volces.com/api/v3` |

3. 单击 **添加模型**，在表单中填写以下字段，保存模型。可以多次点击 **添加模型**，为一个供应商添加多个模型。

    * **模型 ID**：填入需要使用的 Model ID，模型列表参见 [模型列表](/docs/model-list)。
    * **上下文窗口**：按所选模型的最大上下文长度填写。
    * **最大输出 Token**（可选）：按需填写，默认可留空跟随模型上限。

除了在客户端 UI 中添加供应商，也可以直接编辑本地配置文件 `~/.zcode/v2/config.json`（Windows 系统为 `%USERPROFILE%\.zcode\v2\config.json`）。首次通过 UI 完成任意配置后该文件会自动生成，已有内容时在 `provider` 对象中追加一条即可。

API 格式为**Anthropic Messages**时，`~/.zcode/v2/config.json` 示例

```JSON
{
  "provider": {
    ...
    "volcengine": {
      "name": "Ark 按量计费模型服务",
      "kind": "anthropic",
      "options": {
        "apiKey": "<ARK_API_KEY>",
        "baseURL": "https://ark.cn-beijing.volces.com/api/compatible",
        "apiKeyRequired": true
      },
      "enabled": true,
      "source": "custom",
      "models": {
        "doubao-seed-evolving": {
          "limit": { "context": 1024000, "output": 262144 },
          "modalities": { "input": ["text", "image"], "output": ["text"] }
        }
      }
    }
    ...
  }
}
```

API 格式为**Chat Completions**时，`~/.zcode/v2/config.json` 示例

```JSON
{
  "provider": {
    ...
    "volcengine": {
      "name": "Ark 按量计费模型服务",
      "kind": "openai-compatible",
      "options": {
        "apiKey": "<ARK_API_KEY>",
        "baseURL": "https://ark.cn-beijing.volces.com/api/v3",
        "apiKeyRequired": true
      },
      "enabled": true,
      "source": "custom",
      "models": {
        "doubao-seed-evolving": {
          "limit": { "context": 1024000, "output": 262144 },
          "modalities": { "input": ["text", "image"], "output": ["text"] }
        }
      }
    }
    ...
  }
}
```

API 格式为**Responses**时，`~/.zcode/v2/config.json` 示例

```JSON
{
  "provider": {
    ...
    "volcengine": {
      "name": "Ark 按量计费模型服务",
      "kind": "openai",
      "options": {
        "apiKey": "<ARK_API_KEY>",
        "baseURL": "https://ark.cn-beijing.volces.com/api/v3",
        "apiKeyRequired": true
      },
      "enabled": true,
      "source": "custom",
      "models": {
        "doubao-seed-evolving": {
          "limit": { "context": 1024000, "output": 262144 },
          "modalities": { "input": ["text", "image"], "output": ["text"] }
        }
      }
    }
    ...
  }
}
```

> **注意**
>
> * `<ARK_API_KEY>` 替换为您的 [API Key](https://ark.volcengine.com/region:cn-beijing/apikey)。
> * 如需使用其他模型，请替换 Model ID，并根据实际模型能力调整上下文窗口、最大输出 Token 和输入模态。模型列表参见 [模型列表](/docs/model-list)。

4. 保存完成后，回到 ZCode 主界面。

<span id="use-zcode"></span>
# 使用 ZCode

1. 在 ZCode 主界面顶部的模型下拉中，选中刚添加的模型。
2. 在对话框输入你的需求（如生成代码、修复 bug、重构、写单元测试），回车即可开始对话开发。ZCode 支持规划、编码、评审与上线等全流程研发场景。

> 更多使用技巧和高级功能参见 [ZCode 官方文档](https://zcode.net.cn/en/docs)。