JinDaGe - deskmate MCP Details

article

README

🚀 桌面助手（Deskmate）

Deskmate 是一款本地执行代理工具，允许你使用自然语言控制个人计算机，并能在你常用的通讯渠道与你交互。它专注于执行任务，而非自主决策或编排任务。你可以通过手机发送 Telegram 消息，让计算机执行相应操作。Deskmate 支持多种代理后端，如 Claude Code、Codex (OpenAI)、Gemini CLI 和 OpenCode，可全面访问本地工具，无沙盒命令限制，无人工设定的使用限制。

🚀 快速开始

选项 A：从 npm 安装（推荐）

npm install -g @sarkar-ai/deskmate
deskmate init

安装向导会引导你完成所有设置，包括 API 密钥、Telegram 凭证、平台权限和后台服务设置。配置信息存储在 ~/.config/deskmate/.env 中。

设置完成后，你可以手动运行 deskmate，也可以让后台服务自动处理。

选项 B：从源代码安装（适用于贡献者）

git clone https://github.com/sarkar-ai-taken/deskmate.git
cd deskmate
npm install --legacy-peer-deps
npm run build
./install.sh          # 交互式操作：配置 .env、服务和权限

或者，你也可以使用 TypeScript 向导代替 shell 安装程序：

cp .env.example .env  # 用你的凭证编辑
npx deskmate init     # 或者：npm link && deskmate init

若要稍后重新配置，可运行 deskmate init。

✨ 主要特性

全面本地访问：代理可以运行任何命令，读写任何文件，进行屏幕截图。无 6 工具沙盒限制。
多渠道网关：目前支持 Telegram，未来将支持 Discord、Slack、WhatsApp 等。一个网关，多个客户端。
对话记忆：跨消息保持会话连续性，可自然地提出后续问题。
多代理后端：默认使用 Claude Code，还支持 Codex (OpenAI)、Gemini CLI (Google) 和 OpenCode。可在 .env 中通过 AGENT_PROVIDER=codex 切换。
默认批准：安全命令自动批准。受保护文件夹（桌面、文档等）通过内联按钮提示确认。
MCP 服务器：将你的计算机作为工具服务器暴露给 Claude Desktop 或任何 MCP 客户端。
技能系统：在 skills.json 中定义可重复使用的多步骤工作流。技能可以运行命令、代理提示或其他技能，文件更改时自动热加载。
定时任务调度器：通过 crons.json 安排定期任务（命令、代理查询或技能），结果将发送到你活跃的聊天渠道。
健康监控：内置 CPU、内存、磁盘和代理可用性的健康检查。可通过 Telegram 中的 /health、CLI 中的 deskmate health 或 get_health MCP 工具访问。
Docker 容器模式：在 Docker 中运行核心，使用原生边车处理主机命令。设置 INSTALL_MODE=container 并使用 docker-compose up。
作为服务运行：支持 launchd (macOS) 或 systemd (Linux) 集成，开机启动，崩溃自动重启。
可扩展代理层：通过 registerProvider() 引入自定义代理。

📦 安装指南

系统要求

macOS（在 Ventura、Sonoma、Sequoia 上测试）或 Linux（支持 systemd）
通过 WSL2 在 Windows 上运行
Node.js 18+
安装支持的代理 CLI 之一（见代理提供商）
Telegram 账户（用于 Telegram 模式）
所选提供商的 API 密钥（Anthropic、OpenAI 或 Google，OpenCode 自行管理认证）

Linux 前置要求

屏幕截图：安装 ImageMagick (sudo apt install imagemagick) 以支持屏幕截图
服务：支持用户会话的 systemd (systemctl --user)

macOS 权限

安装程序会引导你完成这些设置（仅适用于 macOS），你也可以在 系统设置 > 隐私与安全 中手动配置。

| 权限 | 用途 | |------------|---------| | 屏幕录制 | 根据请求进行屏幕截图 | | 辅助功能 | 控制系统功能 | | 完全磁盘访问 | 在受保护位置读写文件 | | 自动化 | 通过 AppleScript 控制其他应用程序 | | 后台项目 | 在登录时作为后台服务运行 | | 文件夹访问 | 访问桌面、文档、下载等文件夹 |

