客户端集成指南

本文档提供了第三方客户端集成 EMCP Token 的详细配置指南，帮助您在各种客户端中使用 EMCP Token。

集成准备

前置准备

获取 API Key：登录 xftoken.ctclouds.com，进入「密钥管理」页面，创建并获取 API Key
平台接入域名：EMCP Token 的接入域名为 https://api.xftoken.ctclouds.com

通用配置规则

域名替换：将客户端中的 OpenAI 官方域名 https://api.openai.com 替换为 https://api.xftoken.ctclouds.com
密钥填写：在客户端的 API Key 设置中填写您的 EMCP Token Key
模型选择：选择 EMCP Token 支持的模型，如 claude-sonnet-4-6、gpt-5.4 等
协议选择：OpenAI 客户端通常使用 Chat Completions 或 Responses；Claude Code 使用 Anthropic Messages；Gemini CLI 使用 Gemini 原生接口。

CherryStudio 客户端集成

功能特点

CherryStudio 提供以下强大功能：

✅ 多模型支持：支持 Claude、Gemini、GPT 等主流 AI 模型
✅ 统一界面：一个应用管理所有 AI 服务
✅ 自定义 API：支持接入自定义 API 提供商
✅ 跨平台：支持 Windows、macOS、Linux
✅ 本地优先：数据存储在本地，保护隐私
✅ 丰富功能：对话管理、模型切换、参数调整等

安装步骤

下载安装 CherryStudio
- 访问 CherryStudio 官方网站
- 根据你的操作系统选择对应的安装包：
  - Windows：下载 .exe 安装程序
  - macOS：下载 .dmg 镜像文件
  - Linux：下载 .AppImage 或 .deb 包
- 下载完成后，按照系统提示完成安装
macOS 用户注意：如果提示"无法打开，因为它来自身份不明的开发者"，请在系统偏好设置 → 安全性与隐私中允许打开。

配置 Claude 模型

进入设置页面
- 打开 CherryStudio 应用
- 点击左下角的「设置」或「偏好设置」
- 选择「模型配置」或「API 配置」选项
选择 Claude 模型类型
- 在模型列表中选择你需要的 Claude 模型：
  - Claude Sonnet 4.5：claude-sonnet-4-5-20250929 - 最新版本，适合日常编码和对话（推荐）
  - Claude Opus 4.5：claude-opus-4-5-20251101 - 最强性能，适合复杂任务
  - Claude 3.5 Haiku：速度快，适合简单任务
配置 Claude API
- 在 Claude 配置界面中填写以下信息：
  - 提供商类型：选择 Anthropic
  - API 地址：https://api.xftoken.ctclouds.com/v1/messages
  - API Key：粘贴你的 EMCP Token Key
  - 模型名称：输入选择的模型名称（如 claude-sonnet-4-5-20250929）

配置 Gemini 模型

选择 Gemini 模型类型
- 在模型列表中选择你需要的 Gemini 模型：
  - Gemini 3 Flash Preview：gemini-3-flash-preview - 最新版本，速度快，性能优秀（推荐）
  - Gemini 3 Pro Preview：gemini-3.1-pro-preview - 高性能，适合复杂任务
  - Gemini 2.0 Flash：快速响应，适合简单对话
配置 Gemini API
- 在 Gemini 配置界面中填写以下信息：
  - 提供商类型：选择 Gemini
  - API 地址：https://api.xftoken.ctclouds.com/v1beta/models
  - API Key：粘贴你的 EMCP Token Key
  - 模型名称：输入选择的模型名称（如 gemini-3-flash-preview）

开始使用

创建新对话
- 点击「新建对话」或「New Chat」按钮
- 在模型选择器中选择已配置的模型
- 开始与 AI 对话
切换模型
- 在对话过程中，点击顶部的模型选择器
- 选择其他已配置的模型
- 继续对话（上下文可能会保留或重置，取决于应用设置）
调整参数
- CherryStudio 支持调整以下参数：
  - Temperature（温度）：控制回复的随机性（0-1）
  - Max Tokens（最大令牌数）：控制回复长度
  - Top P：控制采样范围
