DroidDroid

模型与开放条件Model & openness

模型无关是它的卖点：官方托管模型、BYOK、本地模型三路并存。

官方托管的模型覆盖四家厂商，另有一个开放权重池。

• Anthropic：Claude Opus / Sonnet / Fable / Haiku
• OpenAI：GPT-6 / GPT-5.5 / GPT-5.3-Codex
• Google：Gemini
• xAI：Grok
• Droid Core 开放权重：GLM、Kimi、Qwen、DeepSeek、MiniMax、Nemotron 等

每个模型都标了消耗倍率与支持的 reasoningEffort。

倍率举例：gpt-5.5 是 2×，claude-sonnet-5 是 0.8×。

BYOK 可以接自家 key，也可以接任意 OpenAI 兼容端点。

官方原文："Use your own OpenAI or Anthropic keys, connect to any open source model providers, or run models locally"

配置写在 ~/.factory/settings.json 的 customModels 里，共三个字段。

• baseUrl
• apiKey
• provider（三选一：anthropic、openai、generic-chat-completion-api）

值可以用 ${VAR} 引用环境变量。

能接 OpenRouter / Fireworks / Together / Ollama / vLLM 等任意 OpenAI 兼容端点。

API key 只留在本地，不上传。

官方原文："Your API keys remain local and are not uploaded to Factory servers"

换模型用 /model。

自定义模型只在 CLI 可用，不出现在 Web / 移动端。

另有官方 Factory Router 自动跨 provider 路由。

Model-agnosticism is its selling point: officially hosted models, BYOK, and local models coexist.

Officially hosted models cover four vendors, plus an open-weight pool.

• Anthropic: Claude Opus / Sonnet / Fable / Haiku
• OpenAI: GPT-6 / GPT-5.5 / GPT-5.3-Codex
• Google: Gemini
• xAI: Grok
• Droid Core open weights: GLM, Kimi, Qwen, DeepSeek, MiniMax, Nemotron, etc.

Every model is labeled with its burn multiplier and supported reasoningEffort.

Multiplier examples: gpt-5.5 is 2×, claude-sonnet-5 is 0.8×.

BYOK can use your own keys or any OpenAI-compatible endpoint.

Official wording: "Use your own OpenAI or Anthropic keys, connect to any open source model providers, or run models locally"

Config lives in customModels in ~/.factory/settings.json, three fields.

• baseUrl
• apiKey
• provider (one of three: anthropic, openai, generic-chat-completion-api)

Values can reference environment variables via ${VAR}.

Any OpenAI-compatible endpoint works: OpenRouter / Fireworks / Together / Ollama / vLLM etc.

API keys stay local and are not uploaded.

Official wording: "Your API keys remain local and are not uploaded to Factory servers"

Switch models with /model.

Custom models are CLI-only and do not appear on Web / mobile.

There is also the official Factory Router for automatic cross-provider routing.

运行位置Where it runs

CLI 优先，但官方定位是「一种 agent、多平台」。

主力是终端进程 droid，也就是交互式 REPL。

它的生命周期绑定终端会话，终端关掉就结束。

安装三选一：

• macOS / Linux：官方脚本 curl -fsSL https://app.factory.ai/cli | sh
• Windows：irm https://app.factory.ai/cli/windows | iex
• 或用 npm：npm install -g droid

同一个 agent 还有另外两个入口。

• Factory App —— 桌面客户端
• Droid SDK —— TypeScript 的 @factory/droid-sdk，Python 的 droid-sdk

官方定价页把这三者并列为 Pro 档内容。

官方原文："Factory App / Droid CLI / Droid SDK"

企业侧还有 Droid Computers，那是 Factory 托管的远端云环境，Plus 起。

本条目只记录 CLI 形态，桌面与 SDK 的差异以官方页面为准。

CLI-first, but the official positioning is "one agent, multiple platforms".

The workhorse is the terminal process droid, an interactive REPL.

Its lifecycle is bound to the terminal session — close the terminal and it ends.

