ZCode

ZCode 不读取 OPTIWAVES_API_KEY 环境变量。把 OptiWaves 密钥写入配置文件的 options.apiKey。也可以运行 optiwaves 并选择 ZCode，由 CLI 完成安装与写入。

1. 安装官方客户端

从 ZCode 官网下载并安装官方桌面端或 CLI。不要使用社区 npm 包。本机已有 ZCode.app、ZCode.exe 或 zcode 命令时，跳过这一步。

2. 写入桌面配置

系统	文件
macOS / Linux	`~/.zcode/v2/config.json`
Windows	`%USERPROFILE%\.zcode\v2\config.json`

将密钥替换为你的 ow_ 密钥，文件权限设为仅当前用户可读：

~/.zcode/v2/config.json

{
  "model": "optiwaves/auto",
  "provider": {
    "optiwaves": {
      "name": "OptiWaves",
      "kind": "openai",
      "apiFormat": "openai-responses",
      "source": "custom",
      "enabled": true,
      "options": {
        "baseURL": "https://api.optiwaves.app/v1",
        "apiKeyRequired": true,
        "apiKey": "ow_your_api_key_here"
      },
      "models": {
        "auto": {
          "name": "OptiWaves Auto",
          "reasoning": true,
          "options": { "store": false }
        }
      }
    }
  }
}

kind 使用 openai，apiFormat 使用 openai-responses。Base URL 带 /v1。模型项保留 options.store: false，保证工具执行后继续发送完整上下文。

3. 写入 CLI 配置

同时使用 ZCode 命令行时，编辑另一份文件，provider 与桌面配置相同，模型写在 main 和 lite：

系统	文件
macOS / Linux	`~/.zcode/cli/config.json`
Windows	`%USERPROFILE%\.zcode\cli\config.json`

~/.zcode/cli/config.json

{
  "model": {
    "main": "optiwaves/auto",
    "lite": "optiwaves/auto"
  },
  "provider": {
    "optiwaves": {
      "name": "OptiWaves",
      "kind": "openai",
      "apiFormat": "openai-responses",
      "source": "custom",
      "enabled": true,
      "options": {
        "baseURL": "https://api.optiwaves.app/v1",
        "apiKeyRequired": true,
        "apiKey": "ow_your_api_key_here"
      },
      "models": {
        "auto": {
          "name": "OptiWaves Auto",
          "reasoning": true,
          "options": { "store": false }
        }
      }
    }
  }
}

已有其他 provider 时，只合并 provider.optiwaves 和需要改动的 model 字段。

4. 启动并验证

open -a ZCode

Windows 打开 ZCode 应用，Linux 或已安装 CLI 时运行 zcode。在客户端选择 optiwaves/auto，发送一个简短的文本问题。

5. 添加 Fast 模型

在 provider.optiwaves.models 中保留 auto，并增加：

{
  "auto-fast": {
    "name": "OptiWaves Auto Fast",
    "reasoning": true,
          "options": { "store": false }
  }
}

将默认模型改为 optiwaves/auto-fast。CLI 配置同步修改 model.main 与 model.lite。Fast 的开启方式与消耗见 Fast 模式。

ZCode 使用模型项的 reasoning: true，不另写 low / medium / high 思考档位。

常见问题

情况	检查
未出现 OptiWaves	`kind` 是否为 `openai`，`apiFormat` 是否为 `openai-responses`，配置文件是否被读取
已配置仍要求密钥	`options.apiKey` 是否写入 `ow_` 密钥；ZCode 不读环境变量
命令找不到	是否从官网安装官方客户端，而不是社区 npm 包

返回客户端选择。

本地记忆

API 接通后，可用 OptiWaves CLI 为这个客户端配置本地记忆：

optiwaves memory --client zcode

重启客户端后，用一次保存和一次新会话召回检查结果。具体路径与限制见本地记忆。