droid-patch

English | 简体中文

用于修补 droid 二进制文件的 CLI 工具。

安装

npm install -g droid-patch
# 或直接使用 npx
npx droid-patch --help

使用方法

修补并创建别名

# 使用 --is-custom 修补并创建别名
npx droid-patch --is-custom droid-custom

# 使用 --skip-login 跳过登录验证
npx droid-patch --skip-login droid-nologin

# 使用 --websearch 启用本地搜索代理
npx droid-patch --websearch droid-search

# 使用 --websearch --standalone 启用完全本地模式（mock 非 LLM API）
npx droid-patch --websearch --standalone droid-local

# 使用 --reasoning-effort 为自定义模型启用推理功能
npx droid-patch --reasoning-effort droid-reasoning

# 组合多个修补选项
npx droid-patch --is-custom --skip-login --websearch --reasoning-effort droid-full

# 指定 droid 二进制文件路径
npx droid-patch --skip-login -p /path/to/droid my-droid

# 试运行 - 验证修补但不实际修改文件
npx droid-patch --skip-login --dry-run droid

# 详细输出
npx droid-patch --skip-login -v droid

输出到指定目录

# 输出修补后的二进制文件到当前目录
npx droid-patch --skip-login -o . my-droid

# 输出到指定目录
npx droid-patch --skip-login -o /path/to/dir my-droid

可用选项

| 选项 | 说明 | | --------------------- | ----------------------------------------------------------------------------------------------- | | --is-custom | 将 isCustom:!0 修改为 isCustom:!1（为自定义模型启用上下文压缩） | | --skip-login | 通过注入假的 FACTORY_API_KEY 跳过登录验证 | | --api-base <url> | 替换 API URL（单独使用：二进制补丁，最多 22 字符；与 --websearch 配合：代理转发目标，无限制） | | --websearch | 外部搜索模式：使用 Smithery、Google PSE、Tavily、Serper、Brave、SearXNG、DuckDuckGo | | --websearch-proxy | 原生搜索模式：使用模型内置的 web_search 能力（需要 proxy 插件） | | --standalone | 独立模式：mock 非 LLM 的 Factory API（与 --websearch 或 --websearch-proxy 配合使用） | | --reasoning-effort | 为自定义模型启用推理强度 UI 选择器（默认 high；可选：high、max、xhigh） | | --disable-telemetry | 禁用遥测数据上传和 Sentry 错误报告 | | --dry-run | 验证修补但不实际修改二进制文件 | | -p, --path <path> | droid 二进制文件路径（默认：~/.droid/bin/droid） | | -o, --output <dir> | 修补后二进制文件的输出目录（直接创建文件，不创建别名） | | --no-backup | 跳过创建原始二进制文件的备份 | | -v, --verbose | 启用详细输出 |

管理自定义模型

# 列出所有自定义模型
npx droid-patch list-models

# 交互式添加模型
npx droid-patch add-model

# 命令行添加模型
npx droid-patch add-model \
  -m "claude-sonnet-4-20250514" \
  -n "Sonnet [proxy]" \
  -u "http://127.0.0.1:20002/droid" \
  -k "your-api-key" \
  -p "anthropic"

# 在指定位置插入模型
npx droid-patch add-model -i 0  # 交互式，插入到位置 0

# 删除模型（支持 index、ID 或 displayName）
npx droid-patch remove-model 0                    # 按索引
npx droid-patch remove-model "custom:Sonnet-[proxy]-1"  # 按 ID
npx droid-patch remove-model "Sonnet [proxy]"    # 按显示名称

模型 ID 格式：custom:{DisplayName}-{index}

• DisplayName 中的空格会被替换为 -
• index 是模型在数组中的位置（从 0 开始）
• 示例：displayName: "Opus [proxy]" → id: "custom:Opus-[proxy]-0"

重要：删除或插入模型时，后续模型的 ID 会自动更新（因为 index 会变化）。

管理别名和文件

# 列出所有别名（显示版本、flags、创建时间）
npx droid-patch list

# 删除别名
npx droid-patch remove <alias-name>

# 通过路径删除修补后的二进制文件
npx droid-patch remove ./my-droid
npx droid-patch remove /path/to/patched-binary

# 按条件删除别名
npx droid-patch remove --patch-version=0.4.0     # 按 droid-patch 版本
npx droid-patch remove --droid-version=1.0.40    # 按 droid 版本
npx droid-patch remove --flag=websearch          # 按功能 flag

# 清除所有 droid-patch 数据（别名、二进制文件、元数据）
npx droid-patch clear

更新别名

当原始 droid 二进制文件更新后，可以重新为所有别名应用补丁：

