Droid BYOK Unleashed

一个用于 Droid CLI BYOK 模式的中间人代理服务，解决推理模型思维链内容导致的工具调用失败问题。

问题背景

在使用 Droid CLI 的 BYOK（自带密钥）模式连接推理模型（如 DeepSeek R1）时，模型返回的 <think>...</think> 标签会导致：

工具调用（Tool Use）解析失败
JSON 格式错误
上下文 Token 浪费

解决方案

本代理服务作为 Droid CLI 和上游推理服务之间的中间层：

Droid CLI  <-->  Proxy (localhost:5000)  <-->  上游 API (DeepSeek/OpenAI/Anthropic/Gemini 等)

核心功能

响应清洗 - 实时过滤流式响应中的 <think> 块，确保 Droid CLI 收到纯净的输出
思考可视化 - 被过滤的思考过程在代理控制台彩色显示，便于调试
请求增强 - 可注入推理参数激活模型思维链能力
多 API 格式适配 - 支持 OpenAI、Anthropic、Gemini、Azure OpenAI 等多种 API 格式转换
LLM 参数管理 - 支持通过环境变量设置默认参数，请求参数优先级更高
前端配置界面 - 提供 React 前端用于可视化配置和聊天测试

快速开始

1. 安装后端依赖

pip install -r requirements.txt

2. 配置文件

复制示例配置文件并填入真实配置：

# Windows
copy proxy_config.example.json proxy_config.json

# Linux/macOS
cp proxy_config.example.json proxy_config.json

然后编辑 proxy_config.json，填入您的上游服务地址与 API Key（支持按 Profile 配置不同上游/模型路由）。

说明：代理端口与代理鉴权从 proxy_config.json 的 proxy.port / proxy.api_key 读取；环境变量 PROXY_PORT / PROXY_API_KEY 不会生效。

3. 配置环境变量（可选）

说明：项目不会自动加载 .env 文件；如果你希望使用 .env，请在启动前用你自己的方式加载（例如 shell set/export、或使用 dotenv 工具）。

复制 .env.example 为 .env 并按需编辑：

# Windows
copy .env.example .env

# Linux/macOS
cp .env.example .env

或直接设置环境变量：

# Windows
set UPSTREAM_API_KEY=your-api-key-here
set UPSTREAM_BASE_URL=https://api.deepseek.com

# Linux/macOS
export UPSTREAM_API_KEY=your-api-key-here
export UPSTREAM_BASE_URL=https://api.deepseek.com

4. 启动代理服务

python proxy.py

5. (可选) 启动前端

cd frontend
npm install
npm run dev

前端默认运行在 http://localhost:5173，会自动连接到代理服务。

Droid CLI 配置

BYOK 自定义模型配置

编辑 ~/.factory/config.json，在 custom_models 数组中添加配置：

{
  "custom_models": [
    {
      "model_display_name": "claude-opus-4-5-byok-unleashed",
      "model": "claude-opus-4-5",
      "base_url": "http://localhost:5000/v1",
      "api_key": "your-proxy-api-key",
      "provider": "generic-chat-completion-api",
      "max_tokens": 64000
    }
  ]
}

配置说明：

字段	说明
`model_display_name`	在 Droid CLI `/model` 选择器中显示的名称（可随意设置）
`model`	发送给代理的模型标识符（代理会根据 Profile 路由到上游）
`base_url`	代理地址，必须以 `/v1` 结尾
`api_key`	代理鉴权密钥（对应 `proxy_config.json` 中的 `proxy.api_key`），如未配置代理鉴权可填任意值
`provider`	必须使用 `generic-chat-completion-api`（OpenAI Chat Completions 兼容格式）
`max_tokens`	最大输出 Token 数

重要提醒：model 字段的值会透传到上游 API，必须是上游服务能识别的模型名称。

配置完成后，在 Droid CLI 中使用 /model 命令即可看到自定义模型。

环境变量配置

proxy_config.json 是主配置（Profiles/路由/上游/代理鉴权等）。环境变量主要用于两类场景：

