文档 - KHaiXAPI

先选择协议

Agent	推荐协议	Base URL
Codex、OpenCode、Kilo、OpenClaw、Pi	OpenAI Responses	`https://api.khaix.net/v1`
Hermes Agent	Responses 或 Chat Completions，二选一	`https://api.khaix.net/v1`
Cline、Aider	OpenAI Chat Completions	`https://api.khaix.net/v1`

请使用表中的 Base URL。客户端会自行拼接 /responses 或 /chat/completions；字段名为 Base URL 时，地址填到 /v1 即可。

Claude Code CLI

Claude Code 通过 Anthropic Messages 工作。KHaiXAPI 原生提供 POST /v1/messages，因此 CLI 可以直接连接，不需要在本机增加协议转换器。

先做最小诊断

先从模型广场确认当前可用的 Anthropic Messages 模型。下面的 claude-sonnet-5 是本站示例模型，执行时必须按模型广场中的当前模型 ID 替换。

Bash / Zsh

export ANTHROPIC_BASE_URL="https://api.khaix.net"
export ANTHROPIC_AUTH_TOKEN="sk-请替换为你的密钥"

curl -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":1,"messages":[{"role":"user","content":"."}]}'

PowerShell

$env:ANTHROPIC_BASE_URL = "https://api.khaix.net"
$env:ANTHROPIC_AUTH_TOKEN = "sk-请替换为你的密钥"

