`bash


列出所有自定义模型

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

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

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

$3

`bash


列出所有别名（显示版本、flags、创建时间）

`bash


更新所有别名

`bash
npx droid-patch version
`

PATH 配置

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

`bash


添加到 shell 配置文件（~/.zshrc、~/.bashrc 等）

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

可用的修补选项

$3

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

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

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

$3

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

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

工作原理：

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

$3

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

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

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

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

`bash


有效的 URL（<=22 个字符）

2. 与 --websearch 配合使用

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

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

`bash


转发到自定义后端（无长度限制）

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

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

$3

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

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

特性：

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

使用方法：

`bash


创建带 websearch 的别名（使用官方 Factory API）

通过 模型原生 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 提供商的搜索）

使用方法：

`bash


创建带原生 websearch 的别名（需要 proxy 插件）

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

`bash


克隆并设置 proxy

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

`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"
}
}
`

$3

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

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

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

工作原理：

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

使用方法：

`bash


为自定义模型启用推理强度

配置 xhigh 推理强度：

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

`bash


编辑 ~/.factory/settings.json

可用的值：
| 值 | 描述 |
|-------|-------------|
| high | 高推理强度（补丁后的默认值） |
| xhigh | 超高推理强度 |
| medium | 中等推理强度 |
| low | 低推理强度 |

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

$3

与 --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 → 返回空 {} 响应

使用方法：

`bash


独立模式 + websearch

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

使用方法：

`bash


仅禁用遥测

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

$3

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

| 优先级 | 提供商 | 质量 | 免费额度 | 设置难度 |
| ------ | ------------ | ---- | --------------------- | -------- |
| 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 的免费代理。

$3

1. 创建 Smithery 账号
- 访问 smithery.ai
- 注册免费账号

2. 获取 API Key
- 进入账号设置
- 复制 API key

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

4. 配置环境变量
`bash
# 添加到 ~/.zshrc 或 ~/.bashrc
export SMITHERY_API_KEY="your_api_key_here"
export SMITHERY_PROFILE="your_profile_id"
`

$3

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

---

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

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

$3

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

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 密钥

#### 第三步：配置环境变量

`bash


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

3. 配置环境变量
`bash
# 添加到 ~/.zshrc 或 ~/.bashrc
export TAVILY_API_KEY="your_api_key_here"
`

---

4. Serper

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

$3

1. 创建账号
- 访问 serper.dev
- 注册免费账号

2. 获取 API Key
- 登录后，API key 显示在仪表板上
- 复制 API key

3. 配置环境变量
`bash
# 添加到 ~/.zshrc 或 ~/.bashrc
export SERPER_API_KEY="your_api_key_here"
`

$3

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

---

5. Brave Search

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

$3

1. 创建账号
- 访问 brave.com/search/api
- 点击 "开始使用"

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

3. 获取 API Key
- 进入 API 仪表板
- 复制 API key

4. 配置环境变量
`bash
# 添加到 ~/.zshrc 或 ~/.bashrc
export BRAVE_API_KEY="BSA..."
`

$3

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

---

6. SearXNG（自托管）

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

$3

#### 选项 A：使用公共实例

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

`bash


公共实例示例（请检查是否可用）

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

2. 配置环境变量
`bash
# 添加到 ~/.zshrc 或 ~/.bashrc
export SEARXNG_URL="http://localhost:8080"
`

$3

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

$3

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

---

7. DuckDuckGo（默认备用）

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

$3

无需配置！ DuckDuckGo 开箱即用。

$3

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

---

快速配置示例

$3

直接使用 DuckDuckGo 备用：

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

$3

`bash


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

`bash


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

选项 1：Google PSE（每天 10,000 次免费）

`bash
export DROID_SEARCH_DEBUG=1
droid-search
`

---

示例

`bash


快速开始：创建带 websearch 的 droid

许可证

MIT