参数建议：
- 编程任务：Temperature 0.2-0.5（更准确）
- 创意写作：Temperature 0.7-0.9（更有创意）
- 日常对话：Temperature 0.5-0.7（平衡）

最佳实践

合理选择模型
- 代码编写：Claude Sonnet 4.5（claude-sonnet-4-5-20250929）
- 快速对话：Gemini 3 Flash Preview（gemini-3-flash-preview）
- 复杂推理：Claude Opus 4.5（claude-opus-4-5-20251101）
- 多模态任务：Gemini 3 Pro Preview（支持图片）
管理 API 使用
- 定期检查账户余额
- 为不同用途创建不同的 API Key
- 避免在公共场合泄露 API Key
优化对话体验
- 使用清晰的提示词
- 合理设置上下文长度
- 善用对话历史管理功能

OpenClaw 集成说明

功能特点

OpenClaw 是一款功能丰富的 AI 编程代理工具，具有以下特点：

✅ 终端 TUI：命令行交互界面，适合 SSH 环境
✅ Web Dashboard：浏览器可视化管理面板
✅ Telegram Bot：支持通过 Telegram 远程对话
✅ 多模型支持：Claude、GPT、Gemini 等多种模型
✅ Gateway 网关：内置网关服务，支持反向代理
✅ Skill 扩展：可通过 Dashboard 安装扩展技能

安装与初始化

运行安装脚本
- 登录服务器 SSH 或在 macOS 终端中运行以下命令：
```
curl -fsSL https://openclaw.ai/install.sh | bash
```
- 耐心等待安装流程结束
初始化配置
- 安装过程中会依次出现以下选项，按照说明操作：
  - 启动方式：选择 QuickStart（快速开始模式）
  - 供应商设置：选择 Skip for now（先跳过，后续手动编辑配置文件）
  - 适配器选择：选择 anthropic
  - 模型选择：选择 opus-4.5 或其他需要的模型
  - 社交适配器：按需选择（如 Telegram，可选）
  - Skill 安装：跳过（后续可通过 Dashboard 安装）
  - Hook 选择：全选（使用空格键全选后回车确认）
  - 打开方式：跳过（先跳过）
  - Shell 补全：yes（安装命令行自动补全）

渠道与模型配置

编辑配置文件
- 打开 OpenClaw 的配置文件进行编辑：
```
vim ~/.openclaw/openclaw.json
```

配置供应商信息

在 models.providers 中配置 EMCP Token 信息，示例配置：

"models": {
  "providers": {
    "emcp-token": {
      "baseUrl": "https://api.xftoken.ctclouds.com/v1",
      "apiKey": "YOUR_SMART_API_KEY",
      "api": "openai-completions",
      "headers": {
        "User-Agent": "claude-cli/2.0.76 (external, cli)",
        "Authorization": "Bearer YOUR_SMART_API_KEY"
      },
      "models": [
        {
          "id": "gpt-5.4",
          "name": "gpt-5.4",
          "contextWindow": 128000,
          "maxTokens": 32000
        },
        {
          "id": "claude-opus-4-6",
          "name": "claude-opus-4-6",
          "contextWindow": 200000,
          "maxTokens": 4096
        }
      ]
    }
  }
}

重要提示：

必须添加 headers 字段，否则请求会被拦截返回 403
Authorization 的值必须与 apiKey 一致，格式为 Bearer YOUR_SMART_API_KEY
User-Agent 必须保持示例中的格式，不可省略或随意修改

重启网关
```
openclaw gateway restart
```
验证配置
- 运行以下命令进入 TUI 界面测试模型是否正常：
```
openclaw tui
```
- 测试成功后输入 /quit 退出 TUI

浏览器访问 Dashboard

获取 Dashboard URL
- 在控制台运行命令获取 Dashboard URL，在浏览器中访问即可进入管理面板
服务器用户注意
- 如果你在远程服务器运行 OpenClaw，需要：
  1. 配置反向代理：使用 Nginx 或其他反向代理工具反代 OpenClaw 服务，并设置 SSL 证书
  2. 修改配置文件：编辑 ~/.openclaw/openclaw.json，在 gateway 字段下添加：
