基于MCP协议实现手机远程操控AI编程助手的完整指南-程序员充电站

1. 项目概述：用手机远程操控你的AI编程伙伴

作为一名长期泡在代码里的开发者，我经常遇到这样的场景：一个绝佳的编程灵感在通勤路上、在咖啡馆小憩时突然闪现，但手边只有手机。传统的远程桌面方案笨重且延迟高，而直接在手机上敲代码又近乎天方夜谭。直到我发现了cc-proxy这个开源项目，它巧妙地利用 MCP 协议，在手机上的即时通讯工具（如微信、钉钉）和本地的 Claude Code CLI 之间架起了一座桥梁，让我能随时随地“指挥”电脑上的 AI 助手进行编程工作。这不仅仅是远程控制，更是将 AI 编程助手的交互体验从桌面延伸到了移动场景，极大地释放了开发者的生产力。

cc-proxy本质上是一个 MCP 服务器。MCP 是 Model Context Protocol 的缩写，你可以把它理解为一套标准化的“插座”规范。cc-proxy这个“插座”的一端连接着像 Hermes 这样的 MCP 客户端（它可以将 MCP 工具暴露给手机 IM 里的聊天机器人），另一端则通过子进程调用本机的 Claude Code CLI，从而间接操控你的 Claude Code 会话。整个过程，你的代码和开发环境始终安全地留在本地电脑上，通过手机发送的只是自然语言指令和接收文本结果，安全又高效。无论你是想在路上检查一下 CI 构建状态、让 Claude 帮你写个函数草稿，还是回顾之前的会话记录，这个工具都能派上用场。接下来，我将带你从零开始，深入它的设计、配置与实战，分享我趟过的一些坑和总结的技巧。

2. 核心架构与设计思路拆解

2.1 为什么是 MCP？协议选型的深层考量

初次接触这个项目时，你可能会问：为什么不直接用 SSH 执行命令，或者写个简单的 HTTP API？选择基于 MCP 来构建，是cc-proxy设计中最精妙的一环。MCP 的核心思想是为大模型提供一套发现、调用外部工具和资源的标准化协议。这意味着，任何兼容 MCP 的客户端（如 Hermes）都能无缝接入cc-proxy暴露的工具，而无需为每个客户端编写适配代码。

从架构上看，这带来了极佳的解耦性。cc-proxy只需专注于一件事：作为 MCP 服务器，提供一组操作 Claude Code 会话和项目的工具。至于用户如何与这些工具交互——是通过 Hermes 接入 Slack、Discord，还是微信、钉钉——cc-proxy完全不用关心。这种设计让工具本身保持了纯粹和可复用性。相比之下，如果自建 HTTP API，你需要额外处理认证、路由、请求格式标准化等一系列繁琐的 Web 服务问题，并且与客户端耦合更紧。

从功能上看，MCP 的工具（Tools）和资源（Resources）模型非常适合当前场景。cc-proxy提供的cc_list_projects、cc_send_to_session等，本质上就是一个个工具。MCP 客户端可以动态地发现这些工具，并以结构化的方式（输入参数、输出格式）调用它们。这对于需要复杂参数传递的操作（如向特定会话发送消息）来说，比通过 SSH 传递一长串难以解析的字符串要可靠和优雅得多。

2.2 数据流与组件职责全景

理解数据流是掌握这个工具的关键。整个流程涉及五个核心组件，它们各司其职，共同完成一次远程指令的执行：

手机 IM：这是用户交互的入口。你向集成了 Hermes 的聊天机器人（比如一个微信里的助手账号）发送一条自然语言指令，例如：“帮我列出所有的 Claude Code 项目”。
Hermes：这是一个 MCP 客户端。它运行在你的服务器或本地机器上，监听 IM 消息。当收到指令后，Hermes 会利用其内置的大模型能力，将你的自然语言指令“翻译”成对特定 MCP 工具的调用请求。例如，它理解“列出项目”对应的是cc_list_projects工具，然后构造一个 MCP 请求。
cc-proxy：作为 MCP 服务器，它持续运行，监听来自 Hermes 的请求。收到cc_list_projects的调用请求后，它并不直接处理，而是委托给下一个组件。
Claude Code CLI：cc-proxy会在后台启动一个claude命令的子进程，通过标准输入输出与其交互。对于列表项目请求，它可能会模拟执行claude projects list之类的命令（具体命令由cc-proxy内部逻辑决定）。
Claude Code 会话：CLI 最终与 Claude Code 的后端服务通信，获取你本地存储的所有项目元数据，然后将结果逐层返回，最终以格式化的消息呈现在你的手机 IM 中。

