本文以一个可运行的 Python 项目 clawdbot/ 为例，拆解“本地优先 + 远程控制”的执行型 AI Agent（LocalPilot）如何从 Gateway 入口、Agent 决策、Tools 执行、Skills 规范四层跑通最小闭环；同时强调远程执行场景的核心难点在安全，给出入口认证、能力收敛、意图确认与审计等可落地的分层风控思路。

重要说明：本项目由Trae结合Gemini大模型全量生成代码，并已完成运行验证，当前可正常运行。

很多团队把“接入大模型”当作 AI 产品的终点：做个对话框、接个知识库、加个 Prompt，效果好一点就叫“智能助手”。但真实业务里，用户更在意的是：你能不能把事情做完。

“做完”意味着：不止回答建议，还要能调用工具、打开系统、操作文件、执行命令、把结果回传到用户常用渠道。也就是从 Chatbot 迈向 Agent。

本文基于一个可运行的 Python 项目 clawdbot/，用产品经理视角拆解：一个“本地优先 + 远程控制”的个人 AI 执行智能体（下文简称“LocalPilot”）应该怎么搭、怎么跑通第一条链路、以及最关键的——如何把安全风险管住。

需要强调的是：这个项目的灵感与结构参考了目前非常火热的开源项目 moltbot/moltbot，但并非简单照搬，而是结合自己的使用诉求重新做了设计取舍。出发点主要有三条：

• 其一，优先接入国内更容易使用、成本更可控的大模型（国外模型在日常长对话/多轮工具调用场景下 token 消耗偏贵）；
• 其二，围绕“本地优先 + 远程控制”跑通最小闭环；
• 其三，把它作为一次实验，验证 AI 在复刻开源项目思路、抽象架构与工程落地方面的能力边界。

一图看懂：从设计到运行的完整流程

