Client Integration Guide

This document provides a detailed configuration guide for integrating third-party clients with EMCP Token, helping you use EMCP Token across various clients.

Integration Preparation

Prerequisites

  1. Get an API Key: Log in to xftoken.ctclouds.com, go to the Key Management page, and create and copy an API Key.
  2. Platform access domain: EMCP Token's access domain is https://api.xftoken.ctclouds.com.

General Configuration Rules

  • Domain replacement: replace the OpenAI official domain https://api.openai.com in the client with https://api.xftoken.ctclouds.com.
  • API Key: fill in your EMCP Token Key in the client's API Key setting.
  • Model selection: select a model supported by EMCP Token, such as claude-sonnet-4-6, gpt-5.4, etc.
  • Protocol selection: OpenAI clients typically use Chat Completions or Responses; Claude Code uses Anthropic Messages; Gemini CLI uses the Gemini native interface.

CherryStudio Integration

Features

CherryStudio offers the following powerful features:

  • ✅ Multi-model support: supports mainstream AI models such as Claude, Gemini, and GPT
  • ✅ Unified interface: manage all AI services in one app
  • ✅ Custom API: supports connecting custom API providers
  • ✅ Cross-platform: supports Windows, macOS, Linux
  • ✅ Local-first: data stored locally for privacy protection
  • ✅ Rich features: conversation management, model switching, parameter tuning, and more

Installation Steps

  1. Download and install CherryStudio

    • Visit the CherryStudio official website
    • Choose the installer for your OS:
      • Windows: download the .exe installer
      • macOS: download the .dmg image
      • Linux: download the .AppImage or .deb package
    • After downloading, complete the installation following the system prompts

    Note for macOS users: if you see "cannot be opened because it is from an unidentified developer", allow it in System Preferences → Security & Privacy.

Configure the Claude Model

  1. Open the Settings page

    • Open the CherryStudio app
    • Click Settings or Preferences at the bottom-left
    • Select Model Configuration or API Configuration

  2. Select the Claude model type

    • Choose the Claude model you need from the model list:
      • Claude Sonnet 4.5: claude-sonnet-4-5-20250929 — latest version, suitable for daily coding and conversation (recommended)
      • Claude Opus 4.5: claude-opus-4-5-20251101 — best performance, suitable for complex tasks
      • Claude 3.5 Haiku: fast, suitable for simple tasks

  3. Configure the Claude API

    • Fill in the following in the Claude configuration screen:
      • Provider type: select Anthropic
      • API Address: https://api.xftoken.ctclouds.com/v1/messages
      • API Key: paste your EMCP Token Key
      • Model name: enter the selected model name (e.g., claude-sonnet-4-5-20250929)

Configure the Gemini Model

  1. Select the Gemini model type

    • Choose the Gemini model you need from the model list:
      • Gemini 3 Flash Preview: gemini-3-flash-preview — latest version, fast and high-performing (recommended)
      • Gemini 3 Pro Preview: gemini-3.1-pro-preview — high performance, suitable for complex tasks
      • Gemini 2.0 Flash: fast response, suitable for simple conversations

  2. Configure the Gemini API

    • Fill in the following in the Gemini configuration screen:
      • Provider type: select Gemini
      • API Address: https://api.xftoken.ctclouds.com/v1beta/models
      • API Key: paste your EMCP Token Key
      • Model name: enter the selected model name (e.g., gemini-3-flash-preview)

Getting Started

  1. Create a new conversation

    • Click the New Chat button
    • Select the configured model in the model selector
    • Start chatting with the AI

  2. Switch models

    • During a conversation, click the model selector at the top
    • Select another configured model
    • Continue the conversation (context may be preserved or reset depending on app settings)

  3. Adjust parameters

    • CherryStudio supports adjusting the following parameters:
      • Temperature: controls response randomness (0–1)
      • Max Tokens: controls response length
      • Top P: controls the sampling range

    Parameter suggestions:

    • Coding tasks: Temperature 0.2–0.5 (more accurate)
    • Creative writing: Temperature 0.7–0.9 (more creative)
    • Daily conversation: Temperature 0.5–0.7 (balanced)