这个链条清晰地将“用户交互”、“意图理解”、“工具调度”、“本地执行”分层，每一层都可以独立演进和替换，体现了良好的软件设计。

2.3 会话管理：活跃与不活跃的智能处理

cc-proxy对 Claude Code 会话的管理策略非常实用。Claude Code 的会话在本地文件系统中以 JSONL 格式存储。cc-proxy的session-store.ts会扫描~/.claude/sessions/目录，但它并非简单罗列所有文件。

其核心逻辑是区分活跃会话和不活跃会话。活跃会话通常对应着一个正在运行的claude进程，可以进行实时交互。cc-list_sessions工具默认会列出所有活跃会话，以及每个项目中最新的大约 2 个不活跃会话。这个设计非常贴心：活跃会话是你当前正在工作的上下文，必须全部可见；而不活跃会话数量可能很多，展示最新的几个足以满足回顾和恢复的需求，避免了列表过长造成的噪音。

更强大的是cc_send_to_session工具，它支持向不活跃会话发送消息。其内部机制是：当目标会话不活跃时，cc-proxy会先尝试“唤醒”它——这可能涉及到使用特定的 CLI 参数来重新连接到该会话的历史上下文——然后再发送你的消息。这相当于让你能随时回到任何一个过去的对话线程中继续工作，保证了上下文的连续性，是远程异步协作的利器。

3. 从零开始的完整部署与配置实战

3.1 基础环境准备：避坑指南

在运行一键安装脚本之前，确保你的基础环境稳固可以避免 90% 的后续问题。

Node.js 版本：项目要求 Node.js >= 18。我推荐使用nvm来管理 Node.js 版本，这是最干净的方式。不要使用系统自带的或通过apt-get安装的老版本。

# 使用 nvm 安装并切换至 LTS 版本（如 20.x） nvm install --lts nvm use --lts # 验证版本 node --version # 应 >= 18

Claude Code CLI：这是核心依赖。请务必通过官方渠道安装，并确保claude命令在终端中可以直接运行。

# 安装后，在终端中测试 claude --version # 进行登录等初始化操作，确保 claude 命令处于可用状态 claude auth login

注意：很多安装失败案例源于claude命令不在全局 PATH 中。例如，如果你通过某些包管理器安装在了用户目录下，可能需要手动将路径添加到~/.bashrc或~/.zshrc中。一键安装脚本会尝试自动检测并配置，但提前处理好更稳妥。

Hermes：作为 MCP 客户端，你需要先部署好 Hermes，并配置好它与你的 IM 平台（如微信、钉钉）的连接。这部分是 Hermes 的职责，cc-proxy不关心。请确保 Hermes 服务本身是正常运行的。

3.2 一键安装的幕后与手动配置详解

官方推荐的一键安装命令非常方便：

curl -fsSL https://raw.githubusercontent.com/cm8421/cc-proxy/main/install.sh | bash

这个脚本做了以下几件事：

将cc-proxy仓库克隆到~/.cc-proxy/目录。
运行npm install安装 Node.js 依赖。
关键步骤：尝试从当前终端环境中捕获ANTHROPIC_*系列的环境变量，并将其写入~/.cc-proxy/.env文件。
在 Hermes 的配置目录（通常是~/.hermes/）下创建或更新 MCP 服务器配置，指向cc-proxy的启动脚本。

为什么环境变量捕获如此重要？因为cc-proxy需要凭据来与 Claude Code API 通信。如果你已经在本机终端中用claude登录过，那么ANTHROPIC_AUTH_TOKEN等变量很可能已经存在于当前 shell 会话中。脚本通过env | grep ANTHROPIC_来抓取这些变量，免去了你手动创建的麻烦。

如果自动捕获失败，如何手动配置？进入~/.cc-proxy/目录，创建.env文件。内容取决于你的 Claude Code 使用方式：

方式一：使用官方 Claude Code 服务

# ~/.cc-proxy/.env ANTHROPIC_API_KEY=sk-ant-xxxxxx...你的官方API密钥

方式二：使用第三方代理服务（常见）

# ~/.cc-proxy/.env ANTHROPIC_BASE_URL=https://你的代理服务地址 ANTHROPIC_AUTH_TOKEN=你的代理服务颁发的令牌

