跳到主要内容
AI教程

CG Claude 教程：检测、配置并安全还原 Claude Code 本机环境

本教程介绍如何安装和使用 CG Claude，完成 31 项环境检查、一键配置、项目扫描、本机连接编辑、双向翻译测试，以及配置快照备份与安全还原。

AI我搜编辑部阅读约 13 分钟
CG Claude 教程：检测、配置并安全还原 Claude Code 本机环境

CG Claude 是什么

CG Claude 是一个面向 Claude Code 本机环境的配置与检查工作台，提供 Electron 桌面版和本机浏览器版。它可以检查系统、终端、浏览器、代理、TLS、Claude 配置和项目覆盖项，并通过预览、备份与快照机制协助修复配置。

工具包含 31 项环境检查，默认连续检查三遍。它不会根据环境结果推算账号状态；账号会话、服务地区、额度、支付、网页隐私和部分网络状态仍需人工复核。

主要能力

  • 检查系统与浏览器时区、终端 TZ、代理、DNS、IPv6、TLS、认证来源和 Claude 配置目录。
  • 通过 13 个流程节点执行配置，每个节点首次失败后最多重试三次，失败后跳过并继续后续节点。
  • 修改前展示预览，并在写入前创建备份；首次配置节点还会保存完整配置快照。
  • 扫描项目中的权限、Hooks、MCP、代理、TLS、凭据声明和依赖锁文件。
  • 编辑 Claude 本地连接设置，包括代理、网关、NO_PROXY 和额外 CA 路径。
  • 保存与恢复文件内容、权限、文件缺失状态、检测偏好以及已记录的时区和 TZ。
  • 配置 OpenAI 兼容 Chat Completions 或 Anthropic Messages，用固定示例测试中英双向翻译。
  • 提供中英文界面、浅色／护眼／深色配色、减少动画和手动版本检查。

CG Claude 只静态解析支持的配置文件，不执行启动脚本、项目脚本、Hooks、MCP 或依赖安装，也不会自动清理钥匙串、Claude 会话、Skills 或 Hooks。

安装桌面版

普通用户优先使用桌面安装包。版本 1.2.7 的安装包位于 Release 附件中的 release/1.2.7/，安装后不需要另行安装 Node.js。

  • macOS Apple Silicon：CG-Claude-1.2.7-macos-arm64.dmg
  • macOS Intel：CG-Claude-1.2.7-macos-x64.dmg
  • Windows x64：CG-Claude-1.2.7-windows-x64-setup.exe
  • Linux x64：CG-Claude-1.2.7-linux-x86_64.AppImage 或 CG-Claude-1.2.7-linux-amd64.deb

下载后可使用 SHA256SUMS.txt 核对文件完整性。需要注意，macOS 构建尚未签名或公证；Windows 和 Linux 桌面交互尚未经过实机验证。

桌面窗口关闭或最小化时通常会隐藏到菜单栏或系统托盘，任务仍会继续执行。若要真正结束服务，应从托盘菜单选择“退出 CG Claude”；程序会等待检测、配置或还原事务结束，再释放服务锁。

桌面版和浏览器服务不能同时使用同一记录目录。启动其中一个版本前，请退出另一个实例，避免并发写入。

从源码启动

准备环境

源码运行要求 Node.js 22.12 或更高版本。进入项目目录后安装锁定依赖并启动 Electron：

npm ci
npm run desktop

macOS 也可双击 启动工具.command，Windows 可双击 启动工具.cmd。Linux 用户应在项目目录中运行 npm run desktop。

准备脚本会按锁定版本下载 Electron，并复用已经安装的二进制文件。下载过程使用现有 HTTP／HTTPS 代理环境，但不会改写用户代理配置。

启动浏览器版

npm run build
npm start

启动后访问 http://127.0.0.1:4318。服务只监听回环地址，可按 Ctrl+C 退出。Linux 也可运行：

./scripts/start.sh

第一次检测：建立环境基线

  1. 设置检测偏好。选择实际网络模式、服务方式、时区目标和隐私偏好。时区默认按照台北建议核对，也可改为当前出口或手动指定。
  2. 确认可选网络检测。默认检测主要读取本机配置。若要查询公网出口或采集 WebRTC 数据，需要额外勾选；相关外部服务将看到连接 IP。
  3. 开始检测。点击“开始检测”，工具默认连续执行三遍检查，以降低瞬时状态造成的误判。
  4. 按状态筛选。使用顶部的“检查通过”“需要关注”或“待确认”入口。入口会清除旧搜索和分类条件，展开并定位到第一项结果。
  5. 查看证据和边界。结果分为通过、需关注、需处理、待确认和未检测。对于账号、地区、支付、网页隐私、手机时区或定位服务等项目，应按照提示人工确认。