Best Practices

  1. Choose models wisely

    • Code writing: Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)
    • Quick conversation: Gemini 3 Flash Preview (gemini-3-flash-preview)
    • Complex reasoning: Claude Opus 4.5 (claude-opus-4-5-20251101)
    • Multimodal tasks: Gemini 3 Pro Preview (supports images)

  2. Manage API usage

    • Check your account balance regularly
    • Create different API Keys for different purposes
    • Avoid exposing your API Key in public

  3. Optimize the conversation experience

    • Use clear prompts
    • Set a reasonable context length
    • Make good use of conversation history management

OpenClaw Integration

Features

OpenClaw is a feature-rich AI coding agent tool with the following characteristics:

  • ✅ Terminal TUI: command-line interactive interface, suitable for SSH environments
  • ✅ Web Dashboard: browser-based visual management panel
  • ✅ Telegram Bot: supports remote conversation via Telegram
  • ✅ Multi-model support: various models such as Claude, GPT, Gemini
  • ✅ Gateway: built-in gateway service with reverse proxy support
  • ✅ Skill extensions: install extension skills via the Dashboard

Installation and Initialization

  1. Run the install script

    • Log in via SSH to the server or run the following command in the macOS terminal:
      curl -fsSL https://openclaw.ai/install.sh | bash
    • Wait patiently for the installation to finish

  2. Initialize configuration

    • During installation you will see the following options in sequence; follow the instructions:
      • Launch mode: select QuickStart (quick start mode)
      • Provider settings: select Skip for now (edit the config file manually later)
      • Adapter selection: select anthropic
      • Model selection: select opus-4.5 or another model you need
      • Social adapter: select as needed (e.g., Telegram, optional)
      • Skill installation: skip (install later via Dashboard)
      • Hook selection: select all (use the spacebar to select all, then press Enter to confirm)
      • Open mode: skip (skip for now)
      • Shell completion: yes (install command-line auto-completion)

Channel and Model Configuration

  1. Edit the configuration file

    • Open the OpenClaw configuration file for editing:
      vim ~/.openclaw/openclaw.json

  2. Configure provider information

    • Configure EMCP Token information under models.providers. Example configuration:
      "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
        }
      ]
    }
  }
}

    Important notes:

    • You must add the headers field, otherwise the request will be blocked and return 403
    • The value of Authorization must match apiKey, in the format Bearer YOUR_SMART_API_KEY
    • The User-Agent must keep the format shown in the example; do not omit or arbitrarily modify it

  3. Restart the gateway

    openclaw gateway restart

  4. Verify the configuration

    • Run the following command to enter the TUI and test whether the model works normally:
      openclaw tui
    • After a successful test, enter /quit to exit the TUI

Access the Dashboard via Browser

  1. Get the Dashboard URL

    • Run a command in the console to get the Dashboard URL, then open it in a browser to enter the management panel

  2. Notes for server users

    • If you run OpenClaw on a remote server, you need to:
      1. Configure a reverse proxy: use Nginx or another reverse proxy tool to proxy the OpenClaw service and set up an SSL certificate
      2. Edit the configuration file: edit ~/.openclaw/openclaw.json and add under the gateway field:
        "controlUi": {
  "allowInsecureAuth": true
}
      3. Restart the gateway:
        openclaw gateway restart
    • Access the Dashboard URL with the token to enter the admin interface

FAQ

Getting "403 Your request was blocked"?

  • Solution: add the headers field in the provider configuration and ensure User-Agent and Authorization are set correctly

Cannot connect to the API

  • Solution:
    • Check whether baseUrl in the configuration file is correct
    • Confirm whether apiKey is valid
    • Check whether the network connection is normal
    • Verify whether the headers configuration is correct

Poor model response quality

  • Solution:
    • Select a model better suited to the task
    • Provide more detailed instructions
    • Check whether the account balance is sufficient