# 更新所有别名
npx droid-patch update

# 更新指定别名
npx droid-patch update <alias-name>

# 预览（不实际更新）
npx droid-patch update --dry-run

# 使用不同的 droid 二进制文件
npx droid-patch update -p /path/to/new/droid

update 命令会读取创建别名时保存的元数据，自动重新应用相同的补丁。

检查版本

npx droid-patch version

PATH 配置

创建别名时（不使用 -o），工具会尝试安装到已在 PATH 中的目录（如 ~/.local/bin）。如果不可用，需要将别名目录添加到 PATH：

# 添加到 shell 配置文件（~/.zshrc、~/.bashrc 等）
export PATH="$HOME/.droid-patch/aliases:$PATH"

工作原理

1. 修补：工具在 droid 二进制文件中搜索特定的字节模式，并用等长的替换内容进行替换
2. 创建别名（不使用 -o）：
   • 将修补后的二进制文件复制到 ~/.droid-patch/bins/
   • 在 PATH 目录或 ~/.droid-patch/aliases/ 中创建符号链接
   • 在 macOS 上，自动使用 codesign 重新签名二进制文件
3. 直接输出（使用 -o）：
   • 将修补后的二进制文件直接保存到指定目录
   • 在 macOS 上，自动使用 codesign 重新签名二进制文件

可用的修补选项

--is-custom

将 isCustom:!0（true）改为 isCustom:!1（false）。

用途：为自定义模型启用上下文压缩（自动摘要）功能，该功能通常仅对官方模型可用。

注意：副作用未知 - 在生产环境使用前请充分测试。

--skip-login

将二进制文件中所有 process.env.FACTORY_API_KEY 引用替换为硬编码的假密钥 "fk-droid-patch-skip-00000"。

用途：无需设置 FACTORY_API_KEY 环境变量即可跳过登录/认证要求。

工作原理：

• 原始代码通过检查 process.env.FACTORY_API_KEY 进行认证
• 修补后，代码直接使用假密钥字符串，绕过环境变量检查
• 这是二进制级别的修补，因此在所有终端会话中都有效，无需任何环境设置

--api-base <url>

替换 Factory API 基础 URL。根据使用方式有不同的行为：

1. 单独使用（不与 --websearch 配合）

通过二进制补丁将 https://api.factory.ai 替换为你的自定义 URL。

• 限制：URL 必须不超过 22 个字符（与原始 URL 长度相同）
• 用途：直接替换 API URL，不使用代理

# 有效的 URL（<=22 个字符）
npx droid-patch --api-base "http://127.0.0.1:3000" droid-local
npx droid-patch --api-base "http://localhost:80" droid-local

# 无效（太长）
npx droid-patch --api-base "http://my-long-domain.com:3000" droid  # 错误！

2. 与 --websearch 配合使用

通过配置代理脚本中的 FACTORY_API 变量来设置 WebSearch 代理的转发目标 URL。

• 无长度限制：可以使用任何有效的 URL
• 用途：将非搜索请求转发到你的自定义 LLM 后端

# 转发到自定义后端（无长度限制）
npx droid-patch --websearch --api-base "http://127.0.0.1:20002" droid-custom
npx droid-patch --websearch --api-base "http://my-proxy.example.com:3000" droid-custom

--websearch vs --websearch-proxy

重要：--websearch 和 --websearch-proxy 互斥 - 只能选择其中一个。

| 模式 | 描述 | 需要 | | ------------------- | ------------------------ | ----------------------- | | --websearch | 外部搜索提供商 | 环境变量配置 | | --websearch-proxy | 模型原生 web_search 能力 | proxy 插件 + 自定义模型 |

--websearch

通过本地代理服务器启用 外部搜索提供商 的 WebSearch 功能。

用途：使用第三方搜索 API 实现 WebSearch。

特性：

• 多搜索提供商：自动降级（Smithery > Google PSE > Tavily > Serper > Brave > SearXNG > DuckDuckGo）
• 每实例独立代理：每个 droid 实例运行自己的代理，自动分配端口
• 自动清理：droid 退出时代理自动停止
• 转发目标：使用 --api-base 配合 --websearch 可将非搜索请求转发到自定义后端
• 非交互直通：运行 --version/version、--help/help、completion(s)、exec 等命令时不会启动代理

使用方法：

# 创建带 websearch 的别名（使用官方 Factory API）
npx droid-patch --websearch droid-search

# 创建带 websearch + 自定义后端的别名
npx droid-patch --websearch --api-base=http://127.0.0.1:20002 droid-custom

# 直接运行 - 一切都是自动的！
droid-search