31 项检查覆盖系统和浏览器时区、TZ、系统代理、虚拟接口、DNS、IPv6、进程与启动文件代理、npm 和 Git 代理、API 地址、Claude 配置目录、隐私、CLI、TLS、代理兼容性、认证来源、自定义 CA／mTLS，以及可选的公网出口与浏览器一致性。

执行一键配置

检测完成后，不要立即盲目写入。先阅读修改预览，确认目标值、影响文件和需要系统授权的操作。

  1. 点击“一键配置”，逐项填写网络模式、服务方式和隐私偏好。自定义 API 地址清理默认不勾选。
  2. 检查系统时区和终端 TZ 两个默认勾选的节点；不希望修改时可以取消。
  3. 阅读写入预览，确认将要修改的字段、文件和权限。
  4. 开始配置。工具按照 13 个节点顺序执行，每次写入前保存备份，第一节点保存完整快照。
  5. 配置结束后，根据集中展示的剩余事项打开设置页、复制命令或启动终端，完成无法自动处理的步骤。
  6. 重新打开终端和 Claude 客户端，再进行三遍复检。已经打开的终端不会因文件变化自动刷新环境变量。

工具可处理 shell、npm 和 Git 用户代理，shell 与 Claude 自定义 API 地址、Claude 隐私变量和 npm TLS 校验；还可在一键流程中配置系统时区与终端 TZ。

支持的配置位置包括：

  • .zshrc、.zprofile、.zshenv
  • .bashrc、.bash_profile、.bash_login、.profile
  • .npmrc、.gitconfig、.config/git/config
  • .claude/settings.json

macOS 修改系统时区时需要管理员授权，Windows 使用 UAC，Linux 依赖可用的 polkit 代理。若 macOS 自动时区已经开启且状态可读取，一键配置会尝试在授权后关闭并回读结果。

编辑 Claude 本地连接

在导航末尾打开“本机配置”，可以逐项选择保持、设置或移除连接参数。该功能只写入 ~/.claude/settings.json 中的以下字段：

  • HTTPS_PROXY
  • HTTP_PROXY
  • NO_PROXY
  • ANTHROPIC_BASE_URL
  • NODE_EXTRA_CA_CERTS

保存前会显示预览，并记录修改前的完整快照和原文件备份。其他字段、Hooks、权限和凭据会保留，JSON 最终统一为两格缩进。同名小写代理项的规范化也会显示在预览中。

额外 CA 文件必须是可读、非空的本机绝对路径。工具不会读取证书内容，也不会为此执行连通性请求。如果检测到自定义 CLAUDE_CONFIG_DIR，连接编辑入口会停用，以避免写入错误目录。

扫描项目配置

打开“项目扫描”，选择本地项目目录。扫描范围包括配置覆盖、权限、命令沙箱、Hooks、MCP、代理、TLS、凭据声明、依赖锁文件和本地 Git 提交。

项目扫描只读取固定配置与元数据文件，不执行项目脚本、Hooks、MCP 或依赖安装。对于 dotenv 文件，工具只检查是否存在，不读取内容；凭据字段只给出提示，不展示值。

项目扫描不能替代源码漏洞、依赖漏洞或构建正确性检查。此类问题仍需使用对应的安全、依赖和构建工具。

备份与完整快照还原

在“备份恢复”中选择已有完整快照，点击“一键还原之前的配置快照”。还原范围可以包括文件内容、原权限、文件原本不存在的状态、检测偏好，以及已记录的系统时区和 TZ。

  1. 选择目标快照并查看还原预览。
  2. 确认文件内容、权限和时区状态仍与预览基线一致。
  3. 执行还原。工具会先额外保存当前状态，再恢复目标快照。
  4. 重新打开终端和客户端，验证环境变量与 Claude 配置。

如果预览后文件内容、权限或时区发生变化，还原会被阻止，避免覆盖新修改。快照只覆盖支持的十一个用户配置位置、检测偏好及可读取的时区与 TZ，不包含翻译配置、完整 ~/.claude 目录、钥匙串或历史会话。

