推理服务基于CC Switch对接常见Agent实践

场景介绍

本文档旨在指导用户通过 CC Switch（配置管理中心）将ModelArts推理平台上部署的在线推理服务与主流Agent工具（Claude Code、Codex、OpenCode、OpenClaw）进行对接，实现一键式API路由切换与协议转换，免去手动修改配置文件的繁琐操作。

CC Switch 是一款开源的 API 路由管理工具，其核心作用是接管 API 路由和协议转换。通过在本地启动代理服务，CC Switch 能够自动完成不同 API 格式之间的双向转换（如将 Responses API 格式转换为 Chat Completions 格式），使 ModelArts 推理平台的在线推理服务与各类 Agent 工具实现无缝对接。

本文档涵盖 CC Switch 基础配置与 OpenClaw、Claude Code、OpenCode、Codex 四款 Agent 工具的详细对接步骤。

本文档适用于以下场景：

• 需要将 ModelArts 推理服务同时对接多款 Agent 工具（Claude Code、Codex、OpenCode、OpenClaw）的用户
• 需要在不同 Agent 工具之间快速切换推理服务后端的用户

前提条件

在开始配置前，请确保满足以下条件：

1. 已在 ModelArts 推理平台上完成模型部署并创建在线推理服务，且服务状态为“运行中”。
2. 已获取在线推理服务的 调用 URL、API Key 和 模型名称（详见获取推理服务信息）。
3. 已安装至少一款Agent工具（Claude Code、Codex、OpenCode 或 OpenClaw）。
4. 系统环境中不存在可能冲突的API环境变量（如 ANTHROPIC_AUTH_TOKEN、OPENAI_API_KEY 等）。若存在，请先清除后再进行配置。

配置流程

核心原则：确保各Agent工具中配置的模型名称（Model ID）与CC Switch中启用/映射的名称、以及ModelArts推理服务中部署的模型名称三者保持一致。配置完成后，建议在各工具内运行简单的代码生成或查询指令，以验证Tool Calling和推理功能是否正常。

获取推理服务信息

在配置CC Switch之前，需要先从ModelArts推理平台获取以下三项关键信息。这三项信息将用于后续在CC Switch中填写自定义供应商参数。

ModelArts的在线推理服务提供标准RESTful API，支持HTTP/HTTPS 协议访问，并提供OpenAI 兼容的Chat Completions接口格式，便于与Agent 工具对接。

获取API访问地址（Base URL）

ModelArts为每个在线推理服务提供独立的API调用地址。获取方式如下：

1. 登录ModelArts管理控制台，在左侧导航栏中选择“模型推理 > 在线推理”
2. 在“在线推理”列表中，单击目标在线服务名称，进入服务详情页。
3. 在服务详情页的“服务”页签中，找到“调用信息”区域，记录其中的调用URL

调用 URL 的格式为：https://{endpoint}/v2/infer/{服务ID}，即为填入CC Switch的Base URL。

如果需要使用SSE（Server-Sent Events）流式输出，调用地址为：{调用URL}/v1/sse。流式输出适用于Agent工具需要实时接收推理结果的场景。

获取鉴权信息（API Key）

ModelArts在线推理服务支持三种认证方式：API KEY 认证（推荐）、IAM Token 认证和无认证。对于Agent 具对接，推荐使用API KEY认证。

创建并获取API Key的步骤如下：

1. 在“在线推理”页面，单击“API Key 授权管理”页签
2. 单击“创建API Key”，填写名称和描述，选择“授权范围”（全部在线服务或指定在线服务）
3. 单击“确定”后系统会自动下载 CSV 文件，其中api_key字段即为API Key内容。请妥善保管此文件，后续不支持重新下载。
4. 若授权范围为“指定在线服务”，需在API Key 授权管理页面单击“绑定”，将API Key绑定到目标在线服务后才会生效。

调用API时，需要在请求头中携带API Key进行认证：Authorization: Bearer {你的API Key}

API Key是访问推理服务的凭证，创建后仅可下载一次，请务必妥善保管。切勿将API Key提交到代码仓库或公开渠道。

确认模型名称（Model ID）

模型名称对应推理请求体中的model字段，用于Agent工具中的模型选择和路由。获取方式如下：

1. 在“在线推理服务”详情页的“服务”页签中，查看模型相关信息
2. 记录部署服务时所选模型的名称，该名称将填入CC Switch 的“默认模型”参数及各Agent工具的模型配置中

   推理请求体示例（OpenAI兼容Chat Completions 格式）：

   {
       "model": "你的模型名称",
       "messages": [
           {
               "role": "user",
               "content": "你是谁？"
           }
       ],
       "max_tokens": 100,
       "stream": false
   }

上述请求体中的model字段值即为需要记录的模型名称。

CC Switch配置

CC Switch的核心作用是接管API 路由和协议转换，免去手动修改配置文件的麻烦。

安装CC Switch

CC Switch支持Windows、macOS 和 Linux三大平台，安装方式如下：

• Windows：从GitHub Releases下载 .msi 安装包，双击安装。
• macOS：执行命令 brew tap farion1231/ccswitch && brew install --cask cc-switch，或下载 .dmg 文件拖入“应用程序”文件夹。
• Linux：下载对应发行版的 .deb、.rpm 或 .AppImage 文件安装。

添加自定义供应商

通过Custom自定义配置，将ModelArts的在线推理服务作为供应商接入CCSwitch。

1. 选择自定义配置

   打开CC Switch，在顶部导航栏选择要配置的工具（如 Codex 或 Claude Code），单击右上角的 + 号添加供应商，在弹出的窗口中选择 Custom（自定义配置）。