实操心得：我遇到过一种情况，安装脚本运行在一个全新的终端窗口里，里面根本没有ANTHROPIC_*变量。这时脚本会静默跳过，导致后续出现 “Not logged in” 错误。最可靠的方法是：先打开一个能正常使用claude命令的终端窗口，然后在这个窗口里运行安装命令。这样就能确保环境变量被成功捕获。

3.3 Hermes 配置的两种模式与选择

cc-proxy与 Hermes 的集成有两种配置方式，理解它们的区别有助于排查问题。

方式一：通过command启动（安装脚本默认）安装脚本会在 Hermes 的mcp_servers配置中添加类似如下条目：

mcp_servers: cc-proxy: command: /home/yourname/.cc-proxy/run.sh args: - --transport - stdio

这种方式下，cc-proxy的运行时环境（包括环境变量）由它自己的.env文件和启动脚本决定。这是最清晰、最推荐的方式，隔离性好。

方式二：通过env字段传递凭证你也可以在 Hermes 的配置中直接注入环境变量：

mcp_servers: cc-proxy: command: /home/yourname/.cc-proxy/run.sh args: - --transport - stdio env: ANTHROPIC_BASE_URL: https://your-proxy.com ANTHROPIC_AUTH_TOKEN: your-token-here

这种方式下，cc-proxy进程会优先使用这里定义的env，而忽略自身的.env文件。它适用于团队共享 Hermes 配置，但个人凭证动态管理的场景。不过，将敏感令牌写在配置文件中需注意安全。

配置生效与重启：无论哪种方式，修改 Hermes 配置后，必须重启 Hermes 服务才能使新的 MCP 服务器配置生效。这是很多初学者容易忽略的一步。

4. 六大核心工具深度使用手册

cc-proxy提供了六个 MCP 工具，它们是远程操作的“遥控器”。下面我们逐一拆解其使用场景、参数和返回结果。

4.1 信息探查：cc_list_projects 与 cc_list_sessions

这两个工具是你了解本地工作状态的“眼睛”。

cc_list_projects

功能：列出本地~/.claude/projects/目录下的所有 Claude Code 项目。
参数：无。直接调用即可。
返回结果：一个项目对象数组。每个对象通常包含id（项目路径的编码形式）、name（项目目录名）、path（绝对路径）以及可能的createdAt时间戳。
使用场景：当你想知道电脑上有哪些项目可以操作时，首先调用它。例如，在手机 IM 里输入“/cc_list_projects”，Hermes 会调用该工具并返回列表。

cc_list_sessions

功能：列出会话。默认返回所有活跃会话 + 每个项目下最新的 2 个不活跃会话。
参数：
- projectId(可选)：指定项目 ID，只返回该项目下的会话。
- limit(可选)：限制返回的不活跃会话总数，用于分页。
- before(可选)：时间戳，返回此时间之前的会话，用于分页。
返回结果：一个会话对象数组。对象包含id（会话唯一标识）、projectId、isActive（布尔值，是否活跃）、summary（会话摘要，通常是最后几条消息的预览）、updatedAt（最后更新时间）等。
实操技巧：这个工具的“活跃会话全部列出+不活跃会话抽样列出”逻辑非常实用。当你想快速切换到某个正在进行的对话时，活跃会话一目了然。当你想找回昨天的某个讨论时，通过projectId过滤并查看其下的不活跃会话，能迅速定位。

4.2 核心交互：cc_send_to_session 的完整流程

这是最常用、最强大的工具，实现了与 Claude 的远程对话。

cc_send_to_session

功能：向指定的 Claude Code 会话发送一条消息，并返回 Claude 的响应。
参数：
- sessionId(必需)：目标会话的 ID，可以从cc_list_sessions获取。
- message(必需)：要发送的文本消息。
内部工作流：
1. cc-proxy根据sessionId定位到具体的会话文件。
2. 检查该会话对应的进程是否存活（isActive）。
3. 如果活跃：直接通过该进程的标准输入发送message。
4. 如果不活跃：启动一个新的claude子进程，并附加参数指向该会话的历史文件，以“恢复”会话上下文，然后发送消息。
5. 监听子进程的标准输出，使用stream-json库解析 Claude 返回的流式 JSONL 数据。
6. 将解析出的文本内容聚合，作为工具调用的结果返回。
使用示例：在 IM 中，你可能通过 Hermes 这样操作：“向会话 [session_id] 发送消息：请帮我检查src/utils.ts文件中的formatDate函数是否有语法错误。” Hermes 会提取参数并调用工具。
注意事项：
- 网络稳定性：由于涉及网络传输和可能启动新进程，响应可能会有几秒到十几秒的延迟，尤其是在恢复不活跃会话时。请保持耐心。
- 消息长度：虽然理论上支持长消息，但过于复杂的指令可能会超出 Claude 单次处理的上下文长度，或者导致解析流数据时出现意外。建议将复杂任务拆分成多个连续的短消息交互。
- 会话锁定：当一个不活跃会话被恢复时，它可能会变成一个“活跃”会话。如果同时从多个地方（如手机和电脑）操作同一个会话，可能会造成状态混乱。建议一段时间内在一个终端操作。

