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

按工具选择接入方式

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

快速选路

不写代码，最快体验：打开 Praxis App，登录即用。

不写代码，用你喜欢的客户端：Cherry Studio（5 分钟接通，模型自动拉取）。

写代码，最少改动：OpenAI SDK（换一个 baseURL 就能用，usage.cost 直接返回费用）。

终端编程，改代码 / 跑命令：Claude Code（settings.json 一个文件搞定）。

已有 OpenAI / Anthropic 代码要迁移：看迁移指南——改一个地址就能迁过来。

把 Praxis 接进终端编程智能体，用你的 Key 驱动——每个工具只需要 Base URL、API Key 和模型 ID 三件事。

所有客户端共用同一套 前提：一个 sk-praxis- 开头的 Praxis API Key。

协议速查：Claude Code 走 Anthropic 协议（/anthropic）；Codex 走 OpenAI Responses 协议（/openai/v1 + wire_api: "responses"）；其余大多数走 OpenAI 兼容协议（/openai/v1）。

你是第一次接触编程 Agent？ 推荐从 Claude Code 开始——配置最少（一个 JSON 文件）、社区最活跃、文档最多。

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

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

你将完成

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

前提

开始前逐项确认：

• 一个 Praxis API Key（sk-praxis- 开头）。没有就到 控制台 → API Keys 创建：点「创建 Key」，弹窗中名称必填，有效期默认 90 天（可改永久），点创建后立即复制保存；之后也随时可在 Key 列表行点「复制」重新获取完整 Key。新账号自带 $1 免费额度。完整流程见快速开始。

• Node.js 18 或更高。终端运行 node --version 检查；没有就到 nodejs.org 装 LTS 版。

• 安装 Claude Code：

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

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

配置

第 1 步：写入配置文件

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

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.deepraxis.com/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——后者是官方直连时用的，配网关时无效。

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

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

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

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

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

验证

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

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

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

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

export PRAXIS_API_KEY=sk-praxis-你的Key

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

curl https://api.deepraxis.com/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 块，属正常。

最后看一眼 控制台 → 用量与费用：刚才的调用已经记在账上——每一次调用都有账、可追溯。

常见问题

官方安装脚本：

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

进阶

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

相关食谱

• Codex · Cline · OpenCode
• 偏好图形界面？看 Cherry Studio · Chatbox

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

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

你将完成

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

前提

开始前逐项确认：

• 一个 Praxis API Key（sk-praxis- 开头）。没有就到 控制台 → API Keys 创建：点「创建 Key」，弹窗中名称必填，有效期默认 90 天（可改永久），点创建后弹窗会展示完整 Key 一次——立即复制保存；之后也随时可在 Key 列表行点复制图标（悬停行时出现）重新获取完整 Key。若弹窗长时间停在「创建中…」，刷新列表确认 Key 已生成即可，行内复制同样能拿到完整 Key。新账号自带 $1 免费额度。完整流程见快速开始。

• Node.js 18 或更高。终端运行 node --version 检查；没有就到 nodejs.org 装 LTS 版。

• 安装 Codex CLI：

  npm install -g @openai/codex

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

配置

第 1 步：写配置文件

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

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

[model_providers.praxis]
name = "Praxis"
base_url = "https://api.deepraxis.com/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 命令即使用新配置（已开着的会话需退出重进）。

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

macOS / Linux（WSL 同）：

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 仓库），运行：

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

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

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

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

export PRAXIS_API_KEY=sk-praxis-你的Key

curl https://api.deepraxis.com/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 是别名，语法不同），并把命令并成一行（去掉行尾 \）。

最后看一眼 控制台 → 用量与费用：刚才的调用已经记在账上——每一次调用都有账、可追溯。

常见问题

进阶

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

相关食谱

• Claude Code（Anthropic 协议姊妹篇）· Cline · OpenCode
• 偏好图形界面？看 Cherry Studio · Chatbox

前提

一个 API Key（见快速开始）。

配置

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

验证

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

常见问题

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

把 Praxis 接入 OpenCode——开源终端编程智能体。项目里放一个 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 创建：点「创建 Key」，名称必填，有效期可选 30/60/90 天或永久、默认 90 天；创建成功弹窗会展示完整 Key 并带「复制 Key」，关闭后列表只显示掩码，随时可点行内复制图标重新获取完整 Key。期望：弹出「创建 API Key」对话框，提交后弹窗展示完整 Key 与「复制 Key」按钮。新账号自带 $1 免费额度。完整流程见快速开始。

• Node.js 18 或更高（node --version 检查）。

• 安装 OpenCode：

  npm install -g opencode-ai

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