Invoke-RestMethod -Method Post -Uri "$env:ANTHROPIC_BASE_URL/v1/messages" `
  -Headers @{ "Authorization" = "Bearer $env:ANTHROPIC_AUTH_TOKEN"; "anthropic-version" = "2023-06-01" } `
  -ContentType "application/json" `
  -Body '{"model":"claude-sonnet-5","max_tokens":1,"messages":[{"role":"user","content":"."}]}'

收到包含消息对象的 JSON 后再写持久配置。若返回模型不存在，URL 和密钥仍可能已经验证通过；按模型广场更换模型后重试。401 表示凭证未被接受。

写入用户配置

Claude Code CLI 的持久配置写在当前用户的 settings.json：Windows 使用 %USERPROFILE%\.claude\settings.json，macOS、Linux 与 WSL 使用 ~/.claude/settings.json。目录或文件不存在时可手动创建；已有配置时，只把下面的字段合并进去，不要覆盖原有的权限、Hooks、Plugins 或 MCP 设置。

~/.claude/settings.json

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.khaix.net",
    "ANTHROPIC_AUTH_TOKEN": "sk-xxxxxxxxxxxxxxxx",
    "ANTHROPIC_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_FABLE_MODEL": "claude-fable-5",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-4-8",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-sonnet-5",
    "CLAUDE_CODE_SUBAGENT_MODEL": "inherit"
  }
}

在 KHaiXAPI 控制台为 Claude Code 单独创建 API Key，并用它替换 sk-xxxxxxxxxxxxxxxx。
确认 JSON 语法有效后，完全退出并重新启动 Claude Code。配置文件中的 env 会应用于之后启动的 CLI 会话。
运行 /status，确认 Anthropic base URL 为 https://api.khaix.net，认证来源为 ANTHROPIC_AUTH_TOKEN，模型为 claude-sonnet-5。
发送一个简短文字任务，再到 KHaiXAPI 控制台核对 Messages 协议、模型、状态与用量记录。

遇到登录冲突、配置层级或状态识别问题时，参阅 Claude Code 官方网关配置。保存过 Claude.ai 登录且认证来源不正确时，可在 Claude Code 中运行 /logout 后重新启动，再用 /status 检查。

Codex

Codex CLI、IDE 插件和 App 都读取当前用户的 .codex 配置。Windows 路径为 %USERPROFILE%\.codex\；macOS、Linux、WSL 和 SSH 环境使用 ~/.codex/。

在 config.toml 中加入以下字段：

~/.codex/config.toml

model = "gpt-5.6-sol"
model_provider = "openai"
openai_base_url = "https://api.khaix.net/v1"

再通过 Codex 登录命令写入密钥：

Bash / Zsh

export KHAIX_API_KEY="sk-请替换为你的密钥"
printenv KHAIX_API_KEY | codex login --with-api-key
codex login status

PowerShell

$env:KHAIX_API_KEY = "sk-请替换为你的密钥"
$env:KHAIX_API_KEY | codex login --with-api-key
codex login status

重启 Codex 后，用 /status 检查当前模型。审批策略、沙箱、Web Search 和命令联网权限可在 API 接通后分别设置。

OpenCode

编辑 ~/.config/opencode/opencode.json，通过 @ai-sdk/openai Responses provider 接入。已有配置时，把下面的 provider 合并进去，保留原有字段。

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "model": "api/gpt-5.6-sol",
  "provider": {
    "api": {
      "npm": "@ai-sdk/openai",
      "name": "KHaiXAPI",
      "options": {
        "baseURL": "https://api.khaix.net/v1"
      },
      "models": {
        "gpt-5.6-sol": {
          "name": "GPT-5.6 Sol",
          "reasoning": true,
          "options": {
            "store": false,
            "reasoningEffort": "high",
            "reasoningSummary": "auto"
          }
        }
      }
    }
  }
}

Terminal

opencode auth login
opencode auth list

认证时选择配置中的 api provider。进入 OpenCode 后可用 /models 检查模型；需要移除旧认证时，运行 opencode auth logout 并按提示选择 provider。

Hermes Agent

Hermes Agent 支持 Responses 和 Chat Completions 两种模式。先用 Responses；如果工具调用出现协议兼容问题，再切换到 Chat Completions 单独测试。

当前 providers 配置格式

~/.hermes/config.yaml

providers:
  khaix-responses:
    api: https://api.khaix.net/v1
    key_env: KHAIX_API_KEY
    transport: codex_responses
    default_model: gpt-5.6-sol

  khaix-chat:
    api: https://api.khaix.net/v1
    key_env: KHAIX_API_KEY
    transport: chat_completions
    default_model: gpt-5.6-sol

model:
  provider: custom:khaix-responses
  default: gpt-5.6-sol

把 KHAIX_API_KEY=sk-请替换为你的密钥 写入 ~/.hermes/.env。默认配置使用 Responses；切换 Chat Completions 时，把 model.provider 改为 custom:khaix-chat。当前 Hermes 使用顶层 providers 字典；旧版 custom_providers 仅用于兼容，不应再作为新配置模板。

不同 Hermes 版本可能迁移配置字段。若校验失败，先更新 Hermes，再运行 hermes model 并选择 Custom Endpoint，按官方 Named Custom Providers页面核对当前 schema。

Cline

Cline 通过 OpenAI Compatible 的 Chat Completions 路径接入：

打开 Cline 设置，将 API Provider 选为 OpenAI Compatible。
Base URL 填写 https://api.khaix.net/v1。
填写 API Key，Model ID 填写 gpt-5.6-sol。
按模型广场或已验证的服务端说明填写上下文、最大输出、图片输入、工具和价格展示字段；不要把客户端默认值当作模型事实，然后执行 Verify。
连接通过后先测试文本任务；使用工具时再单独测试工具调用。

Base URL 填到 /v1 即可，Cline 会自动拼接 /chat/completions。

Kilo Code

以下配置适用于当前 Kilo Code VS Code 版和 CLI。JetBrains 版的 provider 能力与界面不同，本节字段不适用。

打开 Settings → Providers，选择 Custom provider。
Provider ID 填写 khaix，Display name 填写 KHaiXAPI。
Provider API 选择 OpenAI Responses。
Base URL 填写 https://api.khaix.net/v1。
填写 API Key，Model 填写 gpt-5.6-sol。
保存后发送一条短文本任务；模型没有自动出现时，手工添加模型 ID。

OpenClaw

按照 OpenClaw 自定义 provider 格式编辑 ~/.openclaw/openclaw.json。下面只启用文本输入，密钥从环境变量读取。

openclaw.json

{
  "models": {
    "providers": {
      "api": {
        "baseUrl": "https://api.khaix.net/v1",
        "apiKey": "${KHAIX_API_KEY}",
        "auth": "api-key",
        "api": "openai-responses",
        "authHeader": true,
        "models": [
          {
            "id": "gpt-5.6-sol",
            "name": "GPT-5.6 Sol",
            "reasoning": true,
            "input": ["text"]
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "api/gpt-5.6-sol"
      }
    }
  }
}

启动前设置 KHAIX_API_KEY，也可以改用 OpenClaw SecretRef。保存后重启 gateway 或主进程，再测试文本输出和工具调用。

Pi 与 Aider

Pi Agent

编辑 ~/.pi/agent/models.json。下面使用 Responses；如需 Chat Completions，将 api 改为 openai-completions。

models.json

{
  "providers": {
    "khaix": {
      "baseUrl": "https://api.khaix.net/v1",
      "api": "openai-responses",
      "apiKey": "$KHAIX_API_KEY",
      "models": [
        {
          "id": "gpt-5.6-sol",
          "reasoning": true
        }
      ]
    }
  }
}

Aider

安装

python -m pip install aider-install
aider-install

Bash / Zsh

export OPENAI_API_BASE="https://api.khaix.net/v1"
export OPENAI_API_KEY="sk-请替换为你的密钥"
aider --model openai/gpt-5.6-sol

PowerShell

$env:OPENAI_API_BASE = "https://api.khaix.net/v1"
$env:OPENAI_API_KEY = "sk-请替换为你的密钥"
aider --model openai/gpt-5.6-sol

验证与权限

文字：要求 Agent 回复固定短语，核对模型、状态码和控制台记录。
流式：发送一条较长的纯文本任务，检查是否中途断开或重复输出。
工具：如果 Agent 配置了工具，先选择当前目录中的一个无敏感文件进行读取，检查工具参数、结果回传和下一轮模型请求。
错误：填写一个不存在的模型，确认客户端会显示错误，而非切换到其他 provider。

认证、URL、状态码或断流问题可按API 排错与安全中的“先 cURL、后客户端”顺序检查。

编码 Agent 配置

先选择协议

Claude Code CLI

先做最小诊断

写入用户配置

Codex

OpenCode

Hermes Agent

当前 providers 配置格式

Cline

Kilo Code

OpenClaw

Pi 与 Aider

Pi Agent

Aider

验证与权限