```
"controlUi": {
  "allowInsecureAuth": true
}
```
  3. 重启网关：
```
openclaw gateway restart
```
- 访问带有 Token 的 Dashboard URL 即可进入后台界面

常见问题

遇到 403 Your request was blocked？

解决方案：在供应商配置中添加 headers 字段，确保 User-Agent 和 Authorization 设置正确

无法连接到 API

解决方案：
- 检查配置文件中的 baseUrl 是否正确
- 确认 apiKey 是否有效
- 检查网络连接是否正常
- 验证 headers 配置是否正确

模型响应质量不佳

解决方案：
- 选择更适合任务的模型
- 提供更详细的指令
- 检查账户余额是否充足

Claude Code 集成说明

首次安装注意事项

使用 EMCP Token 集成 Claude Code 时，首次启动可能会出现以下报错：

Welcome to Claude Code
Unable to connect to Anthropic services
Failed to connect to api.anthropic.com: ERR_BAD_REQUEST

这是因为 Claude Code 首次启动会尝试连接官方 API 进行初始化确认，需要先手动修改配置文件：

在用户主目录下找到 ~/.claude.json 文件
在末尾添加 "hasCompletedOnboarding": true 字段（注意 JSON 格式，添加字段前需要在上一个字段末尾补英文逗号）：

{
  "installMethod": "unknown",
  "autoUpdates": true,
  "firstStartTime": "2025-07-14T06:11:03.877Z",
  "userID": "xxxx",
  "projects": {
    "/home/your-user": {
      "allowedTools": [],
      "history": [],
      "mcpContextUris": [],
      "mcpServers": {},
      "enabledMcpjsonServers": [],
      "disabledMcpjsonServers": [],
      "hasTrustDialogAccepted": false,
      "projectOnboardingSeenCount": 0,
      "hasClaudeMdExternalIncludesApproved": false,
      "hasClaudeMdExternalIncludesWarningShown": false
    }
  },
  "hasCompletedOnboarding": true  // 新增此字段
}

修改保存后，重新运行 Claude Code 即可正常使用

安装方法

Windows 平台

试用Native Install方法安装：

使用 PowerShell：

irm https://claude.ai/install.ps1 | iex

使用 CMD：

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

验证安装：

claude --version

macOS 平台

方法一：Homebrew（推荐）

brew install --cask claude-code

方法二：Curl Script

curl -fsSL https://claude.ai/install.sh | bash

验证安装

claude -v

环境变量配置

Windows 平台

PowerShell：

[Environment]::SetEnvironmentVariable("ANTHROPIC_AUTH_TOKEN", "YOUR_SMART_API_KEY", "User")
[Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "https://api.xftoken.ctclouds.com", "User")

CMD：

setx ANTHROPIC_AUTH_TOKEN "YOUR_SMART_API_KEY"
setx ANTHROPIC_BASE_URL "https://api.xftoken.ctclouds.com"

macOS 平台

在 ~/.bashrc 或 ~/.zshrc 文件中添加：

export ANTHROPIC_AUTH_TOKEN="YOUR_SMART_API_KEY"
export ANTHROPIC_BASE_URL="https://api.xftoken.ctclouds.com"

然后执行：

source ~/.bashrc  # 或 source ~/.zshrc

配置验证

设置好环境变量后，重启终端以让环境变量生效。

启动与使用

在终端中，进入项目目录或在任意目录输入命令：
```
claude
```
Claude Code 会启动并连接到 EMCP Token
开始使用 Claude Code 进行代码生成、分析和调试

常见问题

1. 首次启动报错

解决方案：

按照「首次安装注意事项」中的方法修改配置文件，跳过初始化确认

2. 无法连接到 API

解决方案：

检查环境变量是否正确设置
确认 EMCP Token Key 是否有效
检查网络连接是否正常

3. 模型响应质量不佳

解决方案：