Claude Code Integration

First-Time Installation Notes

When integrating Claude Code with EMCP Token, the following error may appear on first launch:

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

This is because Claude Code attempts to connect to the official API for initialization confirmation on first launch. You need to manually modify the configuration file first:

  1. Locate the ~/.claude.json file in the user home directory
  2. Add the "hasCompletedOnboarding": true field at the end (mind the JSON format — add a comma after the previous field before adding this one):
{
  "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  // add this field
}
  1. After saving the changes, re-run Claude Code to use it normally

Installation Method

Windows

Try the Native Install method:

  • Using PowerShell:
    irm https://claude.ai/install.ps1 | iex
  • Using CMD:
    curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Verify the installation:

claude --version

macOS

Method 1: Homebrew (recommended)

brew install --cask claude-code

Method 2: Curl Script

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

Verify the installation

claude -v

Environment Variable Configuration

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

Add the following to your ~/.bashrc or ~/.zshrc file:

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

Then run:

source ~/.bashrc  # or source ~/.zshrc

Configuration Verification

After setting the environment variables, restart the terminal to apply them.

Launch and Usage

  1. In the terminal, navigate to a project directory or enter the command in any directory:

    claude

  2. Claude Code starts and connects to EMCP Token

  3. Start using Claude Code for code generation, analysis, and debugging

FAQ

1. Error on first launch

Solution:

  • Modify the configuration file as described in "First-Time Installation Notes" to skip initialization confirmation

2. Cannot connect to the API

Solution:

  • Check whether the environment variables are set correctly
  • Confirm whether the EMCP Token Key is valid
  • Check whether the network connection is normal

3. Poor model response quality

Solution:

  • Make sure you are using the correct model (e.g., claude-opus-4-6)
  • Provide more detailed instructions and context
  • Check whether the account balance is sufficient

Best Practices

  1. Environment variable management:

    • Store the API Key in an environment variable to avoid hardcoding it in code
    • Rotate the API Key regularly to improve security

  2. Model selection:

    • Complex code generation: use gpt-5.4 or claude-opus-4-6
    • Code analysis and debugging: use claude-sonnet-4-6 or gemini-3.1-pro-preview

  3. Instruction optimization:

    • Clearly state the purpose and requirements of the code
    • Provide relevant context information
    • Indicate the expected output format

  4. Configuration backup:

    • Regularly back up the ~/.claude.json configuration file
    • Record important environment variable settings

CodeX Integration

Features

CodeX is a next-generation intelligent coding assistant built on the GPT-5 architecture, providing developers with excellent code generation and optimization capabilities.

Installation Steps

  1. Deploy the CodeX CLI tool

    • Launch Command Prompt or PowerShell as administrator and run:
      npm install -g @openai/codex@latest
codex --version

  2. Get EMCP Token credentials

Manual Command-Line Configuration

Windows

  1. Build the config directory structure

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

  2. Write the configuration files

    • 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": "Paste your EMCP Token Key here"
}

  3. Initialize the workspace

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

macOS

  1. Deploy the CodeX tool

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

  2. Build the config directory

    mkdir -p ~/.codex
cd ~/.codex

  3. Write the configuration files

    • 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": "Paste your EMCP Token Key here"
}
EOF

  4. Initialize the workspace

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

Linux

  1. Deploy the CodeX tool

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

  2. Build the config directory

    mkdir -p ~/.codex
cd ~/.codex

  3. Write the configuration files

    • 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": "Paste your EMCP Token Key here"
}
EOF

  4. Initialize the workspace

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

Getting Started

  1. Code generation

    • In the workspace, type a natural-language description of the code you need
    • CodeX generates the corresponding code based on the description

  2. Code completion

    • Start writing code and CodeX automatically provides completion suggestions
    • Press Tab to accept a suggestion

  3. Code analysis

    • Paste existing code and enter an analysis request
    • CodeX analyzes the code and provides improvement suggestions

FAQ