配置

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

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：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "praxis": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Praxis",
      "options": {
        "baseURL": "https://api.deepraxis.com/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 是平台示例模型。

期望：文件保存即生效。

验证

在项目目录里运行：

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

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

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

export PRAXIS_API_KEY=sk-praxis-你的Key

curl https://api.deepraxis.com/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 字段也正常——推理模型的思维链）。

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

常见问题

进阶

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

相关食谱

• Claude Code · Codex（姊妹篇）
• 偏好 SDK 编程？看 Vercel AI SDK（OpenCode 的 provider 体系同源）

前提

一个 API Key（见快速开始）。

配置

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

验证

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

常见问题

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

前提

一个 API Key（见快速开始）。

配置

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

验证

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

常见问题

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

前提

一个 API Key（见快速开始）。

配置

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

验证

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

常见问题

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

前提

一个 API Key（见快速开始）。

配置

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

验证

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

常见问题

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

前提

一个 API Key（见快速开始）。

配置

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

验证

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

常见问题

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

把 Praxis 接进 AI 增强的 IDE，在编辑器里直接使用你的 Key 驱动模型——补全、对话、代码生成。

所有 IDE 共用同一套 前提：一个 sk-praxis- 开头的 Praxis API Key。

不想换 IDE？ 用终端编程 Agent（如 Claude Code）在你现有编辑器旁边工作，体验一样好。

前提

一个 API Key（见快速开始）。

配置

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

验证

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

常见问题

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

前提

一个 API Key（见快速开始）。

配置

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

验证

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

常见问题

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

前提

一个 API Key（见快速开始）。

配置

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

验证

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

常见问题

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

前提

一个 API Key（见快速开始）。

配置

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

验证

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

常见问题

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

前提

一个 API Key（见快速开始）。

配置

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

验证

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

常见问题

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

把 Praxis 接进聊天客户端，用一个 Key 聊所有模型——全程不写代码，适合非开发者和快速体验。

所有客户端共用同一套 前提：一个 sk-praxis- 开头的 Praxis API Key。

你是第一次接触聊天客户端？ 推荐从 Cherry Studio 开始——免费开源、模型目录自动拉取、中文界面友好、配置只需三步。

想用但不想装客户端？ 直接用 Praxis App：打开 society.deepraxis.ai 登录即用，零配置。

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

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

你将完成

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

前提

开始前逐项确认：

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

配置

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

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

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

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

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

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

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

第 3 步：添加模型

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

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

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

验证

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

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

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

export PRAXIS_API_KEY=sk-praxis-你的Key

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

curl https://api.deepraxis.com/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 拼写问题——对照下方常见问题。

最后看一眼 控制台 → 用量与费用：刚才的调用已经记在账上——每一次调用都有账、可追溯。

常见问题

进阶

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

相关食谱

• Chatbox · LobeHub · Open WebUI
• 从其他服务迁移过来？看迁移指南

前提

一个 API Key（见快速开始）。

配置

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

验证

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

常见问题

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

前提

一个 API Key（见快速开始）。

配置

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

验证

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

常见问题

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

把 Praxis 接入 LobeHub——开源的现代设计 AI 聊天界面，支持插件、多模型、语音。Docker 启动，浏览器里填两处即通。

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

你将完成

• 用 Docker 跑起一个 LobeHub 实例，接入 Praxis 的模型对话
• 完成标志：在聊天框发送「你好」并收到回复
• 预计耗时：5 分钟（不含 Docker 镜像下载）
• 支持协议：OpenAI 兼容（/openai/v1）

前提

• Docker 已安装并运行（docker --version 检查）。
• 一个 Praxis API Key（sk-praxis- 开头）。没有就到 控制台 → API Keys 创建。完整流程见快速开始。

安装与启动

第 1 步：启动容器

docker run -d --name lobehub --restart always -p 3210:3210 lobehub/lobe-chat:latest

期望：容器 ID 输出无报错，首次拉取约 1GB。

第 2 步：打开浏览器

访问 http://localhost:3210。期望：自动跳转到聊天页。

配置

第 3 步：进入模型设置

点击左侧边栏的设置图标（齿轮），选择「Language Model」。期望：看到 API Key 与 API Proxy Address 两个输入区域。

第 4 步：填入 Praxis 连接

点「Check」验证。期望：通过后在 Model List 勾选 deepseek-flash。

环境变量预设（免 UI 配置）：

docker run -d --name lobehub --restart always -p 3210:3210 \
  -e OPENAI_API_KEY=sk-praxis-你的Key \
  -e OPENAI_PROXY_URL=https://api.deepraxis.ai/openai/v1 \
  lobehub/lobe-chat:latest

验证

选模型，发「你好」。期望：收到回复即接入成功。

常见问题

相关食谱

• Cherry Studio · Open WebUI

把 Praxis 接入 Open WebUI——最流行的开源自托管 AI 聊天界面。一条 Docker 命令启动，浏览器里配置连接，就能用 Praxis 的所有模型。

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

你将完成

• 用 Docker 跑起一个自托管的 Open WebUI 实例，接入 Praxis 的模型对话
• 完成标志：在聊天框发送「你好」并收到回复
• 预计耗时：5 分钟（不含 Docker 镜像下载）
• 支持协议：OpenAI 兼容（/openai/v1）

前提

开始前逐项确认：

• Docker 已安装并运行（docker --version 检查）。没有就到 Docker 官网 装。
• 一个 Praxis API Key（sk-praxis- 开头）。没有就到 控制台 → API Keys 创建：点「创建 Key」，名称必填，有效期可选 30/60/90 天或永久、默认 90 天；创建成功弹窗会展示完整 Key 并带「复制 Key」。新账号自带 $1 免费额度。完整流程见快速开始。

安装与启动

第 1 步：启动 Open WebUI 容器

docker run -d --name open-webui --restart always -p 3080:8080 ghcr.io/open-webui/open-webui:main

期望：容器 ID 输出后无报错。首次运行会拉取镜像（约 2GB），需要几分钟。

第 2 步：打开浏览器

在浏览器访问 http://localhost:3080。

期望：看到 Open WebUI 欢迎页，带「Get started」按钮。

第 3 步：创建管理员账号

点「Get started」，填写 Name、Email、Password（这是本地管理员账号，与 Praxis 无关），点「Create Admin Account」。

期望：进入 Open WebUI 主界面——左侧是对话列表，中间是聊天框。

配置

第 4 步：进入连接设置

点击右下角的用户名，选择「Admin Panel」→「Settings」→「Connections」。

期望：看到 OpenAI API 连接配置区域。

第 5 步：填入 Praxis 连接

在 OpenAI API 区域：

点「Save」。

期望：保存后返回聊天页，模型选择器中出现 Praxis 的模型列表。

也可以在启动容器时用环境变量预设连接（免 UI 配置）：

docker run -d --name open-webui --restart always -p 3080:8080 \
  -e OPENAI_API_BASE_URL=https://api.deepraxis.com/openai/v1 \
  -e OPENAI_API_KEY=sk-praxis-你的Key \
  ghcr.io/open-webui/open-webui:main

验证

回到聊天页，在顶部模型选择器中选一个模型（如 deepseek-flash），在输入框发送「你好」。

期望：几秒内收到回复——收到回复即接入成功。

最后看一眼 控制台 → 用量与费用：刚才的调用已经记在账上——每一次调用都有账、可追溯。

常见问题

进阶

• 查这次对话花了多少钱：控制台 → 用量与费用，按次计费、无闲置费
• 换模型：在 Open WebUI 的模型选择器中随时切换；deepseek-flash 是滚动入口始终指向最新一代 Flash
• 多用户：Open WebUI 支持多用户注册，在 Admin Panel → Users 管理权限
• 自定义界面：Admin Panel → Settings → Interface 可改主题、语言（支持中文）
• 数据持久化：加 -v open-webui:/app/backend/data 挂载数据卷，容器重建后聊天记录不丢

相关食谱

• Cherry Studio（桌面客户端，不需要 Docker）
• Dify（低代码平台，同样 Docker 部署）
• 不想装任何东西？看 Praxis App：打开网址即用

前提

一个 API Key（见快速开始）。

配置

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

验证

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

常见问题

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

把 Praxis 作为模型提供商接入低代码/无代码平台，在可视化画布里编排智能体和工作流。

所有平台共用同一套前提：一个 sk-praxis- 开头的 Praxis API Key。

想写代码而不是拖积木？ 看 SDK 与框架——用你熟悉的编程语言直连。

前提

一个 API Key（见快速开始）。

配置

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

验证

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

常见问题

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

把 Praxis 接入 Coze——字节跳动的智能体构建平台。Coze 支持自定义模型接入，在设置中添加 OpenAI 兼容模型即可使用 Praxis。

每一步都标了期望结果。

你将完成

• 在 Coze 中把 Praxis 配置为自定义模型，在智能体中使用
• 完成标志：智能体对话收到 Praxis 模型的回复
• 支持协议：OpenAI 兼容（/openai/v1）

前提

• 一个 Coze 账号（coze.cn 注册）。
• 一个 Praxis API Key。到 控制台 → API Keys 创建。见快速开始。

配置

第 1 步：在 Coze 平台，点击左侧「模型」（或进入 Bot 编辑页 → 模型设置）。

第 2 步：选择「OpenAI 兼容」类型：

点「测试连接」→「保存」。期望：测试通过，模型出现在可用列表。

验证

创建 Bot，选 deepseek-flash，发「你好」。期望：收到回复即接入成功。

常见问题

相关食谱

• Dify · n8n

前提

一个 API Key（见快速开始）。

配置

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

验证

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

常见问题

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

把 Praxis 接入 FastGPT——专注于知识库问答（RAG）的开源平台。Docker Compose 部署，在模型配置中添加 OpenAI 兼容渠道指向 Praxis，即可用你的模型做知识库问答。

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

你将完成

• 在 FastGPT 中把 Praxis 配置为模型渠道，在聊天中使用
• 完成标志：聊天中收到 Praxis 模型的回复
• 支持协议：OpenAI 兼容（/openai/v1）

前提

• Docker 与 Docker Compose 已安装。
• 一个 Praxis API Key（sk-praxis- 开头）。没有就到 控制台 → API Keys 创建。完整流程见快速开始。

安装

完整部署见 FastGPT 官方文档。核心：docker compose up -d，访问 http://localhost:3000，用 .env 中的默认密码登录。

配置

第 1 步：进入模型渠道设置

点击左下角头像 →「账号」→「模型配置」。

第 2 步：添加 OpenAI 兼容渠道

点「新增渠道」，选「OpenAI」类型：

点「保存」。期望：渠道保存成功，模型测试通过。

验证

聊天页选 deepseek-flash，发「你好」。期望：收到回复即接入成功。

常见问题

相关食谱

• Dify · n8n · Open WebUI

用你熟悉的 SDK 写代码调 Praxis 的模型——已有一切 OpenAI / Anthropic 代码不用换库，只改一个 baseURL。

所有 SDK 共用同一套 前提：一个 sk-praxis- 开头的 Praxis API Key（走环境变量，不写进代码）。

协议速查：OpenAI 兼容走 https://api.deepraxis.com/openai/v1；Anthropic 兼容走 https://api.deepraxis.com/anthropic。

你是第一次写 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 创建：点「创建 Key」，名称必填，有效期默认 90 天（可改永久），创建后立即复制保存；之后也随时可在 Key 列表行点复制图标重新获取完整 Key。新账号自带 $1 免费额度。完整流程见快速开始。

• Node.js 18 或更高（node --version 检查；用 Bun 亦可）。

• 安装 SDK：在项目目录里

  npm install openai

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

第一个请求

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

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.deepraxis.com/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);

