1. 项目概述Claw Companion一个为OpenClaw网关打造的移动控制中心如果你正在寻找一个能让你在手机上轻松管理OpenClaw网关的工具那么Claw Companion for Android以下简称Claw Companion绝对值得你花时间深入了解。这不仅仅是一个简单的客户端它是一个从操作员视角出发深度整合了连接、会话管理、即时通讯、语音交互和网关调试等核心功能的移动控制台。想象一下你不再需要时刻守在电脑前通过手机就能查看网关状态、与AI代理对话、审批操作请求甚至进行底层的RPC调用Claw Companion将这些能力都浓缩在了你的掌中。这个项目源自于官方OpenClaw Android客户端的代码但经过开发者alnoori1的深度改造和增强加入了许多针对移动端使用场景的优化和实验性功能。它支持多种灵活的连接方式无论是扫描本地网关生成的二维码还是通过Tailscale Funnel安全地连接远程网关抑或在局域网内手动配置都能快速建立连接。其核心价值在于提供了一个专注、高效的移动操作界面将复杂的网关操作变得直观且触手可及非常适合需要随时随地进行网关监控和交互的开发者、运维人员或高级用户。2. 核心功能深度解析与设计思路Claw Companion的设计哲学非常明确移动优先操作员友好。它没有试图将桌面端的复杂界面照搬到手机上而是重新思考了在移动设备上管理网关的核心工作流。下面我们来拆解它的几个核心功能模块看看它们是如何服务于这一目标的。2.1 多元化连接策略从QR码到Tailscale Funnel连接网关是第一步也是最关键的一步。Claw Companion提供了四种主流的连接方式覆盖了从本地开发到远程部署的各种场景。2.1.1 标准QR码连接最便捷这是为本地开发或已配置好远程WebSocket地址的网关准备的最快方式。在电脑上运行openclaw qr命令终端会生成一个二维码。用手机上的Claw Companion扫描这个二维码应用会自动解析出网关的WebSocket地址ws://或wss://和认证令牌完成连接。这个过程几乎无需手动输入任何信息极大地简化了初始配置。注意openclaw qr生成的二维码包含的是临时的连接信息和令牌。确保在扫描时手机和运行网关的机器处于同一网络对于本地ws://连接或手机可以访问网关的公网地址对于wss://连接。2.1.2 Tailscale Funnel集成最安全便捷的远程访问对于部署在私有网络如家庭NAS、公司内网服务器的OpenClaw网关如何安全地从外网访问是个难题。Claw Companion原生集成了Tailscale Funnel支持完美解决了这个问题。如果你的网关已经配置了gateway.remote.url wss://你的主机.ts.net那么直接使用上述的QR码连接即可。Funnel为你的网关提供了一个由Tailscale管理的、具有TLS加密的公开HTTPS端点而Claw Companion可以无缝通过这个端点建立安全的WebSocket连接无需复杂的端口转发或VPN配置。2.1.3 局域网直连与手动配置提供最大灵活性对于一些受控的局域网环境或者需要连接一个临时搭建的、未配置远程URL的网关Claw Companion支持直接输入ws://地址和端口进行连接。你需要在网关端生成一个包含IP、端口和令牌的“设置载荷”然后在App的手动配置界面输入。这种方式虽然步骤稍多但给予了操作员最大的控制权。高级设置中还可以直接指定完整的WebSocket URLws://或wss://和认证信息。2.2 会话与聊天移动端的高效交互枢纽聊天界面是操作员与网关AI代理交互的主战场。Claw Companion对此进行了大量移动端优化。2.2.1 智能会话选择器在聊天界面顶部有一个下拉式的会话选择器。默认只显示最近活跃的5个会话避免列表过长影响操作。点击“显示全部”可以展开完整的会话列表。这个设计非常贴心因为大多数时候我们只关心少数几个当前会话。2.2.2 会话生命周期管理更强大的是你可以直接在这个选择器中对会话进行管理删除或归档。点击会话旁边的菜单选择相应操作即可。删除会话会要求二次确认防止误操作。如果当前正在活动的会话被删除应用会自动为你创建一个新的手机端会话确保聊天流程不会中断。这个功能对于清理测试会话、结束已完成任务的对话非常有用。2.2.3 增强的Slash命令支持Slash命令以/开头的命令是控制网关的快捷方式。Claw Companion改进了命令执行体验确保在执行如/status查看状态、/help获取帮助等命令时聊天输入框不会被冻结你仍然可以继续输入。特别重要的是/stop命令它被直接关联到会话级别的中止行为可以快速终止当前会话中代理正在进行的长时间运行操作或思考过程。2.2.4 富媒体消息草稿在聊天输入框你可以附加图片、音频或文档文件形成一条带附件的消息草稿。这比先发送文字再想办法传文件要直观得多。编辑好草稿包括可选的文字说明后再一键发送给代理。2.3 “分享到Claw”系统级集成带来的效率革命这是我认为Claw Companion最亮眼的特性之一。它将自己注册为Android系统的一个分享目标。当你在其他App中看到一段有趣的文字、一篇网页链接、一张图片或一个文档只需点击系统的“分享”按钮在分享目标列表中选择“分享到Claw”。接下来Claw Companion会启动并让你选择是创建一个新会话来处理这个内容还是发送到某个已有的会话中。你还可以为这个内容添加一段说明或指令例如“总结一下这篇文章”。确认后应用会跳转到聊天界面并自动将你分享的内容和指令填充为一条待发送的草稿。请注意它不会自动发送这给了你最后检查和修改的机会。这个功能将信息收集与AI处理的工作流无缝衔接极大地提升了移动端的使用效率。2.4 语音交互与调试控制台移动场景的专属优化2.4.1 为移动优化的语音界面Claw Companion有一个独立的“语音”标签页布局针对手机屏幕进行了优化。它提供“实时模式”和“按键通话”两种模式。在Android 13及以上版本它优先使用系统提供的分段/原始音频捕获API来实现PTT这通常能带来更低的延迟和更好的兼容性失败后才会回退到标准的语音识别器路径。界面集中了扬声器开关、代理“思考”状态指示器、停止按钮和会话选择器所有控制触手可及。2.4.2 一体化调试追踪控制台“调试”标签页是一个强大的诊断工具。它将客户端事件、AI代理消息、网关日志以及网络传输的有效载荷细节合并到一个统一的滚动日志视图中。你可以在这里实时看到连接建立、消息收发、语音生命周期等所有事件的详细轨迹。这对于排查连接问题、理解AI代理的响应过程、或者单纯想深入了解系统内部运作时是一个不可或缺的利器。控制台还支持按日志级别进行过滤帮助你快速聚焦于错误或警告信息。3. 从零开始构建、配置与深度使用指南了解了核心功能后我们来看看如何从源码构建并进行深度配置和使用。这对于想要定制功能或参与贡献的开发者尤为重要。3.1 开发环境搭建与源码编译3.1.1 环境准备要编译Claw Companion你需要准备以下环境Android Studio推荐使用最新稳定版它集成了所需的SDK和工具链。Android SDK API 36项目指定的编译目标。可以在Android Studio的SDK Manager中下载。JDK 17确保JAVA_HOME环境变量指向JDK 17或更高版本。测试设备实体Android手机或模拟器系统版本需为Android 12API 31或更高因为minSdk设置为31。3.1.2 获取源码使用Git克隆项目仓库git clone https://github.com/alnoori1/claw-companion-android.git cd claw-companion-android3.1.3 编译调试版APK打开终端在项目根目录执行Gradle命令./gradlew :app:assembleDebug对于Windows PowerShell用户.\gradlew :app:assembleDebug编译成功后你可以在app/build/outputs/apk/debug/目录下找到app-debug.apk文件。将其安装到设备即可进行测试。注意调试版APK由于包含了调试符号和未优化的代码体积会远大于发布版。仅用于开发测试不要将其用于日常使用或分享。3.1.4 编译发布版APK需签名发布版APK需要签名密钥。项目使用Gradle属性来管理签名信息。你需要创建一个本地的keystore.properties文件切记不要提交到Git并填入以下内容OPENCLAW_ANDROID_STORE_FILEyour-keystore.jks OPENCLAW_ANDROID_STORE_PASSWORDyour-store-password OPENCLAW_ANDROID_KEY_ALIASyour-key-alias OPENCLAW_ANDROID_KEY_PASSWORDyour-key-password将your-keystore.jks文件放在项目根目录或指定路径。然后运行发布构建命令./gradlew :app:assembleRelease发布版APK将生成在app/build/outputs/apk/release/目录下。3.2 网关连接配置实战假设你有一个运行在家庭局域网树莓派上的OpenClaw网关并且你希望通过Tailscale Funnel在户外用手机访问它。以下是详细步骤3.2.1 网关端配置确保你的树莓派已经安装了Tailscale并登录了你的账户。在树莓派上启动OpenClaw网关。假设网关运行在localhost:8080。你需要配置网关使其通过Tailscale Funnel暴露一个安全的远程访问地址。这通常需要在网关的配置文件或启动命令中设置gateway.remote.url。具体的配置方法请参考OpenClaw和Tailscale的官方文档。假设配置成功后你的网关远程地址是wss://my-pi-claw.your-account.ts.net。在树莓派上进入OpenClaw网关所在目录运行openclaw qr。这个命令会读取网关配置生成一个包含wss://my-pi-claw.your-account.ts.net地址和临时令牌的二维码。3.2.2 手机端连接在手机上安装并打开Claw Companion App。首次启动会进入引导流程。在连接环节选择“扫描二维码”。用手机摄像头扫描树莓派终端上显示的二维码。App会自动识别出WebSocket地址和令牌尝试建立连接。如果一切正常几秒钟后你就会看到网关的主仪表盘上面显示了会话、设备等状态信息。3.2.3 局域网手动连接备选方案如果暂时没有配置Funnel但手机和树莓派在同一个Wi-Fi下你可以使用局域网手动连接。在树莓派上使用hostname -I或ip addr查看其局域网IP地址例如192.168.1.100。你需要从网关获取一个用于配对的长效令牌或密码具体方式取决于OpenClaw网关的配置。在Claw Companion的“高级设置”或连接页面选择“手动输入”。主机填写192.168.1.100端口填写8080TLS模式选择“关闭”因为本地连接通常用ws://然后输入令牌或密码。点击连接。成功后效果与扫描二维码一致。3.3 权限管理的设计与实践Claw Companion在权限请求上遵循了Android的最佳实践运行时按需请求。这意味着App不会在启动时就一股脑地要求所有权限而是在你真正需要使用某个功能时才会弹出系统授权对话框。麦克风权限只有当你首次点击进入“语音”标签页并尝试说话时才会请求。拒绝后语音功能将无法使用但其他所有功能正常。相机权限仅在扫描二维码时请求。相册/媒体权限仅在聊天中点击附件按钮选择图片、或通过“分享到Claw”功能分享图片时请求。这种设计最大程度地尊重了用户的隐私选择。如果你不小心拒绝了某个权限后续仍然可以在Android系统的“应用信息 - 权限”中重新开启或者在App的设置页面找到入口引导你前往系统设置。此外App还需要一些安装时即被授予的普通权限如网络访问INTERNET和网络状态检查ACCESS_NETWORK_STATE这些是维持WebSocket连接和判断网络状况所必需的。为了保持与网关的长期连接它还声明了前台服务权限这会在连接建立时在通知栏显示一个持续运行的服务通知这是Android系统对后台长时间运行应用的要求。4. 项目架构、开发与协作要点对于开发者而言了解项目的技术栈和协作规范是参与贡献或进行二次开发的基础。4.1 技术栈剖析Claw Companion采用了现代Android开发的推荐技术组合Kotlin作为首选编程语言提供了空安全、扩展函数等特性使代码更简洁、安全。Jetpack Compose声明式UI工具包。项目中的所有用户界面从复杂的聊天列表到简单的设置开关都是用Compose构建的。这带来了更直观的UI代码和更高效的渲染。OkHttp作为网络层的基础负责处理与OpenClaw网关之间的WebSocket连接和HTTP请求。OkHttp的强大在于其拦截器链、连接池和高效的HTTP/2支持为稳定的网关通信提供了保障。加密本地存储所有敏感的网关令牌、连接配置等信息都使用Android的加密存储机制如EncryptedSharedPreferences进行保存确保即使设备被物理访问这些数据也不会轻易泄露。4.2 开发工作流与代码管理项目采用常见的GitHub协作流程main分支代表稳定、可发布的代码状态。任何直接提交都应谨慎。功能分支开发新功能或修复Bug时应从main拉取一个新的特性分支例如feature/add-dark-mode或fix/connection-timeout。拉取请求完成开发后向main分支发起一个拉取请求。这不仅是合并代码的机制更是进行代码审查、自动化测试通过GitHub Actions和讨论的环节。对于非微小的改动都应该通过PR进行。发布流程正式的版本发布通过GitHub Releases进行。维护者会为每个版本打上标签并附上编译好的发布版APK和变更说明。具体的发布清单可以在项目的docs/releasing.md中找到。4.3 安全与隐私考量作为一个处理敏感网关连接信息的应用安全是重中之重代码库中无秘密项目的Git仓库中绝不包含任何真实的网关令牌、API密钥或APK签名密钥。签名密钥通过本地的keystore.properties管理并被.gitignore排除。最小权限原则如前所述应用严格遵守运行时权限请求。敏感信息脱敏项目文档明确提醒在分享截图或日志例如调试控制台的内容时务必手动涂抹掉网关主机地址、令牌和设备ID等敏感信息。上游归属项目坦承自己是基于官方OpenClaw Android源码的衍生作品并在NOTICE和upstream_attribution.md文件中保留了完整的原始许可声明和归属。所有新增或修改的功能也在文档中进行了说明。5. 常见问题排查与实战技巧在实际使用和开发过程中你可能会遇到一些问题。以下是一些常见情况的排查思路和解决技巧。5.1 连接类问题问题现象可能原因排查步骤与解决方案扫描二维码后连接失败1. 手机与网关主机网络不通。2. 网关服务未运行或端口错误。3. 二维码信息已过期。1.检查网络确保手机和网关在同一局域网或手机能访问网关公网IP/域名。2.验证网关在电脑上尝试用curl或浏览器访问网关的HTTP状态端口如果有。3.重新生成在网关端重新运行openclaw qr生成新的二维码。通过Tailscale Funnel连接超时1. Funnel未正确配置或启用。2. 手机未安装/登录Tailscale客户端。3. 网关防火墙阻止了连接。1.检查Funnel在Tailscale Admin控制台确认Funnel已为对应端口启用。2.检查Tailscale确保手机已安装Tailscale App并登录了同一个账户。3.检查网关日志查看网关端是否有连接尝试记录及错误信息。手动输入地址连接失败1. IP、端口或令牌错误。2. 使用了wss://但网关未配置TLS。3. 网关地址是内网IP手机在外网。1.仔细核对确认IP、端口、令牌完全匹配网关配置。2.匹配协议本地测试通常用ws://和 “TLS关闭”远程或Funnel用wss://和 “TLS开启”。3.使用Funnel或VPN从外网访问内网网关必须借助Tailscale Funnel、VPN或端口转发。实战技巧当连接出现问题时第一时间打开App内的“调试”标签页。这里会显示详细的连接握手过程、WebSocket状态和错误信息。例如如果看到“SSL handshake failed”那很可能是TLS配置有问题如果看到“Connection refused”则是网络不通或服务未启动。5.2 功能与使用类问题问题现象可能原因排查步骤与解决方案“分享到Claw”选项未出现在分享菜单1. Android系统限制了分享目标数量。2. App被系统“冻结”或深度优化。3. 分享的内容类型不被支持。1.点击“更多”在分享菜单列表底部点击“更多”或“…”查看全部应用。2.重启应用完全关闭Claw Companion再重新打开使其重新向系统注册。3.检查类型目前支持文本、链接、图片、音频和常见文档。语音识别不准或没反应1. 未授予麦克风权限。2. 环境噪音太大。3. Android语音识别服务问题。1.检查权限进入App设置或系统应用权限设置确保麦克风权限已开启。2.切换模式尝试在“实时模式”和“按键通话”模式间切换。3.测试系统语音用手机的其他录音或语音搜索功能测试排除硬件问题。聊天消息发送失败1. 与网关的连接已断开。2. 网关代理处理超时或出错。3. 消息内容格式问题。1.检查连接状态查看App顶部或主页的连接状态指示。2.查看调试日志在“调试”页查看网关是否有错误响应。3.简化消息尝试发送纯文本消息测试基础功能。实战技巧对于复杂的AI代理指令如果一次发送后代理“卡住”或响应异常不要一直等待。果断使用/stop命令中止当前会话的思考过程然后重新组织更清晰、更简短的指令发送。很多时候指令过于复杂或模糊是导致交互失败的主要原因。5.3 编译与开发类问题问题现象可能原因排查步骤与解决方案./gradlew命令失败1. 未安装JDK或版本不对。2. Gradle Wrapper权限问题。3. 网络问题无法下载依赖。1.检查Java运行java -version确认是JDK 17。2.添加执行权限在Unix系统上运行chmod x gradlew。3.使用国内镜像在gradle.properties中配置阿里云等Maven镜像源。Android Studio无法识别项目1. 项目未正确同步。2. 缺少必要的SDK组件。1.同步项目点击Android Studio右上角的“Sync Project with Gradle Files”图标。2.安装SDK通过SDK Manager确保安装了Android SDK API 36和相应的构建工具。调试版APK体积巨大这是正常现象。调试版包含调试符号、未优化代码和未压缩资源。如需分享测试请编译发布版APK。开发心得在修改UI时充分利用Android Studio对Compose的实时预览功能。你可以为Composable函数添加Preview注解在不运行整个App的情况下实时查看UI修改效果这能极大提升布局调整的效率。Claw Companion作为一个活跃的衍生项目它在官方客户端的基础上切实解决了许多移动端使用的痛点。无论是其深思熟虑的权限设计、无缝的系统集成还是强大的调试支持都体现了一个以用户体验为中心的产品思维。如果你经常需要与OpenClaw网关交互把它安装到手机上可能会彻底改变你的工作流。