文档 - KHaiXAPI

先选对 SDK

用途	建议	网关入口
普通 API 请求	使用开发 SDK	`https://api.khaix.net/v1`
OpenAI 风格 Agent	OpenAI Agents SDK，优先从 Responses 开始	`/v1/responses`
Claude Code 能力作为应用内 Agent	Claude Agent SDK	`https://api.khaix.net`，由 SDK 拼接 Messages 路径

SDK 接口会随版本更新。实现前请同时核对 OpenAI Agents SDK 模型与提供方和 Claude Agent SDK 概览。

OpenAI Agents SDK：Python

安装 SDK，并显式传入自定义 OpenAI 客户端。KHaiX Key 不能用于向 OpenAI 官方追踪端点上传 trace，因此最小示例先关闭 SDK tracing。

Shell

python -m pip install openai-agents

Python · 最小 Agent

import asyncio
import os

from agents import Agent, AsyncOpenAI, OpenAIProvider, RunConfig, Runner
from agents import set_tracing_disabled

client = AsyncOpenAI(
    api_key=os.environ["KHAIX_API_KEY"],
    base_url="https://api.khaix.net/v1",
)
provider = OpenAIProvider(openai_client=client)
set_tracing_disabled(True)

async def main():
    agent = Agent(
        name="Assistant",
        instructions="Reply concisely.",
        model="gpt-5.6-sol",
    )
    result = await Runner.run(
        agent,
        "Reply with exactly: connected",
        run_config=RunConfig(model_provider=provider),
    )
    print(result.final_output)

asyncio.run(main())

模型 ID 必须是当前 Key 可见的真实 ID。若所选分组的 Responses 兼容性不足，可显式改用 OpenAIChatCompletionsModel；这属于降级路径，能力和事件格式会随之改变。

OpenAI Agents SDK：TypeScript

Shell

npm install @openai/agents openai

TypeScript · 自定义客户端

import OpenAI from "openai";
import {
  Agent,
  run,
  setDefaultOpenAIClient,
  setTracingDisabled,
} from "@openai/agents";

setDefaultOpenAIClient(new OpenAI({
  apiKey: process.env.KHAIX_API_KEY,
  baseURL: "https://api.khaix.net/v1",
}));
setTracingDisabled(true);

const agent = new Agent({
  name: "Assistant",
  instructions: "Reply concisely.",
  model: "gpt-5.6-sol",
});

const result = await run(agent, "Reply with exactly: connected");
console.log(result.finalOutput);

不要把 KHaiX Key 同时写入 SDK 的官方 tracing exporter。需要追踪时，应配置独立的 OpenAI tracing 凭据或替换为自己的 trace processor。

Claude Agent SDK

Claude Agent SDK 复用 Claude Code 运行时。先完成Claude Code 持久化配置，或在启动进程中提供以下变量：

Shell

python -m pip install claude-agent-sdk

Shell · 进程环境

export ANTHROPIC_BASE_URL="https://api.khaix.net"
export ANTHROPIC_AUTH_TOKEN="$KHAIX_API_KEY"
export ANTHROPIC_MODEL="claude-sonnet-5"

Python · 无工具最小验证

import asyncio
import os

from claude_agent_sdk import AssistantMessage, ClaudeAgentOptions, query

async def main():
    options = ClaudeAgentOptions(
        model="claude-sonnet-5",
        tools=[],
        allowed_tools=[],
        env={
            "ANTHROPIC_BASE_URL": "https://api.khaix.net",
            "ANTHROPIC_AUTH_TOKEN": os.environ["KHAIX_API_KEY"],
        },
    )
    async for message in query(
        prompt="只回复：连接成功",
        options=options,
    ):
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if hasattr(block, "text"):
                    print(block.text)

asyncio.run(main())

Base URL 不加 /v1；运行时会请求 Anthropic Messages 路径。
KHaiX 使用 Bearer 鉴权，因此使用 ANTHROPIC_AUTH_TOKEN，不要把它替换成发送 x-api-key 的配置。
Python 的 ClaudeAgentOptions.env 会合并继承环境；TypeScript 的 options.env 会替换子进程环境，设置时必须使用 { ...process.env, ANTHROPIC_BASE_URL: "..." }，否则 PATH、HOME 等变量可能丢失。
工具权限仍由你的应用控制。生产环境应从只读、显式 allowlist 开始。

需要逐项验证的兼容边界

能力	验证方式	不要默认
函数工具	单工具调用、工具输出回传、并行工具分别测试	SDK 自动循环能掩盖协议字段缺失
会话状态	优先让 SDK 或应用保存完整历史	普通 HTTP 请求支持 `previous_response_id` 或服务端会话
结构化输出与视觉	按模型、分组和协议做端到端测试	同名模型在所有通道能力完全一致
托管工具与后台任务	模型广场明确标注且实测后再启用	仅因 Responses 基础调用成功就可用
追踪	使用独立 exporter 或自建 processor	KHaiX Key 可写入第三方 tracing 服务

生产检查

先完成不含工具的单轮请求，再测试流式和多轮状态。
工具参数必须在应用端校验；文件、Shell、网络和写操作使用最小权限。
设置最大轮次、超时、取消和预算上限，避免失控循环。
只对明确可重试的错误做有限退避；超时重放可能造成重复调用和计费。
记录响应返回的请求 ID、模型、分组、耗时和用量，不记录完整密钥。

协议字段见文本 API，错误分类见错误与重试。