Clawd on Desk 完整指南：让 AI 编码 Agent 化身像素桌面宠物，实时看清它的工作状态
【免费下载链接】clawd-on-deskA pixel desktop pet that watches Claude Code, Codex, Cursor & other AI coding agents — so you don't have to.项目地址: https://gitcode.com/gh_mirrors/cl/clawd-on-desk
Clawd on Desk（Clawd 桌宠）是一款免费的像素桌面宠物工具，它实时盯住 Claude Code、Codex、Cursor、Copilot、Gemini 等 20+ 款 AI 编码 Agent：Agent 在思考时它冒思考泡泡，跑工具时它敲键盘，任务完成时它庆祝，你离开时它睡觉。发起长任务后不用死守终端——等桌宠告诉你"干完了"再回来即可。本指南带你从零上手这个 AI 编码状态监控桌宠。
一、Clawd on Desk 是什么？解决什么问题？
AI 编码 Agent 跑长任务时，终端输出又长又碎，人很难一眼看清：它是在思考、在改文件、在跑测试，还是卡在了权限确认上？
Clawd 桌宠把这一切变成动画语言：一只住在桌面上的像素螃蟹（也可换成三花猫、云宝），用 12 种动画实时映射 Agent 状态——透明窗口、点击穿透，不占任务栏、不打断你的工作流。
二、快速安装：三种方式让桌宠住上你的桌面
支持Windows 11 / macOS / Ubuntu、Linux，Windows 提供 x64 与 ARM64 双架构安装包。
1. 推荐：下载预构建安装包（普通用户）
- Windows：
Clawd-on-Desk-Setup-<version>-x64.exe（或 arm64） - macOS：
.dmg - Linux：
.AppImage或.deb
安装后直接启动即可。全新安装默认自动同步 Claude Code 和 Codex的 hooks，开箱即用；其他 Agent 在 设置 → Agents 里点一下"安装"即可。
2. 源码运行（贡献者 / 调试集成）
源码运行需要 Node.js ≥ 22.12，应用主入口为 src/main.js：
git clone https://gitcode.com/gh_mirrors/cl/clawd-on-desk cd clawd-on-desk npm install npm start # 启动时自动注册 Claude Code 与 Codex hooks3. 开机自启
Claude Code 的 SessionStart hook 可在 Clawd 未运行时自动拉起它，也可在系统托盘里开启自启动。更多平台细节（WSL、远程 SSH、macOS/Linux 注意事项）见官方配置指南。
三、12 种实时动画：Agent 工作状态一眼看懂
这是 Clawd 桌宠最核心的能力：Agent 的生命周期事件被自动映射成动画，你甚至不用看终端就能"读"出进度。
| 你看到螃蟹在… | Agent 正在… |
|---|---|
| 打转眼球看你（待机） | 会话空闲，等待指令 |
| 冒思考泡泡 | 你提交了 Prompt，模型思考中 |
| 敲键盘打字 | 正在调用工具改文件、跑命令 |
| 戴耳机律动 / 三球杂耍 | 1 个 / 2 个以上子代理并行工作 |
| 疯狂敲打（建造） | 多会话同时构建 |
| 报错姿势 | 工具执行失败 |
| 敲小锣（注意） | 任务结束 / 上下文压缩完成，需要你查看 |
| 举牌报警（通知） | 等待权限确认 |
| 扫地 / 搬箱子 | 上下文压缩 / 创建 worktree |
| 打哈欠 → 倒下睡觉 | 60 秒无活动，自动进入睡眠 |
几个有趣的小细节：待机时它的眼球会跟随你的鼠标移动；你走开 60 秒它会打哈欠、打盹、缓缓躺下入睡，一移动鼠标又会被惊得弹起来；双击戳它、连点 4 下都有隐藏反应彩蛋。完整的事件-状态对照表见状态映射文档，动画循环逻辑可参考 src/animation-cycle.js。
四、权限气泡：不回到终端，一键批准 AI 的敏感操作
AI 编码 Agent 执行高危操作（删文件、跑脚本）前常会请求权限，传统做法是切回终端敲y。Clawd 桌宠把权限请求弹成桌面浮动气泡卡片，右下角堆叠显示：
- 一键 允许 / 拒绝，支持的 Agent 还会提供
Always（永久规则）选项 - 全局快捷键：
Ctrl+Shift+Y允许、Ctrl+Shift+N拒绝最新气泡 - 自动关闭：如果你先在终端里回答了，气泡自动消失
- 处理模式三选一：每次询问 / 仅提问弹窗 / 自动放行（自动放行重启后会安全降级）
- 按 Agent 单独开关：在 设置 → Agents 里可关闭某个 Agent 的弹窗，让提示回到它自己的终端
权限服务的核心路由实现在 src/server.js 与 src/permission.js；自动化策略详见配置指南-权限处理自动化。
五、20+ AI 编码 Agent 一键接入
Clawd 桌宠的杀手锏之一是多 Agent 共存：所有会话独立追踪，统一解析到最高优先级的状态动画。目前支持的阵容（节选）：
| 集成方式 | 代表 Agent |
|---|---|
| 命令 hooks + HTTP 权限 hooks | Claude Code、CodeBuddy、Qwen Code、Kimi CLI |
| 官方 hooks + JSONL 日志兜底 | Codex CLI |
| 配置文件 hooks | Gemini CLI、Copilot CLI、Cursor Agent、Kiro CLI |
| 插件 / 扩展 | opencode、MiMo Code、Pi、OpenClaw、Hermes |
| 自定义 HTTP 上报 | 任意本地可执行程序（POST 到/state端点） |
接新 Agent 只需两步：启动 Clawd → 打开设置 → Agents→ 点对应 Agent 的Install / 安装，Clawd 会在每次启动时自动保持 hooks 同步；卸载也只删它自己管理的条目，不动你的其他配置。各 Agent 的 hook 安装脚本集中在 hooks/ 目录（如 hooks/gemini-install.js、hooks/qwen-code-install.js），Agent 适配逻辑在 agents/ 目录，统一注册表见 agents/registry.js。
不同 Agent 的能力边界（有无权限气泡、终端聚焦、轮询延迟等）整理在已知限制文档。
六、远程监控与手机镜像：人不在电脑前也能看状态
远程 SSH 模式
Agent 跑在云服务器 / 家里的小主机上？Clawd 通过SSH 反向端口转发把远程 hook 事件和权限请求隧道回本地桌面——在 设置 → 远程 SSH 里新建 profile（user@host+ 可选私钥），点部署 / 修复 Hook即可。远程会话的状态动画、权限气泡照常显示在本地螃蟹身上，全程无需改 Clawd 代码。完整教程见远程 SSH 指南。
手机 PWA 实时镜像
开启 设置 → Mobile / PWA 后，用手机打开配对链接，「Clawd Mobile」网页应用会实时广播各会话状态。设计上只读（PWA 无法操作你的电脑），令牌自动轮换，仅限局域网；添加到手机主屏幕即成"类原生 App"。
Telegram / 飞书远程审批、Slack 播报
权限请求可镜像到 Telegram 或飞书交互卡片，人在手机上一键批准；Slack 则负责播报任务完成、错误与权限提醒。通道故障时绝不自动拒绝，请求安全地继续等待。
七、主题、极简模式与桌面小彩蛋
- 三套内置主题：Clawd（像素螃蟹）、Calico（三花猫）、Cloudling（云宝），在 设置 → 主题 一键切换；还能导入 Codex Pet zip 动画包自动转成主题
- 自制主题：运行
npm run create-theme -- my-theme生成脚手架，最少 1 个 SVG（含眼球追踪的待机）+ 7 个动效文件即可；分发前用node scripts/validate-theme.js <路径>校验。教程见主题创建指南，主题素材在 themes/ - 极简模式：把螃蟹拖到屏幕右边缘，它藏起来只露半身，悬停探头招手，任务完成时抛物线跳出来庆祝
- 会话 Dashboard + HUD：右键 / 托盘 → 打开 Dashboard，查看所有活跃会话、最近事件，一键跳转对应终端窗口
- 免打扰模式：右键进入休眠，屏蔽需要处理的弹窗（远程完成通知仍会送达），任务完成还有短音效提醒
- 界面语言：简中、繁中、英、日、韩、西、葡七语随切
右键菜单长这样：
八、项目结构速览
| 路径 | 说明 |
|---|---|
| src/main.js | Electron 主进程入口，窗口与托盘管理 |
| src/server.js | 本机 127.0.0.1 事件 / 权限服务 |
| src/state.js | 多会话状态机与优先级解析 |
| hooks/ | 各 Agent 的 hook 安装与同步脚本 |
| agents/ | Agent 适配层（如 agents/claude-code.js） |
| themes/ | 内置主题（clawd / calico / cloudling） |
| pwa/ | 手机伴侣 PWA 源码 |
| docs/guides/ | 全部使用指南（中文齐备） |
| package.json | 构建与安装脚本（各 Agent install 命令一览） |
九、常见问题
Q：会拖慢我的 AI 编码 Agent 吗？hooks 只是轻量事件上报，走本机 loopback 端口（127.0.0.1:23333-23337），几乎零延迟；日志轮询类集成（Codex JSONL 兜底）也是低频只读。
Q：我改坏了 hooks 配置怎么办？Clawd 每 5 分钟做一次只读健康巡检，能自动发现并修复被清理的 hook 条目；仍失败时 Doctor（诊断面板）会给出手动 Fix 指引。
Q：它读取我的代码内容吗？状态上报只含事件类型与用量数据，权限卡片只显示待批准命令，不抓取 prompt 或代码正文。
Q：支持哪些平台？Windows 11、macOS、Ubuntu/Linux；WSL 场景下应用内 Pair 会自动探测网络链路并给出警告。
写在最后
Clawd on Desk 把"AI 编码 Agent 现在在干嘛"这件小事，做成了一个住在桌面上的像素宠物：看它睡觉你就安心走开，看它敲键盘就知道活还在跑，它敲锣报警时你才需要回头。免费开源（AGPL-3.0），多语言界面，装好后基本零配置——下一篇长任务，就让螃蟹替你看场吧。更多细节请查阅中文 README。
【免费下载链接】clawd-on-deskA pixel desktop pet that watches Claude Code, Codex, Cursor & other AI coding agents — so you don't have to.项目地址: https://gitcode.com/gh_mirrors/cl/clawd-on-desk
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
)
