← Frameworks

模型与开放条件Model & openness

官方口径：任何 LiteLLM 支持的模型都能接，它自己带 LiteLLM 网关层（已核验）。

已验证可用的 provider（Basic 设置下拉里能选）：

• OpenHands provider
• Anthropic
• OpenAI
• Mistral AI

Custom Model 怎么写：用 provider 前缀指定，遵循 LiteLLM 的 provider 规范； 另有 Base URL 可自定义，本地与自托管模型由此接入。 官方说保存 local LLM profile 时会先向后端校验。

LLM profiles：最多 10 套配置并存。可在会话中或 /model 切换。 也可由内置 SwitchLLMTool 让 agent 动态选型。

⚠ 两处官方未给出。一是完整 provider 名单。二是「any LLM」的对齐度数据。 即它在工具调用与 structured output 上是否对齐。核验范围：llm-settings 页。

这一项对该对象尤其重要：它同时是别人的调度层。 「Codex / Claude Code 跑在它上面」这一情况比较特殊。能用哪些模型由那个 agent 决定。

官方 LLM settings 页原文："This can be any model that is supported by litellm"

Official position: any model LiteLLM supports can connect, and it ships its own LiteLLM gateway layer (verified).

Providers verified working (selectable in the Basic settings dropdown):

• OpenHands provider
• Anthropic
• OpenAI
• Mistral AI

How to write a Custom Model: specify a provider prefix following LiteLLM's provider conventions; there is also a customizable Base URL, through which local and self-hosted models connect. The official docs say saving a local LLM profile first validates against the backend.

LLM profiles: up to 10 configurations coexist. Switch mid-session or via /model. The built-in SwitchLLMTool also lets the agent choose dynamically.

⚠ Two things the official docs do not give. One: a complete provider list. Two: alignment data for "any LLM" — i.e. whether tool calling and structured output align. Verification scope: the llm-settings page.

This item matters especially for this object: it is simultaneously other agents' scheduling layer. "Codex / Claude Code run on top of it" is a special case — which models are usable is decided by that agent.

Official LLM settings page, verbatim: "This can be any model that is supported by litellm"

运行位置Where it runs

它有四种官方部署形态。这是本对象最有实用价值的部分。README 四个 Option 全核验。

• Option 1 无沙箱本地跑：npm install -g @openhands/agent-canvas 然后 agent-canvas，起完整本地栈，要 Node.js 24+ 与 uv； 可用 --frontend-only / --backend-only 拆开跑

• Option 2 Docker 沙箱：docker run 官方镜像， 需预先准备 PROJECTS_PATH 宿主目录，agent 可访问该目录下的项目

• Option 3 每会话独立容器：OH_CONVERSATION_RUNTIME=docker agent-canvas， 每次新会话起自己的容器与 Agent Server，适合并发跑多个 agent

• Option 4 从源码跑：clone + npm install + npm run dev

入口地址：http://localhost:8000（Docker 镜像是 /canvas）。

后端可以远程切换，这是它作为调度层的核心能力：官方说 Agent Server 可跑在笔记本 / Mac Mini / 云上 VM / OpenHands Cloud， Canvas 前端可以在多个 Server 之间切换。

关于 Option 3 的官方说明。容器会挂载会话的 workspace 与持久化状态。 容器替换后文件与对话历史仍在。

It has four official deployment forms — the most practically valuable part of this object. All four README Options verified.

• Option 1 local without sandbox: npm install -g @openhands/agent-canvas then agent-canvas, starts the full local stack, requires Node.js 24+ and uv; --frontend-only / --backend-only split it apart

• Option 2 Docker sandbox: docker run the official image, requires preparing a PROJECTS_PATH host directory beforehand; the agent can access projects under it

• Option 3 per-conversation containers: OH_CONVERSATION_RUNTIME=docker agent-canvas, each new conversation starts its own container and Agent Server — good for running multiple agents concurrently

• Option 4 from source: clone + npm install + npm run dev

Entry URL: http://localhost:8000 (the Docker image serves /canvas).

