AxonHub 集成 OpenCode 指南

本文教你配置 OpenCode 通过 AxonHub 连接模型：作为 Anthropic 端点的无缝替代方案，结合 AxonHub 模型配置（Model Profiles）实现统一端点、请求追踪与模型路由。

本文基于 AxonHub 官方文档 - OpenCode 集成指南。

AxonHub 可以作为 Anthropic 端点的无缝替代方案，让 OpenCode 通过您自己的基础设施进行连接。本文说明如何配置 OpenCode 以及如何将其与 AxonHub 模型配置（Model Profiles）结合使用。

1. 概述

核心能力

  • 协议转换：AxonHub 执行 AI 协议/格式转换，配置多个上游渠道（供应商），为 OpenCode 暴露统一的 Anthropic 兼容接口
  • 请求追踪：将同一会话的 OpenCode 请求聚合到一个 Trace 中
  • 模型路由：通过模型配置（Model Profiles）实现灵活的请求分发

前提条件

  • 可从开发机器访问的 AxonHub 实例（参见部署教程）
  • 具有项目访问权限的有效 AxonHub API 密钥
  • 已安装 OpenCode CLI
  • 可选：在 AxonHub 控制台中配置的一个或多个模型配置

2. 配置 OpenCode

2.1 创建配置文件

编辑 ~/.config/opencode/opencode.json：

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": [
    "opencode-axonhub-tracing"
  ],
  "provider": {
    "axonhub": {
      "npm": "@ai-sdk/anthropic",
      "name": "AxonHub",
      "options": {
        "baseURL": "http://127.0.0.1:8090/anthropic/v1",
        "apiKey": "你的AxonHub_API_Key"
      },
      "models": {
        "claude-sonnet-4-5": {
          "name": "AxonHub - Claude Sonnet 4.5",
          "modalities": {
            "input": ["text", "image"],
            "output": ["text"]
          }
        }
      }
    }
  }
}

2.2 配置参数说明

参数描述示例
npm提供商对应的 npm 包@ai-sdk/anthropic
name提供商显示名称AxonHub
baseURLAxonHub Anthropic API 端点http://127.0.0.1:8090/anthropic/v1
apiKeyAxonHub API 密钥替换为实际密钥

baseURL 必须指向 Anthropic 兼容端点 /anthropic/v1，而非通用 /v1。

2.3 添加多个模型

在同一个提供商中配置多个模型：

{
  "provider": {
    "axonhub": {
      "npm": "@ai-sdk/anthropic",
      "name": "AxonHub",
      "options": {
        "baseURL": "http://127.0.0.1:8090/anthropic/v1",
        "apiKey": "your-axonhub-api-key"
      },
      "models": {
        "claude-sonnet-4-5": {
          "name": "AxonHub - Claude Sonnet 4.5",
          "modalities": {
            "input": ["text", "image"],
            "output": ["text"]
          }
        },
        "claude-haiku-4-5": {
          "name": "AxonHub - Claude Haiku 4.5",
          "modalities": {
            "input": ["text", "image"],
            "output": ["text"]
          }
        },
        "claude-opus-4-5": {
          "name": "AxonHub - Claude Opus 4.5",
          "modalities": {
            "input": ["text", "image"],
            "output": ["text"]
          }
        }
      }
    }
  }
}

2.4 使用远程 AxonHub 实例

如果 AxonHub 部署在远程服务器，更新 baseURL：

{
  "options": {
    "baseURL": "https://your-axonhub-domain.com/anthropic/v1",
    "apiKey": "your-axonhub-api-key"
  }
}

3. 追踪插件

opencode-axonhub-tracing 插件为每个 LLM 请求注入追踪头部，实现在 AxonHub 中的请求聚合和追踪。

3.1 启用插件

在 opencode.json 的 plugin 数组中添加：

{
  "plugin": ["opencode-axonhub-tracing"]
}

OpenCode 会在需要时自动安装该插件。

3.2 默认 Headers

Header来源描述
AH-Thread-IdOpenCode sessionID将同一会话的请求分组
AH-Trace-IdOpenCode message.id每条消息的唯一标识符

3.3 自定义 Header 配置（可选）

通过环境变量覆盖默认 header key：

export OPENCODE_AXONHUB_TRACING_THREAD_HEADER="X-Thread-Id"
export OPENCODE_AXONHUB_TRACING_TRACE_HEADER="X-Trace-Id"
环境变量默认值描述
OPENCODE_AXONHUB_TRACING_THREAD_HEADERAH-Thread-Id自定义线程 header key
OPENCODE_AXONHUB_TRACING_TRACE_HEADERAH-Trace-Id自定义追踪 header key

空字符串会自动回退到默认 key。

4. 模型配置（Model Profiles）

AxonHub 模型配置可以将传入的模型名称重映射为特定提供商的等效名称。

4.1 配置方式

  1. 在 AxonHub 控制台中创建一个配置
  2. 添加映射规则（精确名称或正则表达式）
  3. 将该配置分配给 API 密钥
  4. 切换活跃的配置以更改 OpenCode 行为，无需改动工具设置

4.2 使用场景

成本优化：

请求模型映射到效果
claude-sonnet-4-5deepseek-chat降低调用成本
claude-haiku-4-5gpt-4o-mini简单任务走更便宜的模型

性能优化：

请求模型映射到效果
claude-opus-4-5claude-sonnet-4-5获得更快的响应
claude-sonnet-4-5gpt-4o更好的可用性

高级推理：

请求模型映射到效果
claude-sonnet-4-5deepseek-reasoner复杂推理任务
claude-opus-4-5o1-preview数学问题

5. 多提供商配置

可以将多个 AxonHub 实例配置为不同的提供商：

{
  "provider": {
    "axonhub-prod": {
      "npm": "@ai-sdk/anthropic",
      "name": "AxonHub Production",
      "options": {
        "baseURL": "https://prod.axonhub.com/anthropic/v1",
        "apiKey": "prod-api-key"
      },
      "models": {
        "claude-sonnet-4-5": {
          "name": "Production - Claude Sonnet 4.5",
          "modalities": {
            "input": ["text", "image"],
            "output": ["text"]
          }
        }
      }
    },
    "axonhub-dev": {
      "npm": "@ai-sdk/anthropic",
      "name": "AxonHub Development",
      "options": {
        "baseURL": "http://localhost:8090/anthropic/v1",
        "apiKey": "dev-api-key"
      },
      "models": {
        "claude-sonnet-4-5": {
          "name": "Development - Claude Sonnet 4.5",
          "modalities": {
            "input": ["text", "image"],
            "output": ["text"]
          }
        }
      }
    }
  }
}

同时支持 OpenAI 兼容端点：

{
  "provider": {
    "axonhub-openai": {
      "npm": "@ai-sdk/openai",
      "name": "AxonHub OpenAI",
      "options": {
        "baseURL": "http://127.0.0.1:8090/v1",
        "apiKey": "your-axonhub-api-key"
      },
      "models": {
        "gpt-4": {
          "name": "AxonHub - GPT-4",
          "modalities": {
            "input": ["text"],
            "output": ["text"]
          }
        }
      }
    }
  }
}

6. 故障排除

OpenCode 无法连接

症状：连接错误、超时

排查步骤：

  1. 验证 baseURL 指向正确的 AxonHub Anthropic 端点（/anthropic/v1）
  2. 检查 AxonHub 是否运行：curl http://localhost:8090/health
  3. 检查防火墙是否允许出站连接
  4. 对于自签名证书的 HTTPS 端点，配置信任设置

身份验证错误

症状：401 Unauthorized、403 Forbidden

排查步骤：

  1. 验证 API 密钥是否正确
  2. 在 AxonHub 控制台中检查 API 密钥是否过期
  3. 确保 API 密钥具有所请求项目和模型的访问权限

意外的模型响应

症状：错误的模型响应、意外行为

排查步骤：

  1. 在 AxonHub 控制台中查看活跃的配置映射
  2. 检查渠道配置和模型关联
  3. 验证请求的模型名称是否与配置匹配
  4. 如有必要，禁用或调整配置规则

配置文件未加载

症状：OpenCode 使用默认设置，忽略配置文件

排查步骤：

  1. 验证配置文件位置：~/.config/opencode/opencode.json
  2. 检查 JSON 语法是否有效
  3. 确保文件权限允许读取
  4. 更改配置后重启 OpenCode

7. 已知限制

CC Switch 无法注入 OpenCode Go 官方 URL

当 CC Switch 的 Provider Base URL 设置为 https://api.opencode.ai/v1（OpenCode Go 官方地址）时，CC Switch 无法将该 Provider 注入到 OpenCode 的配置文件中，修改不生效。

解决方案：

  • 通过 AxonHub 反代 OpenCode Go（即本文配置方式），CC Switch 指向 localhost:8090，无此问题
  • 或手动编辑 ~/.config/opencode/opencode.json 直接写入官方 URL

验证与自查

  1. curl http://localhost:8090/health 确认 AxonHub 运行中
  2. OpenCode 中 opencode 启动后能列出 axonhub provider 下的模型并成功发起对话
  3. 在 AxonHub 控制台的追踪页面能看到按 AH-Thread-Id 聚合的会话请求
  4. 修改模型配置映射后，OpenCode 中重新请求即按新路由生效，无需改动工具设置

参考