确保使用了正确的模型（如 claude-opus-4-6）
提供更详细的指令和上下文
检查账户余额是否充足

最佳实践

环境变量管理：
- 使用环境变量存储 API Key，避免在代码中硬编码
- 定期更新 API Key，提高安全性
模型选择：
- 复杂代码生成：使用 gpt-5.4 或 claude-opus-4-6
- 代码分析和调试：使用 claude-sonnet-4-6 或 gemini-3.1-pro-preview
指令优化：
- 明确说明代码的用途和要求
- 提供相关的上下文信息
- 指明期望的输出格式
配置备份：
- 定期备份 ~/.claude.json 配置文件
- 记录重要的环境变量设置

CodeX 集成说明

功能特点

CodeX 是基于 GPT-5 架构的下一代智能编程助手，为开发者提供卓越的代码生成与优化能力。

安装步骤

部署 CodeX 命令行工具
- 以管理员权限启动命令提示符或 PowerShell，执行：
```
npm install -g @openai/codex@latest
codex --version
```
获取 EMCP Token 凭证
- 登录 xftoken.ctclouds.com
- 进入「密钥管理」页面
- 创建新的 API Key

手动命令行配置

Windows 平台

构建配置目录结构

mkdir %USERPROFILE%\.codex
cd %USERPROFILE%\.codex

编写配置文件

config.toml

model_provider = "EMCP Token"
model = "gpt-5.4"
model_reasoning_effort = "xhigh"
disable_response_storage = true
approval_policy = "on-request"
sandbox_mode = "danger-full-access"
model_supports_reasoning_summaries = true

[model_providers.EMCPToken]
name = "EMCP Token"
base_url = "https://api.xftoken.ctclouds.com/v1"
wire_api = "responses"
requires_openai_auth = true

auth.json

{
  "OPENAI_API_KEY": "此处粘贴您的 EMCP Token Key"
}

初始化工作空间

mkdir my-codex-project
cd my-codex-project
codex

macOS 平台

部署 CodeX 工具

npm install -g @openai/codex@latest
codex --version

构建配置目录
```
mkdir -p ~/.codex
cd ~/.codex
```

编写配置文件

config.toml

cat > config.toml << 'EOF'
model_provider = "EMCP Token"
model = "gpt-5.4"
model_reasoning_effort = "xhigh"
disable_response_storage = true
approval_policy = "on-request"
sandbox_mode = "danger-full-access"
model_supports_reasoning_summaries = true

[model_providers.EMCPToken]
name = "EMCP Token"
base_url = "https://api.xftoken.ctclouds.com/v1"
wire_api = "responses"
requires_openai_auth = true
EOF

auth.json

cat > auth.json << 'EOF'
{
  "OPENAI_API_KEY": "此处粘贴您的 EMCP Token Key"
}
EOF

初始化工作空间

mkdir my-codex-project
cd my-codex-project
codex

Linux 平台

部署 CodeX 工具

sudo npm install -g @openai/codex@latest
codex --version

构建配置目录
```
mkdir -p ~/.codex
cd ~/.codex
```

编写配置文件

config.toml

cat > config.toml << 'EOF'
model_provider = "EMCP Token"
model = "gpt-5.4"
model_reasoning_effort = "xhigh"
disable_response_storage = true
approval_policy = "on-request"
sandbox_mode = "danger-full-access"
model_supports_reasoning_summaries = true

[model_providers.EMCPToken]
name = "EMCP Token"
base_url = "https://api.xftoken.ctclouds.com/v1"
wire_api = "responses"
requires_openai_auth = true
EOF

auth.json

cat > auth.json << 'EOF'
{
  "OPENAI_API_KEY": "此处粘贴您的 EMCP Token Key"
}
EOF

初始化工作空间

mkdir my-codex-project
cd my-codex-project
codex

开始使用

代码生成
- 在工作空间中，输入自然语言描述你需要的代码
- CodeX 会根据描述生成相应的代码
代码补全
- 开始编写代码，CodeX 会自动提供补全建议
- 按 Tab 键接受建议
代码分析
- 粘贴现有代码，输入分析请求
- CodeX 会分析代码并提供改进建议

