1. 项目概述：Palmier，一个连接AI代理与手机的桥梁

如果你和我一样，日常在电脑上运行着Claude Code、Gemini CLI这类AI代理工具，那你肯定也遇到过这样的场景：人不在电脑前，但突然想让代理帮你查个日程、发条短信，或者代理在执行任务时需要你授权某个操作，你却只能干等着。Palmier就是为了解决这个痛点而生的。简单来说，它是一个 代理无关的手机桥接与控制层 。它不是一个全新的AI代理运行时，而是为你已有的代理（比如Claude Code、Gemini CLI、OpenClaw等）提供一个通往你手机的“高速公路”，让你能远程管理它们，也让它们能调用你手机上的真实能力。

想象一下，你的AI代理不再局限于操作电脑上的文件和终端命令。通过Palmier，它可以在后台读取你手机的短信通知、获取GPS位置、管理通讯录和日历，甚至在你授权后发送短信或邮件。而你，则可以通过手机上的网页应用或安卓App，随时随地启动代理任务、审批请求、查看结果，或者只是简单地给代理下达一个新指令。这相当于给你的AI代理装上了“眼睛”和“手”，让它能感知并影响现实世界，而不仅仅是数字世界。

这个项目最吸引我的地方在于它的“无侵入性”和“专注性”。它不要求你更换现有的AI代理工作流，只是作为一个后台守护进程（Daemon）运行在你的电脑上，通过一个移动友好的渐进式网页应用（PWA）或原生安卓App与你配对。它的架构设计清晰地划分了职责：你的代理负责“思考”和“决策”，Palmier负责“连接”和“执行”。这种设计哲学让它在保持轻量的同时，具备了强大的扩展性。

2. 核心架构与工作原理深度解析

要理解Palmier如何工作，我们需要拆解它的几个核心组件和它们之间的交互方式。这不仅仅是理解一个工具，更是理解一种将本地AI能力与移动设备无缝整合的设计范式。

2.1 三层架构：守护进程、中继服务器与移动端

Palmier的架构可以清晰地分为三层，理解这三层是掌握其精髓的关键。

第一层是运行在你主机（电脑）上的 守护进程 。这是整个系统的核心大脑。它通过 palmier serve 命令启动，并以后台服务的形式持续运行（在Linux上是systemd用户服务，macOS是LaunchAgent，Windows是任务计划程序）。这个守护进程做了几件关键事：首先，它会自动探测你系统上已安装的、受支持的AI代理CLI（如 claude 、 gemini 命令）。其次，它启动了一个HTTP服务器，默认在 localhost:7256 上监听。这个服务器不仅提供了Web管理界面，更重要的是，它暴露了一个 MCP服务器 和一个 RPC API 。MCP（Model Context Protocol）是Anthropic提出的一种协议，旨在让AI模型能动态发现和使用工具。Palmier通过MCP，将“发送通知”、“读取联系人”等手机能力，以标准化工具的形式暴露给你的AI代理。即使你的代理不支持MCP，也可以通过简单的HTTP POST请求调用相同的RPC接口。

第二层是 中继服务器 ，由Palmier官方运营。这是实现远程访问的关键。当你通过手机App或网页（非本地）连接你的主机时，连接并不是直连的，而是通过这个云端中继进行转发。这里有一个非常重要的隐私设计：中继服务器仅充当“邮差”的角色，它对转发的数据（你的任务内容、代理输出、手机指令）是 零知识 的。所有数据在传输前都在你的主机和手机端进行了端到端加密，中继服务器无法解密或存储它们。它只负责路由消息和推送通知（通过FCM，Firebase Cloud Messaging）。这种设计在便利性和隐私之间取得了很好的平衡。

第三层就是 移动端 ，即你的手机。它有两种形式：一是通过任何现代浏览器访问的PWA（渐进式网页应用），二是功能更完整的原生安卓App。PWA提供了基本的管理和交互功能，而原生App则解锁了全部能力，包括后台接收推送通知、访问系统权限（短信、通讯录等），以及最重要的—— Auto-LAN（自动局域网直连） 。