Backends can be switched remotely — the core capability of its scheduling layer: officially the Agent Server can run on a laptop / Mac Mini / cloud VM / OpenHands Cloud, and the Canvas frontend switches between multiple Servers.

On Option 3 the official docs note containers mount the conversation's workspace and persisted state. Files and conversation history survive container replacement.

本地文件Local files

本地文件能碰多少，取决于你选哪种部署形态 —— 官方把这个变量讲得很清楚。

• 无沙箱形态：agent 对文件系统有全量访问权限，官方两次打 WARNING
• Docker 形态：访问范围收敛到 PROJECTS_PATH 挂载的目录
• 每会话容器形态：官方提示共享同一宿主工作区的会话仍会共用同一批文件， 建议用独立目录或 worktree 避免冲突编辑

• 后端远程时（云上 VM / Cloud backend）：agent 在远端 workspace 里跑， SDK 用 Workspace(host=..., working_dir="workspace/project") 指定远端工作目录， 文件与命令操作都在服务端执行

官方未说明「把本地仓库自动同步到远程后端」的机制（已查 agent-server 与 runtime 页）—— 仓库需先位于远端，或自行搬运。

官方 WARNING 原文："This runs the agent-server directly on the machine you're installing on — the agent will have full access to your filesystem!"

How much of the local file system is reachable depends on which deployment form you choose — the official docs make this variable explicit.

• No-sandbox form: the agent has full file-system access; the official docs WARNING twice
• Docker form: access narrows to the directory mounted at PROJECTS_PATH
• Per-conversation container form: the official docs caution that conversations sharing the same host workspace still share the same files; use separate directories or worktrees to avoid conflicting edits

• When the backend is remote (cloud VM / Cloud backend): the agent runs in a remote workspace; the SDK specifies the remote working directory with Workspace(host=..., working_dir="workspace/project"); file and command operations execute server-side

The official docs do not describe a mechanism for "auto-syncing a local repo to a remote backend" (agent-server and runtime pages checked) — the repo must already live remotely, or be moved by you.

Official WARNING, verbatim: "This runs the agent-server directly on the machine you're installing on — the agent will have full access to your filesystem!"

关机后的任务Tasks after shutdown

后台任务是它最突出的强项，也是它与其他 harness 站对象最大的差别。

把 agent 跑在云上服务器的最大好处有两个。一是关掉笔记本它还在跑。 二是更容易被第三方服务触发。比如 Slack、GitHub 或 Datadog。

配套是独立仓 OpenHands/automation，提供两种触发方式：

• 定时（schedule）
• webhook 事件

官方特性表列了可集成的第三方。它们是 Slack、GitHub、Linear 与 Notion。

对比本站其余对象：OpenAI Agents SDK、Deep Agents、Codex SDK 的 thread 状态 都在自己进程 / 自己机器上，关了就没了。 把「关掉笔记本后 agent 仍在跑」当卖点做的，只有这一个。

官方 README 原文：it "allows your agents to continue running even when your laptop is shut"

同一页亦点名 Slack、GitHub、Datadog 是更容易接入的触发渠道。

核验 OpenHands/automation（2026-10-01）：Python，MIT，32★，活跃。

Background tasks are its most prominent strength and its biggest difference from other harness entries.

The two biggest benefits of running agents on a cloud server: they keep running when you close the laptop, and they are easier to trigger from third-party services like Slack, GitHub, or Datadog.

The companion is the standalone repo OpenHands/automation, offering two trigger modes:

• schedules
• webhook events

The official feature table lists integrable third parties: Slack, GitHub, Linear, and Notion.

Compared with our other objects: OpenAI Agents SDK, Deep Agents, and Codex SDK keep thread state in their own process / own machine — gone when closed. Only this one markets "the agent keeps running after you close the laptop".

Official README, verbatim: it "allows your agents to continue running even when your laptop is shut"

The same page names Slack, GitHub, and Datadog as easier trigger channels.

Verified OpenHands/automation (2026-10-01): Python, MIT, 32★, active.

工具与扩展Tools & extensions

