# 概览

Cookbook 只回答一个问题：**怎么把 Praxis 接进你手上的东西**。概念与架构在[开发者文档](/docs/cloud)，端点与参数在 [API](/docs/api)，这里只放可复制的接入步骤。

## 按工具选择接入方式 [#按工具选择接入方式]

绝大多数工具只需要三件事：Base URL、API Key、模型 ID。

| 你在用什么                                   | 推荐入口                                              | 协议                          |
| --------------------------------------- | ------------------------------------------------- | --------------------------- |
| Claude Code、Codex、Gemini CLI 等编程 Agent  | [客户端与 Coding Agent](/docs/cookbook/coding-agents) | Anthropic / OpenAI / Google |
| Cursor、Windsurf、Trae 等 IDE              | [IDE 接入](/docs/cookbook/ide)                      | OpenAI 兼容                   |
| Cherry Studio、Open WebUI、Chatbox 等聊天客户端 | [聊天客户端](/docs/cookbook/chat-clients)              | OpenAI 兼容                   |
| Dify、Coze、FastGPT、n8n 等应用平台             | [框架与应用](/docs/cookbook/sdk)                       | OpenAI 兼容                   |
| 自己写的服务端代码                               | [模型任务](/docs/cookbook/scenarios)                  | 任意协议                        |
| Cloudflare Workers、Next.js 等运行时         | [部署与运行时](/docs/cookbook/scenarios)                | 服务端代理                       |

## 按任务找食谱 [#按任务找食谱]

| 食谱                                                | 解决什么                             |
| ------------------------------------------------- | -------------------------------- |
| [客户端与 Coding Agent](/docs/cookbook/coding-agents) | 把 Praxis 接进已经在用的工具               |
| [框架与应用](/docs/cookbook/sdk)                       | SDK、低代码平台与自己的应用                  |
| [模型任务](/docs/cookbook/scenarios)                  | 第一个请求、流式、结构化输出、多模态               |
| [智能体与沙箱](/docs/cookbook/scenarios)                | Managed Agent、沙箱执行、浏览器与 RAG      |
| [部署与运行时](/docs/cookbook/scenarios)                | Cloudflare Workers、Next.js、服务端代理 |
| [生产化](/docs/cookbook/scenarios)                   | Key 安全、重试降级、成本与观测                |

## 从兼容协议迁移 [#从兼容协议迁移]

* [从 OpenAI 迁移](/docs/cookbook/migration/from-openai)
* [从 Anthropic 迁移](/docs/cookbook/migration/from-anthropic)
* [从 OpenRouter 迁移](/docs/cookbook/migration/from-openrouter)
* [从其他网关迁移](/docs/cookbook/migration/from-other-gateways)

## 运行示例前的准备 [#运行示例前的准备]

1. **API Key**：在 Console 创建，请求头为 `Authorization: Bearer <key>`，详见[鉴权与 Key](/docs/api/authentication)。
2. **Base URL**：生产环境是 `https://api.deepraxis.ai`。
3. **模型 ID**：从[模型目录](/docs/cloud/services/model)选择，例如 `deepseek-v4-flash`。

```bash
curl https://api.deepraxis.ai/openai/v1/chat/completions \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-v4-flash","messages":[{"role":"user","content":"你好"}]}'
```

遇到 401 / 404 / 模型不存在？先看[限流与错误](/docs/cloud/services/model/limits-and-errors)。

# 编程 Agent



# Claude Code

把 Praxis 接入 Claude Code，在终端里用你的 Key 驱动编程智能体——改代码、跑命令、答问题。

每一步都标了**期望结果**：照做即可，也可以把本页直接交给能操作电脑的 AI 助手，让它替你完成安装、配置与验证。

## 你将完成 [#你将完成]

* 在终端用 `claude` 命令调用 Praxis 的模型
* 完成标志：`claude -p "…"` 收到模型回复
* 预计耗时：**3 分钟**（不含 Node.js 安装）
* 支持协议：Anthropic 兼容（Claude Code 原生协议）

## 前提 [#前提]

开始前逐项确认：