Cannot connect to the API

  • Solution:
    • Check whether base_url in the configuration file is correct
    • Confirm whether OPENAI_API_KEY is valid
    • Check whether the network connection is normal

Poor code generation quality

  • Solution:
    • Provide more detailed instructions and context
    • Select a more suitable model (e.g., gpt-5.4)
    • Check whether the account balance is sufficient

Configuration file error

  • Solution:
    • Ensure config.toml and auth.json are correctly formatted
    • Verify the file paths are correct
    • Restart the CodeX app

Gemini CLI Integration

Features

Gemini CLI is Google's AI coding assistant, powered by Gemini 2.5 Pro, providing intelligent code generation and analysis capabilities.

Installation Steps

Windows

  1. Install Gemini CLI globally

    npm install -g @google/gemini-cli

  2. Configure Gemini CLI

    • Create the config directory: create the %USERPROFILE%\.gemini\ folder in your user directory
    • Create the .env file:
      GOOGLE_GEMINI_BASE_URL=https://api.xftoken.ctclouds.com
GEMINI_API_KEY=Your EMCP Token Key
GEMINI_MODEL=gemini-3.1-pro-preview
    • Create the settings.json file:
      {
  "ide": {
    "enabled": true
  },
  "security": {
    "auth": {
      "selectedType": "gemini-api-key"
    }
  }
}

  3. Launch Gemini CLI

    gemini

macOS

  1. Install Gemini CLI globally

    npm install -g @google/gemini-cli

  2. Configure Gemini CLI

    • Create the config directory:
      mkdir -p ~/.gemini
cd ~/.gemini
    • Create the .env file:
      cat > .env << 'EOF'
GOOGLE_GEMINI_BASE_URL=https://api.xftoken.ctclouds.com
GEMINI_API_KEY=Your EMCP Token Key
GEMINI_MODEL=gemini-3.1-pro-preview
EOF
    • Create the settings.json file:
      cat > settings.json << 'EOF'
{
  "ide": {
    "enabled": true
  },
  "security": {
    "auth": {
      "selectedType": "gemini-api-key"
    }
  }
}
EOF

  3. Launch Gemini CLI

    gemini

Linux

  1. Install Gemini CLI globally

    sudo npm install -g @google/gemini-cli

  2. Configure Gemini CLI

    • Create the config directory:
      mkdir -p ~/.gemini
cd ~/.gemini
    • Create the .env file:
      cat > .env << 'EOF'
GOOGLE_GEMINI_BASE_URL=https://api.xftoken.ctclouds.com
GEMINI_API_KEY=Your EMCP Token Key
GEMINI_MODEL=gemini-3.1-pro-preview
EOF
    • Create the settings.json file:
      cat > settings.json << 'EOF'
{
  "ide": {
    "enabled": true
  },
  "security": {
    "auth": {
      "selectedType": "gemini-api-key"
    }
  }
}
EOF

  3. Launch Gemini CLI

    gemini

Getting Started

  1. Send a text request

    gemini chat "Hello, EMCP Token!"

  2. Generate code

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

  3. Analyze a file

    gemini analyze ./example.js

  4. Agent Mode (automated coding)

    • Enter a context description and Gemini CLI will automatically generate and execute code

  5. Google Search (real-time web search)

    • Gemini CLI can fetch the latest information via web search

FAQ

Where do I get the API Key?

Config file location

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

Cannot connect to the API

  • Solution:
    • Check whether GOOGLE_GEMINI_BASE_URL in the .env file is correct
    • Confirm whether GEMINI_API_KEY is valid
    • Check whether the network connection is normal

Poor model response quality

  • Solution:
    • Make sure you are using a suitable model (e.g., gemini-3.1-pro-preview)
    • Provide more detailed instructions and context
    • Check whether the account balance is sufficient

OpenCode Integration

Features