4.3 会话管理：创建与状态查询

cc_create_session

功能：为指定的项目创建一个新的 Claude Code 会话。
参数：
- projectId(必需)：要在其中创建会话的项目 ID。
返回结果：返回新创建会话的sessionId和其他元信息。
使用场景：当你开始一个全新的任务或想隔离某个话题的讨论时，创建一个新会话是最佳实践。例如：“在项目 [project_id] 下创建一个关于用户认证模块重构的新会话。”

cc_get_session_status

功能：检查指定会话的进程是否存活。
参数：
- sessionId(必需)。
返回结果：一个简单的状态对象，如{ “isActive”: true }。
使用场景：在发送重要指令前，可以先检查会话是否“在线”，避免向一个僵死的进程发送消息导致超时。

cc_get_session_summary

功能：获取指定会话的详细摘要和最近的消息历史。
参数：
- sessionId(必需)。
返回结果：比cc_list_sessions更详细的信息，可能包含最近若干条完整的消息往来，帮助你快速回顾会话上下文。
使用场景：当你隔了一段时间重新打开一个会话，或者想确认之前讨论的细节时，这个工具比翻看完整的 JSONL 历史文件要方便得多。

5. 高级配置、故障排查与性能调优

5.1 多 Provider 凭证管理与切换

如果你同时使用多个 Claude API 提供商（例如，一个用于工作，一个用于个人项目），cc-proxy的.env文件支持一种简单的“最后生效”配置法。

原理是：Node.js 的dotenv包会按顺序加载.env文件中的变量，后出现的值会覆盖先出现的同名变量。因此，你可以这样配置：

# ~/.cc-proxy/.env # 默认提供商（公司） ANTHROPIC_BASE_URL=https://company-proxy.example.com ANTHROPIC_AUTH_TOKEN=token-company # 个人提供商（当前生效） ANTHROPIC_BASE_URL=https://personal-proxy.example.com ANTHROPIC_AUTH_TOKEN=token-personal

在上述配置中，实际生效的是个人提供商的凭证。当你想切换回公司提供商时，只需要将公司的那两行配置剪切并粘贴到文件末尾即可。无需重启cc-proxy进程，因为.env文件通常在启动时加载一次。

提示：更优雅的切换方式可以通过脚本实现。例如，写两个脚本switch_to_work.sh和switch_to_personal.sh，分别用正确的配置重写.env文件，然后向cc-proxy进程发送信号（如 SIGHUP）使其重载配置（如果它支持的话）。目前cc-proxy可能需要重启 Hermes 来重新加载环境变量，这是一个可以改进的点。

5.2 常见错误与根因分析

错误一：Error: Not logged in

现象：调用任何工具都返回此错误。
根因：cc-proxy无法获取有效的 Claude API 凭证。
排查步骤：
1. 检查~/.cc-proxy/.env文件是否存在且内容正确：cat ~/.cc-proxy/.env。
2. 确认.env文件中的变量名和值没有拼写错误，特别是ANTHROPIC_AUTH_TOKEN和ANTHROPIC_BASE_URL。
3. 如果你是通过 Hermes 的env配置传递凭证，检查 Hermes 配置文件的语法（YAML 缩进）和变量值。
4. 手动验证凭证：在终端中，使用.env文件中的变量，尝试用curl调用一个简单的 Claude API 端点，看是否返回 401 未授权错误。

错误二：spawn claude ENOENT

现象：调用涉及 CLI 交互的工具时失败。
根因：系统在 PATH 环境变量中找不到claude可执行文件。
解决方案：
1. 首先在终端中直接运行which claude，获取其完整路径（例如/usr/local/bin/claude）。
2. 编辑~/.cc-proxy/config.yaml文件（如果不存在，可以从仓库的示例复制），设置claude.cli_path为完整路径。
```
# ~/.cc-proxy/config.yaml claude: cli_path: “/usr/local/bin/claude” # 替换为你的实际路径
```
1. 重启 Hermes 以使配置生效。

