# Spark-X2.5 工具接入指南

本文介绍如何为 Claude Code、Codex、OpenClaw 和 Hermes 配置 Spark X2.5。

# 接入前准备

本节中的 model、ANTHROPIC_MODEL 等是各 Agent 固定的客户端配置项名称，应按客户端要求保留；它们与接口请求体中的 model_id 字段不是同一层级的配置。

# 接入方式

# 地址选择原则

• Claude Code（Anthropic）：https://maas-api.cn-huabei-1.xf-yun.com/anthropic — 客户端自动追加 /v1/messages。
• Codex（Responses）：https://maas-api.cn-huabei-1.xf-yun.com/v1 — Codex 自动请求 /responses。
• OpenClaw / Hermes（OpenAI）：https://maas-api.cn-huabei-1.xf-yun.com/v2 — 客户端请求 /chat/completions。

# 建议验证顺序

1. 先用 cURL 验证端点：确认 APIKEY、模型 ID 和协议请求正常。
2. 再配置 Agent：Agent 通常会自动追加资源路径，Base URL 不要重复填写完整资源路径。
3. 最后验证工具循环：测试流式输出、工具调用、工具结果回填和长任务场景。

# 接入 Claude Code

通过 Anthropic Messages 协议，将 Claude Code 请求路由到 Spark X2.5。

# 从现有安装迁移

已安装 Claude Code 时，只需配置 Base URL、APIKEY 和模型映射。

# Linux / macOS

export ANTHROPIC_BASE_URL="https://maas-api.cn-huabei-1.xf-yun.com/anthropic"
export ANTHROPIC_AUTH_TOKEN="<你的 APIKEY>"
export ANTHROPIC_MODEL="spark-x2.5"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="spark-x2.5"
export CLAUDE_CODE_SUBAGENT_MODEL="spark-x2.5"

# Windows PowerShell

$env:ANTHROPIC_BASE_URL="https://maas-api.cn-huabei-1.xf-yun.com/anthropic"
$env:ANTHROPIC_AUTH_TOKEN="<你的 APIKEY>"
$env:ANTHROPIC_MODEL="spark-x2.5"
$env:ANTHROPIC_DEFAULT_HAIKU_MODEL="spark-x2.5"
$env:CLAUDE_CODE_SUBAGENT_MODEL="spark-x2.5"

# ~/.claude/settings.json

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://maas-api.cn-huabei-1.xf-yun.com/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "<你的 APIKEY>",
    "ANTHROPIC_MODEL": "spark-x2.5",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "spark-x2.5",
    "CLAUDE_CODE_SUBAGENT_MODEL": "spark-x2.5"
  }
}

# 从零安装

1. 安装 Claude Code

npm install -g @anthropic-ai/claude-code

验证安装

claude --version

2. 配置环境变量

使用上方任一种配置方式。ANTHROPIC_BASE_URL 填写 Anthropic 协议 Base URL，Claude Code 会自动请求 /v1/messages。

3. 启动

cd /path/to/your/project
claude

# 接入验证

# 接入 Codex

使用 Spark X2.5 Responses API 作为 Codex 自定义模型提供商。

# 前置条件

Codex 通过 Responses API 与模型交互。先安装 Codex CLI，并至少运行一次以创建 ~/.codex 目录。

# 安装

npm install -g @openai/codex

# 首次启动

codex

# 配置 APIKEY

# Linux / macOS

export APIKEY="<你的 APIKEY>"

# Windows PowerShell

$env:APIKEY="<你的 APIKEY>"

# 配置 ~/.codex/config.toml

# 推荐配置

model = "spark-x2.5"
model_provider = "spark"
preferred_auth_method = "apikey"
forced_login_method = "api"
model_reasoning_effort = "high"

[model_providers.spark]
name = "Spark X2.5"
base_url = "https://maas-api.cn-huabei-1.xf-yun.com/v1"
wire_api = "responses"
env_key = "APIKEY"
env_key_instructions = "设置 APIKEY 为讯飞平台 APIKEY"

Codex 使用 wire_api = "responses" 并在 Base URL 后请求 /responses，因此 Base URL 使用 https://maas-api.cn-huabei-1.xf-yun.com/v1。

# 启动与验证

# 启动

cd /path/to/your/project
codex

建议依次验证纯文本输出、Responses 流式事件、reasoning summary 和 function call。

# 接入 OpenClaw

通过 Custom Provider 连接 Spark X2.5 的 Chat Completions 端点。

# 从现有安装迁移

重新进入配置向导，并选择自定义 Provider。

# 配置向导

openclaw onboard --install-daemon

# Classic

openclaw onboard --classic

# 从零安装

1. 安装

# Linux / macOS

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

# Windows PowerShell

iwr -useb https://openclaw.ai/install.ps1 | iex

2. 配置默认模型

# 配置

openclaw onboard --install-daemon

3. 开始使用

# Web UI

openclaw dashboard

# TUI

openclaw tui

# Terminal

openclaw terminal

# 验证要点

# 接入 Hermes

将 Spark X2.5 配置为 Hermes 的自定义 OpenAI-compatible Endpoint。

# 安装 Hermes

Linux、macOS 或 WSL2 可使用安装脚本。

# 安装

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

# 运行并配置

# Setup

hermes setup

# 环境变量方式

# Linux / macOS

export OPENAI_BASE_URL="https://maas-api.cn-huabei-1.xf-yun.com/v2"
export OPENAI_API_KEY="<你的 APIKEY>"

# config.yaml 示例

# YAML

model:
  default: spark-x2.5
  provider: custom
  base_url: https://maas-api.cn-huabei-1.xf-yun.com/v2

APIKEY 建议通过 Hermes 的凭证流程保存，避免将明文密钥写入共享配置文件。

# 开始使用

# 聊天

hermes chat

# 切换模型

/model custom:spark-x2.5