2.2 连接模式详解：本地、远程与Auto-LAN

Palmier提供了三种连接模式，适应不同场景，其背后的网络原理值得深究。

本地模式 是最简单直接的。你只需在运行Palmier守护进程的电脑上，打开浏览器访问 http://localhost:7256 。所有流量都在本机回环网络接口（127.0.0.1）内完成，不经过任何外部网络。这种模式适合你就在电脑旁，但想用手机或平板作为第二块控制屏的场景。它的延迟极低，且绝对私密。

远程（网页）模式 让你能在任何有网络的地方，通过浏览器访问 https://app.palmier.me 来管理你的主机。当你在此输入配对码后，你的浏览器会与Palmier中继服务器建立一个持久的、加密的WebSocket连接。你发出的所有指令（如“运行任务”）都会通过这个连接到达中继，中继再转发给你主机上的守护进程。同样，主机的响应和通知也沿原路返回。由于浏览器安全限制（如私有网络访问限制），这种模式无法实现点对点直连，所有流量必须经由中继。

远程（App）模式 是体验最完整的，也是我强烈推荐的方式。安装安卓App后，初始配对同样经过中继服务器。但配对成功后，魔法就发生了：App会尝试在本地网络中发现你的主机。一旦发现（即手机和电脑在同一个Wi-Fi下），App会自动将后续所有的RPC（远程过程调用）请求，从“经由中继转发”切换为“直接向主机的局域网IP地址（如 http://192.168.1.100:7256 ）发送请求”。这就是 Auto-LAN 。它带来了两个巨大好处：一是 极低的延迟 ，指令几乎瞬间到达主机；二是 离线可用 ，即使你的电脑没有公网IP，或者中继服务器暂时不可用，只要在同一局域网内，控制依然畅通无阻。只有推送通知这类需要穿透网络防火墙的通信，才会继续使用中继。

实操心得：Auto-LAN的生效条件 Auto-LAN听起来很美好，但需要满足几个条件：1) 主机和手机必须在同一子网内（通常是连接同一个路由器）。2) 主机的防火墙需要允许对7256端口的入站连接（Palmier安装脚本通常会帮你配置）。3) 主机的IP地址不能是特殊的Docker网桥IP等。如果Auto-LAN失效，App会自动降级到中继模式，不影响基本功能，但交互会稍有延迟。

2.3 MCP服务器：赋予AI代理“手机感知”能力

MCP是Palmier技术栈中一个非常亮眼的部分。它本质上是一套标准化的接口，让AI代理能动态查询“我现在能使用哪些工具？”以及“我能访问哪些资源？”。Palmier守护进程在 http://localhost:7256/mcp 提供了一个MCP服务器。

当你的AI代理（例如配置了MCP客户端的Claude Code）启动时，它可以连接到这个MCP服务器。连接后，Palmier会告诉代理：“嗨，我这里有这些工具可以用： notify （发推送）、 request-input （请求用户输入）、 device-geolocation （获取GPS位置）……” 代理在规划任务时，就能将这些工具纳入考虑。例如，一个旅行规划代理可以主动使用 device-geolocation 获取你的当前位置，作为规划的起点。

对于不支持MCP的代理，Palmier也提供了对等的RESTful API。例如，你可以用 curl 命令手动调用： curl -X POST -H “Authorization: Bearer <token>” -H “Content-Type: application/json” http://localhost:7256/rpc/notify -d ‘{“title”: “提醒”, “body”: “该开会了”}’ 。MCP只是让这一切对代理而言更自动化、更原生。

资源订阅 是另一个强大功能。代理可以“订阅”某个资源，比如 sms-messages://device （设备短信）。一旦手机收到新短信，Palmier会通过MCP的 resources/updated 事件实时通知代理。这使得代理能够实现事件驱动的自动化，比如“监控特定号码的短信，收到验证码后自动填写”。

3. 从零开始：详细安装与配置指南

纸上谈兵终觉浅，下面我带大家走一遍完整的安装和配置流程。我会以macOS系统为例，同时指出Linux和Windows上的关键差异点。请确保你已安装至少一个Palmier支持的AI代理CLI，这是前提。

3.1 环境准备与一键安装

首先，我们需要安装Palmier本身。官方提供了一键安装脚本，非常方便。打开你的终端（Linux/macOS）或PowerShell（Windows）。

对于Linux或macOS用户，运行以下命令：

curl -fsSL https://palmier.me/install.sh | bash

这个脚本会做几件事：1) 检查系统是否安装了Node.js 24或更高版本。如果没安装，它会通过 fnm （一个快速的Node版本管理器）为你安装。2) 通过npm全局安装 palmier 包。3) 在你的用户目录下创建 ~/palmier 作为工作根目录。

对于Windows用户，在PowerShell（管理员身份）中运行：

irm https://palmier.me/install.ps1 | iex

Windows脚本会通过 winget 来确保Node.js的安装。

如果你已经拥有Node.js 24+和npm环境，也可以直接通过npm安装：

npm install -g palmier

安装完成后，你可以通过 palmier --version 来验证安装是否成功。

注意事项：关于Node.js版本 务必使用Node.js 24或更高版本。我在早期测试中使用Node 18遇到了一些ES模块兼容性问题。Palmier的某些依赖利用了较新的Node API。如果你系统上有多个Node版本，建议使用 nvm 或 fnm 进行管理，确保默认版本符合要求。

3.2 初始化向导与守护进程配置

安装好CLI后，进入Palmier的根目录（通常是 ~/palmier ），运行初始化命令：

cd ~/palmier
palmier init

这个交互式向导是配置过程的核心。它会引导你完成以下步骤：

1. 代理检测 ：向导会自动扫描你的 PATH 环境变量，寻找已安装的AI代理CLI（如 claude , gemini , codex 等）。它会列出所有找到的代理，并询问你是否要启用它们。你可以全选，也可以只启用你常用的几个。
2. 网络配置 ：接下来，它会让你设置HTTP服务端口，默认是7256。确保这个端口没有被其他程序占用。然后，它会尝试自动检测你主机的默认网络接口（如 en0 WiFi接口）和对应的IP地址。这个IP地址对于后续的Auto-LAN功能至关重要。
3. 服务安装 ：向导会询问你是否安装后台守护进程。选择“是”。根据你的操作系统，它会进行以下操作：
   • Linux ：在 ~/.config/systemd/user/ 下创建一个 palmier.service 文件，并启用这个用户级systemd服务。这意味着Palmier会在你登录后自动启动，并在后台持续运行。
   • macOS ：在 ~/Library/LaunchAgents/ 下创建一个plist文件，将其注册为当前用户的LaunchAgent。 这里有一个关键点 ：macOS的LaunchAgent只在用户图形界面登录后才运行。如果你重启电脑后没有登录，Palmier服务是不会启动的。对于需要7x24小时运行主机的用户，需要在“系统设置-用户与群组-登录项”中配置自动登录。
   • Windows ：通过 schtasks 命令创建一个计划任务，设置为用户登录时触发，以最高权限运行。
4. 云端注册与配对 ：最后，向导会将你的主机信息注册到Palmier的中继服务器（生成一个唯一的Host ID），并立即进入配对模式，在终端显示一个6位数的配对码。同时，它会在本地生成配置文件 ~/.config/palmier/host.json ，保存所有上述设置。

初始化完成后，守护进程应该已经启动。你可以通过 palmier info 命令查看主机状态，包括本地访问地址、主机ID和网络接口信息。

3.3 移动端配对与能力授权

现在，拿起你的手机，我们进行配对。你有两个选择：

选择一：使用PWA（网页应用） 在任何手机的现代浏览器（Chrome, Safari）中，打开 https://app.palmier.me 。你会看到一个简洁的界面，点击“配对新主机”，然后输入刚才终端里显示的6位配对码。配对成功后，你就能看到你的主机，并可以进行基本的管理操作。但请注意，PWA无法使用Auto-LAN和后台推送通知。

选择二：使用安卓原生App（推荐） 从GitHub Releases页面下载最新的APK文件并安装。打开App，同样输入配对码。配对过程会要求你授予App一些必要的权限，比如“后台运行”、“电池优化忽略”等，请务必允许，这是保证推送和后台服务正常工作的基础。