Three install options:

• macOS / Linux: official script curl -fsSL https://app.factory.ai/cli | sh
• Windows: irm https://app.factory.ai/cli/windows | iex
• or npm: npm install -g droid

The same agent has two more entry points.

• Factory App — a desktop client
• Droid SDK — TypeScript @factory/droid-sdk, Python droid-sdk

The official pricing page lists all three as Pro-tier contents.

Official wording: "Factory App / Droid CLI / Droid SDK"

On the enterprise side there are also Droid Computers, Factory-managed remote cloud environments, from the Plus tier up.

This entry documents the CLI form only; desktop and SDK differences follow the official pages.

本地文件Local files

它在你自己的工作目录里读写，官方另给了两个隔离手段。

一是 --cwd <path>，指定工作目录。

二是 -w, --worktree [name]，在独立 git worktree 上跑。

官方原文："fanning out parallel droid exec jobs against the same repo without file conflicts"

官方说明：clean worktree 退出时自动删除，dirty 的保留待评审。

非交互的 droid exec 默认只读。

DEFAULT 档列出的读命令包括：

• cat / ls / git status / git log
• find，但不带 -delete / -exec

官方在 DEFAULT 档写明：

官方原文："No modifications to files or system"

要改文件，得显式开到 --auto low 以上。

代码库是否做向量索引、大仓库首次建索引要多久，官方未说明 （已查 CLI Reference 与 Quickstart 两页）。

It reads and writes in your own working directory; the official docs add two isolation mechanisms.

One is --cwd <path>, setting the working directory.

Two is -w, --worktree [name], running on a separate git worktree.

Official wording: "fanning out parallel droid exec jobs against the same repo without file conflicts"

Official note: clean worktrees are auto-deleted on exit; dirty ones are kept for review.

Non-interactive droid exec is read-only by default.

Read commands listed under the DEFAULT tier include:

• cat / ls / git status / git log
• find, but not with -delete / -exec

The official docs state plainly under the DEFAULT tier:

Official wording: "No modifications to files or system"

To change files you must explicitly raise it to --auto low or above.

Whether the codebase is vector-indexed, and how long first indexing takes on large repos, is not stated officially (CLI Reference and Quickstart pages checked).

关机后的任务Tasks after shutdown

CLI 本体绑定会话，但官方有明确的云端后台形态。

终端进程退出即结束。

官方定价页 Pro 档写有：

官方原文："Cloud & local background agents"

Plus 档解锁 Droid Computers。

官方原文："Factory-managed Droid Computers (remote cloud environments)"

企业页亦称 Droid 可跑在下列环境上：

• CI runners、VMs、Kubernetes clusters

Missions 是多 agent 编排形态：orchestrator 协调 worker 与 validator。

发起方式二选一：/missions 或 droid exec --mission。

官方要求 High 自主级别，或用 --skip-permissions-unsafe。

云端并发的具体数值与配额官方未给 （已查 Plans & Pricing 与 Missions 概览两页）。

The CLI itself is session-bound, but there is an explicit cloud background form officially.

The terminal process ends on exit.

The official pricing page's Pro tier lists:

Official wording: "Cloud & local background agents"

The Plus tier unlocks Droid Computers.

Official wording: "Factory-managed Droid Computers (remote cloud environments)"

The enterprise page also says Droid can run on:

• CI runners, VMs, Kubernetes clusters

Missions is the multi-agent orchestration form: an orchestrator coordinates workers and validators.

Launch either via /missions or droid exec --mission.

The official docs require the High autonomy level, or --skip-permissions-unsafe.

Concrete cloud concurrency numbers and quotas are not given by the official docs (Plans & Pricing and the Missions overview checked).

工具与扩展Tools & extensions

内置工具面很宽，MCP 支持完整，还带一个交互式管理器。

内置能力包括：

• 命令执行、文件读写、git 操作
• 代码评审（/review）
• 图像生成、PDF 读取

扩展面另有五类：