它有两条接入线：自身工具集 + MCP；另有 ACP 用来调度第三方 agent。

① 自带 agent（CodeAct / software-agent-sdk）的默认工具集， 官方 start-conversation API 示例列出：

• terminal
• file_editor
• task_tracker
• browser_tool_set（cli_mode 可关掉浏览器工具）

② MCP 支持已核验，官方有 MCP Servers 专页：

• CLI 用 openhands mcp，Canvas 用 Customize > MCP Servers
• 传输覆盖 http / sse / stdio
• 认证支持 Bearer / API Key / OAuth
• SDK 侧由 mcp_config（FastMCP 格式）注入 mcpServers

③ 通过 ACP（Agent Client Protocol） 调度第三方 agent （Claude Code、Codex、Gemini 等）。

⚠ 修正上一版档案：本对象并非只走 ACP —— MCP 同样是官方能力。

It has two access lines: its own toolset + MCP; plus ACP for scheduling third-party agents.

① The default toolset of its own agent (CodeAct / software-agent-sdk), listed in the official start-conversation API example:

• terminal
• file_editor
• task_tracker
• browser_tool_set (cli_mode can disable browser tools)

② MCP support verified, with an official MCP Servers page:

• CLI uses openhands mcp; Canvas uses Customize > MCP Servers
• Transports cover http / sse / stdio
• Auth supports Bearer / API Key / OAuth
• On the SDK side, mcp_config (FastMCP format) injects mcpServers

③ Third-party agents (Claude Code, Codex, Gemini, etc.) are scheduled via ACP (Agent Client Protocol).

⚠ Correction to the previous version of this dossier: this object does not go ACP-only — MCP is equally an official capability.

上下文与记忆Context & memory

上下文这一点，官方有明确机制：context condenser。本维度证据已补齐。

默认实现是 LLMSummarizingCondenser（继承 RollingCondenser）， 参数 max_size / keep_first。它超阈值时保留最近的消息不动，只摘要较早的内容。

Canvas 侧的入口在 Settings > Condenser； LLM settings 页有 "Enable memory condensation" 与 "Memory condenser max history size" 两个开关。

官方还说明。配了 condenser 之后，超窗改为发 condensation 请求事件。 而不再抛 LLMContextWindowExceedError。agent 摘要旧历史后继续。

⚠ 按本站「状态 ≠ 上下文」的口径。run history 与容器可替换后的持久化属于状态侧。 上面的 condenser 才是上下文侧的官方手段。两者分开算。

官方 SDK 指南原文：context condenser "intelligently summarizing older parts of the conversation while preserving essential information"； 超阈值时 "Keeps recent messages intact"、"Summarizes older content"。

On context, the official docs have an explicit mechanism: the context condenser. Evidence for this dimension is complete.

The default implementation is LLMSummarizingCondenser (extends RollingCondenser), with parameters max_size / keep_first. Over threshold it keeps recent messages intact and only summarizes older content.

On the Canvas side the entry is Settings > Condenser; the LLM settings page has "Enable memory condensation" and "Memory condenser max history size" toggles.

The official docs also explain: with a condenser configured, exceeding the window emits a condensation-request event instead of throwing LLMContextWindowExceedError. The agent summarizes old history and continues.

⚠ Per our "state ≠ context" framing: run history and persistence across container replacement belong to the state side. The condenser above is the official context-side mechanism. Count them separately.

Official SDK guide, verbatim: the context condenser "intelligently summarizing older parts of the conversation while preserving essential information"; over threshold it "Keeps recent messages intact", "Summarizes older content".

权限与限制Permissions & limits

这一块官方做得最细，也是最需要认真读的部分。

沙箱：官方给了两种收敛手段（见 local_files）。一是 Docker 沙箱，二是每会话独立容器。 但官方同时明确提供无沙箱形态，并两次挂 WARNING。

认证用的是 API key，不是用户体系：