💻 使用示例

基础用法

系统管理：“显示磁盘使用情况”、“哪些进程占用最多 CPU？”、“列出所有正在运行的 Docker 容器”

文件操作：“显示 package.json 的内容”、“查找 src/ 目录下的所有 TypeScript 文件”、“创建一个名为 notes.txt 的新文件，并包含今天的日期”

开发：“运行测试”、“查看 git 状态”、“显示最近的提交记录”

故障排除：“哪个程序占用了 8080 端口？”、“显示错误日志的最后 50 行”、“检查 nginx 是否正在运行”

视觉操作：“进行屏幕截图”、“显示屏幕内容”

高级用法

Deskmate 支持多种复杂操作，例如使用技能系统和定时任务调度器。你可以定义自己的技能，并通过 Telegram 命令或 MCP 工具调用。

📚 详细文档

运行模式

| 模式 | 命令 | 描述 | |------|---------|-------------| | 网关 | deskmate | 多客户端网关（默认） | | MCP | deskmate mcp | 用于 Claude Desktop 的 MCP 服务器 | | 两者 | deskmate both | 同时运行网关和 MCP | | 边车 | deskmate sidecar | 容器模式下的主机边车 |

注意：deskmate telegram 仍然可用，但它是一个已弃用的别名，用于启动网关。

网关模式

网关是运行 Deskmate 的默认方式。它将平台 I/O 与代理逻辑分离，因此添加新的消息客户端无需修改认证、会话或代理层。

# 配置多客户端认证
ALLOWED_USERS=telegram:123456,discord:987654321

# 启动
deskmate

网关会根据可用的环境变量自动注册客户端。如果设置了 TELEGRAM_BOT_TOKEN，则 Telegram 客户端将启用。未来的客户端（Discord、Slack）遵循相同的模式。

机器人命令

| 命令 | 描述 | |---------|-------------| | /start | 显示欢迎消息 | | /screenshot | 进行屏幕截图并发送 | | /status | 显示系统信息和会话状态 | | /health | 显示系统健康和资源指标 | | /skill | 列出或运行已注册的技能 | | /cron | 显示定时任务状态 | | /reset | 清除对话记忆 |

MCP 服务器

MCP 服务器将你的计算机作为工具服务器暴露给 Claude Desktop 或任何 MCP 客户端。

与 Claude Desktop 一起设置

在 ~/Library/Application Support/Claude/claude_desktop_config.json 中添加以下内容：

{
  "mcpServers": {
    "deskmate": {
      "command": "node",
      "args": ["/path/to/deskmate/dist/index.js", "mcp"],
      "env": {
        "WORKING_DIR": "/Users/yourname"
      }
    }
  }
}

重启 Claude Desktop，你现在可以让 Claude 与你的本地计算机进行交互。

组合模式（网关 + MCP）

使用 deskmate both 同时运行两者。MCP 处理 Claude Desktop 请求，网关处理 Telegram（以及未来的客户端），将批准通知发送到你的手机，以便你可以在任何地方批准敏感操作。

可观测性

Deskmate 专注于安全地执行操作。若要监控多个本地代理的行为、资源使用情况和故障，请查看 Riva（本地优先代理可观测性）。

技能

技能是在 JSON 中定义的可重复使用的多步骤工作流。将 skills.json 放在项目根目录或 ~/.config/deskmate/skills.json 中以实现全局技能。文件更改时，技能会自动热加载。

{
  "version": 1,
  "skills": [
    {
      "name": "deploy",
      "description": "构建并部署项目",
      "parameters": [{ "name": "env", "required": true }],
      "steps": [
        { "type": "command", "command": "npm run build" },
        { "type": "command", "command": "./deploy.sh {{env}}" }
      ]
    }
  ]
}