• Skills —— /skills、/create-skill
• Hooks —— PreToolUse / PostToolUse / PreCompact 等九类事件
• Custom Droids 子代理 —— /droids
• Plugins —— /plugins，经 marketplace 分发
• 自定义斜杠命令与 AGENTS.md

MCP 支持两种传输。

官方原文："Droid supports two types of servers: http (remote endpoints) and stdio (local processes)"

添加方式是 droid mcp add <name> <url> --type http 或 droid mcp add <name> "<command>"。

/mcp 打开交互式管理器，可以浏览、查看工具、启停、做 OAuth 认证。

它还能从注册表添加 40+ server。

配置分两层：用户级 ~/.factory/mcp.json 与项目级 .factory/mcp.json。

另有 disabledTools 可以按工具禁用，OAuth token 存系统 keyring。

非交互模式官方也支持。

droid exec 的输出格式有 text / json 两种。

并有 --input-format stream-jsonrpc 的长期 JSON-RPC 控制面。

The built-in tool surface is broad, MCP support is complete, and there is an interactive manager.

Built-in capabilities include:

• command execution, file read/write, git operations
• code review (/review)
• image generation, PDF reading

The extension surface adds five more classes:

• Skills — /skills, /create-skill
• Hooks — nine event types including PreToolUse / PostToolUse / PreCompact
• Custom Droids sub-agents — /droids
• Plugins — /plugins, distributed via a marketplace
• custom slash commands and AGENTS.md

MCP supports two transports.

Official wording: "Droid supports two types of servers: http (remote endpoints) and stdio (local processes)"

Add via droid mcp add <name> <url> --type http or droid mcp add <name> "<command>".

/mcp opens the interactive manager: browse, inspect tools, enable/disable, do OAuth auth.

It can also add 40+ servers from a registry.

Config is two-layer: user-level ~/.factory/mcp.json and project-level .factory/mcp.json.

There is also disabledTools to disable per tool; OAuth tokens are stored in the system keyring.

Non-interactive mode is also officially supported.

droid exec output formats are text / json.

There is also --input-format stream-jsonrpc, a long-lived JSON-RPC control plane.

上下文与记忆Context & memory

会话可以按 id 续接，也可以分叉；压缩与控制面都是公开的。

非交互侧用 droid exec --session-id <id> 续接。

分叉用 --fork <id>。

交互侧退出时会提示 resume，CLI 参考里有 -r, --resume。

stream-jsonrpc 控制面暴露 droid.load_session、fork 会话与 compact history。

官方原文："interrupt work, update settings, manage MCP servers/tools, inspect context, fork sessions, or compact history"

压缩另有 PreCompact hook 事件。

changelog 里也有这一条：

官方原文："in-place compression"

记忆方面，官方企业形态提到跨仓库的「organizational knowledge」。

另有 issue 跟踪上下文。

Enterprise 档另有：

官方原文："Cross-harness agent memory"

CLI 侧记忆的持久化边界与保留策略，官方未在 CLI 页说明 （已查 CLI Overview 与 Droid Exec 两页）。

Sessions can be resumed by id and forked; compaction and the control plane are documented.

On the non-interactive side, resume with droid exec --session-id <id>.

Fork with --fork <id>.

On the interactive side, exit prompts resume, and the CLI reference has -r, --resume.

The stream-jsonrpc control plane exposes droid.load_session, session forking and history compaction.

Official wording: "interrupt work, update settings, manage MCP servers/tools, inspect context, fork sessions, or compact history"

Compaction additionally has a PreCompact hook event.

The changelog also has this line:

Official wording: "in-place compression"

On memory, the official enterprise form mentions cross-repo "organizational knowledge".

There is also issue-tracker context.

The Enterprise tier additionally has:

Official wording: "Cross-harness agent memory"

The persistence boundary and retention policy of memory on the CLI side are not stated on the CLI pages (CLI Overview and Droid Exec pages checked).

权限与限制Permissions & limits