错误三：Hermes 无法发现cc-proxy的工具

现象：在 Hermes 关联的 IM 中，无法调用/cc_list_projects等命令。
根因：Hermes 的 MCP 服务器配置不正确，或cc-proxy进程没有正常运行。
排查步骤：
1. 检查 Hermes 的配置文件（如~/.hermes/config.yaml），确认mcp_servers部分下cc-proxy的command路径是否正确。
2. 手动运行~/.cc-proxy/run.sh，看是否有错误输出。这能判断cc-proxy本身是否能启动。
3. 查看 Hermes 的日志文件，通常会有连接 MCP 服务器失败的具体错误信息。
4. 确保已重启 Hermes：任何对cc-proxy配置或 Hermes MCP 配置的修改，都需要重启 Hermes 服务。

5.3 性能调优与稳定性建议

会话数量管理：cc-proxy在列出会话时会读取 JSONL 文件。如果历史会话文件非常多（成千上万个），cc_list_sessions的调用可能会变慢。定期清理~/.claude/sessions/目录下不再需要的旧会话文件，可以提升性能。你可以写一个定时任务，删除例如 30 天前的会话文件。
网络与超时设置：cc-proxy与 Claude API 通信以及 Hermes 与cc-proxy通信都可能受到网络影响。目前工具本身没有暴露网络超时配置。如果遇到频繁超时，可以考虑：
- 确保运行cc-proxy的机器网络稳定，访问 Claude API 的延迟较低。
- 如果cc-proxy和 Hermes 不在同一台机器，确保它们之间的内网通信畅通。
资源监控：cc-proxy会为每个活跃的claude会话维持一个子进程。如果你同时通过手机操作很多个会话，可能会创建多个claude进程，消耗内存和 CPU。可以通过htop或ps aux | grep claude监控。不用的会话，最好在 IM 中发送一个结束指令（如果 Claude CLI 支持），或者等待其超时关闭。
日志记录：cc-proxy默认的日志输出可能比较简单。对于生产环境或深度调试，可以考虑修改其源码，增加更详细的日志记录（如请求参数、响应时间、错误堆栈），输出到文件，便于问题追踪。

6. 安全考量与最佳实践

将本地开发环境与远程控制工具连接，安全是重中之重。

凭证安全：.env文件包含了你的 API 令牌，等同于密码。务必确保~/.cc-proxy/.env文件的权限设置为仅当前用户可读：chmod 600 ~/.cc-proxy/.env。切勿将此文件提交到版本控制系统或分享给他人。
Hermes 接入安全：Hermes 作为网关，其安全性决定了整个链条的入口安全。确保你部署的 Hermes 服务：
- 使用强密码或 Token 认证。
- 如果暴露在公网，务必启用 HTTPS。
- 严格配置 IM 机器人平台的 Webhook 或 API 调用 IP 白名单。
最小权限原则：cc-proxy通过 Claude CLI 操作你的项目。这意味着，Claude 能访问的文件和目录，理论上都可能通过cc-proxy被远程操作。因此，避免使用高权限账户运行 Claude Code 服务。定期审查 Claude Code 的会话历史，确保没有敏感信息（如密钥、密码）被意外输入并记录在 JSONL 文件中。
操作审计：目前cc-proxy和 Hermes 可能缺少详细的操作日志。对于团队使用或安全要求高的场景，建议在架构上层（如 IM 平台侧或 Hermes 侧）增加操作审计功能，记录谁、在什么时候、执行了什么操作。
网络隔离：理想情况下，运行cc-proxy和 Hermes 的服务器应处于受保护的内部网络，不直接暴露在公网。如果必须从公网访问，应通过 VPN 接入内部网络后再进行操作。

这个工具为我打开了一种全新的工作流可能性。它让我意识到，AI 编程助手的能力可以如此自然地融入碎片化的时间和移动场景中。最大的体会是，可靠性建立在每一环的稳固之上：稳定的 Claude API 连接、正确的环境变量配置、清晰的会话管理习惯。我建议你在正式用于重要工作前，先用一个测试项目熟悉整个流程，从安装、配置到执行几个完整的“列出-创建-发送-查询”循环，把可能遇到的坑都踩一遍。当一切就绪后，你会发现，在公园长椅上用手机让 Claude 帮你修复一个紧急 bug，不再是幻想，而是一种高效且优雅的日常。