← Harness

模型与开放条件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"

运行位置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 与持久化状态。 容器替换后文件与对话历史仍在。

本地文件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!"

关机后的任务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★，活跃。

工具与扩展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 同样是官方能力。

上下文与记忆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"。

权限与限制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 页与部署对比表。

适合什么任务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

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