MEZZH INTEGRATION GUIDE

安装与配置

从下载安装到第一次 API 请求，按你的电脑系统逐步完成。命令可以直接复制，示意框会标出你应当看到的界面或结果。

开始前准备

请先在控制台完成账户激活并创建个人 API Key。Key 只在创建时显示一次，不要粘贴到截图、聊天记录、代码仓库或公开日志中。

1. 登录控制台

打开控制台，使用已激活的账户登录。首次登录按页面提示完成密码修改。

2. 创建个人 Key

在“我的 Key”区域创建 Key，立即复制到本机密码管理器或受保护的环境变量。

3. 记下 API 地址

统一入口：https://api.fscodex.com/v1。不要删除末尾的 /v1。

下载入口：Node.js 官方下载（nodejs.org）。建议安装 Node.js 20 LTS 或更高版本。

安装

每个系统都需要先安装 Node.js，再安装 OpenAI 兼容的 Codex 命令行工具。

Windows 10 / 11

下载 Node.js

打开 Node.js 下载页，选择 Windows Installer (.msi) / LTS / x64。双击下载文件，保持默认选项完成安装。

界面指示：安装向导中保持“Add to PATH”勾选；“Tools for Native Modules”可不勾选。

打开 PowerShell

按 Win 键搜索 PowerShell，打开普通用户窗口。

node --version
npm --version

两条命令都应输出版本号；若提示不是命令，关闭窗口后重新打开。

安装 Codex

npm install --global @openai/codex
codex --version

macOS 12 或更高版本

下载并安装 Node.js

在 Node.js 下载页选择 macOS Installer (.pkg) / LTS。Apple 芯片选 arm64，Intel Mac 选 x64。

界面指示：苹果菜单 → 关于本机，可查看芯片或处理器型号。

打开终端并检查版本

按 Command + Space 搜索“终端”，执行：

node --version
npm --version

安装 Codex

npm install --global @openai/codex
codex --version

Ubuntu / Debian / 其他 Linux

安装 Node.js LTS

推荐使用 NodeSource 安装文档；版本必须是 20 或更高。

sudo apt update
sudo apt install -y nodejs npm
node --version

安装 Codex

npm install --global @openai/codex
codex --version

权限不足时优先修正 npm 全局目录，不建议长期使用 sudo。

配置

配置分为临时测试和长期使用。长期使用请使用环境变量，避免把 Key 写入项目文件。

Windows PowerShell

本次窗口临时配置

$env:OPENAI_BASE_URL = "https://api.fscodex.com/v1"
$env:OPENAI_API_KEY = "YOUR_API_KEY"

界面指示：PowerShell 中命令前缀是 $env:；关闭窗口后临时变量会消失。

写入当前用户环境变量

[Environment]::SetEnvironmentVariable("OPENAI_BASE_URL", "https://api.fscodex.com/v1", "User")
[Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "YOUR_API_KEY", "User")

执行后关闭并重新打开 PowerShell。

macOS / Linux（终端）

当前终端临时配置

export OPENAI_BASE_URL="https://api.fscodex.com/v1"
export OPENAI_API_KEY="YOUR_API_KEY"

长期配置到 shell 文件

macOS 默认 zsh，Ubuntu 默认 bash：

# macOS zsh
printf '\nexport OPENAI_BASE_URL="https://api.fscodex.com/v1"\nexport OPENAI_API_KEY="YOUR_API_KEY"\n' >> ~/.zshrc
source ~/.zshrc

# Linux bash
printf '\nexport OPENAI_BASE_URL="https://api.fscodex.com/v1"\nexport OPENAI_API_KEY="YOUR_API_KEY"\n' >> ~/.bashrc
source ~/.bashrc

多人共用电脑不要写入全局配置。可限制配置文件权限：chmod 600 ~/.zshrc 或 chmod 600 ~/.bashrc。

应用程序配置

配置项	值	说明
API Base URL	`https://api.fscodex.com/v1`	兼容 OpenAI API 的根地址
API Key	`YOUR_API_KEY`	替换为控制台创建的个人 Key
模型	以 `/v1/models` 返回结果为准	不要填写未开放的模型名

第一次请求与验证

先验证地址和 Key，再把相同配置填入 IDE 或脚本。

检查模型列表

curl "$OPENAI_BASE_URL/models" \
  -H "Authorization: Bearer $OPENAI_API_KEY"

Windows PowerShell：

curl.exe "$env:OPENAI_BASE_URL/models" -H "Authorization: Bearer $env:OPENAI_API_KEY"

成功表现：返回 JSON 模型列表并包含 data 字段。401 表示 Key 无效；429 表示触发频率限制；402 表示余额或预算不足。

发送最小对话请求

curl "$OPENAI_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"MODEL_FROM_MODELS","messages":[{"role":"user","content":"你好"}]}'

把 MODEL_FROM_MODELS 换成模型列表中的实际 ID。响应中的 usage 会用于用量与费用记录。

常见问题排查

command not found / 不是命令

重新打开终端；确认 node 可用；Windows 检查 Node.js 是否加入 PATH。

401 Unauthorized

重新从控制台复制 Key，确认没有多余空格或换行；不要把 Bearer 重复写入 Key 值。

证书或网络错误

确认系统时间正确，浏览器能打开健康检查地址；企业网络请联系网管放行 HTTPS。