常见问题

无法连接到 API

解决方案：
- 检查配置文件中的 base_url 是否正确
- 确认 OPENAI_API_KEY 是否有效
- 检查网络连接是否正常

代码生成质量不佳

解决方案：
- 提供更详细的指令和上下文
- 选择更适合的模型（如 gpt-5.4）
- 检查账户余额是否充足

配置文件错误

解决方案：
- 确保 config.toml 和 auth.json 格式正确
- 验证文件路径是否正确
- 重启 CodeX 应用

Gemini CLI 集成说明

功能特点

Gemini CLI 是 Google AI 编程助手，由 Gemini 2.5 Pro 驱动，提供智能代码生成和分析能力。

安装步骤

Windows 平台

全局安装 Gemini CLI
```
npm install -g @google/gemini-cli
```

配置 Gemini CLI

创建配置目录：在用户目录下创建 %USERPROFILE%\.gemini\ 文件夹

创建 .env 文件：

GOOGLE_GEMINI_BASE_URL=https://api.xftoken.ctclouds.com
GEMINI_API_KEY=你的EMCP Token Key
GEMINI_MODEL=gemini-3.1-pro-preview

创建 settings.json 文件：

{
  "ide": {
    "enabled": true
  },
  "security": {
    "auth": {
      "selectedType": "gemini-api-key"
    }
  }
}

启动 Gemini CLI
```
gemini
```

macOS 平台

全局安装 Gemini CLI
```
npm install -g @google/gemini-cli
```

配置 Gemini CLI

创建配置目录：
```
mkdir -p ~/.gemini
cd ~/.gemini
```

创建 .env 文件：

cat > .env << 'EOF'
GOOGLE_GEMINI_BASE_URL=https://api.xftoken.ctclouds.com
GEMINI_API_KEY=你的EMCP Token Key
GEMINI_MODEL=gemini-3.1-pro-preview
EOF

创建 settings.json 文件：

cat > settings.json << 'EOF'
{
  "ide": {
    "enabled": true
  },
  "security": {
    "auth": {
      "selectedType": "gemini-api-key"
    }
  }
}
EOF

启动 Gemini CLI
```
gemini
```

Linux 平台

全局安装 Gemini CLI
```
sudo npm install -g @google/gemini-cli
```

配置 Gemini CLI

创建配置目录：
```
mkdir -p ~/.gemini
cd ~/.gemini
```

创建 .env 文件：

cat > .env << 'EOF'
GOOGLE_GEMINI_BASE_URL=https://api.xftoken.ctclouds.com
GEMINI_API_KEY=你的EMCP Token Key
GEMINI_MODEL=gemini-3.1-pro-preview
EOF

创建 settings.json 文件：

cat > settings.json << 'EOF'
{
  "ide": {
    "enabled": true
  },
  "security": {
    "auth": {
      "selectedType": "gemini-api-key"
    }
  }
}
EOF

启动 Gemini CLI
```
gemini
```

开始使用

发送文本请求
```
gemini chat "Hello, EMCP Token!"
```

生成代码

gemini code "Write a Python function to calculate Fibonacci numbers"

分析文件
```
gemini analyze ./example.js
```
Agent Mode 自动编程模式
- 输入上下文描述，Gemini CLI 会自动生成和执行代码
Google Search 实时联网搜索
- Gemini CLI 可以通过联网搜索获取最新信息

常见问题

API Key 在哪里获取？

配置文件位置

Windows: %USERPROFILE%\.gemini\
macOS/Linux: ~/.gemini/

无法连接到 API

解决方案：
- 检查 .env 文件中的 GOOGLE_GEMINI_BASE_URL 是否正确
- 确认 GEMINI_API_KEY 是否有效
- 检查网络连接是否正常

模型响应质量不佳

解决方案：
- 确保使用了合适的模型（如 gemini-3.1-pro-preview）
- 提供更详细的指令和上下文
- 检查账户余额是否充足

OpenCode 集成说明

功能特点

OpenCode 是一款开源的 AI 编程助手，具有以下特点：