这张图刻画的是当前代码实现的真实链路：启动时扫描 skills/*/SKILL.md 只提取 name/description（技能索引），每次请求先让大模型从索引里挑选需要的技能，再按需加载对应 SKILL.md 全文拼进 Prompt，最后再决定是否调用 Tool。

一、这个“LocalPilot”解决的是什么问题？

1）目标用户与场景

它面向的不是“泛问答”，而是非常明确的个人/小团队场景：

• 你在手机上发一句话，家里/公司电脑能执行：查文件、跑脚本、导出数据、截屏、汇总结果。
• 你不想把文件和命令执行权限交给云端服务，希望尽量在本机完成（Local-first）。
• 你愿意接受“能力先跑通、体验逐步打磨”的迭代节奏。

2）核心价值主张

用一句话概括：把大模型从“回答器”升级为“执行器”。

在该项目里，这个升级由三点共同完成：

1. 本地能力：文件系统、命令行、鼠标键盘等真实执行能力
2. 可插拔大脑：默认通义千问 Qwen，也支持 Mock 快速调试
3. 远程入口：HTTP / Telegram 等网关把“外部指令”送进来，再把结果送回去

二、产品形态拆解：Gateway / Agent / Tools / Skills 各司其职

这套结构在 docs/DESIGN_CONCEPTS.md 里有完整分层思路，落到代码里，大致是四层：

1）Gateway（入口层）：让用户“随时能喊它”

“LocalPilot”的入口不是一个 App，而是“你已有的沟通渠道”：

• HTTP：适合局域网/内网测试
• Telegram：适合公网远程控制
• CLI：适合开发调试

产品启示：入口层是“控制平面”，不是产品本体。真正的产品是 Agent 本身的执行能力与可靠性。

2）Agent（决策层）：把自然语言变成“下一步动作”

Agent 的核心工作是：

• 接收用户消息
• 带上技能说明（Skills）与可用工具列表（Tools）
• 让大模型决定“调用哪个工具 + 传什么参数”
• 执行工具并返回结果

当前实现是一个“单步工具调用”版本：一次请求最多执行一次工具。这对 MVP 验证链路很友好，但对复杂任务（多步规划、循环、失败重试）还不够。

3）Tools（执行层）：真实世界的“手和脚”

Tools 是可执行的 Python 代码，提供原子能力：

• 文件：列目录、读文件
• 命令：执行 shell
• 电脑控制：鼠标键盘、截图

4）Skills（知识层）：不是能力本身，而是“怎么用能力的说明书”

很多人会误解：Skills 和 Tools 功能重复。这个项目里，它们的关系更像：

• Tools：能做什么（代码能力）
• Skills：应该怎么做（策略与操作规程）

Skills 用 SKILL.md 形式存在（带 Frontmatter + 说明），通过 Loader 加载后注入到 Agent 的提示词上下文中。

产品启示：把“能力”与“用法”解耦，可以让 PM/运营用更低成本迭代行为规范，而不是每次都改代码发版。

三、模型层：为什么默认用通义千问？如何做到可切换？

模型层提供了：

Qwen（通义千问）：通过 LangChain 的 ChatTongyi 接入

并通过工厂模式做统一入口。对产品落地很关键：模型会变、策略会变，但系统不应为每次换模型重写一遍。

同时，服务启动脚本支持从 .env 加载环境变量（例如 DASHSCOPE_API_KEY），降低配置门槛，贴近“个人助理”的使用体验。

四、远程控制怎么跑通？MVP 链路长什么样？

MVP 远程链路大致是：

1. 远程设备发送指令（HTTP/Telegram）
2. Gateway 收到消息，交给 Agent
3. Agent 询问大模型：是直接回复，还是调用某个工具
4. 执行工具，拿到结果
5. 返回给 Gateway，再回传给远程设备

项目内置了一个简单的 HTTP 远程测试脚本，用于模拟“远程设备发消息”，优先用于验证“链路是否可用”。

产品启示：先把链路跑通，再谈体验。否则你会在“对话很聪明”上反复打磨，却无法证明“它能把事做完”。

演示示例：用户提问与效果展示

下面用几组“用户提问 → 返回效果”快速感受一次远程闭环的交互形态（示例输出会随你的机器环境而不同）。

示例 1：查看工作目录与文件

用户提问

帮我列出当前工作目录下的文件，并告诉我我现在在哪个路径。

演示效果

Agent 触发命令执行工具，返回：当前路径（cwd）与目录列表（含关键文件/文件夹名称）。

示例 2：读取文件并提炼要点

用户提问

打开 clawdbot/docs/DESIGN_CONCEPTS.md，用 3 条要点概括它的核心分层。

演示效果

Agent 触发文件读取工具，返回：3 条分层要点（如 Gateway / Agent / Tools / Skills 的职责划分）。

示例 3：截屏确认“发生了什么”

用户提问

截一张当前屏幕图，告诉我桌面上有哪些窗口在前台。

演示效果

Agent 触发截图工具，返回：截图（或截图保存路径）与对前台窗口的简要描述。

示例 4：高风险操作的拦截与确认

用户提问

把 C 盘根目录下的所有 .log 文件都删掉。

演示效果

Agent 识别为高风险意图，拒绝直接执行，并返回：需要确认的影响范围、建议的安全替代方案（例如先列出匹配文件并让用户选择）。

五、最关键的一节：远程 Agent 的安全怎么做？

当你允许 Agent 访问命令行、文件、鼠标键盘时，产品就不是“聊天工具”，而是“远程控制系统”。安全问题必须前置成产品能力，而不是事后补丁。

这里给出一套 PM 可落地的“分层风控”框架：

1）入口层（Gateway）做“人”的认证与授权

• 默认拒绝未知来源：陌生人消息不进入 Agent
• 配对/白名单：新设备/新账号需要一次性配对码
• 请求签名（HTTP）：至少要有 token/签名，避免内网被随便扫到就能控制
• 限流与熔断：异常频率直接暂停处理，避免被刷爆或诱导多次执行

2）能力层（Tools）做“动作”的权限收敛

不要只做“黑名单”拦截，更推荐：

• 白名单优先：只允许一组安全命令（例如 dir / ls / whoami / ipconfig），其它全部拒绝
• 按能力分级：
  • 只读（读文件、列目录、查询命令）默认允许
  • 破坏性（删除/覆盖/写入/安装/杀进程）默认需要二次确认或人工审批
• 路径沙箱：文件操作限定在某个 workspace 目录，避免全盘读写

3）交互层（Agent）做“意图”的再确认

• 高风险意图必须复述 + 二次确认：例如“删除文件”“格式化磁盘”“发外部邮件”
• 提供 dry-run：先给执行计划与影响范围，让用户确认后再执行
• 审计日志：至少记录“谁在什么时间触发了什么动作”

4）UI 自动化（鼠标键盘）是风险放大器

很多人只在“命令执行工具”上做防护，但一旦引入 GUI 自动化，“输入字符”也可能变成危险操作（例如在 cmd 窗口里输入删除命令）。

产品结论：电脑控制能力要比命令行更敏感，默认应该是：

• 最小权限开启
• 强制可视化（让用户看到发生了什么）
• 对高风险输入增加拦截与确认

六、给产品经理的落地建议：怎么把它从 Demo 变成可用产品？

如果把这个项目当作“下一代个人助理”的雏形，后续的产品化路径可以按优先级推进：

• 从单步到多步：支持规划-执行-校验-重试的循环
• 从黑名单到白名单：尤其是命令执行与文件写入
• 从“能用”到“可信”：配对、授权、审计、回放
• 从“工具集合”到“任务模板”：把高频任务沉淀为可复用流程

结语：Agent 产品的护城河不在模型，而在“执行闭环 + 安全信任”

把大模型接进来很容易，真正难的是：

• 能不能稳定执行、失败可控、结果可解释
• 能不能在远程场景下，把风险关进笼子里
• 能不能把“能力”沉淀为用户可复用的工作流

“LocalPilot”这类“本地优先的执行型助理”提供了一个很现实的答案：先把链路跑通、把权限收紧、把信任建立起来，再逐步扩展能力边界。模型会迭代，但产品价值最终落在“把事办成”。

附录：项目生成提示词

## Role

你是资深 Python 工程师 + Agent 产品架构师。

## Context

请从零生成一个可运行的“本地优先 + 远程控制”的个人 AI 执行智能体项目。

对外产品名：LocalPilot（仅用于文档/对外展示）。

代码包名与目录：clawdbot（兼容历史）。

分层参考：moltbot/moltbot（Gateway / Agent / Tools / Skills），但不要照搬代码，实现必须自洽、可运行、可测试。

参考开源项目（明确来源）：https://github.com/moltbot/moltbot （moltbot/moltbot）

## Output Format (Strict)

1) 先输出完整文件树（纯文本，和实际文件路径一致）。

2) 然后按文件逐个输出完整内容：每个文件一个代码块；代码块第一行必须是该文件的相对路径；不得省略任何文件内容。

3) 除“文件树 + 文件内容”外，不要输出其它解释性文字。

## Goals (MVP)

– 通过 HTTP / Telegram / CLI 接收自然语言指令

– 通过 Skills（Markdown）指导模型的决策方式

– 通过 Tools（Python）执行真实动作

– 有安全策略（尤其是命令执行与写文件）

– 支持多轮工具调用循环（单次请求可调用多个工具）

– Skills 按需加载（先索引，后全文）

## Constraints (Must)

1) 不要使用任何未声明依赖的假设；如需第三方库，写进 requirements.txt，并说明最小可运行方式。

2) Tools 必须是 Python 类，统一继承 BaseTool，具备：name / description / parameters(JSON Schema) / execute。

3) 必须有 run_command 工具，且具备安全拦截与超时：

– 禁止 shell 操作符：”>”、”>>”、”|”、”&”（即使不按空格分词也要拦截）

– 禁止危险命令关键字：rm/del/format/mkfs/…（可扩展）

– 命令执行必须有 timeout（例如 30s）

4) 必须有 write_file 工具：用于创建/覆盖文本文件内容，避免通过 run_command 重定向写文件：

– 必须校验父目录存在

– 支持 overwrite 参数（默认 true）

– 返回写入成功信息（包含写入字节数或行数即可）

5) Skills 文件必须是 skills/<skill-name>/SKILL.md：

– 包含 frontmatter：name / description

– 正文是指令说明（instructions）

– 至少提供三个 skills：

– file-explorer：指导 list_files/read_file/write_file

– terminal：指导 run_command，强调避免重定向并建议写文件走 write_file

– pc-control：能力可先留空或提供最小占位 Tool，但 skill 文件必须存在

6) Skills 按需加载（核心流程）：

– 启动阶段：只扫描 skills 目录，解析每个 SKILL.md 的 frontmatter，得到技能索引：name/description + file_path（不加载正文 instructions）

– 请求阶段（两段式）：

a) 先把技能索引（name/description 列表）发给 LLM，让其“只返回 JSON 数组的 skill 名称”，例如 [“terminal”]

b) 再按需读取被选中的 SKILL.md 正文 instructions，拼接进最终 prompt，再让 LLM 进入工具调用决策

7) Agent 必须支持多轮工具调用循环：

– 每轮：LLM 决策 -> 若选择 tool 则执行 -> 将 tool result 追加到上下文 -> 再问 LLM 下一步

– 设置 max_steps（例如 5）防止无限循环

8) docs 必须包含一张 Mermaid 流程图，且能被大多数 Mermaid 渲染器解析：

– 使用 graph TD（不要用 flowchart TD）

– 不要用 subgraph 到 subgraph 的连线

– 流程图必须体现：技能索引 -> LLM 选技能 -> 按需加载全文 -> LLM 决策 -> Tool 循环 -> 完成返回

9) 必须提供 test_remote.py：向 HTTP 网关 /chat 发送中文指令并打印响应（包含 1/2/3 三条测试文案）。

10) 代码必须能在 Windows 下运行；路径示例要兼容 Windows（如 G:\\测试.txt）；tools 的 path 参数允许相对路径。

## Project Structure (Must)

clawdbot/

core/

agent.py

llm.py

skill_loader.py

tools/

base_tool.py

file_tools.py

cli_tools.py

computer_tools.py

gateways/

http_gateway.py

telegram_gateway.py

skills/

file-explorer/SKILL.md

terminal/SKILL.md

pc-control/SKILL.md

docs/

WOSHIPM_ARTICLE.md

server.py

test_remote.py

requirements.txt

README.md

## Implementation Requirements (By File)

1) clawdbot/tools/base_tool.py

– BaseTool 抽象类：name/description/parameters/execute

2) clawdbot/tools/file_tools.py

– ListFilesTool(list_files)：列目录

– ReadFileTool(read_file)：读文本

– WriteFileTool(write_file)：写文本（关键：避免命令重定向写文件）

3) clawdbot/tools/cli_tools.py

– RunCommandTool(run_command)：执行命令 + 安全拦截 + 超时

– 拦截逻辑必须能识别 shell 操作符（即使不按空格分词也要拦截）

4) clawdbot/core/skill_loader.py

– SkillDefinition：name/description/instructions/file_path

– parse_skill_file(file_path, include_instructions: bool)

– 解析 frontmatter（–

– … —）与正文

– include_instructions=False 时只返回空 instructions，但仍返回 file_path

– SkillLoader.load_skills(include_instructions: bool = True)

5) clawdbot/core/llm.py

– LLMProvider 接口：generate_tool_call(prompt, tools_def)

– MockLLM：在无 key 时可用（简单规则即可：看到“列出”-> list_files；看到“读取”-> read_file；看到“创建/写入”-> write_file；看到“运行命令”-> run_command；否则返回自然语言 response）

– Qwen Provider：如使用 dashscope/langchain 等请写入 requirements，并可从 env 读取 DASHSCOPE_API_KEY；初始化失败必须 fallback 到 MockLLM（server.py 里处理也可）

6) clawdbot/core/agent.py

– _select_skills(user_input)：把 skills 索引（name/description）发给 LLM，让其仅返回 JSON 数组 skill 名称；解析失败要有合理 fallback（例如默认全选或返回空）

– _ensure_instructions(skill)：若 instructions 为空则 parse_skill_file(skill.file_path, include_instructions=True) 加载全文

– run(user_input)：组装 tools_def；按需加载 skills；进入多轮 tool loop（max_steps=5）；每次 tool 执行结果追加到上下文，再继续问 LLM

7) clawdbot/gateways/http_gateway.py

– SimpleHTTPGateway，提供 POST /chat：接收 {“message”: “…”} 返回 {“response”: “…”}

8) clawdbot/gateways/telegram_gateway.py

– 可以最小占位（如果实现完整请说明依赖与 token 使用）

– 至少保证代码不影响 http/cli 模式运行

9) server.py

– argparse 支持：mode=cli/http/telegram，port，llm-provider=mock/qwen，api-key 可选

– 初始化 tools（包含 write_file）与 skills 索引：loader.load_skills(include_instructions=False)

– Agent 内部 name 可用 “Clawdbot”，但文档对外叫 LocalPilot

– http 模式启动 0.0.0.0 监听 port

10) docs/WOSHIPM_ARTICLE.md

– 标题必须包含：从 Moltbot 出发、本地优先、远程电脑 AI 执行智能体、名称 LocalPilot

– 文中强调：参考 moltbot/moltbot 的思路，但为国内模型成本与实验目的自研

– Mermaid 流程图体现：Skills 按需加载 + Tool 多轮循环

– 全文不要出现 “Clawdbot” 作为产品名（仅可在代码目录名处出现 clawdbot/）

11) README.md

– 环境要求、安装、如何运行（cli/http）

– 如何配置 DASHSCOPE_API_KEY（可选）

– 如何用 test_remote.py 测试三条测试指令

– 必须包含运行命令示例（Windows PowerShell 友好）

– 必须包含一次 test_remote.py 的预期输出样例（说明写文件会走 write_file，不会触发 ‘>’ 拦截）

– 安全说明：run_command 禁止重定向；写文件用 write_file