权限是两级设计：分级自主（Autonomy Level）加命令黑白名单。

企业还能给这两级设上限。

官方 Autonomy 页把执行风险分成四档。

• Off —— 只读工具 + 白名单命令
• Low —— 文件编辑 + 低风险命令 / MCP
• Medium —— 加上可逆的工作区改动，如 npm install、git commit
• High —— 高风险操作，如 git push、迁移

切换用 Ctrl+L 循环，Shift+Tab 切 Auto / Spec。

命令策略是三张表。

• commandAllowlist —— 视为低风险
• commandDenylist —— 即使放宽也需批准
• commandBlocklist —— 任何级别都拒绝、没有审批提示，能识破 bash -c 包裹绕过

官方称 commandBlocklist 是：

官方原文："the strongest control available"

非交互的 droid exec 默认只读。

放开用 --auto low|medium|high 逐级提升。

--skip-permissions-unsafe 是全放开，官方标注 DANGEROUS，仅限隔离环境。

越级即停：返回非零码，不做部分改动（fail-fast）。

企业可以设 Default / Maximum Autonomy Level 封顶。

Permissions are a two-level design: tiered autonomy (Autonomy Level) plus command allow/deny/block lists.

Enterprises can additionally cap both levels.

The official Autonomy page splits execution risk into four tiers.

• Off — read-only tools + allowlisted commands
• Low — file edits + low-risk commands / MCP
• Medium — plus reversible workspace changes, e.g. npm install, git commit
• High — high-risk operations, e.g. git push, migrations

Switch by cycling with Ctrl+L; Shift+Tab toggles Auto / Spec.

Command policy is three tables.

• commandAllowlist — treated as low risk
• commandDenylist — requires approval even when relaxed
• commandBlocklist — refused at any level, with no approval prompt; sees through bash -c wrapper evasion

The official docs call commandBlocklist:

Official wording: "the strongest control available"

Non-interactive droid exec is read-only by default.

Open it up stepwise with --auto low|medium|high.

--skip-permissions-unsafe opens everything; officially labeled DANGEROUS, isolated environments only.

Exceeding the level stops immediately: non-zero exit code, no partial changes (fail-fast).

Enterprises can cap with Default / Maximum Autonomy Level.

适合什么任务Best for

适合在终端里跑端到端软件工程、且需要企业级治理的团队。

三类团队最对得上：

• 已有仓库，想跑完规划 → 实现 → 测试的完整流程（/missions 多 agent 编排）
• 要做 CI/CD 自动化：droid exec 单次执行、JSON 输出、失败返回非零码
• 需要 BYOK / 本地模型 / 气隙部署，以此摆脱单一厂商锁定

不适合只想找一个免费轻量终端助手的个人——官方没有免费档，最低是付费档 Pro。

Fits teams running end-to-end software engineering in the terminal and needing enterprise-grade governance.

Three kinds of teams match best:

• those with existing repos who want the full plan → implement → test flow (/missions multi-agent orchestration)
• those automating CI/CD: droid exec one-shot runs, JSON output, non-zero exit on failure
• those needing BYOK / local models / airgapped deployment, to break free of single-vendor lock-in

Not a fit for individuals just wanting a free lightweight terminal assistant — there is no free tier officially; the lowest is the paid Pro tier.

curl -fsSL https://app.factory.ai/cli | sh      # macOS / Linux
irm https://app.factory.ai/cli/windows | iex    # Windows
npm install -g droid

curl -fsSL https://app.factory.ai/cli | sh      # macOS / Linux
irm https://app.factory.ai/cli/windows | iex    # Windows
npm install -g droid

5-hour / 7-day / 30-day 三个窗口独立，都需有余额才能发请求

5-hour / 7-day / 30-day windows are independent; all must have headroom for a request to go through

本页由This page is generated from the ai-handbook 数据层生成（CC BY 4.0）。data layer (CC BY 4.0). 方法论与坐标系定义见仓库内For the methodology and coordinate definitions, see METHODOLOGY.md.