首次启动且不存在 proxy_config.json 时：用 UPSTREAM_* / REASONING_* / FILTER_THINKING_TAGS 生成默认 Profile
运行时默认 LLM 参数：通过 DEFAULT_* 注入（当客户端未显式传入时生效）

基础配置

变量	说明	默认值
`UPSTREAM_API_KEY`	上游服务 API 密钥	-
`UPSTREAM_BASE_URL`	上游服务地址	`https://api.deepseek.com`

默认 LLM 参数

这些参数在客户端未指定时使用，客户端请求参数优先级更高。

变量	说明	范围
`DEFAULT_TEMPERATURE`	控制随机性	0-2
`DEFAULT_TOP_P`	核采样阈值	0-1
`DEFAULT_TOP_K`	Top-k 采样	1-100
`DEFAULT_MAX_TOKENS`	最大输出 Token 数	1-1000000
`DEFAULT_PRESENCE_PENALTY`	存在惩罚	-2 到 2
`DEFAULT_FREQUENCY_PENALTY`	频率惩罚	-2 到 2
`DEFAULT_SEED`	随机种子	整数

推理模型配置

变量	说明	可选值
`REASONING_ENABLED`	是否启用推理模式	`true`/`false`
`REASONING_TYPE`	推理参数类型	`deepseek`, `openai`, `anthropic`, `gemini`, `qwen`, `openrouter`, `custom`
`REASONING_EFFORT`	推理强度	`none`, `minimal`, `low`, `medium`, `high`, `auto`
`REASONING_BUDGET_TOKENS`	思考 Token 预算	整数
`REASONING_CUSTOM_PARAMS`	自定义推理参数 (JSON)	JSON 字符串
`FILTER_THINKING_TAGS`	是否过滤 `<think>` 标签	`true`/`false` (默认 `true`)

API 端点

核心端点

端点	方法	说明
`/v1/chat/completions`	POST	聊天补全（兼容 OpenAI 格式，支持流式）
`/v1/models`	GET	获取模型列表
`/v1/thinking/stream`	GET	Thinking 内容 SSE（供前端 ThinkingViewer 使用）
`/health`	GET	健康检查

配置管理端点

端点	方法	说明
`/v1/config/reasoning/types`	GET	获取支持的推理类型和强度选项
`/v1/config/proxy`	GET	获取代理配置
`/v1/config/proxy`	PUT	更新代理配置
`/v1/config/profiles`	GET	获取全部 Profiles
`/v1/config/profiles`	POST	创建 Profile
`/v1/config/profiles/<profile_id>`	GET	获取单个 Profile
`/v1/config/profiles/<profile_id>`	PUT	更新 Profile
`/v1/config/profiles/<profile_id>`	DELETE	删除 Profile
`/v1/config/profiles/test`	POST	测试模型名匹配结果
`/v1/config/default-profile`	PUT	设置默认 Profile
`/v1/config/export`	GET	导出完整配置
`/v1/config/import`	POST	导入配置（支持 merge/replace）

使用示例

基本聊天请求

curl -X POST http://localhost:5000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-chat",
    "messages": [{"role": "user", "content": "Hello!"}],
    "stream": true
  }'

带参数的请求

curl -X POST http://localhost:5000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-chat",
    "messages": [{"role": "user", "content": "Explain quantum computing"}],
    "stream": true,
    "temperature": 0.7,
    "max_tokens": 2048
  }'

使用自定义上游 API

通过请求头指定上游服务：

curl -X POST http://localhost:5000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -H "X-Upstream-Base-URL: https://api.openai.com" \
  -H "X-API-Format: openai" \
  -d '{
    "model": "gpt-4",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

注意：如果在 proxy_config.json 里配置了 proxy.api_key，则请求头 Authorization 会被用于代理鉴权（而不是上游鉴权）。这时上游 api_key 需要写在对应 Profile 的 upstream.api_key 中（或使用未开启代理鉴权的模式）。

支持的 API 格式