Key 可能泄露

立即在控制台撤销该 Key 并创建新 Key；不要把泄露内容发送给客服或工单。

预算不足 / 402

在控制台查看额度与用量，确认账户已经激活；不要通过重复请求绕过预算规则。

需要进一步帮助

提交问题时只提供时间、HTTP 状态码和脱敏错误信息，不要提供 Key、密码、私钥或业务数据。

CC Switch 安装与使用

CC Switch 用于在本机管理和切换不同 AI 编程服务的配置。请优先使用环境变量或系统凭据管理器，不要把真实 Key 发到截图、聊天或仓库。

下载地址：CC Switch 官方 Releases。只从项目 Releases 下载与你系统匹配的安装包。

Windows 10 / 11

下载和安装

下载 Windows x64 的 .exe 或 .msi，双击安装并保持默认选项。SmartScreen 弹窗时核对发布者和下载来源。

界面指示：安装完成后，从开始菜单搜索 CC Switch；首次启动允许创建用户配置目录。

添加 Mezzh 配置

选择 OpenAI-compatible / Custom Provider，填写：

名称：Mezzh
Base URL：https://api.fscodex.com/v1
API Key：粘贴控制台生成的个人 Key
模型：以 /v1/models 返回的实际模型 ID 为准

保存后确认地址末尾保留 /v1。

切换并验证

选中 Mezzh 配置并点击 Activate / Use，在 PowerShell 执行：

echo $env:OPENAI_BASE_URL
curl.exe "$env:OPENAI_BASE_URL/models" -H "Authorization: Bearer $env:OPENAI_API_KEY"

没有自动写入环境变量时，按本页 Windows 配置章节手动设置。

macOS

选择架构并安装

下载 .dmg 或 .zip，Apple 芯片选 arm64，Intel 选 x64，将应用拖入 Applications。

界面指示：系统设置 → 隐私与安全性中核对开发者来源后再打开。

创建 Provider

新增自定义 Provider，填写 Mezzh 地址、个人 Key 和模型，保存后点击 Use/Activate。

export OPENAI_BASE_URL="https://api.fscodex.com/v1"
export OPENAI_API_KEY="YOUR_API_KEY"
curl "$OPENAI_BASE_URL/models" -H "Authorization: Bearer $OPENAI_API_KEY"

Ubuntu / Debian / 其他 Linux

下载并启动

下载 Linux x64 的 .AppImage 或压缩包，放到个人目录，不要使用 root 运行桌面应用。

chmod +x CC-Switch*.AppImage
./CC-Switch*.AppImage

配置并验证

新增自定义 Provider 后执行：

echo "$OPENAI_BASE_URL"
curl "$OPENAI_BASE_URL/models" -H "Authorization: Bearer $OPENAI_API_KEY"

切换原则：切换后先验证模型列表；流式请求开始后不要中途切换 Provider。

Visual Studio Code 安装与使用

VS Code 是编辑器，CC Switch 或环境变量负责 API 配置。可在 VS Code 集成终端验证配置，再在扩展或脚本中复用。

下载地址：Visual Studio Code 官方下载。

Windows

安装 VS Code

下载 Windows User Installer x64，安装时勾选 Add to PATH 和 Add Open with Code action。

界面指示：左侧活动栏包含资源管理器、搜索、源代码管理、运行和扩展；底部终端用于验证。

安装扩展

点击扩展图标，先安装可信发布者的 EditorConfig；AI 扩展需核对发布者和隐私说明。

配置集成终端

终端 → 新建终端，选择 PowerShell：

$env:OPENAI_BASE_URL = "https://api.fscodex.com/v1"
$env:OPENAI_API_KEY = "YOUR_API_KEY"
curl.exe "$env:OPENAI_BASE_URL/models" -H "Authorization: Bearer $env:OPENAI_API_KEY"

成功后用文件 → 打开文件夹进入项目。

macOS

下载并启动

下载 Universal、Apple Silicon 或 Intel 版本，将 VS Code 拖入 Applications。

安装 code 命令

按 Command + Shift + P，运行 Shell Command: Install 'code' command in PATH：

export OPENAI_BASE_URL="https://api.fscodex.com/v1"
export OPENAI_API_KEY="YOUR_API_KEY"
code --version

打开项目并验证

终端执行 code .，在 VS Code 新建终端运行：

curl "$OPENAI_BASE_URL/models" -H "Authorization: Bearer $OPENAI_API_KEY"

Linux

安装 VS Code

从官方下载页选择 .deb、.rpm 或 tar.gz，使用发行版包管理器安装。

配置集成终端

export OPENAI_BASE_URL="https://api.fscodex.com/v1"
export OPENAI_API_KEY="YOUR_API_KEY"
code --version
curl "$OPENAI_BASE_URL/models" -H "Authorization: Bearer $OPENAI_API_KEY"

在 VS Code 中使用 API

脚本或项目

使用环境变量；将 .env 加入 .gitignore，不要把真实 Key 写入代码。

AI 扩展

在扩展设置中寻找 API Base URL 或 Custom Endpoint，填入 https://api.fscodex.com/v1；Key 使用扩展安全存储。

终端工作流

先运行 code --version 和模型列表验证，再执行脚本或启动扩展。

安全提醒：提交前检查 Source Control，确认没有把 .env、Key、密码、私钥或敏感数据加入提交。