--websearch-proxy

通过 模型原生 web_search 能力（如 Claude 的 web_search_20250305 工具）启用 WebSearch。

用途：使用 LLM 提供商内置的网页搜索，而非外部提供商。

需求：

1. 在 ~/.factory/settings.json 中配置支持的 provider（anthropic 或 openai）的 自定义模型
2. Proxy 插件（jixoai/proxy）处理 Claude Code 格式转换

特性：

• 从 ~/.factory/settings.json 读取模型配置
• 支持 Anthropic（web_search_20250305）和 OpenAI（web_search）原生工具
• 自动检测当前模型的 provider
• 无需外部 API 密钥（使用 LLM 提供商的搜索）

使用方法：

# 创建带原生 websearch 的别名（需要 proxy 插件）
npx droid-patch --is-custom --skip-login --websearch-proxy droid-native

# 配合推理强度使用
npx droid-patch --is-custom --skip-login --reasoning-effort --websearch-proxy droid-full

# 调试模式
DROID_SEARCH_DEBUG=1 droid-native

Proxy 插件设置：

--websearch-proxy 模式需要 jixoai/proxy 插件在 Claude Code 格式和标准 Anthropic API 格式之间转换。

# 克隆并设置 proxy
git clone https://github.com/jixoai/proxy.git
cd proxy

# 安装并运行（详见 proxy README）
pnpm install
pnpm dev

在 ~/.factory/settings.json 中配置自定义模型：

{
  "customModels": [
    {
      "model": "claude-sonnet-4-20250514",
      "id": "custom:Claude-Proxy-0",
      "baseUrl": "http://127.0.0.1:20002/droid",
      "apiKey": "your-api-key",
      "displayName": "Claude [proxy]",
      "provider": "anthropic"
    }
  ],
  "sessionDefaultSettings": {
    "model": "custom:Claude-Proxy-0"
  }
}

--reasoning-effort

通过修补二进制文件为自定义模型启用推理强度控制：

1. 将 supportedReasoningEfforts 从 ["none"] 改为 ["high","max","xhigh"]
2. 将 defaultReasoningEffort 从 "none" 改为 "high"
3. 启用推理强度 UI 选择器（通常对自定义模型隐藏）
4. 绕过验证以允许通过 settings.json 设置 xhigh

用途：允许自定义模型使用通常仅对官方模型可用的推理强度功能。

工作原理：

• 当 supportedReasoningEfforts.length > 1 时，droid UI 会显示推理强度选择器
• 自定义模型硬编码为 ["none"]，隐藏了选择器
• 此补丁将值改为 ["high","max","xhigh"] 并修改 UI 条件以显示选择器
• 推理强度设置将发送到您的自定义模型 API

使用方法：

# 为自定义模型启用推理强度
npx droid-patch --reasoning-effort droid-reasoning

# 与其他补丁组合使用
npx droid-patch --is-custom --reasoning-effort droid-full

配置 xhigh 推理强度：

默认推理强度为 high。要使用 xhigh（超高），请编辑设置文件：

# 编辑 ~/.factory/settings.json
{
  "model": "custom:Your-Model-0",
  "reasoningEffort": "xhigh",
  // ... 其他设置
}

可用的值： | 值 | 描述 | |-------|-------------| | high | 高推理强度（补丁后的默认值） | | max | 最大推理强度 | | xhigh | 超高推理强度 |

注意：xhigh 值会绕过验证直接发送到 API。请确保您的自定义模型/代理支持此参数。

--standalone

与 --websearch 配合使用时启用独立模式。在此模式下，非 LLM 的 Factory API 会在本地 mock，而不是转发到 Factory 服务器。

用途：减少不必要的网络请求，实现完全本地化运行（LLM API 调用除外）。

工作原理：