每个步骤可以是 command（shell 命令）、prompt（代理查询）或 skill（嵌套技能）。可以通过 Telegram 中的 /skill deploy env=staging 或 run_skill MCP 工具运行。

定时任务

通过 crons.json（项目本地或 ~/.config/deskmate/crons.json）安排定期任务。

{
  "version": 1,
  "jobs": [
    {
      "name": "daily-backup",
      "schedule": "0 2 * * *",
      "action": { "type": "command", "command": "tar czf ~/backup.tar.gz ~/Documents" },
      "notify": true
    }
  ]
}

操作可以是 command、agent_query（自然语言提示）或 skill。设置 notify: true 以在活跃的聊天渠道接收结果。可以通过 Telegram 中的 /cron 或 list_cron_jobs MCP 工具检查状态。

安全性

⚠️ 重要提示

代理可以在你的计算机上执行任意命令。这是设计使然，策略是对只读操作默认批准，对受保护文件夹和写操作进行批准控制。

内置保护机制

| 层级 | 功能 | |-------|-------------| | 用户认证 | 通过 SecurityManager 基于白名单的访问控制。只有 ALLOWED_USERS 中的用户可以交互。支持按客户端认证（telegram:123、discord:456）和通配符（*:*）。 | | 操作批准 | ApprovalManager 控制敏感操作。写命令、文件写入和文件夹访问需要明确的人工批准，并可配置超时时间（默认 5 分钟）。 | | 受保护文件夹 | 操作系统感知的文件夹保护。桌面、文档、下载、图片、电影/视频、音乐和 iCloud（macOS）需要批准。基于会话的缓存避免重复提示。 | | 安全命令自动批准 | 只读命令（ls、cat、git status、docker ps、node -v 等）自动批准。完整列表见 src/core/approval.ts。 | | 命令执行限制 | 每个命令有 2 分钟的超时时间和 10 MB 的输出缓冲区。防止失控进程和内存耗尽。 | | 会话隔离 | 会话通过 clientType:channelId 键控。30 分钟闲置超时，自动清理。可选的磁盘持久化可在重启后保留会话。 | | 输入验证 | MCP 工具使用 Zod 模式验证。Telegram 回调通过正则表达式模式验证。 | | 无开放端口 | 机器人轮询 Telegram 服务器，无入站端口暴露。 | | 默认不使用 sudo | 除非你明确要求，否则代理不会使用 sudo。 | | 结构化日志记录 | 所有操作都记录时间戳、上下文层次结构和可配置的日志级别，用于审计跟踪。 | | 陈旧消息保护 | Telegram 客户端在启动时丢弃待处理的更新（drop_pending_updates: true），防止离线时收到的消息重播。 |

批准工作流程

用户发送触发敏感操作的消息（例如，写入 ~/Documents）
ApprovalManager 检查操作是否匹配安全自动批准模式
如果不安全，创建带有超时倒计时的待批准请求
批准请求广播到最近活跃（过去 30 分钟）的所有客户端
用户通过内联按钮（Telegram）或等效方式点击批准/拒绝
批准后执行操作，拒绝或超时则取消操作

设置 REQUIRE_APPROVAL_FOR_ALL=true 可对所有操作进行批准控制，包括读取操作。

建议

设置 WORKING_DIR 以限制默认命令范围
使用 ALLOWED_USERS 进行多客户端白名单设置
使用 ALLOWED_FOLDERS 预先批准特定目录
定期查看日志（logs/stdout.log）
确保 .env 文件安全，切勿提交
如果你希望对每个操作进行批准控制，请使用 REQUIRE_APPROVAL_FOR_ALL=true

执行理念

Deskmate 遵循 默认批准、设计可见 的模型。

只读操作自动批准
敏感操作需要明确确认
所有操作都在本地记录

目标是在不隐藏行为的情况下实现快速执行。

非目标

Deskmate 有意不具备以下功能：

多代理编排框架
云托管控制平面
长期运行的自主系统

这些限制是有意为之。

代理提供商

Deskmate 支持多种代理后端。在 .env 中设置 AGENT_PROVIDER，或在 deskmate init 期间选择。

