接入 PhanEdge - PhanEdge 幻锋AI 用户文档

前置条件

PhanEdge 账号与 API Key

OpenClaw 已安装并启动

确保 OpenClaw CLI 已安装且 Gateway 可正常运行。参见安装与启动。

协议背景

不同品牌模型的接口协议并不相同，PhanEdge 同时支持以下三类协议。你可以按需配置一个或多个 provider。

协议	典型接口	适用模型
OpenAI（GPT 协议）	`POST /v1/chat/completions` 或 `POST /v1/responses`	GPT 系列及 OpenAI 兼容模型
Anthropic（Claude 协议）	`POST /v1/messages`	Claude 系列
Google（Gemini 协议）	`POST .../models/{model}:generateContent`	Gemini 系列

配置 PhanEdge 模型提供方

编辑 OpenClaw 配置文件 ~/.openclaw/openclaw.json。

以下示例使用 JSON5 写法（允许注释与尾逗号）；若你环境严格要求 JSON，请去掉注释与尾逗号。示例中的模型 ID 需替换为你在 PhanEdge 控制台中实际启用的模型 ID。

GPT（OpenAI 协议）

用于对接 GPT 系列以及任何走 OpenAI 协议的模型。

{
  agents: {
    defaults: {
      model: { primary: "phanedge-openai/gpt-5.4" },
    },
  },

  models: {
    mode: "merge",
    providers: {
      "phanedge-openai": {
        baseUrl: "https://models.phanedge.cloud",
        apiKey: "${KAPON_API_KEY}",
        api: "openai-completions",
        // 如 PhanEdge 要求额外请求头，可在此追加
        // headers: { "X-PhanEdge-Project": "xxx" },
        models: [
          { id: "gpt-5.4", name: "GPT 5.4 (via PhanEdge, OpenAI protocol)" },
        ],
      },
    },
  },
}

Claude（Anthropic 协议）

用于对接 Claude 系列（Anthropic 原生 messages 协议，推荐 claude-opus-4-6）。

{
  agents: {
    defaults: {
      model: { primary: "phanedge-anthropic/claude-opus-4-6" },
    },
  },

  models: {
    mode: "merge",
    providers: {
      "phanedge-anthropic": {
        baseUrl: "https://models.phanedge.cloud",
        apiKey: "${KAPON_API_KEY}",
        api: "anthropic-messages",
        models: [
          { id: "claude-opus-4-6", name: "Claude Opus 4.6 (via PhanEdge, Anthropic protocol)" },
        ],
      },
    },
  },
}

Gemini（Google 协议）

Gemini 走 Google 原生协议，接口与鉴权方式不同于 OpenAI / Anthropic。

{
  agents: {
    defaults: {
      model: { primary: "google/gemini-3-pro-preview" },
    },
  },

  models: {
    mode: "merge",
    providers: {
      google: {
        baseUrl: "https://models.phanedge.cloud",
        apiKey: "${KAPON_API_KEY}",
      },
    },
  },
}

配置说明：

字段	说明
`agents.defaults.model.primary`	OpenClaw 默认模型，格式为 `provider/model`
`models.providers.*.baseUrl`	对应协议的 PhanEdge 入口地址
`models.providers.*.apiKey`	PhanEdge 幻锋AI的 API Key
`models.providers.*.api`	请求协议类型：`openai-completions`（GPT）或 `anthropic-messages`（Claude），Gemini 无需指定
`models.providers.*.models[].id`	PhanEdge 控制台中的实际模型 ID，需完全一致（含前缀、大小写）
`models.providers.*.models[].name`	在 OpenClaw 中展示的模型名称

若只需一种协议，仅配置对应的 provider 即可。多协议可同时配置，在 agents.defaults.model.primary 中指定默认使用的模型。

使用环境变量（推荐）

为避免在配置文件中写死密钥，推荐使用系统环境变量：

export KAPON_API_KEY="YOUR_KAPON_API_KEY"

配置中使用 ${KAPON_API_KEY} 占位符即可引用。确保启动 OpenClaw 的进程环境中已设置该变量。

重启 Gateway

修改配置后需重启 Gateway 使其生效。 直接启动：

openclaw gateway --port 18789 --verbose

守护进程模式（systemd）：

systemctl --user restart openclaw-gateway.service

重启后建议执行健康检查：

openclaw doctor

验证集成

curl 验证协议连通性

分别验证已配置的协议是否打通。 GPT（OpenAI 协议）：

curl -X POST "https://models.phanedge.cloud/v1/chat/completions" \
  -H "Authorization: Bearer ${KAPON_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.4",
    "messages": [{ "role": "user", "content": "你好，请用一句话介绍你自己。" }],
    "temperature": 0.7
  }'

Claude（Anthropic 协议）：

curl -X POST "https://models.phanedge.cloud/v1/messages" \
  -H "Authorization: Bearer ${KAPON_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4-6",
    "max_tokens": 1024,
    "messages": [{ "role": "user", "content": "你好，请介绍你自己" }]
  }'

Gemini（Google 协议）：

curl -X POST "https://models.phanedge.cloud/v1beta/models/gemini-3-pro-preview:generateContent" \
  -H "Authorization: Bearer ${KAPON_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{ "parts": [{ "text": "你好" }] }]
  }'

终端验证

openclaw agent --message "请说明你当前是通过 PhanEdge 聚合平台调用模型的。"

若配置正确：

终端会返回模型生成的文本
PhanEdge 控制台的「调用日志 / 监控」中可看到对应调用记录

Web UI 验证

打开 OpenClaw Web UI
在「Models / 模型配置」中确认可看到已配置的 PhanEdge 模型条目
在 WebChat / Playground 中选择模型，发送测试消息，确认返回正常

常见问题排查

401 / 403 — 鉴权失败

检查 PhanEdge API Key 是否正确、未过期、权限充足
使用上方的 curl 命令单独测试 PhanEdge 接口
示例验证：

curl -X POST "https://models.phanedge.cloud/v1/messages" \
  -H "Authorization: Bearer YOUR_KAPON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4-6",
    "max_tokens": 1024,
    "messages": [{ "role": "user", "content": "你好，请介绍你自己" }]
  }'

404 — 模型不存在

确认模型 ID 与 PhanEdge 控制台中的完全一致（包括前缀、大小写）
在 PhanEdge 控制台查看当前可用模型列表

curl 成功但 OpenClaw 报错

确认 OpenClaw 读取的是当前 ~/.openclaw/openclaw.json
确认 agents.defaults.model.primary 与对应 provider 的 models[].id 一致
如使用环境变量，确保启动 OpenClaw 的同一进程环境中已设置相关变量

超时或连接失败

检查网络连通性：curl -I https://models.phanedge.cloud
确认各 baseUrl 地址正确
如有代理，确保 OpenClaw 进程也使用了相同的代理配置

​前置条件

​协议背景

​配置 PhanEdge 模型提供方

​GPT（OpenAI 协议）

​Claude（Anthropic 协议）

​Gemini（Google 协议）

​使用环境变量（推荐）

​重启 Gateway

​验证集成

​curl 验证协议连通性

​终端验证

​Web UI 验证

​常见问题排查

前置条件

协议背景

配置 PhanEdge 模型提供方

GPT（OpenAI 协议）

Claude（Anthropic 协议）

Gemini（Google 协议）

使用环境变量（推荐）

重启 Gateway

验证集成

curl 验证协议连通性

终端验证

Web UI 验证

常见问题排查