• 白名单方式：只有 /api/llm/a/*（Anthropic）和 /api/llm/o/*（OpenAI）会转发到上游
• 其他所有 Factory API 都会被 mock：
  • /api/sessions/create → 返回唯一的本地 session ID
  • /api/cli/whoami → 返回 401（触发本地 token 回退）
  • /api/tools/get-url-contents → 返回 404（触发本地 URL 获取）
  • 其他 API → 返回空 {} 响应

使用方法：

# 独立模式 + websearch
npx droid-patch --websearch --standalone droid-local

# 与其他补丁组合实现完全本地化
npx droid-patch --is-custom --skip-login --websearch --standalone droid-full-local

--disable-telemetry

禁用遥测数据上传和 Sentry 错误报告。

用途：阻止 droid 向 Factory 服务器发送使用数据和错误报告。

工作原理：

• 破坏 Sentry 环境变量检查（ENABLE_SENTRY、VITE_VERCEL_ENV）
• 使 flushToWeb() 始终提前返回，阻止任何遥测 fetch 请求

使用方法：

# 仅禁用遥测
npx droid-patch --disable-telemetry droid-private

# 与其他补丁组合
npx droid-patch --is-custom --skip-login --disable-telemetry droid-private

WebSearch 配置指南

--websearch 功能支持多个搜索提供商。通过 shell 配置文件（~/.zshrc、~/.bashrc 等）中的环境变量进行配置。

搜索提供商优先级

代理按以下顺序尝试提供商，使用第一个成功的：

| 优先级 | 提供商 | 质量 | 免费额度 | 设置难度 | | ------ | ------------ | ---- | --------------------- | -------- | | 1 | Smithery Exa | 优秀 | 免费（通过 Smithery） | 简单 | | 2 | Google PSE | 很好 | 10,000 次/天 | 中等 | | 3 | Tavily | 很好 | 免费额度（不固定） | 简单 | | 4 | Serper | 很好 | 2,500 免费额度 | 简单 | | 5 | Brave Search | 好 | 2,000 次/月 | 简单 | | 6 | SearXNG | 好 | 无限（自托管） | 较难 | | 7 | DuckDuckGo | 基本 | 无限 | 无需配置 |

1. Smithery Exa（推荐）

Smithery Exa 通过 MCP 协议提供高质量的语义搜索结果。Smithery 作为 Exa 搜索 API 的免费代理。

设置步骤

1. 创建 Smithery 账号

   • 访问 smithery.ai
   • 注册免费账号

2. 获取 API Key

   • 进入账号设置
   • 复制 API key

3. 获取 Profile ID

   • 访问 smithery.ai/server/exa
   • Profile ID 显示在连接 URL 或设置中

4. 配置环境变量

   # 添加到 ~/.zshrc 或 ~/.bashrc
   export SMITHERY_API_KEY="your_api_key_here"
   export SMITHERY_PROFILE="your_profile_id"

价格

• 通过 Smithery 免费（Smithery 免费代理 Exa API）
• 注意：官方 Exa API (exa.ai) 是收费的，但通过 Smithery 可以免费使用

2. Google 可编程搜索引擎 (PSE)

Google PSE 提供高质量的搜索结果，免费额度充足。

设置步骤

第一步：创建可编程搜索引擎

1. 访问 Google 可编程搜索引擎控制台
2. 点击 "添加" 创建新的搜索引擎
3. 配置：
   • 要搜索的网站：输入 * 以搜索整个网络
   • 名称：给它一个描述性的名称（如 "Web Search"）
4. 点击 "创建"
5. 点击新搜索引擎的 "控制面板"
6. 复制 搜索引擎 ID (cx) - 格式类似 017576662512468239146:omuauf_lfve

第二步：获取 API Key

1. 访问 Google Cloud Console
2. 创建新项目或选择现有项目
3. 启用 Custom Search API：
   • 进入 "API 和服务" > "库"
   • 搜索 "Custom Search API"
   • 点击 "启用"
4. 创建凭据：
   • 进入 "API 和服务" > "凭据"
   • 点击 "创建凭据" > "API 密钥"
   • 复制 API 密钥

第三步：配置环境变量

# 添加到 ~/.zshrc 或 ~/.bashrc
export GOOGLE_PSE_API_KEY="AIzaSy..."        # 你的 API 密钥
export GOOGLE_PSE_CX="017576662512468239146:omuauf_lfve"  # 你的搜索引擎 ID

免费额度限制

• 每天 10,000 次查询 免费
• 每次查询最多 10 个结果
• 超出后：每 1,000 次查询 $5

3. Tavily

Tavily 提供简单易用的 Web 搜索 API。

设置步骤

1. 创建账号

   • 访问 tavily.com
   • 注册账号

2. 获取 API Key

   • 在控制台/API 设置中找到并复制 API key

3. 配置环境变量

   # 添加到 ~/.zshrc 或 ~/.bashrc
   export TAVILY_API_KEY="your_api_key_here"

4. Serper

Serper 通过易用的 API 提供 Google 搜索结果。

设置步骤

1. 创建账号

   • 访问 serper.dev
   • 注册免费账号

2. 获取 API Key

   • 登录后，API key 显示在仪表板上
   • 复制 API key

3. 配置环境变量

   # 添加到 ~/.zshrc 或 ~/.bashrc
   export SERPER_API_KEY="your_api_key_here"

免费额度

• 注册时获得 2,500 免费额度
• 1 额度 = 1 次搜索查询
• 可购买付费计划获得更多用量

5. Brave Search

Brave Search API 提供注重隐私的搜索结果。

设置步骤

1. 创建账号

   • 访问 brave.com/search/api
   • 点击 "开始使用"

2. 订阅计划

   • 选择 免费 计划（每月 2,000 次查询）
   • 或付费计划以获得更多查询次数

3. 获取 API Key

   • 进入 API 仪表板
   • 复制 API key

4. 配置环境变量

   # 添加到 ~/.zshrc 或 ~/.bashrc
   export BRAVE_API_KEY="BSA..."

免费额度

• 每月 2,000 次查询 免费
• 速率限制：每秒 1 次查询
• 付费计划起价 $5/月，20,000 次查询

6. SearXNG（自托管）

SearXNG 是一个免费、注重隐私的元搜索引擎，可以自托管。

设置步骤

选项 A：使用公共实例

可以使用公共 SearXNG 实例，但可用性和可靠性不稳定。

# 公共实例示例（请检查是否可用）
export SEARXNG_URL="https://searx.be"

在 searx.space 查找公共实例

选项 B：使用 Docker 自托管

1. 使用 Docker 运行 SearXNG

   docker run -d \
     --name searxng \
     -p 8080:8080 \
     -e SEARXNG_BASE_URL=http://localhost:8080 \
     searxng/searxng

2. 配置环境变量

   # 添加到 ~/.zshrc 或 ~/.bashrc
   export SEARXNG_URL="http://localhost:8080"

优点

• 无限搜索
• 不需要 API 密钥
• 注重隐私
• 聚合多个搜索引擎的结果

缺点

• 需要自托管才能保证可靠性
• 公共实例可能较慢或不可用

7. DuckDuckGo（默认备用）

当没有配置其他提供商或其他提供商不可用时，自动使用 DuckDuckGo 作为最终备用。

配置

无需配置！ DuckDuckGo 开箱即用。

限制

• HTML 抓取（不如 API 可靠）
• 与其他提供商相比结果较基础
• 大量使用可能被限速

快速配置示例

最简设置（免费，无需 API Key）

直接使用 DuckDuckGo 备用：

npx droid-patch --websearch droid-search
droid-search  # 立即使用 DuckDuckGo 工作

推荐设置（最佳质量）

# 添加到 ~/.zshrc 或 ~/.bashrc
export SMITHERY_API_KEY="your_smithery_key"
export SMITHERY_PROFILE="your_profile_id"

# 备用：Google PSE
export GOOGLE_PSE_API_KEY="your_google_key"
export GOOGLE_PSE_CX="your_search_engine_id"

经济实惠设置（全免费）

# 添加到 ~/.zshrc 或 ~/.bashrc

# 选项 1：Google PSE（每天 10,000 次免费）
export GOOGLE_PSE_API_KEY="your_google_key"
export GOOGLE_PSE_CX="your_search_engine_id"

# 选项 2：Tavily（免费额度不固定）
export TAVILY_API_KEY="your_tavily_key"

# 选项 3：Serper（2,500 免费额度）
export SERPER_API_KEY="your_serper_key"

# 选项 4：Brave（每月 2,000 次免费）
export BRAVE_API_KEY="your_brave_key"

# DuckDuckGo 始终作为最终备用可用

调试模式

启用详细日志以排查搜索问题：

export DROID_SEARCH_DEBUG=1
droid-search

示例

# 快速开始：创建带 websearch 的 droid
npx droid-patch --websearch droid-search
droid-search  # 直接使用！

# 全功能 droid
npx droid-patch --is-custom --skip-login --websearch --reasoning-effort droid-full

# 独立模式：websearch + mock 非 LLM API
npx droid-patch --websearch --standalone droid-local

# 隐私模式：禁用遥测
npx droid-patch --disable-telemetry droid-private

# 完全本地化：所有功能组合
npx droid-patch --is-custom --skip-login --websearch --standalone --disable-telemetry droid-full-local

# websearch + 自定义后端
npx droid-patch --websearch --api-base=http://127.0.0.1:20002 droid-custom

# 在当前目录创建独立的修补后二进制文件
npx droid-patch --skip-login -o . my-droid
./my-droid --version

# 列出所有别名及版本信息
npx droid-patch list

# 清理
npx droid-patch remove droid-search              # 删除单个别名
npx droid-patch remove --flag=websearch          # 删除所有 websearch 别名
npx droid-patch remove --flag=standalone         # 删除所有 standalone 别名
npx droid-patch remove --patch-version=0.4.0     # 按 droid-patch 版本删除
npx droid-patch clear                            # 删除所有

许可证

MIT