| 提供商 | 二进制文件 | 环境变量 | 安装 | |----------|--------|---------|---------| | Claude Code（默认） | claude | ANTHROPIC_API_KEY | docs.anthropic.com | | Codex (OpenAI) | codex | OPENAI_API_KEY | github.com/openai/codex | | Gemini CLI (Google) | gemini | GEMINI_API_KEY | github.com/google-gemini/gemini-cli | | OpenCode | opencode | (自行管理认证) | github.com/opencode-ai/opencode |

# 切换提供商
AGENT_PROVIDER=codex
OPENAI_API_KEY=sk-...

# 或者使用向导
deskmate init

仅需要所选提供商的 API 密钥。如果切换回其他提供商，.env 中会保留其他提供商的密钥。

架构

src/
├── core/
│   ├── agent/
│   │   ├── types.ts              # 代理提供商接口
│   │   ├── factory.ts            # 提供商工厂 + registerProvider()
│   │   └── providers/
│   │       ├── claude-code.ts    # Claude Code SDK（默认）
│   │       ├── base-cli.ts       # CLI 生成提供商的基类
│   │       ├── codex.ts          # Codex (OpenAI)
│   │       ├── gemini.ts         # Gemini CLI (Google)
│   │       └── opencode.ts       # OpenCode
│   ├── approval.ts               # 批准管理器（自动批准 + 手动）
│   ├── executor.ts               # 命令执行、文件 I/O、屏幕截图
│   ├── executor-factory.ts       # 创建本地或远程执行器
│   ├── executor-interface.ts     # IExecutor 接口
│   ├── remote-executor.ts        # 委托给边车的执行器
│   ├── health.ts                 # 健康监控（CPU、内存、磁盘、代理）
│   ├── skills/                   # 技能系统
│   │   ├── types.ts              # 技能定义模式（Zod）
│   │   ├── registry.ts           # 加载 skills.json，文件更改时热加载
│   │   └── executor.ts           # 运行多步骤技能工作流
│   ├── cron/                     # 定时任务调度器
│   │   ├── types.ts              # 定时任务定义模式（Zod）
│   │   └── scheduler.ts          # 基于 node-cron 的任务运行器
│   └── logger.ts                 # 结构化日志记录
├── gateway/
│   ├── types.ts                  # 消息客户端、消息处理程序接口
│   ├── gateway.ts                # 中央协调器
│   ├── security.ts               # 多客户端白名单认证
│   └── session.ts                # 会话管理器（复合键、闲置清理）
├── clients/
│   └── telegram.ts               # Telegram 适配器（grammY）
├── sidecar/                      # 容器模式下的主机边车
│   ├── server.ts                 # 通过 HTTP 暴露执行器的 Express 服务器
│   └── cli.ts                    # 边车 CLI 入口点
└── mcp/
    └── server.ts                 # MCP 服务器

代理层：提供四个提供商：Claude Code（通过 @anthropic-ai/claude-agent-sdk）、Codex、Gemini CLI 和 OpenCode。三个非 Claude 提供商扩展了 BaseCliProvider，该类处理子进程生成和标准输出流。可以通过 registerProvider() 注册自定义代理提供商。

网关层：中央协调器处理认证（SecurityManager）、会话（SessionManager）、代理编排、批准路由和屏幕截图交付。平台适配器实现 MessagingClient 接口，仅处理 I/O。

添加新客户端

创建 src/clients/discord.ts 实现 MessagingClient（见 src/gateway/types.ts）
在 .env 中添加 DISCORD_BOT_TOKEN
将 discord:userId 添加到 ALLOWED_USERS
在网关启动时注册：gateway.registerClient(new DiscordClient(token))

无需更改网关、SecurityManager、SessionManager 或代理层。

引入自定义代理

import { AgentProvider, registerProvider } from "./core/agent";

class MyAgent implements AgentProvider {
  readonly name = "my-agent";
  readonly version = "1.0.0";
  // 实现 query()、queryStream()、isAvailable()
}