* **一个 Praxis API Key**（`sk-praxis-` 开头）。没有就到 [控制台 → API Keys](https://console.deepraxis.ai/keys) 创建：点「创建 Key」，弹窗中**名称必填*&#x2A;，有效期默认 90 天（可改永久），点创建后立即复制保存；之后也随时可在 Key 列表行点「复制」重新获取完整 Key。新账号自带 **$1 免费额度**。完整流程见[快速开始](/docs/cloud/services/model/quickstart)。
* **Node.js 18 或更高**。终端运行 `node --version` 检查；没有就到 [nodejs.org](https://nodejs.org) 装 LTS 版。
* **安装 Claude Code**：

  ```bash
  npm install -g @anthropic-ai/claude-code
  ```

  期望：`claude --version` 输出版本号（本页以 2.1.211 为准）。

## 配置 [#配置]

**第 1 步：写入配置文件**

创建 `~/.claude/settings.json`（Windows 原生版为 `%USERPROFILE%\.claude\settings.json`），填入：

```json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.deepraxis.ai/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "sk-praxis-你的Key"
  },
  "model": "deepseek-flash"
}
```

两处说明：

* `model` **必须指定**。Claude Code 默认请求的模型不在 Praxis 目录里，不指定会在首次对话时报「Model does not exist」。`deepseek-flash` 是平台示例模型——便宜、快、中英文都好；目录里的其他模型同样可填。
* 密钥写在 `ANTHROPIC_AUTH_TOKEN`，不是 `ANTHROPIC_API_KEY`——后者是官方直连时用的，配网关时无效。

期望：文件保存即生效，无需重启任何服务。

<img alt="终端里查看 ~/.claude/settings.json 的实际内容" src="__img0" />

**第 2 步（可选）：临时会话不落盘**

不想把 Key 写进文件时，可以用一次性环境变量：

```bash
ANTHROPIC_BASE_URL=https://api.deepraxis.ai/anthropic \
ANTHROPIC_AUTH_TOKEN=sk-praxis-你的Key \
claude --model deepseek-flash -p "你好"
```

期望：收到中文回复。Windows PowerShell 用户不必用此方式，直接按第 1 步写入配置文件即可。在代码项目目录里运行时，回复可能带上该项目 `AGENTS.md` / `CLAUDE.md` 的上下文口吻，属正常。

## 验证 [#验证]

```bash
claude -p "用中文回复四个字：连接成功"
```

期望：终端直接输出 `连接成功`——**收到回复即接入成功**。

<img alt="终端运行 claude -p 的真实输出" src="__img1" />

去掉 `-p` 进入交互模式，就是完整的编程智能体工作台。首次启动会先让你选界面主题，选完即进入主界面：

<img alt="claude 交互模式欢迎屏" src="__img2" />

也可以在命令行完成等价验证。先设置变量（不然照抄 curl 会得到 401）：

```bash
export PRAXIS_API_KEY=sk-praxis-你的Key
```

以下命令为 macOS / Linux / WSL（bash）写法。Windows PowerShell 用户：上面 `claude -p` 已收到回复即接入成功，可跳过；如需命令行验证，先执行 `$env:PRAXIS_API_KEY="你的Key"`，再把 curl 写成一行（去掉每行末尾的 `\`）。

```bash
curl https://api.deepraxis.ai/anthropic/v1/messages \
  -H "x-api-key: $PRAXIS_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{"model": "deepseek-flash", "max_tokens": 256, "messages": [{"role": "user", "content": "你好"}]}'
```

期望：HTTP 200 即接入成功。`content` 中 `type` 为 `text` 的块是回复文本——`deepseek-flash` 是推理模型，前面可能先带一段 `thinking` 块，属正常。

最后看一眼 [控制台 → 用量与费用](https://console.deepraxis.ai/usage)：刚才的调用已经记在账上——每一次调用都有账、可追溯。

<img alt="控制台用量与费用页：deepseek-flash 的调用已逐笔记账" src="__img3" />

## 常见问题 [#常见问题]

| 症状                                                                             | 原因                                                | 解法                                                                                                                                      |
| ------------------------------------------------------------------------------ | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| 首次对话报「issue with the selected model … may not exist」或 `Model … does not exist` | 没有指定 `model`，Claude Code 用了它的默认模型，而它不在 Praxis 目录里 | 在 `settings.json` 加 `"model"`，或命令加 `--model`，填[目录](https://console.deepraxis.ai/models)内的模型（如 `deepseek-flash`）                         |
| 提示无效令牌 / 401                                                                   | Key 复制不完整或已吊销；或把 Key 写进了 `ANTHROPIC_API_KEY`      | 重新完整复制（注意 `sk-praxis-` 前缀）；确认写在 `ANTHROPIC_AUTH_TOKEN`；仍失败到[控制台](https://console.deepraxis.ai/keys)重建一个                                 |
| `Connection closed mid-response`                                               | 网络瞬断                                              | 直接重试一次即可                                                                                                                                |
| `npm install -g` 报权限错误                                                         | 系统 npm 全局目录不可写                                    | 设用户级前缀重装，或改用官方脚本安装（命令见下）；两法细节见 [npm 官方指南](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally) |

官方安装脚本：

```bash
curl -fsSL https://claude.ai/install.sh | bash
```

## 进阶 [#进阶]

* **查这段对话花了多少钱**：[控制台 → 用量与费用](https://console.deepraxis.ai/usage)，按次计费、无闲置费
* **换模型**：改 `settings.json` 的 `model`（或临时用 `--model`）。要 Claude 系旗舰就填 `claude-opus-5`；要固定版本快照用 `deepseek-v4-flash`，`deepseek-flash` 则始终指向最新一代 Flash
* **在项目里用**：进入代码目录直接运行 `claude`，它能读文件、改代码、执行命令——每一项动作都会先征求你的确认

## 相关食谱 [#相关食谱]

* [Codex](/docs/cookbook/coding-agents/codex) · [Cline](/docs/cookbook/coding-agents/cline) · [OpenCode](/docs/cookbook/coding-agents/opencode)
* 偏好图形界面？看 [Cherry Studio](/docs/cookbook/chat-clients/cherry-studio) · [Chatbox](/docs/cookbook/chat-clients/chatbox)

# Codex

把 Praxis 接入 Codex，在终端里用你的 Key 驱动 OpenAI 的编程智能体——改代码、跑命令、答问题。密钥只存环境变量，不落配置文件。

每一步都标了**期望结果**：照做即可，也可以把本页直接交给能操作电脑的 AI 助手，让它替你完成安装、配置与验证。

## 你将完成 [#你将完成]

* 在终端用 `codex` 命令调用 Praxis 的模型
* 完成标志：`codex exec "…"` 收到模型回复
* 预计耗时：**3–5 分钟**（不含 Node.js 安装）
* 支持协议：OpenAI Responses（Codex 原生协议）

## 前提 [#前提]

开始前逐项确认：

* **一个 Praxis API Key**（`sk-praxis-` 开头）。没有就到 [控制台 → API Keys](https://console.deepraxis.ai/keys) 创建：点「创建 Key」，弹窗中**名称必填*&#x2A;，有效期默认 90 天（可改永久），点创建后弹窗会展示完整 Key 一次——立即复制保存；之后也随时可在 Key 列表行点复制图标（悬停行时出现）重新获取完整 Key。若弹窗长时间停在「创建中…」，刷新列表确认 Key 已生成即可，行内复制同样能拿到完整 Key。新账号自带 **$1 免费额度**。完整流程见[快速开始](/docs/cloud/services/model/quickstart)。
* **Node.js 18 或更高**。终端运行 `node --version` 检查；没有就到 [nodejs.org](https://nodejs.org) 装 LTS 版。
* **安装 Codex CLI**：

  ```bash
  npm install -g @openai/codex
  ```

  期望：`codex --version` 输出 `codex-cli <版本号>`（本页以 0.162.1 为准）。

## 配置 [#配置]

**第 1 步：写配置文件**

创建 `~/.codex/config.toml`（Windows 为 `%USERPROFILE%\.codex\config.toml`）：

```toml
model = "deepseek-flash"
model_provider = "praxis"

[model_providers.praxis]
name = "Praxis"
base_url = "https://api.deepraxis.ai/openai/v1"
env_key = "PRAXIS_API_KEY"
wire_api = "responses"
```

三处说明：

* 密钥**不写进这个文件**——`env_key` 声明从环境变量 `PRAXIS_API_KEY` 读取，下一步设置。
* `wire_api` 必须是 `responses`：Codex 走的是 OpenAI Responses 协议，不是传统 chat completions。
* `model` 填目录内的模型 ID；`deepseek-flash` 是平台示例模型——便宜、快、中英文都好。

期望：文件保存后，下一次启动的 `codex` 命令即使用新配置（已开着的会话需退出重进）。

<img alt="终端里查看 ~/.codex/config.toml 的实际内容" src="__img0" />

**第 2 步：设置密钥环境变量**

macOS / Linux（WSL 同）：

```bash
export PRAXIS_API_KEY=sk-praxis-你的Key
```

想持久化就把这行加进 `~/.bashrc` 或 `~/.zshrc`。Windows PowerShell：`$env:PRAXIS_API_KEY="你的Key"`（或设置系统级环境变量后重开终端）。

期望：`echo $PRAXIS_API_KEY` 输出你的 Key（PowerShell 用 `echo $env:PRAXIS_API_KEY`）。

## 验证 [#验证]

进入一个代码项目目录（git 仓库），运行：

```bash
codex exec "用中文回复四个字：连接成功"
```

期望：回复正文包含 `连接成功`，末尾附 tokens used 统计——**收到回复即接入成功**。首次运行可能提示「Model metadata for deepseek-flash not found … Defaulting to fallback metadata」，这是自定义模型的正常回退提示，不影响使用。

<img alt="终端运行 codex exec 的真实输出" src="__img1" />

去掉 `exec` 直接运行 `codex`，进入交互式工作台（出现版本横幅与输入框即进入；本页不验证此项）。

也可以在命令行完成等价验证。先设置变量（不然照抄 curl 会得到 401）：

```bash
export PRAXIS_API_KEY=sk-praxis-你的Key
```

```bash
curl https://api.deepraxis.ai/openai/v1/responses \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "deepseek-flash", "input": "你好", "max_output_tokens": 256}'
```

期望：HTTP 200 即接入成功。`output` 里 `type` 为 `text` 的块是回复文本——`deepseek-flash` 是推理模型，前面可能先带 `reasoning` 块，属正常。

> 上述命令为 macOS / Linux / WSL（bash）写法。Windows PowerShell 用户：上面的 `codex exec` 已成功即接入完成，可跳过；如需命令行验证，先 `$env:PRAXIS_API_KEY="你的Key"`，用 `curl.exe`（PowerShell 的 `curl` 是别名，语法不同），并把命令并成一行（去掉行尾 `\`）。

最后看一眼 [控制台 → 用量与费用](https://console.deepraxis.ai/usage)：刚才的调用已经记在账上——每一次调用都有账、可追溯。

## 常见问题 [#常见问题]

| 症状                                   | 原因                                           | 解法                                                      |
| ------------------------------------ | -------------------------------------------- | ------------------------------------------------------- |
| 提示 `Model metadata … not found`      | 自定义模型不在 Codex 内置元数据表里                        | 正常回退提示，直接用；不影响对话与工具调用                                   |
| 提示无效令牌 / 401                         | `PRAXIS_API_KEY` 未导出、复制不完整，或改完 shellrc 没重开终端 | `echo $PRAXIS_API_KEY` 检查；重新完整复制；重开终端让配置生效              |
| 报 `Not inside a trusted directory …` | 不在 git 仓库目录里运行                               | 进项目目录运行；或临时加 `--skip-git-repo-check`                    |
| 报 `unknown configuration field`      | Codex 版本较旧，不认识新配置键                           | `npm install -g @openai/codex` 升级后重试                    |
| 报模型不存在                               | 模型 ID 与目录不一致                                 | 到[控制台 → 模型](https://console.deepraxis.ai/models)复制确切 ID |

## 进阶 [#进阶]

* **查这段对话花了多少钱**：[控制台 → 用量与费用](https://console.deepraxis.ai/usage)，按次计费、无闲置费
* **换模型**：改 `config.toml` 的 `model`，或运行 `codex -m <模型ID>`。可选 `deepseek-flash`、`deepseek-v4-flash`。Codex 只能使用声明了 Responses 协议的模型；在[模型目录](https://console.deepraxis.ai/models)打开模型详情，确认支持协议包含 Responses 后再选择。
* **在项目里用**：`codex` 交互模式能读文件、改代码、执行命令，敏感动作会先征求你的确认

## 相关食谱 [#相关食谱]

* [Claude Code](/docs/cookbook/coding-agents/claude-code)（Anthropic 协议姊妹篇）· [Cline](/docs/cookbook/coding-agents/cline) · [OpenCode](/docs/cookbook/coding-agents/opencode)
* 偏好图形界面？看 [Cherry Studio](/docs/cookbook/chat-clients/cherry-studio) · [Chatbox](/docs/cookbook/chat-clients/chatbox)

# Cline

|      |           |
| ---- | --------- |
| 支持协议 | OpenAI 兼容 |
| 备注   | —         |

## 前提 [#前提]

一个 API Key（见[快速开始](/docs/cloud/services/model/quickstart)）。

## 配置 [#配置]

（待补充：在 Cline 中填入 `https://api.deepraxis.ai` 与 API Key 的步骤，配截图 / 30 秒视频。）

## 验证 [#验证]

（待补充：接入成功的界面长什么样。）

## 常见问题 [#常见问题]

（待补充：模型 id 怎么填、流式、国内网络。）

# OpenCode

把 Praxis 接入 [OpenCode](https://opencode.ai)——开源终端编程智能体。项目里放一个 `opencode.json` 声明 provider，密钥走环境变量，`opencode run` 即通。

每一步都标了**期望结果**：照做即可，也可以把本页直接交给能操作电脑的 AI 助手，让它替你完成安装、配置与验证。

## 你将完成 [#你将完成]

* 在终端用 `opencode run` 调 Praxis 的模型
* 完成标志：`opencode run "…"` 收到模型回复
* 预计耗时：**3–5 分钟**（不含 Node.js 安装）
* 支持协议：OpenAI 兼容（`/openai/v1`）

## 前提 [#前提]

开始前逐项确认：

* **一个 Praxis API Key**（`sk-praxis-` 开头）。没有就到 [控制台 → API Keys](https://console.deepraxis.ai/keys&#x29; 创建：点「创建 Key」，名称必填，有效期可选 30/60/90 天或永久、默认 90 天；创建成功弹窗会展示完整 Key 并带「复制 Key」，关闭后列表只显示掩码，随时可点行内复制图标重新获取完整 Key。期望：弹出「创建 API Key」对话框，提交后弹窗展示完整 Key 与「复制 Key」按钮。新账号自带 **$1 免费额度**。完整流程见[快速开始](/docs/cloud/services/model/quickstart)。
* **Node.js 18 或更高**（`node --version` 检查）。
* **安装 OpenCode**：

  ```bash
  npm install -g opencode-ai
  ```

  期望：`opencode --version` 输出版本号（本页以 1.19.0 为准）。若 npm 提示平台包问题，按提示补装对应平台包（Linux x64 为 `npm install -g opencode-linux-x64`）。

## 配置 [#配置]

**第 1 步：设置密钥环境变量**

```bash
export PRAXIS_API_KEY=sk-praxis-你的Key
```

想持久化就把这行加进 `~/.bashrc` 或 `~/.zshrc`。Windows PowerShell：`$env:PRAXIS_API_KEY="你的Key"`。

期望：`echo $PRAXIS_API_KEY` 输出你的 Key（PowerShell 用 `echo $env:PRAXIS_API_KEY`）。

**第 2 步：在项目里声明 provider**

进入你的代码项目目录，创建 `opencode.json`：

```json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "praxis": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Praxis",
      "options": {
        "baseURL": "https://api.deepraxis.ai/openai/v1",
        "apiKey": "{env:PRAXIS_API_KEY}"
      },
      "models": {
        "deepseek-flash": {}
      }
    }
  },
  "model": "praxis/deepseek-flash"
}
```

三处说明：

* `npm` 指定 OpenCode 用 `@ai-sdk/openai-compatible` 驱动对话——OpenCode 的 provider 体系建立在 AI SDK 之上，首次运行会自动装驱动。
* `apiKey` 用 `{env:PRAXIS_API_KEY}` 引用环境变量——密钥不落文件。
* 模型以 `provider/模型ID` 的命名空间引用；`deepseek-flash` 是平台示例模型。

期望：文件保存即生效。

<img alt="终端里查看 opencode.json 的实际内容" src="__img0" />

## 验证 [#验证]

在项目目录里运行：

```bash
opencode run "用中文回复四个字：连接成功"
```

期望：末行为模型回复 `连接成功`（其前有一行会话标题，如 `> build · deepseek-flash`）——**收到回复即接入成功**。去掉 `run` 直接运行 `opencode`，进入交互式终端界面。

<img alt="终端运行 opencode run 的真实输出" src="__img1" />

也可以在命令行完成等价验证。以下命令为 macOS / Linux / WSL（bash）写法；Windows PowerShell 用户：上面的 `opencode run` 已成功即可跳过；如需命令行验证，先执行 `$env:PRAXIS_API_KEY="你的Key"`，用 `curl.exe`（PowerShell 的 `curl` 是别名，语法不同），并把命令并成一行（去掉行尾 `\`）。

```bash
export PRAXIS_API_KEY=sk-praxis-你的Key
```

```bash
curl https://api.deepraxis.ai/openai/v1/chat/completions \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "deepseek-flash", "messages": [{"role": "user", "content": "你好"}]}' \
  -w '\nHTTP %{http_code}\n'
```

期望：HTTP 200 即接入成功，`choices[0].message.content` 是回复文本（响应出现 `reasoning` / `reasoning_details` 字段也正常——推理模型的思维链）。

最后看一眼 [控制台 → 用量与费用](https://console.deepraxis.ai/usage)：刚才的调用已经记在账上——每一次调用都有账、可追溯。用量页默认按资源聚合展示，点「查看用量明细」或某资源行可逐笔核对。

## 常见问题 [#常见问题]

| 症状                                                 | 原因                               | 解法                                                                              |
| -------------------------------------------------- | -------------------------------- | ------------------------------------------------------------------------------- |
| 401 / Missing authentication                       | 密钥未导出，或 `apiKey` 没用 `{env:…}` 引用 | 先 `echo $PRAXIS_API_KEY` 检查；确认 `apiKey` 写的是 `{env:PRAXIS_API_KEY}`              |
| 报 `EACCES`（mkdir `~/.local/share` 或 `~/.config` 等） | OpenCode 需要可写的用户数据目录，当前环境不可写     | 把 `XDG_DATA_HOME`/`XDG_CONFIG_HOME`/`XDG_STATE_HOME`/`XDG_CACHE_HOME` 指向可写目录后重试 |
| 报平台包安装失败                                           | npm 没装对平台的二进制包                   | 按报错提示补装（Linux x64 为 `opencode-linux-x64`）                                       |
| 404 / 路径不存在                                        | `baseURL` 写错                     | 必须是 `https://api.deepraxis.ai/openai/v1`（以 `/openai/v1` 结尾）                     |
| 模型不存在                                              | 模型 ID 与目录不一致                     | 到[控制台 → 模型 → 模型目录](https://console.deepraxis.ai/models)复制确切 ID                  |

## 进阶 [#进阶]

* **查这次对话花了多少钱**：[控制台 → 用量与费用](https://console.deepraxis.ai/usage)，按次计费、无闲置费
* **换模型**：在 `models` 里加目录中的其他 ID（如 `claude-opus-5`），并把 `model` 改成 `praxis/<新ID>`
* **在项目里用**：交互模式能读文件、改代码、执行命令，敏感动作会先征求你的确认

## 相关食谱 [#相关食谱]

* [Claude Code](/docs/cookbook/coding-agents/claude-code) · [Codex](/docs/cookbook/coding-agents/codex)（姊妹篇）
* 偏好 SDK 编程？看 [Vercel AI SDK](/docs/cookbook/sdk/vercel-ai-sdk)（OpenCode 的 provider 体系同源）

# Kilo Code

|      |                              |
| ---- | ---------------------------- |
| 支持协议 | OpenAI 兼容                    |
| 备注   | 自动从 /openai/v1/models 拉取模型列表 |

## 前提 [#前提]

一个 API Key（见[快速开始](/docs/cloud/services/model/quickstart)）。

## 配置 [#配置]

（待补充：在 Kilo Code 中填入 `https://api.deepraxis.ai` 与 API Key 的步骤，配截图 / 30 秒视频。）

## 验证 [#验证]

（待补充：接入成功的界面长什么样。）

## 常见问题 [#常见问题]

（待补充：模型 id 怎么填、流式、国内网络。）

# Roo Code

|      |           |
| ---- | --------- |
| 支持协议 | OpenAI 兼容 |
| 备注   | —         |

## 前提 [#前提]

一个 API Key（见[快速开始](/docs/cloud/services/model/quickstart)）。

## 配置 [#配置]

（待补充：在 Roo Code 中填入 `https://api.deepraxis.ai` 与 API Key 的步骤，配截图 / 30 秒视频。）

## 验证 [#验证]

（待补充：接入成功的界面长什么样。）

## 常见问题 [#常见问题]

（待补充：模型 id 怎么填、流式、国内网络。）

# Gemini CLI

|      |                          |
| ---- | ------------------------ |
| 支持协议 | Google (generateContent) |
| 备注   | —                        |

## 前提 [#前提]

一个 API Key（见[快速开始](/docs/cloud/services/model/quickstart)）。

## 配置 [#配置]

（待补充：在 Gemini CLI 中填入 `https://api.deepraxis.ai` 与 API Key 的步骤，配截图 / 30 秒视频。）

## 验证 [#验证]

（待补充：接入成功的界面长什么样。）

## 常见问题 [#常见问题]

（待补充：模型 id 怎么填、流式、国内网络。）

# Kimi Code

|      |           |
| ---- | --------- |
| 支持协议 | OpenAI 兼容 |
| 备注   | —         |

## 前提 [#前提]

一个 API Key（见[快速开始](/docs/cloud/services/model/quickstart)）。

## 配置 [#配置]

（待补充：在 Kimi Code 中填入 `https://api.deepraxis.ai` 与 API Key 的步骤，配截图 / 30 秒视频。）

## 验证 [#验证]

（待补充：接入成功的界面长什么样。）

## 常见问题 [#常见问题]

（待补充：模型 id 怎么填、流式、国内网络。）

# Qwen Code

|      |                                   |
| ---- | --------------------------------- |
| 支持协议 | OpenAI 兼容                         |
| 备注   | Gemini CLI 分支，走 OPENAI\_BASE\_URL |

## 前提 [#前提]

一个 API Key（见[快速开始](/docs/cloud/services/model/quickstart)）。

## 配置 [#配置]

（待补充：在 Qwen Code 中填入 `https://api.deepraxis.ai` 与 API Key 的步骤，配截图 / 30 秒视频。）

## 验证 [#验证]

（待补充：接入成功的界面长什么样。）

## 常见问题 [#常见问题]

（待补充：模型 id 怎么填、流式、国内网络。）

# AI IDE



# Trae

|      |                   |
| ---- | ----------------- |
| 支持协议 | OpenAI 兼容（国内版待核实） |
| 备注   | 字节；自定义模型入口待核实     |

## 前提 [#前提]

一个 API Key（见[快速开始](/docs/cloud/services/model/quickstart)）。

## 配置 [#配置]

（待补充：在 Trae 中填入 `https://api.deepraxis.ai` 与 API Key 的步骤，配截图 / 30 秒视频。）

## 验证 [#验证]

（待补充：接入成功的界面长什么样。）

## 常见问题 [#常见问题]

（待补充：模型 id 怎么填、流式、国内网络。）

# WorkBuddy / CodeBuddy

|      |               |
| ---- | ------------- |
| 支持协议 | 待核实           |
| 备注   | 腾讯；自定义模型入口待核实 |

## 前提 [#前提]

一个 API Key（见[快速开始](/docs/cloud/services/model/quickstart)）。

## 配置 [#配置]

（待补充：在 WorkBuddy / CodeBuddy 中填入 `https://api.deepraxis.ai` 与 API Key 的步骤，配截图 / 30 秒视频。）

## 验证 [#验证]

（待补充：接入成功的界面长什么样。）

## 常见问题 [#常见问题]

（待补充：模型 id 怎么填、流式、国内网络。）

# Cursor

|      |                          |
| ---- | ------------------------ |
| 支持协议 | OpenAI 兼容                |
| 备注   | Override OpenAI Base URL |

## 前提 [#前提]

一个 API Key（见[快速开始](/docs/cloud/services/model/quickstart)）。

## 配置 [#配置]

（待补充：在 Cursor 中填入 `https://api.deepraxis.ai` 与 API Key 的步骤，配截图 / 30 秒视频。）

## 验证 [#验证]

（待补充：接入成功的界面长什么样。）

## 常见问题 [#常见问题]

（待补充：模型 id 怎么填、流式、国内网络。）

# Windsurf

|      |           |
| ---- | --------- |
| 支持协议 | OpenAI 兼容 |
| 备注   | —         |

## 前提 [#前提]

一个 API Key（见[快速开始](/docs/cloud/services/model/quickstart)）。

## 配置 [#配置]

（待补充：在 Windsurf 中填入 `https://api.deepraxis.ai` 与 API Key 的步骤，配截图 / 30 秒视频。）

## 验证 [#验证]

（待补充：接入成功的界面长什么样。）

## 常见问题 [#常见问题]

（待补充：模型 id 怎么填、流式、国内网络。）

# 通义灵码

|      |     |
| ---- | --- |
| 支持协议 | 待核实 |
| 备注   | 阿里  |

## 前提 [#前提]

一个 API Key（见[快速开始](/docs/cloud/services/model/quickstart)）。

## 配置 [#配置]

（待补充：在 通义灵码 中填入 `https://api.deepraxis.ai` 与 API Key 的步骤，配截图 / 30 秒视频。）

## 验证 [#验证]

（待补充：接入成功的界面长什么样。）

## 常见问题 [#常见问题]

（待补充：模型 id 怎么填、流式、国内网络。）

# 聊天客户端



# Cherry Studio

把 Praxis 接入 Cherry Studio，用一个 Key 聊所有模型——全程不写代码。

每一步都标了**期望结果**：照做即可，也可以把本页直接交给能操作电脑的 AI 助手，让它替你完成配置与验证。

## 你将完成 [#你将完成]

* 在 Cherry Studio 里直接使用 Praxis 的模型对话
* 完成标志：向 `deepseek-flash` 发送「你好」并收到回复
* 预计耗时：**5 分钟**（不含下载安装）
* 支持协议：OpenAI 兼容（本页路线）/ Anthropic 兼容（见[进阶](#进阶)）

## 前提 [#前提]

开始前逐项确认：

* **一个 Praxis API Key**（`sk-praxis-` 开头）。没有就到 [控制台 → API Keys](https://console.deepraxis.ai/keys) 创建：点「创建 Key」，弹窗中**名称必填*&#x2A;，有效期默认 90 天（可改永久），点创建后立即复制保存；之后也随时可在 Key 列表行点「复制」重新获取完整 Key。新账号自带 **$1 免费额度**，跑完本页绰绰有余。完整流程见[快速开始](/docs/cloud/services/model/quickstart)。
* **Cherry Studio 已安装**。从[官网](https://cherry-ai.com)下载（自动匹配系统），或到 [GitHub Releases](https://github.com/CherryHQ/cherry-studio/releases) 手选：Windows 选 `-setup.exe`（安装版）或 `-portable.exe`（免安装）；macOS 选 `.dmg`（Intel 芯片选 x64，Apple 芯片选 arm64）；Linux 选 `.AppImage`（下载后 `chmod +x` 加执行权限再运行）。
* **首次启动**：先选语言（默认 English，可切中文），欢迎页点「稍后设置」跳过登录即可使用。
* 本页以 v2.1.4 界面为准，菜单位置可能随版本微调。

## 配置 [#配置]

**第 1 步：打开模型服务设置**

主界面左下角的齿轮图标「设置」，再点左侧菜单「模型服务」。

期望：右侧出现提供商列表（OpenAI、硅基流动、智谱开放平台……）。

<img alt="设置入口：左下角齿轮进入设置，左侧菜单选「模型服务」，右侧是提供商列表" src="__img0" />

**第 2 步：添加服务商，一次填齐名称、密钥、地址**

点提供商列表底部的「添加服务商」按钮，弹窗「添加自定义提供商」里填三处：

| 字段                | 填什么                                  |
| ----------------- | ------------------------------------ |
| 提供商名称（必填）         | `Praxis`（显示名，可任取）                    |
| API 密钥            | `sk-praxis-` 开头的你的 Key               |
| 端点设置 → OpenAI 根地址 | `https://api.deepraxis.ai/openai/v1` |

地址必须**以 `/v1` 结尾**——弹窗会实时显示「请求路径」预览，看到 `…/openai/v1/chat/completions` 即为正确。填完点「添加」。

期望：提供商列表末尾出现 Praxis 条目，卡片上密钥显示为掩码。

<img alt="添加自定义提供商弹窗：名称填 Praxis，密钥与 OpenAI 根地址已填，下方显示请求路径预览" src="__img1" />

**第 3 步：添加模型**

添加成功后，Cherry Studio 会**自动拉取 Praxis 的模型目录**并弹出「选择模型」对话框。在列表中勾选 `deepseek-flash`——平台示例模型：便宜、快、中英文都好——点「添加所选模型」，应用会自动检测并启用。

期望：模型出现在 Praxis 的模型列表中，启用开关为开。

<img alt="选择模型对话框：自动拉取的模型目录中勾选 deepseek-flash" src="__img2" />

拉取失败或列表为空时，点 Praxis 卡片上的「手动添加模型」，模型 ID 填 `deepseek-flash`，其余留空即可。

## 验证 [#验证]

回到对话页，点**右上角的模型选择器**，切到 Praxis 下的 `deepseek-flash`，发送「你好」。

期望：几秒内收到一段中文回复——**收到回复即接入成功**。

<img alt="对话页收到第一条回复：模型选择器显示 DeepSeek V4.1 Flash | Praxis" src="__img3" />

也可以在命令行完成等价验证。先设置变量（不然照抄 curl 会得到 401）：

```bash
export PRAXIS_API_KEY=sk-praxis-你的Key
```

以下命令为 macOS / Linux / WSL（bash）写法。Windows PowerShell 用户：界面已收到回复即接入成功，可跳过；如需命令行验证，先执行 `$env:PRAXIS_API_KEY="你的Key"`，再把 curl 写成一行（去掉每行末尾的 `\`）。

```bash
curl https://api.deepraxis.ai/openai/v1/chat/completions \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "deepseek-flash", "messages": [{"role": "user", "content": "你好"}]}'
```

期望：返回 HTTP 200，`choices[0].message.content` 是一段中文回复（响应里出现 `reasoning` 字段也正常——那是推理模型的思维链）。返回 `401` 是密钥问题，报「模型不存在」是 ID 拼写问题——对照下方常见问题。

最后看一眼 [控制台 → 用量与费用](https://console.deepraxis.ai/usage)：刚才的调用已经记在账上——每一次调用都有账、可追溯。

## 常见问题 [#常见问题]

| 症状                                  | 原因                 | 解法                                                                                                      |
| ----------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------- |
| 提示无效令牌 / 401                        | 密钥复制不完整，或 Key 已被吊销 | 重新完整复制（注意 `sk-praxis-` 前缀）；仍失败就到[控制台](https://console.deepraxis.ai/keys)重建一个                            |
| 首次发消息报「需要通过本地 API Gateway 桥接，网关已禁用」 | 本地网关默认关闭           | 按弹窗提示点「启用」，再重发一次                                                                                        |
| 模型列表拉取失败或为空                         | API 地址路径不对         | 地址必须是 `https://api.deepraxis.ai/openai/v1`（以 `/v1` 结尾，弹窗的请求路径预览可自查）；先跑上面 curl 分辨是网络还是配置问题；拉取不成用「手动添加模型」 |
| 报「模型不存在」                            | 模型 ID 与目录不一致       | 到[控制台 → 模型](https://console.deepraxis.ai/models)复制确切 ID                                                 |
| 请求超时 / 无响应                          | 本地网络环境             | 换网络或代理后重试；若 curl 同样超时，则是网络问题，与配置无关                                                                      |

## 进阶 [#进阶]

* **查这段对话花了多少钱**：[控制台 → 用量与费用](https://console.deepraxis.ai/usage)，按次计费、无闲置费
* **换模型**：模型列表里随时勾选添加其他模型，对话页随时切换。`deepseek-flash` 是滚动入口，始终指向最新一代 Flash（随官方更新换代）；需要固定版本时改用 `deepseek-v4-flash`（版本快照）
* **用 Anthropic 协议接入**：在第 2 步弹窗的端点设置里改填 **Anthropic** 根地址 `https://api.deepraxis.ai/anthropic`（不加 `/v1`，客户端自动拼 `/v1/messages`，弹窗预览可核对），其余步骤相同

## 相关食谱 [#相关食谱]

* [Chatbox](/docs/cookbook/chat-clients/chatbox) · [LobeHub](/docs/cookbook/chat-clients/lobehub) · [Open WebUI](/docs/cookbook/chat-clients/open-webui)
* 从其他服务迁移过来？看[迁移指南](/docs/cookbook/migration)

# Chatbox

|      |           |
| ---- | --------- |
| 支持协议 | OpenAI 兼容 |
| 备注   | —         |

## 前提 [#前提]

一个 API Key（见[快速开始](/docs/cloud/services/model/quickstart)）。

## 配置 [#配置]

（待补充：在 Chatbox 中填入 `https://api.deepraxis.ai` 与 API Key 的步骤，配截图 / 30 秒视频。）

## 验证 [#验证]

（待补充：接入成功的界面长什么样。）

## 常见问题 [#常见问题]

（待补充：模型 id 怎么填、流式、国内网络。）

# ChatWise

|      |           |
| ---- | --------- |
| 支持协议 | OpenAI 兼容 |
| 备注   | —         |

## 前提 [#前提]

一个 API Key（见[快速开始](/docs/cloud/services/model/quickstart)）。

## 配置 [#配置]

（待补充：在 ChatWise 中填入 `https://api.deepraxis.ai` 与 API Key 的步骤，配截图 / 30 秒视频。）

## 验证 [#验证]

（待补充：接入成功的界面长什么样。）

## 常见问题 [#常见问题]

（待补充：模型 id 怎么填、流式、国内网络。）

# LobeHub

|      |           |
| ---- | --------- |
| 支持协议 | OpenAI 兼容 |
| 备注   | —         |

## 前提 [#前提]

一个 API Key（见[快速开始](/docs/cloud/services/model/quickstart)）。

## 配置 [#配置]

（待补充：在 LobeHub 中填入 `https://api.deepraxis.ai` 与 API Key 的步骤，配截图 / 30 秒视频。）

## 验证 [#验证]

（待补充：接入成功的界面长什么样。）

## 常见问题 [#常见问题]

（待补充：模型 id 怎么填、流式、国内网络。）

# Open WebUI

|      |           |
| ---- | --------- |
| 支持协议 | OpenAI 兼容 |
| 备注   | —         |

## 前提 [#前提]

一个 API Key（见[快速开始](/docs/cloud/services/model/quickstart)）。

## 配置 [#配置]

（待补充：在 Open WebUI 中填入 `https://api.deepraxis.ai` 与 API Key 的步骤，配截图 / 30 秒视频。）

## 验证 [#验证]

（待补充：接入成功的界面长什么样。）

## 常见问题 [#常见问题]

（待补充：模型 id 怎么填、流式、国内网络。）

# NextChat

|      |           |
| ---- | --------- |
| 支持协议 | OpenAI 兼容 |
| 备注   | —         |

## 前提 [#前提]

一个 API Key（见[快速开始](/docs/cloud/services/model/quickstart)）。

## 配置 [#配置]

（待补充：在 NextChat 中填入 `https://api.deepraxis.ai` 与 API Key 的步骤，配截图 / 30 秒视频。）

## 验证 [#验证]

（待补充：接入成功的界面长什么样。）

## 常见问题 [#常见问题]

（待补充：模型 id 怎么填、流式、国内网络。）

# 智能体与工作流平台



# Dify

|      |                    |
| ---- | ------------------ |
| 支持协议 | OpenAI 兼容 provider |
| 备注   | —                  |

## 前提 [#前提]

一个 API Key（见[快速开始](/docs/cloud/services/model/quickstart)）。

## 配置 [#配置]

（待补充：在 Dify 中填入 `https://api.deepraxis.ai` 与 API Key 的步骤，配截图 / 30 秒视频。）

## 验证 [#验证]

（待补充：接入成功的界面长什么样。）

## 常见问题 [#常见问题]

（待补充：模型 id 怎么填、流式、国内网络。）

# Coze

|      |                    |
| ---- | ------------------ |
| 支持协议 | OpenAI 兼容 provider |
| 备注   | —                  |

## 前提 [#前提]

一个 API Key（见[快速开始](/docs/cloud/services/model/quickstart)）。

## 配置 [#配置]

（待补充：在 Coze 中填入 `https://api.deepraxis.ai` 与 API Key 的步骤，配截图 / 30 秒视频。）

## 验证 [#验证]

（待补充：接入成功的界面长什么样。）

## 常见问题 [#常见问题]

（待补充：模型 id 怎么填、流式、国内网络。）

# n8n

|      |             |
| ---- | ----------- |
| 支持协议 | OpenAI 兼容节点 |
| 备注   | —           |

## 前提 [#前提]

一个 API Key（见[快速开始](/docs/cloud/services/model/quickstart)）。

## 配置 [#配置]

（待补充：在 n8n 中填入 `https://api.deepraxis.ai` 与 API Key 的步骤，配截图 / 30 秒视频。）

## 验证 [#验证]

（待补充：接入成功的界面长什么样。）

## 常见问题 [#常见问题]

（待补充：模型 id 怎么填、流式、国内网络。）

# FastGPT

|      |                    |
| ---- | ------------------ |
| 支持协议 | OpenAI 兼容 provider |
| 备注   | —                  |

## 前提 [#前提]

一个 API Key（见[快速开始](/docs/cloud/services/model/quickstart)）。

## 配置 [#配置]

（待补充：在 FastGPT 中填入 `https://api.deepraxis.ai` 与 API Key 的步骤，配截图 / 30 秒视频。）

## 验证 [#验证]

（待补充：接入成功的界面长什么样。）

## 常见问题 [#常见问题]

（待补充：模型 id 怎么填、流式、国内网络。）

# SDK 与框架



# OpenAI SDK

把 Praxis 接入 OpenAI 官方 SDK——已有一切 OpenAI 代码不用换库，只改一个 `baseURL`。本页 Node 与 Python 均实测（其余语言同形）。

每一步都标了**期望结果**：照做即可，也可以把本页直接交给能操作电脑的 AI 助手，让它替你完成安装、运行与验证。

## 你将完成 [#你将完成]

* 用 OpenAI SDK 调 Praxis 的模型，拿到回复与用量
* 完成标志：`hello.mjs` 打印中文回复与 `usage`，`stream.mjs` 逐字打印回复
* 预计耗时：**3 分钟**（不含 Node.js 安装）
* 支持协议：OpenAI 兼容（`/openai/v1`）

## 前提 [#前提]

开始前逐项确认：

* **一个 Praxis API Key**（`sk-praxis-` 开头）。没有就到 [控制台 → API Keys](https://console.deepraxis.ai/keys&#x29; 创建：点「创建 Key」，名称必填，有效期默认 90 天（可改永久），创建后立即复制保存；之后也随时可在 Key 列表行点复制图标重新获取完整 Key。新账号自带 **$1 免费额度**。完整流程见[快速开始](/docs/cloud/services/model/quickstart)。
* **Node.js 18 或更高**（`node --version` 检查；用 [Bun](https://bun.sh) 亦可）。
* **安装 SDK**：在项目目录里

  ```bash
  npm install openai
  ```

  期望：安装无报错，`node -e "require('openai')"` 不抛错。

## 第一个请求 [#第一个请求]

新建 `hello.mjs`，原样粘贴（把 Key 换成你的）：

```javascript
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.deepraxis.ai/openai/v1",
  apiKey: "sk-praxis-你的Key",
});

const completion = await client.chat.completions.create({
  model: "deepseek-flash",
  messages: [{ role: "user", content: "用一句话介绍你自己" }],
});

console.log(completion.choices[0].message.content);
console.log(completion.usage);
```

运行：

```bash
node hello.mjs
```

期望：打印一段中文回复，随后是 `usage` 对象——注意里面有 `cost` 字段，**这次调用花了多少钱直接给你算好**（平台按次计费，控制台[用量与费用](https://console.deepraxis.ai/usage)同口径）。

<img alt="终端运行示例脚本的真实输出" src="__img0" />

建议把 Key 放进环境变量而不是写进代码：`export PRAXIS_API_KEY=sk-praxis-…`（PowerShell：`$env:PRAXIS_API_KEY="…"`），然后 `apiKey: process.env.PRAXIS_API_KEY`。

## Python 版 [#python-版]

```bash
pip install openai
```

先设置环境变量 `export PRAXIS_API_KEY=sk-praxis-你的Key`（PowerShell：`$env:PRAXIS_API_KEY="你的Key"`），再新建 `hello.py`：

```python
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.deepraxis.ai/openai/v1",
    api_key=os.environ["PRAXIS_API_KEY"],
)

completion = client.chat.completions.create(
    model="deepseek-flash",
    messages=[{"role": "user", "content": "用一句话介绍你自己"}],
)

print(completion.choices[0].message.content)
print(completion.usage)
```

运行 `python3 hello.py`。期望：打印中文回复，随后是 `CompletionUsage`——其中 `cost` 字段直接给出本次费用。流式用法与 Node 同形（`stream=True` 后迭代 `delta.content`）。

<img alt="Python 版示例的真实输出" src="__img1" />

## 流式响应 [#流式响应]

新建 `stream.mjs`：

```javascript
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.deepraxis.ai/openai/v1",
  apiKey: process.env.PRAXIS_API_KEY,
});

const stream = await client.chat.completions.create({
  model: "glm-5.3-flash",
  messages: [{ role: "user", content: "用两句话解释什么是 API" }],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}
console.log();
```

期望：回复逐字打印、以换行收尾——这就是流式。示例用 `glm-5.3-flash`；流式支持按模型路由而异，个别路由可能暂未开放，详见下方常见问题。

<img alt="终端运行流式示例：回复逐字输出" src="__img2" />

## 常见问题 [#常见问题]

| 症状                       | 原因                  | 解法                                                      |
| ------------------------ | ------------------- | ------------------------------------------------------- |
| 401 / 无效令牌               | Key 复制不完整或未设进环境变量   | 重新完整复制（注意 `sk-praxis-` 前缀）；用 `echo $PRAXIS_API_KEY` 检查  |
| 400 `STREAMING_UNPROVEN` | 该模型暂未开放流式（逐路由开通，偶发） | 去掉 `stream: true`，或换个模型重试                               |
| 模型不存在                    | 模型 ID 与目录不一致        | 到[控制台 → 模型](https://console.deepraxis.ai/models)复制确切 ID |
| 连接超时                     | 本地网络                | 重试或换网络；也可先用下面的命令测网关连通（期望 200）                           |

连通性自检：

```bash
curl -sS https://api.deepraxis.ai/openai/v1/models \
  -H "Authorization: Bearer $PRAXIS_API_KEY" -o /dev/null -w "%{http_code}"
```

期望输出 `200`。

## 进阶 [#进阶]

* **查这次调用花了多少钱**：非流式调用的 `usage.cost` 直接返回费用，无需自行按 token 换算；流式的费用在最后一个 chunk 的 `usage` 里（该 chunk 的 `choices` 为空、含 `cost`）——`stream_options: { include_usage: true }` 可加可不加，平台两种情况都会回；[控制台 → 用量与费用](https://console.deepraxis.ai/usage)有逐笔明细
* **列出可用模型**：`await client.models.list()`——和[控制台 → 模型](https://console.deepraxis.ai/models)同源
* **换模型**：改 `model` 字段即可；`deepseek-flash` 是滚动入口始终指向最新一代 Flash，`deepseek-v4-flash` 是固定版本快照

## 相关食谱 [#相关食谱]

* [Anthropic SDK](/docs/cookbook/sdk/anthropic-sdk)（Anthropic 协议姊妹篇）· [LangChain](/docs/cookbook/sdk/langchain) · [Vercel AI SDK](/docs/cookbook/sdk/vercel-ai-sdk)
* 不想写代码？看 [Cherry Studio](/docs/cookbook/chat-clients/cherry-studio) · [Codex](/docs/cookbook/coding-agents/codex)

# Anthropic SDK

把 Praxis 接入 Anthropic 官方 SDK——已有一切 Anthropic 代码不用换库，只改一个 `baseURL`。本页 Node 与 Python 均实测（其余语言同形）。

每一步都标了**期望结果**：照做即可，也可以把本页直接交给能操作电脑的 AI 助手，让它替你完成安装、运行与验证。

## 你将完成 [#你将完成]

* 用 Anthropic SDK 调 Praxis 的模型，拿到回复与用量
* 完成标志：`hello.mjs` 打印中文回复与 `usage`，`stream.mjs` 逐字打印回复
* 预计耗时：**3 分钟**（不含 Node.js 安装）
* 支持协议：Anthropic 兼容（`/anthropic`）

## 前提 [#前提]

开始前逐项确认：

* **一个 Praxis API Key**（`sk-praxis-` 开头）。没有就到 [控制台 → API Keys](https://console.deepraxis.ai/keys&#x29; 创建：点「创建 Key」，名称必填，有效期默认 90 天（可改永久）；创建成功弹窗会展示完整 Key 并带「复制 Key」，关闭后列表只显示掩码，随时可点行内复制图标重新获取完整 Key。新账号自带 **$1 免费额度**。完整流程见[快速开始](/docs/cloud/services/model/quickstart)。
* **Node.js 18 或更高**（`node --version` 检查；用 [Bun](https://bun.sh) 亦可）。
* **安装 SDK**——注意包名是 `@anthropic-ai/sdk`（npm 上的 `anthropic` 是同名的占位包，不是它）：

  ```bash
  npm install @anthropic-ai/sdk
  ```

  期望：安装无报错。

## 第一个请求 [#第一个请求]

先把 Key 放进环境变量（`export PRAXIS_API_KEY=sk-praxis-…`；PowerShell：`$env:PRAXIS_API_KEY="…"`），再新建 `hello.mjs`：

```javascript
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  baseURL: "https://api.deepraxis.ai/anthropic",
  apiKey: "sk-praxis-你的Key",
});

const message = await client.messages.create({
  model: "deepseek-flash",
  max_tokens: 256,
  messages: [{ role: "user", content: "用一句话介绍你自己" }],
});

console.log(message.content.find((b) => b.type === "text")?.text);
console.log(message.usage);
```

运行：

```bash
node hello.mjs
```

期望：打印一段中文回复，随后是 `usage`——至少包含 `input_tokens` / `output_tokens&#x60;，SDK 还会附带缓存、服务分层等字段。两处注意：**`max_tokens` 必填**（Anthropic 协议的要求）；`content` 是块数组，取 `type` 为 `text` 的块是回复文本——推理模型前面可能先带 `thinking` 块。

<img alt="终端运行示例脚本的真实输出" src="__img0" />

## Python 版 [#python-版]

```bash
pip install anthropic
```

新建 `hello.py`：

```python
import os
from anthropic import Anthropic

client = Anthropic(
    base_url="https://api.deepraxis.ai/anthropic",
    api_key=os.environ["PRAXIS_API_KEY"],
)

message = client.messages.create(
    model="deepseek-flash",
    max_tokens=256,
    messages=[{"role": "user", "content": "用一句话介绍你自己"}],
)

print(next(b.text for b in message.content if b.type == "text"))
print(message.usage)
```

运行 `python3 hello.py`。期望：打印中文回复，随后是 `Usage`——同样必填 `max_tokens`，`content` 是块数组。流式用 `client.messages.stream(...)` 上下文管理器，与 Node 同形。

<img alt="Python 版示例的真实输出" src="__img1" />

## 流式响应 [#流式响应]

新建 `stream.mjs`：

```javascript
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  baseURL: "https://api.deepraxis.ai/anthropic",
  apiKey: process.env.PRAXIS_API_KEY,
});

const stream = client.messages.stream({
  model: "deepseek-flash",
  max_tokens: 256,
  messages: [{ role: "user", content: "用两句话解释什么是 API" }],
});

for await (const event of stream) {
  if (event.type === "content_block_delta" && event.delta.type === "text_delta") {
    process.stdout.write(event.delta.text);
  }
}
console.log();
```

期望：回复逐字打印、以换行收尾。流式支持按模型路由而异，个别路由可能暂未开放（报 `STREAMING_UNPROVEN` 时去掉流式或换模型重试）。

<img alt="终端运行流式示例：回复逐字输出" src="__img2" />

## 常见问题 [#常见问题]

| 症状                                                                             | 原因                | 解法                                                      |
| ------------------------------------------------------------------------------ | ----------------- | ------------------------------------------------------- |
| 导入名为 `anthropic` 的包后运行失败（报错指向 `node_modules/anthropic/index.js` 缺失或 `main` 无效） | 装到了 npm 上的同名占位包   | 卸掉重装正主：卸载 `anthropic` 后安装 `@anthropic-ai/sdk`           |
| 401 / 无效令牌                                                                     | Key 复制不完整或未设进环境变量 | 重新完整复制（注意 `sk-praxis-` 前缀）；用 `echo $PRAXIS_API_KEY` 检查  |
| 400 提示缺 `max_tokens`                                                           | Anthropic 协议必填该参数 | 在 `messages.create` 里加上 `max_tokens`（如 256）             |
| 400 `STREAMING_UNPROVEN`                                                       | 该模型路由暂未开放流式       | 去掉流式用普通调用，或换个模型重试                                       |
| 模型不存在                                                                          | 模型 ID 与目录不一致      | 到[控制台 → 模型](https://console.deepraxis.ai/models)复制确切 ID |

## 进阶 [#进阶]

* **查这次调用花了多少钱**：非流式 `message.usage.cost`（Python SDK）直接返回费用；流式在 `message_delta` 事件的 `usage.cost` 上（`get_final_message().usage` 不带该字段）。JS SDK 的 `Usage` 类型不声明 cost（运行时字段仍在，`as any` 可读），Node 用户也可看[控制台 → 用量与费用](https://console.deepraxis.ai/usage)逐笔明细，或走 [OpenAI SDK](/docs/cookbook/sdk/openai-sdk)
* **换模型**：改 `model` 字段即可，Claude 系旗舰填 `claude-opus-5`；`deepseek-flash` 是滚动入口始终指向最新一代 Flash
* **拿思维链**：推理模型的 `content` 里 `type` 为 `thinking` 的块即思维链，按需读取

## 相关食谱 [#相关食谱]

* [OpenAI SDK](/docs/cookbook/sdk/openai-sdk)（OpenAI 协议姊妹篇）· [LangChain](/docs/cookbook/sdk/langchain) · [Vercel AI SDK](/docs/cookbook/sdk/vercel-ai-sdk)
* 不想写代码？看 [Cherry Studio](/docs/cookbook/chat-clients/cherry-studio) · [Claude Code](/docs/cookbook/coding-agents/claude-code)

# Vercel AI SDK

把 Praxis 接入 [Vercel AI SDK](https://ai-sdk.dev)——React/Vue/Svelte 里做 AI 应用的事实标准库。自定义 provider 两个参数即接通，`generateText` / `streamText` 及全家能力照常用。本页以 Node 实测。

每一步都标了**期望结果**：照做即可，也可以把本页直接交给能操作电脑的 AI 助手，让它替你完成安装、运行与验证。

## 你将完成 [#你将完成]

* 用 AI SDK 的 `generateText` / `streamText` 调 Praxis 的模型
* 完成标志：`hello.mjs` 打印中文回复与 `usage`，`stream.mjs` 逐字打印回复
* 预计耗时：**3–5 分钟**（不含 Node.js 安装）
* 支持协议：OpenAI 兼容（`/openai/v1`）

## 前提 [#前提]

开始前逐项确认：

* **一个 Praxis API Key**（`sk-praxis-` 开头）。没有就到 [控制台 → API Keys](https://console.deepraxis.ai/keys&#x29; 创建：点「创建 Key」，名称必填，有效期默认 90 天（可改永久）；创建成功弹窗会展示完整 Key 并带「复制 Key」，关闭后列表只显示掩码，随时可点行内复制图标重新获取完整 Key。期望：弹出「创建 API Key」对话框，提交后弹窗展示完整 Key 与「复制 Key」按钮。新账号自带 **$1 免费额度**。完整流程见[快速开始](/docs/cloud/services/model/quickstart)。
* **Node.js 18 或更高**（`node --version` 检查；用 [Bun](https://bun.sh) 亦可）。
* **安装 SDK**：

  ```bash
  npm install ai @ai-sdk/openai
  ```

  期望：安装无报错。空目录直接装即可，无需先 `npm init`。

## 第一个请求 [#第一个请求]

先把 Key 放进环境变量（`export PRAXIS_API_KEY=sk-praxis-…`；PowerShell：`$env:PRAXIS_API_KEY="…"`），再新建 `hello.mjs`：

```javascript
import { createOpenAI } from "@ai-sdk/openai";
import { generateText } from "ai";

const praxis = createOpenAI({
  baseURL: "https://api.deepraxis.ai/openai/v1",
  apiKey: process.env.PRAXIS_API_KEY,
});

const { text, usage } = await generateText({
  model: praxis("deepseek-flash"),
  prompt: "用一句话介绍你自己",
});

console.log(text);
console.log(usage);
```

运行：

```bash
node hello.mjs
```

期望：打印一段中文回复，随后是 `usage` 对象——驼峰形态，含 `inputTokens` / `outputTokens` / `totalTokens` 与 `raw` 原始字段；推理模型的 `reasoningTokens` 在 `outputTokenDetails` 明细里。

<img alt="终端运行示例脚本的真实输出" src="__img0" />

## 流式响应 [#流式响应]

新建 `stream.mjs`：

```javascript
import { createOpenAI } from "@ai-sdk/openai";
import { streamText } from "ai";

const praxis = createOpenAI({
  baseURL: "https://api.deepraxis.ai/openai/v1",
  apiKey: process.env.PRAXIS_API_KEY,
});

const stream = streamText({
  model: praxis("deepseek-flash"),
  prompt: "用两句话解释什么是 API",
});

for await (const chunk of stream.textStream) {
  process.stdout.write(chunk);
}
console.log();
```

期望：回复逐字打印、以换行收尾。流式支持因模型及其上游通道而异，个别可能暂未开放（报 `STREAMING_UNPROVEN` 时去掉流式或换模型重试）。

<img alt="终端运行流式示例：回复逐字输出" src="__img1" />

## 常见问题 [#常见问题]

| 症状                       | 原因                           | 解法                                                             |
| ------------------------ | ---------------------------- | -------------------------------------------------------------- |
| 401 / 无效令牌               | Key 复制不完整或未设进环境变量            | 重新完整复制（注意 `sk-praxis-` 前缀）；用 `echo $PRAXIS_API_KEY` 检查         |
| 404 / 路径不存在              | `baseURL` 少了 `/openai/v1` 后缀 | 必须是 `https://api.deepraxis.ai/openai/v1`（以 `/v1` 结尾）           |
| 400 `STREAMING_UNPROVEN` | 该模型路由暂未开放流式                  | 去掉流式用 `generateText`，或换个模型重试                                   |
| 模型不存在                    | 模型 ID 与目录不一致                 | 到[控制台 → 模型 → 模型目录](https://console.deepraxis.ai/models)复制确切 ID |

## 进阶 [#进阶]

* **前端聊天组件**：AI SDK 的 `useChat` 等 React Hooks 与后端 `streamText` 天然配套（见 [AI SDK 官方文档](https://ai-sdk.dev)），provider 写法与本页相同
* **查这次调用花了多少钱**：AI SDK 的 `usage` 不带费用；用 [OpenAI SDK](/docs/cookbook/sdk/openai-sdk) 那条路 `usage.cost` 直接返回，或看[控制台 → 用量与费用](https://console.deepraxis.ai/usage)
* **换模型**：改 `praxis("…")` 里的模型 ID；`deepseek-flash` 是滚动入口始终指向最新一代 Flash

## 相关食谱 [#相关食谱]

* [OpenAI SDK](/docs/cookbook/sdk/openai-sdk) · [Anthropic SDK](/docs/cookbook/sdk/anthropic-sdk) · [LangChain](/docs/cookbook/sdk/langchain)
* 不想写代码？看 [Cherry Studio](/docs/cookbook/chat-clients/cherry-studio) · [Codex](/docs/cookbook/coding-agents/codex)

# LangChain

把 Praxis 接入 [LangChain](https://js.langchain.com)（JS/TS 版）——链、记忆、工具全家桶照常用，模型侧只改一个 `baseURL`。本页以 Node 实测。

每一步都标了**期望结果**：照做即可，也可以把本页直接交给能操作电脑的 AI 助手，让它替你完成安装、运行与验证。

## 你将完成 [#你将完成]

* 用 LangChain 的 `ChatOpenAI` 调 Praxis 的模型，拿到回复与用量
* 完成标志：`hello.mjs` 打印中文回复与用量，`stream.mjs` 逐字打印回复
* 预计耗时：**3–5 分钟**（不含 Node.js 安装）
* 支持协议：OpenAI 兼容（`/openai/v1`）

## 前提 [#前提]

开始前逐项确认：

* **一个 Praxis API Key**（`sk-praxis-` 开头）。没有就到 [控制台 → API Keys](https://console.deepraxis.ai/keys&#x29; 创建：点「创建 Key」，名称必填，有效期可选 30/60/90 天或永久，默认 90 天；创建成功弹窗会展示完整 Key 并带「复制 Key」，关闭后列表只显示掩码，随时可点行内复制图标重新获取完整 Key。期望：弹出「创建 API Key」对话框，提交后弹窗展示完整 Key 与「复制 Key」按钮。新账号自带 **$1 免费额度**。完整流程见[快速开始](/docs/cloud/services/model/quickstart)。
* **Node.js 18 或更高**（`node --version` 检查；用 [Bun](https://bun.sh) 亦可）。
* **安装 SDK**：

  ```bash
  npm install @langchain/openai
  ```

  期望：安装无报错。空目录直接装即可（npm 会在当前目录生成 package.json、package-lock.json 与 node\_modules）；需要链、提示词模板、输出解析器时再 `npm install langchain`。

## 第一个请求 [#第一个请求]

先把 Key 放进环境变量（`export PRAXIS_API_KEY=sk-praxis-…`；PowerShell：`$env:PRAXIS_API_KEY="…"`），再新建 `hello.mjs`：

```javascript
import { ChatOpenAI } from "@langchain/openai";

const model = new ChatOpenAI({
  model: "deepseek-flash",
  configuration: {
    baseURL: "https://api.deepraxis.ai/openai/v1",
    apiKey: process.env.PRAXIS_API_KEY,
  },
});

const res = await model.invoke("用一句话介绍你自己");
console.log(res.content);
console.log(res.usage_metadata);
```

运行：

```bash
node hello.mjs
```

期望：打印一段中文回复，随后是用量对象（`input_tokens` / `output_tokens` / `total_tokens`；推理 token 数见 `output_token_details.reasoning`）。注意与 OpenAI 官方 SDK 的差别：**地址与密钥写在 `configuration` 嵌套对象里**，不是顶层字段。

<img alt="终端运行示例脚本的真实输出" src="__img0" />

## 流式响应 [#流式响应]

新建 `stream.mjs`：

```javascript
import { ChatOpenAI } from "@langchain/openai";

const model = new ChatOpenAI({
  model: "deepseek-flash",
  configuration: {
    baseURL: "https://api.deepraxis.ai/openai/v1",
    apiKey: process.env.PRAXIS_API_KEY,
  },
});

const stream = await model.stream("用两句话解释什么是 API");
for await (const chunk of stream) {
  process.stdout.write(chunk.content);
}
console.log();
```

期望：回复逐字打印、以换行收尾。流式支持因模型及其上游通道而异，个别可能暂未开放（报 `STREAMING_UNPROVEN` 时去掉流式或换模型重试）。

<img alt="终端运行流式示例：回复逐字输出" src="__img1" />

## 常见问题 [#常见问题]

| 症状                       | 原因                           | 解法                                                             |
| ------------------------ | ---------------------------- | -------------------------------------------------------------- |
| 401 / 无效令牌               | Key 复制不完整或未设进环境变量            | 重新完整复制（注意 `sk-praxis-` 前缀）；用 `echo $PRAXIS_API_KEY` 检查         |
| 404 / 路径不存在              | `baseURL` 少了 `/openai/v1` 后缀 | 必须是 `https://api.deepraxis.ai/openai/v1`（以 `/v1` 结尾）           |
| 配置不生效                    | 地址写在了顶层而不是 `configuration` 里 | 移进 `configuration: { baseURL, apiKey }`                        |
| 400 `STREAMING_UNPROVEN` | 该模型暂未开放流式                    | 改用 `invoke`，或换个模型重试                                            |
| 模型不存在                    | 模型 ID 与目录不一致                 | 到[控制台 → 模型 → 模型目录](https://console.deepraxis.ai/models)复制确切 ID |

## 进阶 [#进阶]

* **链式调用**：`model.pipe(...)` 接提示词模板、输出解析器即成链——Praxis 侧无需任何额外配置
* **查这次调用花了多少钱**：LangChain 的用量不带费用；用 [OpenAI SDK](/docs/cookbook/sdk/openai-sdk) 那条路 `usage.cost` 直接返回，或看[控制台 → 用量与费用](https://console.deepraxis.ai/usage)
* **换模型**：改 `model` 字段；`deepseek-flash` 是滚动入口始终指向最新一代 Flash

## 相关食谱 [#相关食谱]

* [OpenAI SDK](/docs/cookbook/sdk/openai-sdk) · [Anthropic SDK](/docs/cookbook/sdk/anthropic-sdk) · [Vercel AI SDK](/docs/cookbook/sdk/vercel-ai-sdk)
* 不想写代码？看 [Cherry Studio](/docs/cookbook/chat-clients/cherry-studio) · [Claude Code](/docs/cookbook/coding-agents/claude-code)

# 迁移指南



# 从 OpenAI 官方迁移

保留 OpenAI SDK，改地址、Key 和模型 ID，先迁移一次 Chat Completions 请求。更换模型会改变回答行为；这不是让 DeepSeek 变成 GPT-4o。

```diff
 client = OpenAI(
-    base_url="https://api.openai.com/v1",
-    api_key=os.environ["OPENAI_API_KEY"],
+    base_url="https://api.deepraxis.ai/openai/v1",
+    api_key=os.environ["PRAXIS_API_KEY"],
 )
-model = "gpt-4o"
+model = "deepseek-flash"
```

## 1. 准备 [#1-准备]

需要 Python 3.10+、[uv](https://docs.astral.sh/uv/getting-started/installation/) 和一个 Praxis Key。在[控制台 → API Keys](https://console.deepraxis.ai/keys)创建 Key，将它安全注入当前终端的 `PRAXIS_API_KEY` 环境变量；不要把 Key 写进代码或日志。保留原服务的配置与 Key，供回滚使用。以下命令在 macOS / Linux 的 Bash 中执行。

```bash
test -n "${PRAXIS_API_KEY:-}"
```

期望：退出码 0；退出码 1 表示变量未设置，先设置再继续。

## 2. 选择模型 ID [#2-选择模型-id]

下表是迁移选择，不是别名或等价效果承诺。可用性核对于 2026-10-12；切换流量前再查[模型目录](https://console.deepraxis.ai/models)。

| 原 ID                        | Praxis 选择                          | 需要注意                              |
| --------------------------- | ---------------------------------- | --------------------------------- |
| `gpt-4o`、`gpt-4o-mini`      | `deepseek-flash`                   | 原 ID 不存在；重新评估提示词、工具与回答质量          |
| `gpt-4.1`、`o3-mini`、`gpt-5` | `deepseek-flash`                   | 不自动映射；原 ID 返回 404                 |
| 必须使用 OpenAI 系模型             | `gpt-5.6-sol`                      | 可用 Chat Completions，不支持 Responses |
| 原代码使用 Responses             | `deepseek-flash` 或 `glm-5.3-flash` | 当前可用的 Responses 选择                |

使用 Responses 时，确认选定 ID 出现在 `GET /openai/v1/models?api=responses`（Python：`client.models.list(extra_query={"api": "responses"})`）。也可查看 `GET /model/v1/models` 或 `GET /model/v1/models/{id}` 的 `supported_apis`，确认包含 `openai.responses`。OpenAI 面还可按 `chat`、`embeddings`、`images`、`audio`、`videos` 筛选；逗号分隔表示匹配任一协议。

## 行为差异 [#行为差异]

* 同协议请求按原协议转发，不代表所有官方模型、端点、字段都可用。
* 列表内的模型仍可能对某个操作返回 `404 model_protocol_not_offered`；Chat 与 Responses 要分别确认。
* 切流量前用自己的提示词检查流式、工具执行、结构化输出和思考行为。字段差异以 [Chat Completions](/docs/api/compatible/openai/createChatCompletion) 与 [Responses](/docs/api/compatible/openai/createResponse) 为准。
* 原服务的文件、会话与响应 ID 不随地址修改自动迁移；保留源数据，并重建应用需要的资源。
* Chat 的 `usage.cost` 是实付金额；Responses 和 Messages 目前不返回该字段。收到 `X-Praxis-Generation-Id` 时，可按 [生成记录 API](/docs/api/native/model/getGeneration) 用 `GET /model/v1/generation?id=生成ID` 查费用（记录可能延迟几秒）。若响应没有该头，去[控制台 → 用量与费用](https://console.deepraxis.ai/usage)查本次调用；不要把响应正文的 `id` 或 `X-Request-Id` 当成生成 ID，也不要将缺失费用当成零。

## 不支持的端点与替代 [#不支持的端点与替代]

以下路径相对于 `/openai/v1`，调用返回 404。替代流程不保证与原端点等价；有依赖时先拆分调用，保留原服务。

| 原端点                  | 迁移选择                                    |
| -------------------- | --------------------------------------- |
| `moderations`        | 无直接替代，继续使用原审核服务                         |
| `batches`            | 由应用逐次调用并控制并发                            |
| `fine_tuning`        | 选已有模型；保留原微调流程                           |
| `assistants`         | 重新组织为 Responses / Conversations 与应用工具循环 |
| `completions`        | 改用 `chat/completions` 和 `messages`      |
| `audio/translations` | 先转写，再用对话翻译                              |
| `uploads`            | 改用 `files`；核对文件大小与用途限制                  |
| `images/variations`  | 用 `images/edits` 提交图片与编辑提示词，重新评估效果      |

可用端点包括 `chat/completions`、`responses`、`embeddings`、`images/generations`、`images/edits`、`audio/speech`、`audio/transcriptions`、`videos`、`files`、`models`。可用端点不表示每个模型都支持该能力；具体操作与限制见 [OpenAI API 参考](/docs/api/compatible/openai)。

## 3. 验证一次请求 [#3-验证一次请求]

设置好 `PRAXIS_API_KEY` 后运行以下完整示例：

```bash
unset HTTP_PROXY HTTPS_PROXY ALL_PROXY http_proxy https_proxy all_proxy
uv run -q --no-project --with openai --with anthropic python - <<'PY'
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.deepraxis.ai/openai/v1",
    api_key=os.environ["PRAXIS_API_KEY"],
    timeout=90.0,
    max_retries=0,
)
models = client.models.list(extra_query={"api": "chat"})
assert "deepseek-flash" in {m.id for m in models.data}
raw = client.chat.completions.with_raw_response.create(
    model="deepseek-flash",
    messages=[{"role": "user", "content": "Reply OK."}],
    max_tokens=1024,
)
reply = raw.parse()
text = reply.choices[0].message.content
print("HTTP", raw.status_code)
print("X-Request-Id:", raw.headers.get("x-request-id"))
print("X-Praxis-Generation-Id:", raw.headers.get("x-praxis-generation-id"))
print(text)
assert raw.status_code == 200 and text and text.strip()
assert raw.headers.get("x-request-id")
PY
```

期望：退出码 0，输出 `HTTP 200`、非空正文（通常为 `OK.`）和 `X-Request-Id`。断言同时检查模型存在与真实回复；不是只检查能否连接。保留请求 ID 便于排查，不要记录 Key。示例会产生少量调用费用。

## 失败分支 [#失败分支]

| 实测报错                                   | 处理                                                       |
| -------------------------------------- | -------------------------------------------------------- |
| `404`，`Model "gpt-4o" does not exist.` | 地址与 Key 之外也要改模型；使用目录中的完整 ID                              |
| `404 model_protocol_not_offered`       | 换支持该操作的模型；Responses 选 `deepseek-flash` 或 `glm-5.3-flash` |
| 上表端点返回 `404 Not Found`                 | 按表替代，或让该请求继续使用原服务                                        |

## 4. 回滚 [#4-回滚]

一起恢复三个原值：`https://api.openai.com/v1`、`OPENAI_API_KEY` 中的原 Key、原模型 ID。移除 Praxis 专有请求字段，恢复原资源 ID。重启应用让客户端加载旧配置，再跑原有冒烟请求并保留请求 ID。

期望：原端点成功返回可用正文。配置回滚不会退还已发生的调用费用，也不会在服务之间复制会话状态。

[API 参考 →](/docs/api/compatible/openai) · [兼容指南 →](/docs/cloud/services/model/guides/openai-compatible)

# 从 Anthropic 迁移

保留 Anthropic SDK 和 Messages 请求结构，修改地址、Key、模型 ID，再用新模型验证原提示词。

```diff
 client = Anthropic(
-    base_url="https://api.anthropic.com",
-    api_key=os.environ["ANTHROPIC_API_KEY"],
+    base_url="https://api.deepraxis.ai/anthropic",
+    api_key=os.environ["PRAXIS_API_KEY"],
 )
-model = "claude-sonnet-4-5"
+model = "deepseek-flash"
```

## 1. 准备 [#1-准备]

需要 Python 3.10+、[uv](https://docs.astral.sh/uv/getting-started/installation/) 和一个 Praxis Key。在[控制台 → API Keys](https://console.deepraxis.ai/keys)创建 Key，将它安全注入当前终端的 `PRAXIS_API_KEY` 环境变量；不要把 Key 写进代码或日志。保留原服务的配置与 Key，供回滚使用。以下命令在 macOS / Linux 的 Bash 中执行。

```bash
test -n "${PRAXIS_API_KEY:-}"
```

期望：退出码 0；退出码 1 表示变量未设置，先设置再继续。

## 2. 选择模型 [#2-选择模型]

| 原选择                                | Praxis 选择                                | 要检查什么                                     |
| ---------------------------------- | ---------------------------------------- | ----------------------------------------- |
| 官方 Claude ID，如 `claude-sonnet-4-5` | 本例使用 `deepseek-flash`                    | 这是另一个模型，不是 Claude 别名；重新评估质量与工具行为          |
| 必须使用 Claude                        | 从 `/anthropic/v1/models` 复制可用的 Claude ID | 2026-10-12 目录包含 `claude-opus-5`；使用前确认所需能力 |

SDK 基础地址只到 `/anthropic`，不要加 `/v1`，SDK 会追加 `/v1/messages`。目录仅列可走 Anthropic 协议的模型，与 `/openai/v1/models`、`/google/v1beta/models` 各自独立。

期望：完整模型 ID 出现在 `client.models.list()`；不要未经检查直接沿用官方 ID。

## 行为差异 [#行为差异]

* `thinking` 可用 `enabled`、`adaptive`、`disabled`，并支持 `output_config.effort`。部分模型不能关闭思考，返回 `400`（`cannot disable thinking`）；组合选项前查 [Messages 字段支持](/docs/api/compatible/anthropic/createMessage)。
* 从 `content` 中读取文本块，不要假定第一块就是正文；推理模型可能先返回思考块。
* `count_tokens` 返回带 `x-praxis-token-count: estimated` 的校准估算，不是精确计费依据，见 [统计 token](/docs/api/compatible/anthropic/countTokens)。
* Chat 的 `usage.cost` 是实付金额；Responses 和 Messages 目前不返回该字段。收到 `X-Praxis-Generation-Id` 时，可按 [生成记录 API](/docs/api/native/model/getGeneration) 用 `GET /model/v1/generation?id=生成ID` 查费用（记录可能延迟几秒）。若响应没有该头，去[控制台 → 用量与费用](https://console.deepraxis.ai/usage)查本次调用；不要把响应正文的 `id` 或 `X-Request-Id` 当成生成 ID，也不要将缺失费用当成零。

## 不支持的操作与替代 [#不支持的操作与替代]

模型兼容接口提供 Messages、token 统计、模型列表和文件操作，各自限制见 [Anthropic API 参考](/docs/api/compatible/anthropic)。不提供 Message Batches（`/anthropic/v1/messages/batches`）；改为应用控制并发逐次调用 Messages，或保留原服务的批处理。官方模型 ID、文件 ID 不会自动映射；应选择目录模型，并重新上传需要的源文件。

## 3. 验证一次请求 [#3-验证一次请求]

```bash
unset HTTP_PROXY HTTPS_PROXY ALL_PROXY http_proxy https_proxy all_proxy
uv run -q --no-project --with openai --with anthropic python - <<'PY'
import os
from anthropic import Anthropic

client = Anthropic(
    base_url="https://api.deepraxis.ai/anthropic",
    api_key=os.environ["PRAXIS_API_KEY"],
    timeout=90.0,
    max_retries=0,
)
models = client.models.list()
assert "deepseek-flash" in {m.id for m in models.data}
raw = client.messages.with_raw_response.create(
    model="deepseek-flash",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Reply OK."}],
)
reply = raw.parse()
text = "".join(block.text for block in reply.content if block.type == "text")
print("HTTP", raw.status_code)
print("X-Request-Id:", raw.headers.get("x-request-id"))
print("X-Praxis-Generation-Id:", raw.headers.get("x-praxis-generation-id"))
print(text)
assert raw.status_code == 200 and text and text.strip()
assert raw.headers.get("x-request-id")
PY
```

期望：退出码 0，输出 `HTTP 200`、非空正文（通常为 `OK.`）和 `X-Request-Id`。断言同时检查模型存在与真实回复；不是只检查能否连接。保留请求 ID 便于排查，不要记录 Key。示例会产生少量调用费用。

## 失败分支 [#失败分支]

| 实测报错                                             | 处理                            |
| ------------------------------------------------ | ----------------------------- |
| `400`（`cannot disable thinking`）                 | 移除关闭思考的要求，或选择目录声明可关闭思考的模型     |
| `404`（`anthropic.messages is not offered for …`） | 选择 Anthropic 协议目录内且支持所需操作的 ID |
| Message Batches 返回 `404 Not Found`               | 逐次调用 Messages，或保留原批处理服务       |

## 4. 回滚 [#4-回滚]

恢复 `https://api.anthropic.com`、`ANTHROPIC_API_KEY` 中的原 Key 和原 Claude 模型 ID，同时恢复原思考选项与文件引用。重启客户端，运行原 Messages 冒烟请求，保留请求 ID。

期望：原服务返回可用正文。修改配置不会搬运文件、历史会话状态，也不会撤销已产生的费用。

[API 参考 →](/docs/api/compatible/anthropic) · [兼容指南 →](/docs/cloud/services/model/guides/anthropic-compatible)

# 从 OpenRouter 迁移

保留 OpenAI SDK，替换连接配置与模型 ID；切流量前逐项处理 OpenRouter 专有选项。

```diff
 client = OpenAI(
-    base_url="https://openrouter.ai/api/v1",
-    api_key=os.environ["OPENROUTER_API_KEY"],
+    base_url="https://api.deepraxis.ai/openai/v1",
+    api_key=os.environ["PRAXIS_API_KEY"],
 )
-model = "openai/gpt-4o"
+model = "deepseek-flash"
```

## 1. 准备 [#1-准备]

需要 Python 3.10+、[uv](https://docs.astral.sh/uv/getting-started/installation/) 和一个 Praxis Key。在[控制台 → API Keys](https://console.deepraxis.ai/keys)创建 Key，将它安全注入当前终端的 `PRAXIS_API_KEY` 环境变量；不要把 Key 写进代码或日志。保留原服务的配置与 Key，供回滚使用。以下命令在 macOS / Linux 的 Bash 中执行。

```bash
test -n "${PRAXIS_API_KEY:-}"
```

期望：退出码 0；退出码 1 表示变量未设置，先设置再继续。

## 2. 替换模型 ID [#2-替换模型-id]

| OpenRouter 选择     | Praxis 选择                           |
| ----------------- | ----------------------------------- |
| `openai/gpt-4o`   | 先用 `deepseek-flash` 跑通；这是另一个模型，不是别名 |
| `vendor/model`    | 从 Praxis 目录复制完整 ID，不能假设去掉前缀就可用      |
| 带 `:nitro` 后缀的 ID | 选不带后缀的目录 ID；不支持该后缀                  |
| `openrouter/auto` | 明确选择一个模型，或配置 `models` 回退列表          |

期望：`client.models.list()` 包含选定 ID。回退列表中的每个 ID 都必须是有效的 Praxis ID，并支持你调用的操作。

## 行为差异 [#行为差异]

| OpenRouter 选项                                      | 迁移处理                                                                  |
| -------------------------------------------------- | --------------------------------------------------------------------- |
| `provider.order`、`provider.only`、`provider.ignore` | 仅自带上游 Key（BYOK）可用；使用平台凭据时移除，否则返回 `400 provider_selection_not_allowed` |
| `provider.allow_fallbacks`、`provider.sort`         | 无效果；移除并重新评估选路假设                                                       |
| `provider.data_collection`、`provider.zdr`          | 无效果；请求被接受不代表这些策略已执行                                                   |
| `models`                                           | 支持模型回退列表；替换每个 ID 并检查响应中的 `model`                                      |
| `provider.require_parameters: true`                | 对工具参数与已声明的采样参数进行支持检查；要求未声明支持的参数时返回 400；不支持的采样参数默认忽略                   |

参数检查范围是工具参数与已声明的采样参数，不是供应商任意功能。准确范围见 [Chat Completions 字段支持](/docs/api/compatible/openai/createChatCompletion)。如果应用依赖被忽略选项所控制的数据策略，应继续使用原服务，直到单独确认所需策略。

Chat 的 `usage.cost` 是实付金额；Responses 和 Messages 目前不返回该字段。收到 `X-Praxis-Generation-Id` 时，可按 [生成记录 API](/docs/api/native/model/getGeneration) 用 `GET /model/v1/generation?id=生成ID` 查费用（记录可能延迟几秒）。若响应没有该头，去[控制台 → 用量与费用](https://console.deepraxis.ai/usage)查本次调用；不要把响应正文的 `id` 或 `X-Request-Id` 当成生成 ID，也不要将缺失费用当成零。

## 不支持的操作与替代 [#不支持的操作与替代]

`vendor/model`、`:nitro`、`openrouter/auto` 都不是受支持的模型选择方式，也不会自动映射。缺失的 OpenAI 端点见[不支持清单与替代](/docs/cookbook/migration/from-openai#不支持的端点与替代)。具体操作与字段以 [API 参考](/docs/api/compatible/openai) 为准，不要假设 OpenRouter 扩展也适用于 Responses。

## 3. 验证一次请求 [#3-验证一次请求]

先跑通不带供应商偏好的最小 Chat 请求：

```bash
unset HTTP_PROXY HTTPS_PROXY ALL_PROXY http_proxy https_proxy all_proxy
uv run -q --no-project --with openai --with anthropic python - <<'PY'
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.deepraxis.ai/openai/v1",
    api_key=os.environ["PRAXIS_API_KEY"],
    timeout=90.0,
    max_retries=0,
)
models = client.models.list()
assert "deepseek-flash" in {m.id for m in models.data}
raw = client.chat.completions.with_raw_response.create(
    model="deepseek-flash",
    messages=[{"role": "user", "content": "Reply OK."}],
    max_tokens=1024,
)
reply = raw.parse()
text = reply.choices[0].message.content
print("HTTP", raw.status_code)
print("X-Request-Id:", raw.headers.get("x-request-id"))
print("X-Praxis-Generation-Id:", raw.headers.get("x-praxis-generation-id"))
print(text)
assert raw.status_code == 200 and text and text.strip()
assert raw.headers.get("x-request-id")
PY
```

期望：退出码 0，输出 `HTTP 200`、非空正文（通常为 `OK.`）和 `X-Request-Id`。断言同时检查模型存在与真实回复；不是只检查能否连接。保留请求 ID 便于排查，不要记录 Key。示例会产生少量调用费用。

然后逐个加回应用需要的选项。期望：每次请求成功且返回预期模型；被忽略的字段不能作为策略生效的证据。

## 失败分支 [#失败分支]

| 实测报错                                 | 处理                          |
| ------------------------------------ | --------------------------- |
| `400 provider_selection_not_allowed` | 平台凭据移除供应商选择；或先配置 BYOK 再选择上游 |
| `404`，包含 `does not exist`            | 将带厂商前缀、后缀或自动选择器的 ID 换成目录 ID |
| `404 model_protocol_not_offered`     | 选择提供该操作的模型                  |

## 4. 回滚 [#4-回滚]

恢复 `https://openrouter.ai/api/v1`、原 `OPENROUTER_API_KEY`、原模型 ID 和保存的 OpenRouter 选项。重启客户端后跑原冒烟请求。不要把 Praxis Key 发给 OpenRouter。

期望：原请求返回可用正文与预期模型。Praxis 上已产生的调用费用仍保留。

[API 参考 →](/docs/api/compatible/openai) · [Cookbook：OpenAI SDK →](/docs/cookbook/sdk/openai-sdk)

# 从其他网关迁移

先迁移一次请求：改 API 地址、Key 和模型 ID。下面示例面向兼容 OpenAI Chat Completions 的客户端，不会自动把其他请求协议转换成 Chat。

## 1. 准备终端 [#1-准备终端]

准备 Python 3.10+ 和 [uv](https://docs.astral.sh/uv/getting-started/installation/)。将 [Praxis 云 API Key](/docs/cloud/account/api-keys) 放入环境变量 `PRAXIS_API_KEY`，不要写入代码或日志。

```bash
test -n "$PRAXIS_API_KEY"
```

期望：退出码为 0。退出码 1 表示变量未设置，先设置再继续。示例默认使用 `https://api.deepraxis.ai`。切换环境时，将 `PRAXIS_API_BASE` 设为相应 API 域名，不带末尾斜杠或 API 路径。

## 2. 修改三项配置 [#2-修改三项配置]

1. 将 `base_url` 改为 `https://api.deepraxis.ai/openai/v1`。期望：地址只含一次 `/openai/v1`，不是控制台网址，也不是完整的 `/chat/completions` 端点。
2. 将客户端 Key 改为 `PRAXIS_API_KEY`。期望：不再向 Praxis 发送旧网关的 Key；另存原配置以便回滚。
3. 本次冒烟验证将模型 ID 改为 `deepseek-flash`。期望：它出现在 `GET /openai/v1/models?api=chat`。旧网关的供应商前缀或别名不一定在此有效。

按当前使用的 API 选择更详细的迁移指南：

| 当前 API 或网关                          | 指南                                                          |
| ----------------------------------- | ----------------------------------------------------------- |
| OpenAI Chat Completions 或 Responses | [从 OpenAI 迁移](/docs/cookbook/migration/from-openai)         |
| OpenRouter                          | [从 OpenRouter 迁移](/docs/cookbook/migration/from-openrouter) |
| Anthropic Messages                  | [从 Anthropic 迁移](/docs/cookbook/migration/from-anthropic)   |

## 3. 验证新配置 [#3-验证新配置]

保存为 `gateway-migration.py`，运行 `uv run -q --no-project --with openai --with anthropic --with google-genai python gateway-migration.py`。

```python
import os
from openai import OpenAI

client = OpenAI(api_key=os.environ['PRAXIS_API_KEY'],
    base_url=os.environ.get('PRAXIS_API_BASE', 'https://api.deepraxis.ai') + '/openai/v1')
models = client.models.list(extra_query={'api': 'chat'})
print('catalog X-Request-Id:', models._request_id)
assert 'deepseek-flash' in [model.id for model in models]
response = client.chat.completions.create(model='deepseek-flash',
    messages=[{'role': 'user', 'content': 'Reply with exactly: MIGRATION_OK'}],
    reasoning_effort='none', max_tokens=256)
print('X-Request-Id:', response._request_id)
assert response.choices[0].finish_reason == 'stop'
assert response.choices[0].message.content.strip() == 'MIGRATION_OK'
assert response.usage is not None and response.usage.total_tokens > 0
print(response.choices[0].message.content)
print('usage:', response.usage.model_dump())
```

期望：输出 `MIGRATION_OK`、大于 0 的 token 用量、目录请求 ID 与推理请求 ID，退出码 0。保留请求 ID 用于排障，不记录 Key。

## 4. 切流量前检查 [#4-切流量前检查]

用自己的提示词检查流式、工具、结构化输出和[思考设置](/docs/cloud/services/model/guides/reasoning)。冒烟通过不代表模型行为相同。按需重建文件或响应资源：旧网关的 ID 不随配置迁移。验证失败时，一起恢复原地址、Key 和模型配置。

实测 `gpt-5.6-sol` 调用 Responses 返回 `model_protocol_not_offered`（HTTP 404）。支持 Chat 不代表支持 Responses，应按 [Responses 指南](/docs/cloud/services/model/guides/responses-api)查询对应目录。模型断言失败表示所选 ID 未出现在该协议目录中，应先核对再切流量。

[API 参考 →](/docs/api/compatible/openai) · [模型指南 →](/docs/cloud/services/model/guides/openai-compatible)

# 实战场景

（待补充）

导出自 Praxis 文档 · 2026-10-14 · 共 40 页