OpenProgram Docs
内置工具#
工具审批行为及运行中切换请参见工具权限模式。
OpenProgram 自带一批注册为工具的函数，模型在聊天里直接调用。这一页按 openprogram/programs/tools/ 目录逐个列出：每个工具做什么、需要什么 key 或本地依赖。大多数工具零配置；需要 key 的集中在网络检索和图像两类。
文件与代码#
| 工具 | 做什么 | 需要什么 |
|---|---|---|
read |
读文件内容 | 无 |
write |
新建或整体覆盖文件 | 无 |
edit |
文件内字符串替换 | 无 |
apply_patch |
Codex / OpenClaw 格式的多文件结构化 patch | 无 |
list |
列目录内容 | 无 |
glob |
按文件名模式找文件 | 无 |
grep |
内容搜索，优先 ripgrep，缺 rg 回退 Python re | 无（装 rg 更快） |
semble_search / semble_find_related |
语义 + 词法代码搜索，返回排好序的代码块 | 每个受支持的 release 已包含；source developer 通过锁定的项目环境安装 search extra |
lsp_diagnostics / lsp_references / lsp_definition |
从 language server 拿类型检查错误、真实调用点、真实定义位置，见Language server 工具 | Python 装 pyright，TypeScript 装 typescript-language-server（缺哪个工具就报哪条安装命令） |
文档版本#
对于 Word、PowerPoint、PDF、图片等二进制文件，模型可以先生成独立的临时结果，再调用 write(file_path="/absolute/final.docx", source_path="/absolute/staged.docx") 写入最终文件。source_path 与文本 content 只能指定一个。来源必须是本地普通文件，最大 64 MiB。覆盖已有目标前须先读取；二进制读取返回文件信息，并建立与文本读取相同的内容变更检查。
在会话中写入时，系统将修改前后的完整字节保存到这一轮的文件历史。重新打开会话或重启应用后，记录仍然存在。撤销和重新应用使用保存的版本；文件后来被修改且发生冲突时，不会覆盖后续内容。新建文件也能撤销，不要求项目文件夹是 Git 仓库。
完整版本保留格式和嵌入媒体，但当前 Review 不比较文档排版，也不显示 Word 修订标记。直接覆盖最终文件的普通 shell 命令不会成为本轮精确修改记录。过去未记录的版本无法根据文件卡片或命令输出补建；脚本应生成独立结果，再通过 write 写入最终文件。
后续历史提交失败时，之前已发布的版本仍完整保留。写入后尚未记录结果就中断时，文件历史显示结果未确认，并禁止精确恢复；不推断成功，也不把它当作没有修改。历史损坏会阻止继续记录写入，不会覆盖为空记录。首次尝试失败后，重新读取当前文件再重试。版本随所属轮次保留，并沿用现有历史保留策略。新增本地文档生成器复用 source_path 发布接口，无需另建版本存储。
通过项目文件编辑器进行的手动修改也会保留修改前后的完整字节，独立于会话历史。每次成功写入立即发布；同一编辑器的连续修改最多合并为五分钟的一条版本，结束分组或发现外部修改时另建版本。恢复历史版本会新增记录，并检查当前文件版本后再覆盖。项目磁盘断开时仍可读取已保存的历史；写入和恢复需要项目位置可用。项目位置变化后，恢复使用登记的新位置。文档 API 接受不超过 64 MiB 的二进制内容，但这并不代表每种二进制格式都已提供编辑界面。
项目文件默认打开预览。加载时居中显示资源准备和文档打开状态；加载期间关闭文件会取消待加载的编辑器，初始化失败后可以重试。支持的 UTF-8 文本文件可以选择“编辑”，修改会自动保存，也可以按 Ctrl/Cmd+S 立即保存。预览与编辑之间切换会保留编辑器的撤销记录。“历史”可查看保留版本修改前后的内容，并恢复选定版本。保存失败或磁盘文件被其他程序修改时，草稿会保留，可以重试、导出或明确选择丢弃。关闭文件会等待待保存修改完成；保存失败时标签保持打开。聊天附件使用同一预览窗口，以只读方式打开。
PDF 预览支持翻页、缩放和文本搜索；搜索前 500 页，更长的文档会明确显示这个范围。PSD 预览显示 8 位 RGB 文件保存的合成图和图层名称，TIFF 预览显示首页。这些解码器最多接收 64 MiB，并限制渲染图像大小。常见图片默认打开预览，音频和视频使用浏览器播放控件，编解码器支持取决于浏览器。损坏或不支持的文件仍可下载原文件。查看历史版本时使用该版本保留的字节。解码器资源保存在本地，打开对应格式时才加载。这些预览模式不编辑 PDF、PSD、TIFF、音频或视频文件。
Office 支持是演示文稿、文档和表格共用的可选本地组件，默认 App 和运行环境不附带它。未安装时打开 Office 文件会显示“安装”和“取消”，只有选择“安装”才开始下载。下载约 699 MiB，包含 ONLYOFFICE 资源、字体、许可证和源码材料，文件在本机处理。安装先校验固定版本压缩包和全部资源，再选择完整版本；失败可以重试，已有安装保留。安装成功后自动打开当前文档，无需重启 App。取消后仍可下载原文件，也可通过“安装选项”重新选择。通过远端访问应用时，本地 Office 编辑器不可用。PDF 预览不依赖这个组件。文件窗口支持 DOCX、PPTX、XLSX、ODT、ODP 和 ODS 的预览与编辑，默认打开预览。选择编辑后会等待原生编辑器进入可写状态，修改随后自动保存。切换预览、标签、分栏或历史时保留当前编辑器及其原生撤销记录。关闭前会等待尚未提交的输入和文件写入；写入失败时保留文档供重试。历史版本只读预览，恢复版本会新建一条保留记录。旧 DOC、PPT、XLS 可以明确转换为新路径下的 DOCX、PPTX、XLSX，原文件保留，已有目标不会被覆盖。附件保持只读，编辑器无法加载时仍可下载原文件。这些窗口不提供 Office 内容修订差异视图。
静态 PNG、JPEG 和 WebP 支持编辑，可裁剪、旋转、绘图、添加形状和文字。修改通过文档历史控制器自动保存；切换预览、历史、标签或页面时保留原生撤销与重做记录。写入失败会保留可编辑草稿供重试，关闭前等待导出完成。转换为 PNG 会创建独立文件，已有目标不会被覆盖。动画 PNG/WebP 和 16 位 PNG 保持只读。编辑最多接收 64 MiB、1600 万像素，单边不超过 16384 像素；不支持或损坏的文件仍可下载原文件。图片编辑导出渲染后的像素，不承诺保留嵌入元数据。附件和历史预览保持只读。
同一个“历史”界面汇总该项目相对路径下的手动修改和已确认的模型修改。模型版本直接读取原会话 checkpoint 保留的修改前后字节，不另建会话副本。恢复所选版本只修改这一个文件，检查当前版本后新建一条手动历史记录。归档会话保留文件历史；彻底删除会话后，其模型版本不再可读。手动历史独立保留。旧会话历史分批索引，点击“继续加载历史”处理下一批；尚未完成或无法核实的历史会明确标注。旧路径只有能够确认项目归属时才会汇总。项目移动不改变新记录的文件历史身份；磁盘离线时可读取保留版本，恢复需要项目位置可用。
执行#
| 工具 | 做什么 | 需要什么 |
|---|---|---|
bash |
同步执行 shell 命令，返回 stdout / stderr / 退出码 | 无 |
process |
管理后台 shell 会话（长跑服务、可轮询输出） | 无 |
execute_code |
在独立子进程里跑 Python 片段 | 无 |
execute_code 返回 stdout、stderr 和已观察到的退出码。非零退出或超时返回错误结果，部分输出仍可用于检查失败原因。只有零退出码表示成功。每次调用使用新的 Python 子进程。
独立命令的执行目录#
bash 每次调用都启动新的 shell。可通过可选参数 workdir 指定本次调用的起始目录，例如 bash(command="npm test", workdir="apps/web")。这是工具调用写法；普通 Python 导出的对象是 AgentTool，而不是直接执行 shell 的函数。
本地相对路径从当前绑定的 worktree 解析；未绑定时使用宿主进程目录，也支持绝对路径。路径按字面值处理，不展开 ~、环境变量或 shell 表达式。省略 workdir 保留原来的 worktree／后端默认目录。某次命令里的 cd 或 export 不影响下一次调用；workdir 也不改变 worktree 绑定或文件工具的路径基准。
目录不存在、不是目录或未获授权时，不执行请求的命令，不自动创建目录，也不回退到其他位置。指定目录本身不授予访问权限。启用本地沙箱策略时，显式目录须符合原工作区的读写策略，包括符号链接和已有额外授权目录；执行仍受原沙箱边界约束。配置的沙箱不可用时，显式 workdir 不会绕过它继续执行。
SSH 和 Docker 在后端文件系统中按 POSIX 路径解释显式目录，不使用宿主文件系统解析远端路径。远端相对路径需要绝对 POSIX worktree 绑定。受保护的目录切换在目录不可用时阻止后续整个命令列表，Docker 不会通过 -w 自动创建指定目录。启用宿主沙箱策略时，在后端原生路径授权可用之前，显式远端 workdir 会被拒绝。省略该参数保留现有后端行为。
结果包含选择的本地起始 cwd；对于未独立观测规范位置的远端路径，显示 requested_cwd。这不是命令结束后的目录，也不表示 shell 状态持续。长时间运行的进程仍由独立的 process 工具管理；bash 不操作桌面集成终端。
网络#
| 工具 | 做什么 | 需要什么 |
|---|---|---|
web_search |
关键词 → 相关 URL 列表，多后端可选 | 见下方后端表 |
web_fetch |
拉取 URL 并转成可读文本 | 无（装 trafilatura 抽取更干净） |
playwright_browser |
Playwright 驱动无头 Chromium（open / navigate 等动作） | 每个受支持的 release 已包含 Playwright Chromium |
agent_browser |
经 npm agent-browser CLI 驱动浏览器，snapshot 返回可访问性树 |
开发者增加的替代 backend，不用于补齐产品 Browser 功能 |
web_search 后端与 key（arXiv 与 DuckDuckGo 免 key，始终可用）：
| 后端 | 环境变量 |
|---|---|
| DuckDuckGo / arXiv | 无 |
| Brave | BRAVE_API_KEY |
| Exa | EXA_API_KEY |
| Firecrawl | FIRECRAWL_API_KEY |
| Google PSE | GOOGLE_PSE_API_KEY + GOOGLE_PSE_CX |
| Jina | JINA_API_KEY |
| Kagi | KAGI_API_KEY |
| MiniMax | MINIMAX_CODE_PLAN_KEY、MINIMAX_CODING_API_KEY 或 MINIMAX_API_KEY |
| Moonshot (Kimi) | KIMI_API_KEY 或 MOONSHOT_API_KEY |
| Perplexity | PERPLEXITY_API_KEY |
| SearXNG | SEARXNG_URL（自托管实例地址） |
| Serper | SERPER_API_KEY |
| Tavily | TAVILY_API_KEY |
| You.com | YDC_API_KEY 或 YOU_API_KEY |
| Ollama | 本地 Ollama（需 ollama signin），或用 OLLAMA_API_KEY 走 Ollama Cloud |
聊天中的 Web Search 开关控制本条消息是否可使用 web_search；关闭后，即使是自动工具模式也会排除此工具。开启后直接提供搜索工具定义，Tools 关闭时也可调用。开启仍遵守 Agent 禁用工具和权限设置。Tool profile 按会话保存，切换标签和刷新后保留。
新增搜索 key 在后续调用中生效，无需重启。默认后端不可用时使用其他可用后端；显式指定不可用后端则报错，错误说明原因（例如缺少的 key）并列出当前可用的后端。Jina 搜索需要 JINA_API_KEY。DuckDuckGo 读取其无 JavaScript 结果页，返回第一页结果（约十条）；遇到机器人验证或无法解析的页面时报错，而不是返回空结果。combine="race" 返回首个非空成功结果；providers 中无法运行的后端会被跳过，全部无法运行时错误逐个列出原因；combine="rrf" 保留截止时间前完成的结果。全部失败返回错误，与成功但无结果区分；已开始的请求按各自传输超时结束。
图像与 PDF#
| 工具 | 做什么 | 需要什么 |
|---|---|---|
image_generate |
prompt → PNG 存盘 | 任一后端：OpenAI（OPENAI_API_KEY）、Gemini（GEMINI_API_KEY 或 GOOGLE_API_KEY）、fal（FAL_KEY） |
image_analyze |
描述图片 / 回答关于图片的问题（本地路径或 URL） | 任一视觉模型 key：OpenAI / Anthropic / Gemini（复用已配置的 provider key） |
pdf |
从 PDF 抽取文本，支持 offset / limit 翻页 | 完整 release 已内置（pypdf） |
图像工具在所选 Provider 不可用、调用失败或图片无法保存时返回错误结果。mixture_of_agents 在模型引用未知、所有参考调用失败或汇总失败时也返回错误结果。部分参考调用失败但得到有效回答，或成功回答的文本包含 Error 字样时，结果仍然是成功。普通 Python 的 execute(...) 调用保持字符串返回值。
会话与协作#
协作分四个域，一词一义，见 agent 协作 §1。
| 域 | 工具 | 做什么 | 需要什么 |
|---|---|---|---|
| 计划 | todo_create / todo_update / todo_list |
会话规划清单：手写的计划清单（建条目、设状态/负责人/依赖、按状态分组列出）。写一条不会启动任何东西 | 无 |
| 执行 | list_jobs / job_output |
列出本会话的后台任务，等待或查看结果。结果读取检查派发会话和祖先任务的所有权 | 无 |
| 实体 | agent |
新建一个 agent 并取回回复，或用 to= 给已存在的 agent 派受管任务。run_in_background=true 不阻塞、直接返回 job_id；start_from 决定新 agent 从哪起（clean / inherit / SID:MSG_ID）；archive_when_done=true 让它在任务结束、结果回流之后自动归档 |
无 |
| 实体 | list_agents |
agent 列表：有哪些 agent、它们的名字、地址、体量和忙闲（scope="archived" 看已归档的） |
无 |
| 实体 | archive_agent |
把活干完的 agent 归档：它从 list_agents 消失，并拒收后续 send_message / agent(to=) 投递；read_conversation 照读它的历史，agent(start_from="SID:MSG_ID") 照 fork。归档不中断在跑的工作、不删数据，所以任何会话都能归档任何 agent；归档单向，没有反归档 |
无 |
| 通讯 | send_message |
跟已存在的 agent 说话，按 "SID:HEAD" 或名字寻址。不产生任务、不产生 job_id、没有东西可取消，所以任何 agent 都能发 |
无 |
| 通讯 | read_conversation |
把任意 agent 的历史读成纯文本（含工具调用），可指定轮次范围和字数预算 | 无 |
协作消息额度耗尽后，job_output 仍可用；读取已有结果不消耗该额度。新的 Agent 投递仍须遵守相应上限。取消任务使用它的执行控制；API 取消使用 execution.command，设置 action="execution.cancel" 并传入当前执行版本。当前工具目录没有 job_stop。
| 工具 | 做什么 | 需要什么 |
|---|---|---|
program |
调用任意已注册的 Agent method |
无 |
mixture_of_agents |
并行问N个模型再综合;默认从模型注册表选,每个provider取一个 | 模型注册表里至少2个provider |
ask_user_question |
向用户提 1–N 个带选项的问题 | 需要交互前端；输入基础设施不可用、问题数组无效或无交互上下文时返回工具错误 |
enter_plan_mode / exit_plan_mode |
进入 / 退出计划模式 | 无 |
canvas |
往 markdown 文件的具名块里增量写入；set 的 content="" 清空正文，省略内容则返回错误 |
无 |
memory_* |
读取持久记忆工作区——memory_search（按语义找）、memory_grep（找确切字符串）、memory_get（读一个文件、章节或段落）、memory_browse（看有什么）、memory_status（规模与版本），以及 memory_update 用来更正某一处。没有记录对话的工具：那件事在后台完成。每个实例只有一份工作区，所有agent、所有对话（含聊天渠道）共用（见聊天渠道）。 |
无 |
worktree_* |
git worktree：worktree_create（也可直接从 PR 开 worktree，传 pr="123" / "#123" / GitHub PR 链接，走 gh）/ merge / discard / list / keep |
git |
cron |
登记周期性 agent 任务 | 无 |
list_mcp_resources / read_mcp_resource / list_mcp_prompts / get_mcp_prompt |
把 MCP 的 resources / prompts 原语暴露给模型（mcp_meta 目录） |
已配置的 MCP server（见 MCP） |
tool_search |
按需加载延迟工具；下一次模型请求包含其完整 schema | 无 |
已注册的 canvas 与 agent_browser 对明确的校验、依赖和进程失败设置错误标记。成功的 Canvas 正文与 CLI stdout 即使以 Error: 开头也保持成功。普通 Python execute() 调用仍返回字符串。