2. 填写核心参数

   在自定义配置界面，手动填入以下关键信息：

   参数	说明	示例
   供应商名称	自定义一个便于识别的名称	ModelArts-推理服务
   Base URL	调用URL，参见获取推理服务信息章节	https://{endpoint}/v2/infer/{服务ID}
   API Key	从CSV文件获取的API Key，参见获取推理服务信息章节	从下载的 CSV 文件中获取
   默认模型	确认的模型名称，参见获取推理服务信息章节	部署时指定的模型名称

   ModelArts的在线推理服务原生支持OpenAI 兼容的Chat Completions格式。在CC Switch中将上游格式设为Chat Completions即可直接匹配，无需额外的格式转换开销。

3. 设置关键协议与路由（核心步骤）

   这是整个配置流程中最关键的步骤。ModelArts的在线推理服务使用Chat Completions 协议（OpenAI 兼容格式），而Codex等部分Agent工具默认使用Responses API，两种协议格式不兼容，因此必须通过CC Switch进行协议转换。

   1. 上游格式/协议类型：将格式设置为 Chat Completions（或 openai_chat）。
   2. 开启本地路由映射：务必勾选“需要本地路由映射”或“开启路由接管”。
   3. 确认路由开关：进入CC Switch的“设置 > 路由”，确保路由总开关和对应工具（如 Codex）的专属开关均已打开。

   完成上述设置后，CC Switch会在本地（默认 127.0.0.1:15721）启动代理服务，自动完成请求格式的双向转换。

4. 保存并启用

   单击“保存”后，回到供应商列表，选中刚添加的自定义供应商并单击“启用（Enable）”。CC Switch会自动接管并修改底层配置文件，将请求指向本地代理，最终转发到 ModelArts 在线推理服务。

5. 验证生效
   完成配置后，请按以下步骤验证是否生效。

   1. 完全退出并重启Agent工具（如 Codex）。
   2. 在终端输入 /model 命令，确认模型列表中是否成功显示了已配置的自定义模型名称。
   3. 发送一条简单的测试指令（如代码生成或项目分析），验证响应和流式输出是否正常。

Agent端配置与验证

配置好CC Switch后，需要在各个Agent工具中进行验证或进一步的个性化配置。以下分别介绍四款Agent工具的对接方法。

Claude Code

Claude Code是Anthropic推出的终端AI编程助手，支持代码生成、调试、重构等功能。

• 生效与验证
  1. 如果开启了CC Switch的本地路由，Claude Code通常支持热切换，无需重启终端。
  2. 在终端输入 /model 命令，选择刚启用的模型。
  3. 输入 /status，检查 ANTHROPIC_BASE_URL 是否指向了本地代理（如 127.0.0.1:15721）。
• 自定义子代理（Subagent）配置

  若需为特定任务创建专属Agent，可在项目级 .claude/agents/ 或全局 ~/.claude/agents/ 目录下创建Markdown文件（如 code-reviewer.md）。

  在 YAML 头部指定模型（此处填写 ModelArts推理平台上部署的模型名称）：

  ---
  name: code-reviewer
  description: 审查代码质量和安全问题
  model: sonnet
  tools: Read, Grep, Bash
  ---

Codex

Codex 是 OpenAI 推出的终端 AI 编程助手，支持沙箱模式执行和代码自动化操作。

• 生效与验证
  1. 配置修改后，必须完全退出并重启Codex终端或桌面版（因为模型目录等配置需新进程刷新）。
  2. 启动后输入 /model，确认显示的模型名称为在ModelArts推理平台上部署的模型（如 deepseek-chat）。
• 自定义 Agent 配置

  在项目级 .codex/agents/ 或全局 ~/.codex/agents/ 目录下创建 .toml 文件。

  指定模型与沙箱权限：

  name = "pr_explorer"
  description = "只读代码库探索，在提出变更前先收集证据。"
  model = "deepseek-chat"
  sandbox_mode = "read-only"
  developer_instructions = "保持探索模式，不要修改任何文件"

OpenCode

OpenCode是一款开源的终端AI编程助手，支持自定义子代理和灵活的模型切换。

• 生效与验证
  1. 重启OpenCode终端即可生效。
  2. 按 Tab 键可循环切换主代理，或在消息中使用 @explore 等方式手动调用子代理。
• 自定义 Agent 配置

  方式一：编辑全局配置文件

  编辑全局 ~/.config/opencode/opencode.json 或项目级 opencode.json：

  {
    "agent": {
      "code-reviewer": {
        "description": "审查代码质量",
        "mode": "subagent",
        "model": "anthropic/claude-sonnet-4-20250514"
      }
    }
  }

  方式二：使用Agent目录

  在 .opencode/agents/ 目录下创建Markdown文件（文件名即代理名），使用YAML头部配置description、model、temperature等参数。

OpenClaw

OpenClaw是一款开源的AI编程助手，支持首选与备用模型配置及工具权限管理。

• 生效与验证
  1. CC Switch会自动将配置写入OpenClaw的设置文件，重启OpenClaw即可生效。
  2. 执行 openclaw chat，若能正常进入对话模式并响应，说明配置成功。
• 进阶配置（手动编辑）

  若需更精细的控制，可手动编辑配置文件 ~/.openclaw/openclaw.json。

  配置首选与备用模型：

  {
    "agents": {
      "defaults": {
        "model": {
          "primary": "anthropic/claude-sonnet-4-5",
          "fallbacks": ["openai/gpt-5.2"]
        }
      }
    }
  }

提醒：OpenClaw3.2及以上版本默认工具权限为 chat（仅能聊天），若需执行文件、代码等操作，必须手动将tools.profile 改为 "full" 并重启。

常见问题排查