registerProvider("my-agent", MyAgent);
// 然后在 .env 中设置 AGENT_PROVIDER=my-agent

CLI 命令

| 命令 | 描述 | |---------|-------------| | deskmate | 启动网关（默认模式） | | deskmate init | 交互式设置向导 | | deskmate status | 显示服务状态和配置验证 | | deskmate health | 显示系统健康和资源指标 | | deskmate logs | 查看 stdout.log（--stderr 查看错误日志） | | deskmate restart | 重启后台服务 | | deskmate doctor | 运行诊断检查 | | deskmate sidecar | 启动主机边车（容器模式） |

Docker / 容器模式

在 Docker 容器中运行 Deskmate，使用原生边车处理主机级命令（屏幕截图、文件访问）。

# 设置安装模式
INSTALL_MODE=container

# 在主机上启动边车
deskmate sidecar

# 启动容器
docker-compose up -d

包中包含 Dockerfile 和 docker-compose.yml。边车暴露一个本地 HTTP API，容器化核心使用该 API 在主机上执行命令。

服务管理

macOS (launchd)

# 查看日志
tail -f logs/stdout.log
tail -f logs/stderr.log

# 停止服务
launchctl unload ~/Library/LaunchAgents/com.deskmate.service.plist

# 启动服务
launchctl load ~/Library/LaunchAgents/com.deskmate.service.plist

# 检查状态
launchctl list | grep deskmate

Linux (systemd)

# 查看日志
tail -f logs/stdout.log
journalctl --user -u deskmate.service -f

# 停止 / 启动 / 重启
systemctl --user stop deskmate.service
systemctl --user start deskmate.service
systemctl --user restart deskmate.service

# 检查状态
systemctl --user status deskmate.service

卸载

./uninstall.sh

故障排除

机器人无响应？

检查日志：tail -f logs/stderr.log
验证 ALLOWED_USERS 中包含你的 Telegram ID（例如 telegram:123456）
确保已安装代理 CLI（例如 which claude、which codex、which gemini、which opencode）
运行 deskmate doctor 诊断配置问题

命令超时？

默认超时时间为 2 分钟
长时间运行的命令可能需要调整

计算机进入睡眠状态？

macOS：运行 ./install.sh 配置防止睡眠，或手动执行 sudo pmset -c sleep 0
Linux：systemd 服务使用闲置抑制剂。检查桌面环境的电源设置。

权限被拒绝错误？（macOS）

重新运行 ./install.sh 并完成权限设置
或者在系统设置 > 隐私与安全中手动授予权限

屏幕截图无法工作？

macOS：在系统设置 > 隐私与安全 > 屏幕录制中授予屏幕录制权限
Linux：安装 ImageMagick (sudo apt install imagemagick)
更改设置后重启服务

🔧 技术细节

Deskmate 的工作流程如下：

Telegram / Discord* / Slack* / ...
            |
            v
  +-------------------+
  |      网关         |    认证、会话、批准路由
  |  (控制平面)       |
  +--------+----------+
           |
           v
  +-------------------+
  |   代理提供商      |    Claude Code | Codex | Gemini | OpenCode
  |   (可插拔)        |    全面本地工具访问
  +-------------------+
           |
           v
     你的计算机
     (执行任务)

*Discord 和 Slack 适配器正在计划中 — 见添加新客户端。

网关是控制平面。每个消息平台是一个轻量级 I/O 适配器。代理可以无限制地访问你的计算机（默认批准），对受保护文件夹可选择进行批准控制。

📄 许可证

本项目采用 MIT 许可证，详情见 LICENSE。

致谢

Claude Agent SDK — 默认代理运行时
Codex — OpenAI 代理后端
Gemini CLI — Google 代理后端
OpenCode — OpenCode 代理后端
grammY — Telegram 机器人框架
@modelcontextprotocol/sdk — MCP 支持

社区

Discord — 加入社区，提问，分享你的设置

如果你觉得 Deskmate 有用，欢迎分享：