CC Pocket 安全设计深度解析：自托管架构、目录白名单与 Claude 鉴权风险完整指南-平芜编程栈

人工智能
代码智能体
交互助手
工具调用

【免费下载链接】ccpocket

Mobile client for Codex and Claude — control coding agents from your phone via WebSocket bridge

项目地址：https://gitcode.com/gh_mirrors/cc/ccpocket

CC Pocket是一款免费开源的手机端编码代理客户端，让你在手机上远程控制自己电脑上的Codex和Claude Code会话。它的核心安全理念是：自托管（self-hosting）+ 最小数据收集。你的代码始终留在自己的机器上，Bridge Server 负责在 WebSocket 上校验每一个路径请求，Claude 订阅鉴权则需要显式开启才能使用。这篇指南带你完整看懂它的安全设计。

一、自托管架构：代码为什么不会经过第三方服务器

CC Pocket 由两部分组成：

CC Pocket App <-> 你电脑上的 Bridge Server <-> Codex / Claude

手机 App 只是"遥控器"，真正的 Agent 进程（Codex CLI / Claude Code）运行在你自己的 Mac、Linux 或 Windows 主机上，通过 Bridge Server 中转。这意味着：

🏠代码不过境：源码、git 仓库、shell 操作全部发生在本地，不进入任何托管 IDE 或开发者的服务器；
📊零遥测：无分析统计、无崩溃上报、无行为追踪、无广告标识符（见 PRIVACY_POLICY.md）；
📤唯一的例外是可选的推送通知：开启后仅通过 Firebase 匿名认证传递通知令牌，不携带对话内容。

换句话说，"你的数据"这条线只有一条：手机 → 你自己的 Bridge Server。

二、目录白名单：BRIDGE_ALLOWED_DIRS 如何锁住文件访问

Bridge Server 通过 WebSocket 暴露文件系统操作，因此目录白名单是第一道防线。相关实现位于 path-utils.ts：

环境变量	默认值	作用
`BRIDGE_ALLOWED_DIRS`	`$HOME`	逗号分隔的项目目录白名单
`BRIDGE_FILE_DOWNLOAD_ALLOW_ALL_PATHS`	未设置（仅限项目内）	设为`1`才允许下载白名单外的任意文件

关键设计点：

默认锁在 $HOME：不配置时，Bridge 只能访问你的用户目录；
*是唯一的"全放行"值：只有精确写入*才会解除限制，防止误写通配符（见 index.ts）；
路径解析后校验：每个请求路径都会先resolve规范化，再检查是否落在白名单内，符号链接指向白名单外同样会被拒绝。核心判断逻辑 isPathWithinAllowedDirectory 通过相对路径前缀防止../穿越，并在 websocket.ts 中对文件操作、目录浏览等接口逐一执行；
按需扩容：需要访问$HOME外的项目时，显式追加即可，例如BRIDGE_ALLOWED_DIRS="$HOME,/scratch/myuser"。

# 只允许访问两个目录，并启用 API Key 认证 BRIDGE_ALLOWED_DIRS="$HOME,/scratch/myuser" \ BRIDGE_API_KEY=my-secret \ npx @ccpocket/bridge@latest

三、连接认证：BRIDGE_API_KEY 与网络层安全

🔑BRIDGE_API_KEY：可选的 API Key 认证。设置后，手机连接时必须携带该 Key（index.ts 在启动时启用认证并打印提示）。官方部署文档明确推荐启用，仅在"Tailnet 里全是完全可信的个人设备"时才建议关闭；
🌐网络层建议：局域网内扫二维码直连即可；离开家庭网络后，官方推荐使用Tailscale组虚拟专用网，再连接ws://<tailscale-ip>:8765，而不是把端口暴露到公网（详见 bridge-tailscale-aliyun-guide.zh-CN.md）；
📱手机侧凭据加密：API Key 与 SSH 私钥在手机上通过平台原生加密存储（iOS Keychain / Android Keystore），不存普通文件（见 SECURITY.md）；
🏷️mDNS 可关闭：macOS 上自动禁用 mDNS 广播，其他平台可用BRIDGE_DISABLE_MDNS=1关闭，减少局域网内的服务暴露面。

完整配置项清单见 packages/bridge/README.md 的 Configuration 表格，setup命令可把上述设置持久化为 macOS launchd / Linux systemd 后台服务。

四、Claude 鉴权风险：为什么订阅登录必须显式开启

这是 CC Pocket 安全设计中最需要理解的一块，详细说明见 auth-troubleshooting.zh-CN.md 与 packages/bridge/README.md。

两种鉴权方式对比

方式	启用条件	风险
API Key（推荐）	配置`ANTHROPIC_API_KEY`即可	低，符合 Anthropic 对第三方产品的官方要求
Claude 订阅登录（OAuth）	必须显式设置`BRIDGE_ALLOW_CLAUDE_OAUTH=1`并重启	存在不确定性，未来可能被限制

风险从何而来？

Anthropic 的 Legal and compliance 页面允许平台托管未修改的 Claude Code，由终端用户用自己的订阅登录——CC Pocket 正是运行官方 Agent SDK 并把凭据加载完全委托给宿主机的 Claude Code 环境，自身不复制、不存储、不刷新任何 OAuth 凭据；
但 Agent SDK 概览页同时要求：未经事先批准的第三方产品应使用 API Key，而不是提供 Claude.ai 登录或订阅限流；
这两条声明对 CC Pocket 这种"自托管 + 远程操控"架构的适用范围并不清晰，因此订阅鉴权未来可能被限制或失效。

所以 CC Pocket 选择了显式 opt-in策略：默认关闭订阅登录，只有你明确运行下面的命令才会开启——

BRIDGE_ALLOW_CLAUDE_OAUTH=1 npx @ccpocket/bridge@latest

官方建议：如果不追求订阅额度，直接用ANTHROPIC_API_KEY最稳妥。此外，运行在 Amazon Bedrock 上的 Claude Code 使用 AWS 凭据签名，两条鉴权都不需要（packages/bridge/README.md 中有专门章节）。

五、安全设计速查清单 ✅

机制	位置	默认行为
目录白名单	`BRIDGE_ALLOWED_DIRS`	仅`$HOME`
路径校验（含符号链接）	path-utils.ts	始终执行
API Key 认证	`BRIDGE_API_KEY`	关闭（推荐开启）
全路径文件下载	`BRIDGE_FILE_DOWNLOAD_ALLOW_ALL_PATHS`	关闭
Claude 订阅登录	`BRIDGE_ALLOW_CLAUDE_OAUTH=1`	关闭
手机凭据存储	Keychain / Keystore	始终加密
数据收集	隐私政策	零遥测、零分析

总结

CC Pocket 的安全模型可以概括为一句话：默认收紧、显式放开。自托管架构保证代码不出本机，目录白名单 + 路径规范化校验封死文件越权，API Key 与 Tailscale 守住网络入口，而 Claude 订阅鉴权则被刻意设计成"知情后手动开启"的可选项。理解了这套机制，你就能安心地把编码代理真正装进口袋 📱。