OpenCode is an open-source AI coding assistant with the following characteristics:

  • ✅ Native terminal TUI: designed for command-line developers, efficient and smooth
  • ✅ Smart LSP loading: automatically loads the correct language server to improve context understanding
  • ✅ Multi-session parallelism: multiple sessions can run simultaneously without interference
  • ✅ Session link sharing: share session links with others for collaboration
  • ✅ 75+ model support: supports many model providers, including local models
  • ✅ Multi-platform support: terminal CLI, desktop app (Beta), IDE extensions

Installation and Configuration

  1. Install OpenCode

    • Open a terminal and run the following command to install OpenCode globally:
      npm install -g opencode-ai
    • After installation, type the opencode command in the terminal; if the TUI appears, the installation succeeded

  2. Install CC-Switch

    • Download and install the CC-Switch configuration tool

  3. Add the EMCP Token provider

    • Open CC-Switch, select OpenCode in the top configuration item, then click the Add Provider button
    • Fill in the provider information:
      • Preset provider: select EMCP Token
      • Provider ID: a custom name, e.g., EMCP Token
      • Interface format:
        • Claude models select Anthropic
        • GPT models select OpenAI
        • Gemini models select Google (Gemini)
      • API Key: enter the Key you created in the EMCP Token console
      • Extra options: enter {"setCacheKey":true}

Verify the Configuration

  1. Reopen the terminal and run opencode
  2. Enter the /models command and check whether the configured channel appears in the model list
  3. If you can see the model you added, the configuration is successful
  4. Start using OpenCode for coding

Getting Started

  1. Create a new session

    • Run the opencode command
    • Enter the /new command to create a new session
    • Select your configured EMCP Token model

  2. Code generation

    • Enter a natural-language description of the code you need
    • OpenCode generates the corresponding code based on the description

  3. Code analysis

    • Paste existing code
    • Enter an analysis request
    • OpenCode analyzes the code and provides improvement suggestions

  4. Multi-session management

    • Enter /list to view all sessions
    • Enter /switch <session ID> to switch to a specified session
    • Enter /share to generate a session share link

FAQ

npm not found during installation?

  • Solution: install the Node.js environment first

Configured channel not visible in the model list?

  • Solution:
    • Confirm the configuration is saved correctly in CC-Switch
    • Restart the terminal and run opencode again
    • Check whether the API Key is filled in correctly

Cannot connect to the API

  • Solution:
    • Check whether the API Key in CC-Switch is correct
    • Confirm whether the EMCP Token service is running normally
    • Check whether the network connection is normal

Poor code generation quality

  • Solution:
    • Select a model better suited to code generation (e.g., gpt-5.4)
    • Provide more detailed instructions and context
    • Check whether the account balance is sufficient

Best Practices

  1. Model selection

    • Complex code generation: use gpt-5.4 or claude-opus-4-6
    • Code analysis: use claude-sonnet-4-6 or gemini-3.1-pro-preview
    • Quick prototyping: use claude-haiku-4-5-20251001 or gemini-3-flash-preview

  2. Session management

    • Create different sessions for different projects
    • Use the session sharing feature to collaborate with your team
    • Clean up unnecessary sessions regularly to save resources

  3. Instruction optimization

    • Clearly state the purpose and requirements of the code
    • Provide relevant context information
    • Indicate the expected output format

  4. Security management

    • Avoid sharing sensitive information in sessions
    • Rotate the API Key regularly
    • Set reasonable API usage limits

Common Questions and Solutions

Client cannot connect

  • Check the network connection: ensure the network connection is normal
  • Check the API Key: ensure the API Key is correct and not expired
  • Check the domain configuration: ensure the domain is configured correctly, using https://api.xftoken.ctclouds.com

Model fails to load

  • Check API Key permissions: ensure the API Key has sufficient permissions
  • Check model availability: ensure the selected model is available in EMCP Token
  • Check the network connection: ensure the network connection is normal

Call failed

  • Check the API Key: ensure the API Key is correct and not expired
  • Check request parameters: ensure the request parameters meet EMCP Token's requirements
  • Check model permissions: ensure you have permission to use the selected model
  • Check the account balance: ensure the account has sufficient balance