配对成功后，进入主机详情页，你会发现一个“设备能力”或类似的抽屉菜单。这里列出了所有Palmier可以调用的手机功能：通知、位置、短信、联系人、日历等。每个功能都有一个开关。 你需要在这里手动开启某个功能，并且当App首次尝试使用该功能时，系统会弹出Android原生权限申请对话框，你必须点击“允许” 。例如，当你第一次尝试通过Palmier发送短信时，App会请求短信发送权限，你授权后，该功能才能正常工作。

实操心得：权限管理与安全边界 Palmier将权限控制分为两层：第一层是Palmier App内部的开关，由你控制；第二层是Android系统级的权限弹窗。这种设计给了你精细的控制权。我的建议是，按需开启。例如，如果你只打算用手机接收任务完成通知，那就只开“通知”权限。这遵循了最小权限原则，降低了安全风险。同时，记住你的AI代理能做什么，完全取决于你在这里开启了什么。这是一个清晰的安全边界。

4. 核心功能实战：任务调度与手机能力调用

配置完毕，我们来实战Palmier最核心的两个功能：如何从手机管理AI代理任务，以及如何让AI代理调用手机能力。

4.1 创建与管理自动化任务

Palmier的Web界面和App界面都提供了直观的任务管理面板。你可以创建两种主要类型的任务：

1. 即时任务： 这就像给你的AI代理发一条即时消息。在任务面板点击“新建”，选择你的目标代理（如Claude Code），然后在输入框中写下你的指令。例如：“总结我今天~/work目录下所有新创建的Markdown文件内容，并通过通知发给我摘要”。点击运行，任务就会被发送到主机，由对应的代理CLI执行。你可以在手机上实时看到任务状态（排队中、运行中、完成、失败）和输出日志。

2. 定时任务： 这是实现自动化的关键。创建任务时，你可以设置一个Cron表达式或选择简单的重复模式（如每天、每小时）。例如，你可以创建一个每天上午9点运行的任务，指令是：“检查我的日历，获取今天第一个会议的主题和参会人，然后从通讯录中查找参会人的电话，最后通过短信发送‘我已出发’给前三个参会人”。这样，一个结合了日历、通讯录和短信的自动化提醒就完成了。

任务创建后，Palmier守护进程会利用操作系统的原生定时器（Linux的systemd.timer, macOS的launchd, Windows的Task Scheduler）来调度它们。这意味着即使Palmier的主进程重启，已设定的定时任务也会被恢复。

CLI管理任务 ：除了图形界面，你也可以通过命令行管理任务。例如， palmier run <task-id> 可以手动触发一个定时任务，这在调试时非常有用。

4.2 AI代理调用手机能力实战

让我们看几个具体的例子，看看AI代理如何通过Palmier与手机交互。假设我们有一个配置了Palmier MCP服务器的Claude Code会话。

场景一：基于位置的提醒 你在Claude Code中可以直接说：“帮我设置一个提醒，当我下次离家（假设家坐标已预设）超过5公里时，通知我检查是否关了空调。” Claude Code在理解指令后，可以调用MCP工具序列：首先，周期性（或通过订阅）调用 device-geolocation 获取当前位置；计算与家的距离；当距离超过阈值时，调用 notify 工具发送推送通知。这一切都在后台静默完成。

场景二：智能短信处理 你收到一条银行交易短信。你可以设置一个Palmier任务，让代理监控短信资源（ sms-messages://device ）。当新短信来自银行短号且包含关键词“支出”时，代理可以读取短信内容，解析出金额和商户，然后调用 create-calendar-event 在你的日历中创建一条财务记录，或者通过 request-confirmation 弹窗问你：“监测到一笔XX元在YY商户的消费，是否需要记录为‘餐饮’类别？”

场景三：复杂的交互工作流 代理在执行一个复杂任务时可能需要你的决策。例如，一个自动整理照片的代理发现了几张相似的照片，它可以调用 request-input 工具，在你的手机上弹出一个选择框：“检测到5张相似的照片，请选择最好的一张保留（1-5）”。你点击选择后，代理才会继续执行删除冗余照片的操作。这种“请求-批准”模式极大地增强了自动化流程的可靠性和可控性。

注意事项：工具调用的阻塞与异步 像 request-input 和 request-confirmation 这类需要用户交互的工具是“阻塞”式的。这意味着代理执行到这一步时会暂停，直到你在手机上做出响应。而像 notify 、 send-sms 这类工具则是“异步”的，调用后立即返回，不影响代理继续执行后续步骤。在设计自动化流程时，需要合理规划这些工具的调用顺序，避免不必要的等待。

5. 高级配置、故障排查与安全实践

随着深入使用，你可能会遇到一些网络问题，或者想要进行更高级的配置。下面分享一些我踩过坑后总结的经验。

5.1 网络问题与Auto-LAN故障排查

Auto-LAN功能失效是最常见的问题之一。表现为手机App可以连接，但延迟很高（说明走了中继），或者直接连接失败。

1. 检查基础连接 ：首先确认手机和电脑连接的是同一个Wi-Fi网络，并且处于同一子网（IP地址前三位相同，如192.168.1.x）。可以尝试在电脑上ping手机的IP，以及在手机上用网络扫描工具查看电脑的7256端口是否开放。
2. 防火墙设置 ：这是最常见的拦路虎。Palmier安装脚本通常会尝试配置防火墙，但并非百分百成功。
   • macOS ：前往“系统设置-网络-防火墙-选项”，确保允许 node 或 palmier 的传入连接。或者，直接在终端临时关闭防火墙测试： sudo /usr/libexec/ApplicationFirewall/socketfilterfw --setglobalstate off （测试后记得打开）。
   • Windows ：在“Windows Defender 防火墙-允许应用通过防火墙”中，确保Node.js或相关规则允许7256端口的入站连接（私有网络）。
   • Linux ：如果使用 ufw ，需要 sudo ufw allow 7256 。如果使用 firewalld ，则 sudo firewall-cmd --add-port=7256/tcp --permanent && sudo firewall-cmd --reload 。
3. 主机IP变更 ：如果电脑是DHCP获取IP，且IP地址变了，Auto-LAN可能失效。运行 palmier info 查看当前主机用于Auto-LAN的IP是否正确。如果不正确，可以重新运行 palmier init 来重新检测网络接口。
4. 使用App的诊断功能 ：好的安卓App通常有连接诊断页。Palmier App内可能有一个“连接状态”或“诊断”页面，它会显示当前是“直连模式”还是“中继模式”，并给出失败原因。

5.2 多代理配置与切换

如果你安装了多个AI代理CLI（比如同时有Claude Code和Gemini CLI），Palmier可以同时管理它们。在创建任务时，你可以选择由哪个代理来执行。

一个高级用法是创建“接力任务”。例如，你可以设置一个任务，先用Claude Code分析一份文档并生成要点，然后将要点作为输入，触发另一个由Gemini CLI执行的任务来将其翻译成另一种语言。这可以通过Palmier的API或者在一个代理的脚本中调用另一个代理的CLI命令来实现。

代理路径问题 ：有时Palmier守护进程可能找不到你的代理CLI，尤其是当你通过虚拟环境（如Python的venv、conda）安装时。确保代理的安装路径在系统PATH中，或者你可以在Palmier的配置中指定绝对路径。配置文件位于 ~/.config/palmier/host.json ，你可以手动编辑其中的 agentPaths 部分。

5.3 安全最佳实践

尽管Palmier设计上注重隐私和安全，但将AI代理与手机这么私密的设备连接，我们必须保持警惕。