• 生成 key：openssl rand -base64 32，赋给 LOCAL_BACKEND_API_KEY
• --public 模式下 key 不烘进前端，用户首次打开 UI 要手动粘贴 key 才能用； 之后每个 /api/* 请求都要带 X-Session-API-Key 头

• 默认绑定 loopback-only（127.0.0.1）。官方说明这是为了让自动注入的 session key 不被局域网其他机器拿到

• 要监听 0.0.0.0 时 key 不再注入，改用同样的 API-key 输入界面
• 官方提醒用 export 而不是命令行参数传 key， 避免出现在 ps aux 进程列表里

• 暴露到公网时官方另有防火墙要求（Cloud Firewall / AWS Security Group / GCP firewall rule）

⚠ 多用户与权限分级，官方把这一档划给 Enterprise。 官方部署对比表明示 Open Source 档「Users = 1」， Multi-user RBAC 与 SSO/SAML 只有 Enterprise 有（OSS 栏为「—」）。

因此 OSS 自托管不含用户 / 角色 / 审计体系。上面那把会话 key 就是全部。 需要多用户分级与审计，须上 Enterprise。

docs/SELF_HOSTING.md（核验 286 行）给的就是这套 API key 机制。

核验：已查 enterprise 页与部署对比表。

This is where the official docs are most thorough — and the part that most deserves careful reading.

Sandbox: the official docs give two containment measures (see local_files): the Docker sandbox and per-conversation containers. But the official docs also explicitly offer the no-sandbox form, WARNING twice.

Authentication uses an API key, not a user system:

• generate a key: openssl rand -base64 32, assign to LOCAL_BACKEND_API_KEY
• in --public mode the key is not baked into the frontend; users must paste the key manually on first UI open; afterwards every /api/* request carries the X-Session-API-Key header

• loopback-only binding by default (127.0.0.1). The official rationale: keep the auto-injected session key from being reachable by other machines on the LAN

• when listening on 0.0.0.0 the key is no longer injected; the same API-key input UI is used instead
• the official docs advise export over command-line arguments for the key, to keep it out of ps aux process listings

• exposing to the public internet carries official firewall requirements (Cloud Firewall / AWS Security Group / GCP firewall rule)

⚠ Multi-user and permission tiers are assigned by the official docs to Enterprise. The official deployment comparison table shows the Open Source tier "Users = 1"; Multi-user RBAC and SSO/SAML exist only in Enterprise (the OSS column reads "—").

So OSS self-hosting includes no user/role/audit system — that session key is all there is. Multi-user tiering and auditing require Enterprise.

docs/SELF_HOSTING.md (verified, 286 lines) covers exactly this API-key mechanism.

Verified: enterprise page and deployment comparison table checked.

适合什么任务Best for

能做的事：

• 把 agent 放到自己服务器上 7×24 跑
• 定时或 webhook 触发（Slack / GitHub / Linear / Notion）
• 用一个界面统管多种 agent（含 Codex、Claude Code、Gemini 等 ACP 兼容的）
• 需要 per-conversation 隔离容器
• 团队里前端 / 平台与 agent 运行时分离部署
• 长会话需要官方 condenser 控制上下文成本

不适合做的事：

• 只想要一个轻量库，把 agent 嵌进自己的 Python 进程 （那种需求请用 software-agent-sdk 或 OpenAI Agents SDK）

• 单机临时用一下 —— 它是一整套栈，不是库
• 需要多用户与细粒度权限分级 —— 官方把 Multi-user RBAC 划给 Enterprise， OSS 自托管只有单 key

What it can do:

• Put agents on your own server running 7×24
• Trigger by schedule or webhook (Slack / GitHub / Linear / Notion)
• Manage multiple agent kinds from one UI (including ACP-compatible Codex, Claude Code, Gemini)
• You need per-conversation isolated containers
• Your team deploys frontend/platform separately from the agent runtime
• Long sessions need the official condenser to control context cost

What it is not for:

• You just want a lightweight library to embed agents in your own Python process (use software-agent-sdk or OpenAI Agents SDK for that need)

• Ad-hoc single-machine use — it is a whole stack, not a library
• You need multi-user fine-grained permission tiers — the official docs assign Multi-user RBAC to Enterprise; OSS self-hosting has a single key only

本页由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.