✅ 原生终端 TUI：专为命令行开发者设计，高效流畅
✅ 智能 LSP 加载：自动加载正确的语言服务器，提升上下文理解
✅ 多会话并行：支持多个会话同时运行，互不干扰
✅ 会话链接共享：可分享会话链接给他人协作
✅ 75+ 模型支持：支持多种模型提供商，包括本地模型
✅ 多平台支持：终端 CLI、桌面应用（Beta）、IDE 扩展

安装与配置

安装 OpenCode
- 打开终端，运行以下命令全局安装 OpenCode：
```
npm install -g opencode-ai
```
- 安装完成后，在终端输入 opencode 命令，若出现 TUI 界面则安装成功
安装 CC-Switch
- 下载并安装 CC-Switch 配置工具
添加 EMCP Token 供应商
- 打开 CC-Switch，上方配置项选择 OpenCode，然后点击「添加供应商」按钮
- 填写供应商信息：
  - 预设供应商：选择 EMCP Token
  - 供应商标识：自定义名称，如 EMCP Token
  - 接口格式：
    - Claude 模型选 Anthropic
    - GPT 模型选 OpenAI
    - Gemini 模型选 Google (Gemini)
  - API Key：填入你在 EMCP Token 控制台创建的 Key
  - 额外选项：填写 {"setCacheKey":true}

验证配置

重新打开终端，输入 opencode 运行
输入 /models 命令，检查配置的渠道是否出现在模型列表中
如果能看到你添加的模型，说明配置成功
开始使用 OpenCode 进行编码

开始使用

创建新会话
- 运行 opencode 命令
- 输入 /new 命令创建新会话
- 选择你配置的 EMCP Token 模型
代码生成
- 输入自然语言描述你需要的代码
- OpenCode 会根据描述生成相应的代码
代码分析
- 粘贴现有代码
- 输入分析请求
- OpenCode 会分析代码并提供改进建议
多会话管理
- 输入 /list 命令查看所有会话
- 输入 /switch <会话ID> 切换到指定会话
- 输入 /share 命令生成会话分享链接

常见问题

安装时提示 npm 未找到？

解决方案：请先安装 Node.js 环境

模型列表中看不到配置的渠道？

解决方案：
- 确认 CC-Switch 中已正确保存配置
- 重启终端后再次运行 opencode
- 检查 API Key 是否填写正确

无法连接到 API

解决方案：
- 检查 CC-Switch 中的 API Key 是否正确
- 确认 EMCP Token 服务是否正常运行
- 检查网络连接是否正常

代码生成质量不佳

解决方案：
- 选择更适合代码生成的模型（如 gpt-5.4）
- 提供更详细的指令和上下文
- 检查账户余额是否充足

最佳实践

模型选择
- 复杂代码生成：使用 gpt-5.4 或 claude-opus-4-6
- 代码分析：使用 claude-sonnet-4-6 或 gemini-3.1-pro-preview
- 快速原型：使用 claude-haiku-4-5-20251001 或 gemini-3-flash-preview
会话管理
- 为不同的项目创建不同的会话
- 使用会话分享功能与团队协作
- 定期清理不需要的会话以节省资源
指令优化
- 明确说明代码的用途和要求
- 提供相关的上下文信息
- 指明期望的输出格式
安全管理
- 避免在会话中分享敏感信息
- 定期更新 API Key
- 合理设置 API 使用限制

常见问题与解决方案

客户端无法连接

检查网络连接：确保网络连接正常
检查 API Key：确保 API Key 正确且未过期
检查域名配置：确保域名配置正确，使用 https://api.xftoken.ctclouds.com

模型加载失败

检查 API Key 权限：确保 API Key 有足够的权限
检查模型可用性：确保所选模型在 EMCP Token 中可用
检查网络连接：确保网络连接正常

调用失败

检查 API Key：确保 API Key 正确且未过期
检查请求参数：确保请求参数符合 EMCP Token 的要求
检查模型权限：确保您有权限使用所选模型
检查账户余额：确保账户有足够的余额