1. 最小权限原则 ：在手机App的“设备能力”设置中，严格按需开启权限。如果某个自动化流程只需要日历读取权限，就不要开启短信发送权限。
2. 使用强配对码与定期轮换 ：配对码是短期有效的，但一旦配对成功，会生成一个长期有效的访问令牌。定期在主机上运行 palmier clients list 查看已配对的设备，对于不常用的设备，使用 palmier clients revoke <token> 撤销其访问权限。你甚至可以 palmier clients revoke-all 全部撤销，然后重新配对，就像更换密码一样。
3. 审计任务日志 ：Palmier会记录任务的执行历史和输出。定期检查这些日志，看看是否有非预期的操作发生。特别是关注那些调用了敏感权限（如发短信、写日历）的任务。
4. 隔离环境运行 ：对于高度实验性或不受信任的AI代理脚本，考虑在虚拟机或容器内运行Palmier和对应的代理，以隔离对宿主机和手机的影响。
5. 理解中继服务器的信任模型 ：再次强调，Palmier的云中继是“不可信中继”模型。它看不到你的数据内容，但知道你的主机和手机在线以及通信频率。如果你对此仍有顾虑，那么 仅使用本地模式 是最安全的选择，所有数据不出局域网。

5.4 常见问题速查表

问题现象	可能原因	解决方案
palmier init 失败，提示Node版本过低	系统Node.js版本 < 24	使用nvm/fnm安装Node.js 24+，或运行官方安装脚本让其自动安装。
手机App无法配对，提示“配对码无效”	1. 配对码已过期（有效时间短） 2. 主机守护进程未运行 3. 网络阻止连接中继	1. 在主机重新运行 palmier pair 获取新码。 2. 运行 palmier serve 或重启服务。 3. 检查主机防火墙/代理设置，确保能访问外部网络。
任务创建成功但从未执行	1. 定时任务Cron表达式错误 2. 守护进程崩溃或未启动 3. 代理CLI路径错误	1. 检查Cron表达式语法。 2. 查看服务状态（ systemctl --user status palmier ）。 3. 运行 palmier restart 让守护进程重新检测代理。
代理无法调用手机工具，返回“未链接设备”或“权限拒绝”	1. 手机未与主机“链接” 2. 该能力在App中未启用 3. Android系统权限未授予	1. 在App中该主机的抽屉菜单，确保“链接此设备”已勾选。 2. 在“设备能力”中打开对应开关。 3. 当首次使用时，在Android系统弹窗中点击“允许”。
Auto-LAN不工作，延迟高	1. 手机电脑不在同一网络 2. 主机防火墙阻止7256端口 3. 主机IP地址变更	1. 连接同一Wi-Fi。 2. 配置防火墙允许7256 TCP端口入站。 3. 重启主机网络或重新运行 palmier init 。
推送通知收不到	1. 手机App被系统“电池优化”杀死 2. FCM服务问题（国内网络可能受限） 3. 通知权限未开	1. 在手机设置中，将Palmier App加入电池优化白名单。 2. 尝试切换网络或使用代理。 3. 检查App和系统通知权限。

6. 总结与延伸思考

经过一段时间的深度使用，Palmier给我的感觉更像是一个“能力放大器”和“控制面板”。它没有重新发明AI代理，而是巧妙地用工程手段将现有的、强大的本地AI代理与移动设备生态桥接起来，创造出了“1+1>2”的效果。这种设计思路非常值得借鉴——与其做一个大而全的平台，不如做一个专注的、能无缝融入现有工作流的连接器。

从技术实现上看，它结合了本地守护进程的可靠性、云中继的穿透便利性、MCP协议的标准化以及原生App的性能优势，是一个相当扎实的工程作品。特别是Auto-LAN的设计，在用户体验上做到了“无感切换”，既保证了在外网的可访问性，又在内网提供了最佳性能。

当然，它也有其边界。目前它对iOS的支持仅限于网页版，功能受限；所有手机能力的调用最终都依赖于一个安卓App，这引入了额外的维护点和潜在的稳定性变量；复杂的自动化流程设计仍然需要用户对AI代理的提示词工程有一定理解。

对于未来，我期待看到更多AI代理原生集成MCP，使得工具调用更加流畅；也期待Palmier社区能涌现出更多可分享的、开箱即用的“技能模板”，让普通用户也能轻松搭建强大的个人自动化流程。无论如何，Palmier已经为我们打开了一扇窗，让我们看到了个人AI助理如何更自然、更强大地融入我们的数字生活与物理世界。