运行：

node hello.mjs

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

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

Python 版

pip install openai

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

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.deepraxis.com/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）。

流式响应

新建 stream.mjs：

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.deepraxis.com/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；流式支持按模型路由而异，个别路由可能暂未开放，详见下方常见问题。

常见问题

连通性自检：

curl -sS https://api.deepraxis.com/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 } 可加可不加，平台两种情况都会回；控制台 → 用量与费用有逐笔明细
• 列出可用模型：await client.models.list()——和控制台 → 模型同源
• 换模型：改 model 字段即可；deepseek-flash 是滚动入口始终指向最新一代 Flash，deepseek-v4-flash 是固定版本快照

相关食谱

• Anthropic SDK（Anthropic 协议姊妹篇）· LangChain · Vercel AI SDK
• 不想写代码？看 Cherry Studio · Codex

把 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 创建：点「创建 Key」，名称必填，有效期默认 90 天（可改永久）；创建成功弹窗会展示完整 Key 并带「复制 Key」，关闭后列表只显示掩码，随时可点行内复制图标重新获取完整 Key。新账号自带 $1 免费额度。完整流程见快速开始。

• Node.js 18 或更高（node --version 检查；用 Bun 亦可）。

• 安装 SDK——注意包名是 @anthropic-ai/sdk（npm 上的 anthropic 是同名的占位包，不是它）：

  npm install @anthropic-ai/sdk

  期望：安装无报错。

