企业官网建设流程全解析

PalmClaw 是一个运行在手机上的端侧 AI Agent 框架，它允许 Agent 直接操作日历、联系人、文件等本机能力。本文拆解 PalmClaw 的 Agent 安全设计：工具参数 schema 校验、Android 权限按需申请、高危操作用户确认三道防线，让你放心把手机交给 Agent。

为什么不能"直接把手机交给Agent"

传统聊天机器人只会"动嘴"，而 PalmClaw 这样的端侧 Agent 会"动手"：创建日程、改联系人、读写文件。能力越强，风险也越大——一个不受约束的 Agent 可能误删数据、越权访问隐私。

PalmClaw 的思路是给 Agent 的每次行动都设置层层关卡。整体架构中，所有消息进入 Agent Loop 后，必须先经过Permission Check（权限检查）才能调用 Tools，整个流程运行在手机沙箱内：

更关键的是工程文档中的一条硬性规则："每个工具必须保持类型化 schema、Android 权限、高危操作确认、显式超时、结构化错误、操作边界"，见 docs/engineering/architecture.md。下面逐层拆解。

第一道防线：schema 校验——工具参数的"入学考"

Agent 输出的工具调用是自由文本，模型完全可能拼错参数、漏掉必填字段。PalmClaw 内置了一个轻量的 JSON Schema 校验器 ToolArgumentsValidator.kt，它在工具执行前逐条检查：

• 必填字段：缺少required声明的参数直接拒绝
• 类型匹配：string/number/boolean/array/object 逐一核对
• 枚举与范围：enum、minLength/maxLength、minimum/maximum、数组minItems/maxItems全部生效
• 多余字段：additionalProperties=false时禁止未声明的参数

校验发生在 ToolRegistry.kt 的execute流程中：解析参数 → schema 校验 → 带超时执行。任何一步失败，都返回结构化的错误信息并附上恢复提示，让模型自己"改错重来"，而不是带着脏参数去执行。这相当于把"执行权"和"合法性"彻底解耦：不合法的调用根本到不了真正的设备操作。

第二道防线：Android 权限——用时才要，缺了会引导

PalmClaw 在 AndroidManifest.xml 中声明了它可能用到的全部权限（联系人、日历、蓝牙、媒体等），但声明不等于使用——真正的授权发生在每次调用时：

• 执行contacts工具的search前，会先检查READ_CONTACTS；写操作才追加WRITE_CONTACTS
• 权限缺失时，通过 AndroidUserActionBridge.kt 弹出系统授权框，并支持 60 秒超时兜底，避免 Agent 无限挂起
• 被拒绝后可以打开应用设置页引导用户手动授权，技能文档中称为"权限恢复流程"（request_if_missing/open_settings_if_failed/wait_user_confirmation），见 skills/android-personal/SKILL.md

这套机制遵循最小权限原则：Agent 什么时候需要权限、为什么需要，用户都看得见、随时可拒。

第三道防线：用户确认——高危操作的"刹车"

读取类操作（搜索、查询）自动执行，但破坏性操作必须用户点头。以删除联系人为例，AndroidContactsTools.kt 中的delete_contact流程是：

1. 先校验该联系人是否全部可写（含只读分片的直接拒绝并给出替代方案）
2. 弹出确认框，明确提示"将删除该联系人及全部 N 条 RawContact 记录"
3. 用户选择"取消"→ 返回user_cancelled，数据零变更；确认框不可用 → 返回错误并引导手动操作

同样的刹车出现在其他高危路径：

注意确认超时的设计：用户长时间不操作，Agent 会默认中止而不是默认通过——超时是"拒绝"的语义，这是安全设计里很关键的一个细节。

数据与网络层的加固：沙箱、加密与端点策略

除了上述三道防线，PalmClaw 在存储和网络侧还有几层加固：

• 工作区沙箱：文件工具统一走 WorkspaceFileSystem.kt，路径被限制在批准的工作区根目录内，默认不跟随符号链接，写入采用有界/原子操作
• 密钥加密存储：API Key 等敏感配置由 SecureStringStore.kt 使用 AndroidKeyStore 中的 AES/GCM 密钥加密落盘，密钥本身不出硬件安全边界
• MCP 端点策略：外部工具服务器默认要求 HTTPS；公共网络明文 HTTP 直接拒绝，局域网 HTTP 需按 origin 显式批准且不允许携带 Bearer Token，凭据也不允许出现在 URL 里，见 McpEndpointPolicy.kt

给用户的几条安全实践

结合 SECURITY.md 的官方建议：

• 🔒 只从可信的发布渠道安装构建
• 🎫 为渠道（Telegram、Discord、飞书等）和模型服务使用最小权限的 token
• 🔄 token 一旦泄露立即轮换
• 📵 避免在公开场合贴出可能含密钥的日志
• 🚨 发现漏洞通过官方私报渠道报告，修复前不要公开

小结：分层防御，把"信任"变成"可验证"

PalmClaw 的安全设计可以浓缩成一句话：Agent 的每一分权力，都对应一层可校验的约束——

1. schema 校验拦住"参数层面"的失控（ToolArgumentsValidator.kt）
2. Android 权限拦住"系统层面"的越权（AndroidManifest.xml + 运行时授权）
3. 用户确认拦住"后果层面"的不可逆操作（AndroidUserActionBridge.kt）
4. 沙箱、加密与网络策略拦住"数据与传输层面"的泄露（SecureStringStore.kt、McpEndpointPolicy.kt）

这种分层结构正是端侧 Agent 能落地的前提：能力给足，但每一步都可审计、可拒绝、可回滚。