配置双向翻译

在左侧“双向翻译”中，可设置协议、API 地址、模型名、密钥和超时。支持 OpenAI 兼容 Chat Completions 与 Anthropic Messages。

点击“测试双向翻译”后，工具会实际发送两段固定示例，并分别展示中译英和英译中结果。测试不会读取项目内容或 Claude 会话，也不会自动重试可能收费的请求。

密钥使用 AES-256-GCM 加密，主密钥保存在本机私有记录目录。不过它并非系统钥匙串，拥有该目录读取权限的人仍可能解密。已保存密钥不会返回界面；更换服务地址或协议后需要重新填写。

翻译模型测试通过不代表 Claude Code 原生终端已被接入，也不会自动启用会话拦截。

使用隔离演示和 CLI

在修改真实配置前，可以先使用隔离演示模式：

npm run demo
npm run desktop:demo

demo 使用专门的临时配置目录和 4319 端口；desktop:demo 使用独立 Electron 资料目录。演示写入只作用于测试目录，系统时区与 TZ 采用隔离模拟，但平台信息和客户端版本仍从本机读取。

需要自动化读取检测结果时，可使用 CLI：

npm run doctor -- --json

CLI 默认只检测，不修改配置。如需开启终端公网查询，增加 --network：

npm run doctor -- --json --network

常用运行变量

  • CG_PORT：浏览器服务端口，默认 4318；Electron 使用随机回环端口。
  • CG_HOME：用户配置根目录，默认是当前用户主目录，可用于隔离验证。
  • CG_DATA_DIR：记录目录，默认位于配置根目录下的 .claude-guard。
  • CG_DEMO=1：标记隔离模式，应同时指定独立配置根目录。

高级使用建议

避免使用过期预览

如果历史报告、检测偏好或配置基线已经变化，应重新检测后再预览修复。旧报告仍可阅读，但不应直接作为新一轮写入依据。工具也会核对文件权限和读取状态，拒绝沿用已经变化的预览。

正确处理复杂配置文件

启动文件只静态解析直接赋值。复杂函数、条件块、多行表达式和 heredoc 不会自动编辑。配置文本必须是严格 UTF-8；包含非法 UTF-8 或 NUL 的文件会被排除出快照，并提示手动检查，而不会猜测 GBK 等编码。

理解公网检测的隐私边界

公网检测可能访问 https://ipinfo.io/json、https://api.ipify.org?format=json 和 stun:stun.l.google.com:19302。这些服务会看到连接 IP，但不会收到本机配置或密钥。报告导出默认会进一步隐藏 IP 和主机名。

区分浏览器语言与时区配置

浏览器目标语言默认是 en-US，en-CN 虽然也是英文，但地区不同。该检查属于项目扩展项，并非原文强制要求。一键时区配置不会修改外部浏览器语言，需要按照页面提供的 Chrome、Edge、Firefox 或 Safari 指引手动设置。

保护本地记录

默认记录目录为 ~/.claude-guard/，其中保存检测偏好、最近 30 次报告、备份、快照、人工复核和工作流状态。备份或快照原文可能包含凭据，因此不要随意复制或提交该目录。

POSIX 系统中记录目录权限为 0700、记录文件为 0600；Windows 继承用户目录 ACL。新建配置文件在 POSIX 上使用 0600，同时尽量保留原配置权限。

开发与打包

开发模式使用前端 5173 端口和后端 4318 端口：

npm run dev

提交修改前可运行完整检查和格式校验：

npm run check
npm run format:check

生成应用目录或当前平台安装包：

npm run pack
npm run dist

pack 生成应用目录；dist 根据当前系统生成 macOS dmg／zip、Windows NSIS／portable 或 Linux AppImage／deb，并使用当前系统与 CPU 架构对应的 Electron 运行时。

结语

CG Claude 将环境检测、配置预览、字段修复、项目扫描和快照还原集中到一个本地工作台中。推荐先在演示模式熟悉流程，再建立真实环境基线；每次写入前检查预览，完成后重新打开终端并连续复检。对于账号、地区、支付、手机时区和浏览器隐私等无法可靠自动判断的项目，应保留人工复核步骤。

如需查看浏览器环境配置插件，可访问 LC-time 项目。