第一个请求

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

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

const client = new Anthropic({
  baseURL: "https://api.deepraxis.com/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);

运行：

node hello.mjs

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

Python 版

pip install anthropic

新建 hello.py：

import os
from anthropic import Anthropic

client = Anthropic(
    base_url="https://api.deepraxis.com/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 同形。

流式响应

新建 stream.mjs：

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

const client = new Anthropic({
  baseURL: "https://api.deepraxis.com/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 时去掉流式或换模型重试）。

常见问题

进阶

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

相关食谱

• OpenAI SDK（OpenAI 协议姊妹篇）· LangChain · Vercel AI SDK
• 不想写代码？看 Cherry Studio · Claude Code

把 Praxis 接入 Vercel AI SDK——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 创建：点「创建 Key」，名称必填，有效期默认 90 天（可改永久）；创建成功弹窗会展示完整 Key 并带「复制 Key」，关闭后列表只显示掩码，随时可点行内复制图标重新获取完整 Key。期望：弹出「创建 API Key」对话框，提交后弹窗展示完整 Key 与「复制 Key」按钮。新账号自带 $1 免费额度。完整流程见快速开始。

• Node.js 18 或更高（node --version 检查；用 Bun 亦可）。

• 安装 SDK：

  npm install ai @ai-sdk/openai

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

第一个请求

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

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

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

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

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

运行：

node hello.mjs

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

流式响应

新建 stream.mjs：

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

const praxis = createOpenAI({
  baseURL: "https://api.deepraxis.com/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 时去掉流式或换模型重试）。

常见问题

进阶

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

相关食谱

• OpenAI SDK · Anthropic SDK · LangChain
• 不想写代码？看 Cherry Studio · Codex

把 Praxis 接入 LangChain（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 创建：点「创建 Key」，名称必填，有效期可选 30/60/90 天或永久，默认 90 天；创建成功弹窗会展示完整 Key 并带「复制 Key」，关闭后列表只显示掩码，随时可点行内复制图标重新获取完整 Key。期望：弹出「创建 API Key」对话框，提交后弹窗展示完整 Key 与「复制 Key」按钮。新账号自带 $1 免费额度。完整流程见快速开始。

• Node.js 18 或更高（node --version 检查；用 Bun 亦可）。

• 安装 SDK：

  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：

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

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

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

运行：

node hello.mjs

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

流式响应

新建 stream.mjs：

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

const model = new ChatOpenAI({
  model: "deepseek-flash",
  configuration: {
    baseURL: "https://api.deepraxis.com/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 时去掉流式或换模型重试）。

常见问题

进阶

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

相关食谱

• OpenAI SDK · Anthropic SDK · Vercel AI SDK
• 不想写代码？看 Cherry Studio · Claude Code

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

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

1. 准备

需要 Python 3.10+、uv 和一个 Praxis Key。在控制台 → API Keys创建 Key，将它安全注入当前终端的 PRAXIS_API_KEY 环境变量；不要把 Key 写进代码或日志。保留原服务的配置与 Key，供回滚使用。以下命令在 macOS / Linux 的 Bash 中执行。

test -n "${PRAXIS_API_KEY:-}"

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

2. 选择模型 ID

下表是迁移选择，不是别名或等价效果承诺。可用性核对于 2026-10-12；切换流量前再查模型目录。

使用 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 与 Responses 为准。
• 原服务的文件、会话与响应 ID 不随地址修改自动迁移；保留源数据，并重建应用需要的资源。
• Chat 的 usage.cost 是实付金额；Responses 和 Messages 目前不返回该字段。收到 X-Praxis-Generation-Id 时，可按 生成记录 API 用 GET /model/v1/generation?id=生成ID 查费用（记录可能延迟几秒）。若响应没有该头，去控制台 → 用量与费用查本次调用；不要把响应正文的 id 或 X-Request-Id 当成生成 ID，也不要将缺失费用当成零。

不支持的端点与替代

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

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

3. 验证一次请求

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

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.com/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。示例会产生少量调用费用。

失败分支

4. 回滚

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

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

API 参考 → · 兼容指南 →

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

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

1. 准备

需要 Python 3.10+、uv 和一个 Praxis Key。在控制台 → API Keys创建 Key，将它安全注入当前终端的 PRAXIS_API_KEY 环境变量；不要把 Key 写进代码或日志。保留原服务的配置与 Key，供回滚使用。以下命令在 macOS / Linux 的 Bash 中执行。

test -n "${PRAXIS_API_KEY:-}"

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

2. 选择模型

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 字段支持。
• 从 content 中读取文本块，不要假定第一块就是正文；推理模型可能先返回思考块。
• count_tokens 返回带 x-praxis-token-count: estimated 的校准估算，不是精确计费依据，见 统计 token。
• Chat 的 usage.cost 是实付金额；Responses 和 Messages 目前不返回该字段。收到 X-Praxis-Generation-Id 时，可按 生成记录 API 用 GET /model/v1/generation?id=生成ID 查费用（记录可能延迟几秒）。若响应没有该头，去控制台 → 用量与费用查本次调用；不要把响应正文的 id 或 X-Request-Id 当成生成 ID，也不要将缺失费用当成零。

不支持的操作与替代

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

3. 验证一次请求

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.com/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。示例会产生少量调用费用。

失败分支

4. 回滚

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

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

API 参考 → · 兼容指南 →

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

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

1. 准备

需要 Python 3.10+、uv 和一个 Praxis Key。在控制台 → API Keys创建 Key，将它安全注入当前终端的 PRAXIS_API_KEY 环境变量；不要把 Key 写进代码或日志。保留原服务的配置与 Key，供回滚使用。以下命令在 macOS / Linux 的 Bash 中执行。

test -n "${PRAXIS_API_KEY:-}"

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

2. 替换模型 ID

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

行为差异

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

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

不支持的操作与替代

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

3. 验证一次请求

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

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.com/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。示例会产生少量调用费用。

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

失败分支

4. 回滚

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

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

API 参考 → · Cookbook：OpenAI SDK →

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

1. 准备终端

准备 Python 3.10+ 和 uv。将 Praxis 云 API Key 放入环境变量 PRAXIS_API_KEY，不要写入代码或日志。

test -n "$PRAXIS_API_KEY"

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

2. 修改三项配置

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

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

3. 验证新配置

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

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.com') + '/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. 切流量前检查

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

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

API 参考 → · 模型指南 →

这里的每一篇都是一个完整的端到端场景：跨多个服务、用到多种能力、有可运行的结果。如果你只想接一个工具，去上面各分区；如果你想做一件事，从这里开始。

已上线的场景

正在规划的场景

以上场景正在编写中，优先级由社区反馈驱动——你想先看哪个，告诉我们就优先写。

本页带你给一个帮助中心或文档站加上「⌘K 问答」：访客按下 ⌘K（Windows / Linux 为 Ctrl+K）或点击搜索框，弹出一个居中的对话窗口，由服务型智能体依据你写好的内容回答。参照实现是仓库里「好物集」演示站（apps/kit-demo）的帮助中心页，路径 /help。

你需要：一个 Praxis API Key、一个能放后端接口的站点、一个前端页面。

工作方式

访客按 ⌘K ──▶ 页面加载 Kit，调用 getToken
                         │
                         ▼
        你的后端 POST /api/praxis-token ──(API Key)──▶ POST /agent/v1/embed_tokens
                         │
                         ◀── { token, expires_at }
Kit（modal）──(token)──▶ Praxis API ──▶ 服务型智能体

浏览器里没有 API Key。Kit 只在访客第一次打开时才加载，之后令牌由 getToken 按需取得。

1. 创建智能体并写入答案范围

1. 在 Console 打开「服务型智能体」，点「新建服务型智能体」。
2. 进入「接入与配置 · 配置 · 指令」，写明角色、回答范围和越界时怎么办，并把要回答的内容放进去。演示站的帮助中心智能体就是这样做的：把 FAQ 全文放进指令，要求「依据下面的内容回答，不编造政策、优惠或时效；范围外的问题请用户联系客服」，并且不配置任何工具。
3. 在「配置 · 安全」选择运行环境，在来源白名单里点「添加来源」，填你的站点来源（例如 https://help.example.com）。本地调试可打开「允许 localhost」。点「保存安全设置」。
4. 记下页面标题下方的智能体短号（旁边有复制按钮）。

期望：保存安全设置后出现「已保存，不产生新版本」；「接入与配置 · 试用调试」里能直接和智能体对话。

指令不是秘密，模型可能被用户要求复述，不要放不想公开的内容，见传入上下文。

2. 后端签发令牌

在 Console 的 API Keys 里创建一个专门用来签发令牌的 Key，放进后端环境变量。下面是一个与框架无关的处理函数，参照演示站的 /api/praxis-token：

const API = "https://api-develop.deepraxis.com"; // 正式地址上线后替换

export async function handlePraxisToken(request: Request, currentUserId: string | null): Promise<Response> {
  if (!currentUserId) return Response.json({ error: "请先登录" }, { status: 401 });
  const response = await fetch(`${API}/agent/v1/embed_tokens`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.PRAXIS_API_KEY}`, // 占位：只放在后端
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      agent: process.env.PRAXIS_AGENT,   // 智能体 id 或短号
      external_user_id: currentUserId,   // 来自你的登录态，不接受前端传入
    }),
    signal: AbortSignal.timeout(15_000),
  });
  // 不要把上游错误原文转给浏览器
  if (!response.ok) return Response.json({ error: "问答暂时不可用，请稍后重试" }, { status: 502 });
  const { token, expires_at } = await response.json();
  return Response.json({ token, expires_at });
}

期望：已登录请求返回 HTTP 200 和 { token, expires_at }；未登录返回 401。令牌字段与错误见嵌入令牌与终端用户。

3. 前端：⌘K 打开 modal

Kit 的 layout: "modal" 是居中的原生对话框，自带遮罩、焦点管理和 Esc 关闭。launcher: { type: "none" } 表示不显示启动按钮，由你的页面调用 open()。⌘K 快捷键由页面自己监听，Kit 不内置。

<button id="help-search">搜索或提问（⌘K）</button>

<script type="module">
  let pending;
  function loadAssistant() {
    pending ??= (async () => {
      await import("/praxis-kit.js"); // Kit 的构建产物，由你的站点提供
      await customElements.whenDefined("praxis-agent");
      const agent = document.createElement("praxis-agent");
      agent.setOptions({
        api: {
          url: "https://api-develop.deepraxis.com", // 正式地址上线后替换
          getToken: async () => {
            const response = await fetch("/api/praxis-token", { method: "POST", credentials: "same-origin" });
            if (!response.ok) throw new Error("问答暂时不可用，请稍后重试");
            return (await response.json()).token;
          },
        },
        agent: { name: "帮助中心问答" },
        layout: "modal",
        launcher: { type: "none" },
        header: { title: "帮助中心问答", icon: "help-circle" },
        startScreen: {
          greeting: "有什么可以帮你？",
          prompts: ["如何申请退货？", "在哪里查看配送进度？"].map(text => ({ label: text, prompt: text })),
        },
        composer: { placeholder: "输入你的问题…" },
      });
      document.body.appendChild(agent);
      return agent;
    })().catch(error => { pending = undefined; throw error; }); // 加载失败后允许再次尝试
    return pending;
  }

  async function openAssistant() {
    try { (await loadAssistant()).open(); }
    catch { alert("问答加载失败，请重新打开搜索。"); }
  }

  document.querySelector("#help-search").addEventListener("click", openAssistant);
  document.addEventListener("keydown", event => {
    if ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === "k") {
      event.preventDefault();
      openAssistant();
    }
  });
</script>

• open() / close() 是元素方法；窗口关闭时元素触发 praxis.close 事件，可以在里面把焦点还给搜索框。
• 想用 CDN 加载而不是自托管，见安全里的「子资源完整性」：浮动路径 https://kit-develop.praxisusercontent.com/v1/praxis-kit.js，或不可变路径 /v0.1.0/praxis-kit.js 配 integrity。
• 用 React 时换成 @deepractice-ai/praxis-kit-react 的 <PraxisAgent> 与 usePraxisAgent()，control.open() 打开，见嵌入方式。

期望：按 ⌘K 或点击按钮，弹出带遮罩的对话窗口并出现欢迎语与两个推荐问题；点推荐问题收到回复；按 Esc 关闭。

4. 验证

不打开浏览器也可以验证后端和令牌：

curl -X POST https://api-develop.deepraxis.com/agent/v1/embed_tokens \
  -H "Authorization: Bearer $PRAXIS_API_KEY" -H "Content-Type: application/json" \
  -d '{"agent":"<智能体 id 或短号>","external_user_id":"smoke-test"}'

期望：HTTP 200，返回 id、token、expires_at。随后在 Console 的「运营与管理 · 签发记录」能看到这条记录，见运营与管理。

未登录的访客

演示站为了能让任何人试用，对帮助中心智能体在未登录时用固定的 external_user_id: "guest" 签发。这只适合演示：所有访客共用同一个终端用户身份，嵌入策略里「单个终端用户的活跃会话上限」「每分钟请求上限」按这个身份合计，封禁一个访客就等于封禁全部。正式站点请在「可公开 key」上线前只对已登录用户开放，或自行给每位访客分配稳定的匿名 ID。

常见问题

• 签发返回 INVALID_PARAMS「embed policy not configured」：智能体还没有嵌入策略，回到「配置 · 安全」保存一次。
• 签发返回 EMBED_USER_BLOCKED：这个 external_user_id 在封禁名单里，在「运营与管理 · 终端用户」解封。
• 弹窗打开但无法对话：确认页面来源在来源白名单里，api.url 与签发令牌用的是同一个环境。
• 页面设置了 CSP 后脚本被拦截：见安全里的内容安全策略。

下一步：在 SaaS 后台按登录用户嵌入 · 组件参考 · 限制与错误

本页带你把服务型智能体放进一个有登录的 SaaS 后台，并做到三件事：智能体知道当前是谁、知道他正在看什么、只能查他自己的数据。参照实现是仓库里「好物集」演示站（apps/kit-demo）的两个场景：右下角浮窗客服，和课程页右侧的课程助教。

你需要：一个 Praxis API Key、一个有登录态的后端、一个前端页面，以及（想让智能体查订单时）一个你自己的 MCP 服务。

工作方式

登录用户 ──▶ 你的后端 /api/praxis-token
              │  用登录态里的用户 ID + 用户信息
              ▼
        POST /agent/v1/embed_tokens
        { agent, external_user_id, system_message }
              │
              ◀── { token, expires_at }
浏览器（Kit）──(token)──▶ Praxis API ──▶ 智能体 ──MCP──▶ 你的订单服务
                                                 └ 带 X-Praxis-External-User-Id

三类信息各走各的渠道，可信度不同，完整说明见传入上下文：

1. 创建智能体

在 Console「服务型智能体」点「新建服务型智能体」，然后在「接入与配置 · 配置」里：

1. 指令：写角色与边界。演示站客服的要点是：只回答本店商品、订单、退货与会员问题；查订单和退货必须使用订单工具，不编造订单；退货前先用一句话向用户确认订单与原因。
2. MCP 与凭据：添加 MCP 服务器，名称填 orders，类型选 HTTP，URL 填 https://你的域名/mcp。再到下方「凭据库」勾选存放该服务访问令牌的凭据库，并保存凭据库选择。凭据的「允许的主机」要包含 MCP 服务的域名，会话按它自动匹配凭据。
3. 工具与授权：在「授权方式」里，查询类工具选「自动执行」，申请退货这类写入工具选「每次询问」。
4. 安全：选运行环境，在来源白名单添加你的后台域名，保存安全设置。要允许用 system_message 之外的方式覆盖指令才打开「允许宿主覆盖指令」，这里不需要。

期望：在「试用调试」里用「模拟」页签填入 external_user_id 与 system_message，点「重新签发」后能和智能体对话，「上下文」页签的 host_context 显示你填的内容。

2. 后端：按登录用户签发，并带上用户信息

const API = "https://api-develop.deepraxis.com"; // 正式地址上线后替换

export async function handlePraxisToken(request: Request, user: { id: string; name: string; level: string } | null) {
  if (!user) return Response.json({ error: "请先登录" }, { status: 401 });
  const response = await fetch(`${API}/agent/v1/embed_tokens`, {
    method: "POST",
    headers: { Authorization: `Bearer ${process.env.PRAXIS_API_KEY}`, "Content-Type": "application/json" },
    body: JSON.stringify({
      agent: process.env.PRAXIS_AGENT_SUPPORT,
      external_user_id: user.id, // 稳定且唯一，来自登录态
      system_message: [{ type: "text", text: `当前用户 ${user.name}，会员等级 ${user.level}` }],
    }),
    signal: AbortSignal.timeout(15_000),
  });
  if (!response.ok) return Response.json({ error: "客服暂时不可用，请稍后重试" }, { status: 502 });
  const { token, expires_at } = await response.json();
  return Response.json({ token, expires_at });
}

• external_user_id 只能来自你的登录态，不接受请求体里的值；它还是下面 MCP 鉴权用的身份。
• system_message 是文本块数组，合计不超过 8192 字节。它不是秘密，模型可能被要求复述。
• 课程助教是另一个智能体：同一个接口，换 agent，system_message 里换成学员信息。演示站用一个 agent 参数在后端选择，并且只接受预先登记的几个值。

期望：HTTP 200 与 { token, expires_at }；未登录 401。

3. 前端：浮窗客服

import "/praxis-kit.js"; // Kit 的构建产物，由你的站点提供

const agent = document.createElement("praxis-agent");
agent.setOptions({
  api: {
    url: "https://api-develop.deepraxis.com",
    getToken: async () => {
      const response = await fetch("/api/praxis-token", { method: "POST", credentials: "same-origin" });
      if (!response.ok) throw new Error("客服暂时不可用，请稍后重试");
      return (await response.json()).token;
    },
  },
  agent: { name: "好物集客服" },
  layout: "popup",
  launcher: { type: "bubble", position: "bottom-right", label: "咨询客服" },
  header: { title: "好物集客服", subtitle: "通常几秒内回复" },
  startScreen: {
    greeting: "你好！有问题随时问我。",
    prompts: ["我的订单到哪了", "怎么退货"].map(text => ({ label: text, prompt: text })),
  },
});
document.body.appendChild(agent);

只在用户登录之后才创建这个元素；退出登录时整页刷新，这样上一位用户的令牌不会留在内存里。

期望：右下角出现气泡，点开出现欢迎语；问「我的订单到哪了」时智能体调用订单工具并给出该用户的订单。

4. 前端：侧栏课程助教，带页面上下文和前端工具

课程页用 layout: "sidebar"（右侧 400px 非模态面板，需要你为它在页面上留出位置）。助教要知道「学员正在看哪一课、播到哪里」，用两个入口：页面上下文放每轮都用得上的小事实，前端工具放需要时才读的数据。

先在智能体定义的 tools 里声明前端工具（类型 custom，写法见前端工具与页面上下文）：

{
  "type": "custom",
  "name": "get_playback_progress",
  "description": "读取学员当前的视频播放进度",
  "input_schema": { "type": "object", "properties": {}, "additionalProperties": false }
}

再在页面里实现：

const tutor = document.createElement("praxis-agent");
tutor.setOptions({
  api: { url: "https://api-develop.deepraxis.com", getToken: fetchTokenForTutor },
  agent: { name: "课程助教" },
  layout: "sidebar",
  launcher: { type: "none" },
  header: { title: "课程助教", icon: "message-circle" },
});

// 页面上下文：随每条用户消息附带，标记为不可信
tutor.setReadable("course", "降噪耳机入门");
tutor.setReadable("lesson", "第 1 课：认识主动降噪");

// 前端工具：智能体调用时在页面里执行，返回值交还给智能体
tutor.onClientTool = ({ name }) => {
  if (name !== "get_playback_progress") throw new Error("unknown tool");
  return { lesson: "第 1 课：认识主动降噪", position_seconds: 83, duration_seconds: 300, playing: true };
};

document.body.appendChild(tutor);
tutor.addEventListener("praxis.open", () => document.body.classList.add("tutor-open"));
tutor.addEventListener("praxis.close", () => document.body.classList.remove("tutor-open"));
document.querySelector("#open-tutor").addEventListener("click", () => tutor.open());

换课时再调用一次 setReadable("lesson", …)，之后每条消息自动带最新值。onClientTool 是元素的 JavaScript 属性，不是 setOptions 的选项；对不认识的工具名必须抛错。限制、超时与 React 写法见前端工具与页面上下文。

期望：打开侧栏后问「我现在看到哪了」，智能体调用 get_playback_progress 并据返回值回答，页面上能看到它没有编造进度。

5. 服务端按用户鉴权的 MCP 工具

平台调用你的 MCP 服务时会带上 X-Praxis-External-User-Id（令牌里的 external_user_id）、X-Praxis-Agent-Id、X-Praxis-Session-Id。工具必须按这个头限定数据范围，不要用模型传来的参数确定用户。

// MCP 请求入口：先校验平台出示的访问令牌，再取用户身份
export async function handleMcp(request: Request, expectedToken: string) {
  if (request.headers.get("authorization") !== `Bearer ${expectedToken}`) {
    return Response.json({ error: "未授权" }, { status: 401 });
  }
  const userId = request.headers.get("X-Praxis-External-User-Id"); // 每个请求单独读取
  // list_orders: 只返回 userId 名下的订单
  // request_return: 先确认订单属于 userId，再受理
  // userId 缺失或不认识 → 以工具错误返回，不返回任何数据
}

演示站的 MCP 服务有两个工具：list_orders（readOnlyHint: true）和 request_return（destructiveHint: true，参数 order_id、reason，订单不属于当前用户时返回「订单不存在或不属于当前用户」）。每个请求单独创建服务与闭包，并发请求之间不会串用户。

期望：用 alice 登录问订单只看到 alice 的订单；换 bob 登录看到 bob 的；让智能体「查 alice 的订单」时 bob 拿不到任何数据。询问确认只是帮用户确认意图，不是安全手段，详见工具授权。

常见问题

• 智能体说查不了订单：在「配置 · MCP 与凭据」确认 MCP 服务器地址可访问，凭据库已勾选，且凭据的允许主机包含该域名。
• 工具总是返回「缺少用户身份」：只有会话属于某位终端用户时才带身份头；确认令牌签发时传了 external_user_id。
• 侧栏遮住了页面内容：侧栏是浮在页面上的面板，要用 praxis.open / praxis.close 事件给页面留出空位。
• 前端工具总是「not available」：onClientTool 要在智能体调用之前赋到元素上。

下一步：给文档站加问答助手 · 令牌与终端用户 · 安全