格式	说明	适用服务
`openai`	OpenAI 兼容 API（默认）	OpenAI, DeepSeek, 兼容服务
`openai-response`	OpenAI Response API	OpenAI Response API
`anthropic`	Anthropic Claude API	Claude 系列
`gemini`	Google Gemini API	Gemini 系列
`azure-openai`	Azure OpenAI Service	Azure 托管的 OpenAI

支持的推理模型类型

类型	参数格式	适用模型
`deepseek`	`thinking.type`	DeepSeek R1/V3.1；Zhipu GLM-4.5/4.6（glm-4.5/glm-4.6）
`openai`	`reasoning_effort`	OpenAI o1/o3/GPT-5（含 GPT-5.1 Codex 等）
`anthropic`	`thinking.type` + `thinking.budget_tokens`	Claude 3.7/4（含 Claude 4/Opus 4.5 等）
`gemini`	`thinkingConfig.includeThoughts` + `thinkingConfig.thinkingBudget`	Gemini 2.5+（含 Gemini 3 系列）
`qwen`	`enable_thinking` + `thinking_budget`	Qwen3
`openrouter`	`reasoning.enabled` + `reasoning.effort`	OpenRouter
`custom`	自定义 JSON（Profile 的 `reasoning.custom_params`）	任意

项目结构

droid-byok-unleashed/
├── proxy.py              # 主代理服务
├── config_manager.py     # Profile/Proxy 配置管理（当前主配置）
├── proxy_config.json     # 持久化配置文件（不提交到 Git）
├── proxy_config.example.json  # 配置文件模板
├── reasoning_config.py   # 推理模型配置
├── reasoning_builder.py  # 推理参数构建器
├── api_format_adapter.py # API 格式适配器
├── requirements.txt      # Python 依赖
├── .env.example          # 环境变量示例
├── test_filter.py        # StreamFilter 单元测试
├── test_params.py        # LLM 参数处理单元测试
├── test_proxy.py         # 端到端脚本（手动运行，需先启动服务）
└── frontend/             # React 前端
    ├── src/
    │   ├── components/   # UI 组件
    │   ├── hooks/        # React Hooks
    │   ├── services/     # API 服务
    │   └── types/        # TypeScript 类型定义
    └── package.json

运行测试

# 推荐：pytest
python -m pytest -q

# 手动端到端测试（需先启动 python proxy.py）
python test_proxy.py

技术栈

后端

Python 3.8+
Flask + Flask-CORS
Requests

前端

React 19 + TypeScript
Vite
Tailwind CSS
Lucide Icons

参考项目

UI 设计参考: oroio
LLM 配置设计参考: cherry-studio

Name		Name	Last commit message	Last commit date
Latest commit History 9 Commits
frontend		frontend
.env.example		.env.example
.gitignore		.gitignore
README.md		README.md
agents.md		agents.md
api_format_adapter.py		api_format_adapter.py
config_manager.py		config_manager.py
proxy.py		proxy.py
proxy_config.example.json		proxy_config.example.json
reasoning_builder.py		reasoning_builder.py
reasoning_config.py		reasoning_config.py
requirements.txt		requirements.txt
test_codex.json		test_codex.json
test_filter.py		test_filter.py
test_params.py		test_params.py
test_proxy.py		test_proxy.py
test_request.json		test_request.json
update_config.json		update_config.json

Folders and files

Latest commit

History

Repository files navigation

Droid BYOK Unleashed

问题背景

解决方案

核心功能

快速开始

1. 安装后端依赖

2. 配置文件

3. 配置环境变量（可选）

4. 启动代理服务

5. (可选) 启动前端

Droid CLI 配置

BYOK 自定义模型配置

环境变量配置

基础配置

默认 LLM 参数

推理模型配置

API 端点

核心端点

配置管理端点

使用示例

基本聊天请求

带参数的请求

使用自定义上游 API

支持的 API 格式

支持的推理模型类型

项目结构

运行测试

技术栈

后端

前端

参考项目

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages