CodeFree Helper

CodeFree Helper 是 CodeFree 平台辅助工具，提供用于 CodeFree CLI 的 OAuth2 授权、API Key 管理和 Claude Code 集成功能。

功能介绍

• 独立授权：独立生成 CodeFree CLI 所需的认证凭证文件 oauth_creds.json，解决 CodeFree CLI 在授权过程中无法自动打开浏览器的问题。
• CLI API Key 提取：解密并显示已保存的 API Key，便于用户直接使用或配置到其他工具。
• Claude Code 集成：将 SRDCloud Transformer 安装到 Claude Code Router 插件目录，实现 SRDCloud API 与 Claude Code 的无缝集成。
• MCP 服务器安装：从 SRDCloud 获取 MCP 服务器配置，批量安装到 Claude Code，提供 API中心、Wiki文档、工作项、文档空间等 MCP 服务。

前置要求

• Node.js >= 20.0.0

安装

推荐：使用 npx（无需安装到本地）

npx codefree-helper

全局安装

npm install -g codefree-helper

使用

npx 方式

npx codefree-helper

全局安装方式

运行命令：

cfh

工具会提供交互式菜单，支持以下操作：

1. 生成 CLI OAuth 凭证文件 - 执行完整的 OAuth2 授权流程，生成包含加密 API Key 的凭证文件
2. 提取 CLI API Key - 解密并显示已保存的 API Key
3. 安装 CCR Transformer - 将 SRDCloud Transformer 安装到 Claude Code Router 插件目录
4. 安装 SRDCloud MCP 服务器配置 - 从 SRDCloud 获取 MCP 服务器列表，批量安装到 Claude Code

凭证存储

凭证文件保存在 ~/.codefree-cli/oauth_creds.json，包含：

• access_token
• id_token
• apikey（加密存储）
• baseUrl

Claude Code 集成

注意：此集成方式仅使用 SRDCloud API 大模型接口，并不包含使用数据统计。

如需使用数据统计功能，请参考 CodeFree Stat 工具。

安装 SRDCloud Transformer

Claude Code Router 用于将 SRDCloud API 转换为 Anthropic 接口协议。安装过程中会自动检测并提示安装 Claude Code Router（如未安装）。

Transformer 安装路径为 ~/.claude-code-router/plugins/srdcloud.transformer.js。

安装完成后需配置路由。可通过 ccr ui 命令打开 UI，或直接编辑 ~/.claude-code-router/config.json 添加如下配置：

{
  "Router": {
    "default": "srdcloud,GLM-4.7",
    "background": "srdcloud,GLM-4.7",
    "think": "srdcloud,GLM-5.1",
    "longContext": "srdcloud,GLM-5.1",
    "longContextThreshold": 60000,
    "webSearch": "srdcloud,GLM-4.7",
    "image": "srdcloud,Qwen3.5-122B-A10B"
  }
}

请根据实际需求调整，对于长上下文场景，建议选择支持更大上下文的模型。

注意：配置修改后需执行 ccr restart 使其生效。

后续使用claude code，需执行 ccr code 命令启动 Claude Code，或者将 ccr 的 Base URL 和 API Key 配置到环境变量中，具体方法可运行 ccr -h 查看ccr使用和参考 Claude Code 官方文档配置环境变量。

安装 SRDCloud MCP 服务器

本功能通过 claude mcp add-json 命令将 SRDCloud 提供的 MCP 服务器批量注册到 Claude Code，实现 API中心、Wiki文档、工作项、文档空间等 MCP 服务的直接调用。

headersHelper 认证方案

优势：

• ✅ 凭证集中管理：所有 MCP 服务器共享同一凭证文件
• ✅ 无明文存储：userId/apiKey/mcpId 都不在配置文件中明文存储
• ✅ 自动更新：凭证更新后无需重新配置 MCP 服务器
• ✅ 无需本地脚本：使用 npx 直接调用，无需安装本地脚本文件
• ✅ 动态 mcpId：每个 MCP 服务器通过 --mcp-id 参数传递对应的 mcpId

安装流程

1. 从凭证文件读取并解密认证信息
2. 调用 SRDCloud API 获取可用的 MCP 服务器列表
3. 选择要安装的 MCP 服务器（支持多选）
4. 选择安装范围（local/user/project）
5. 确认后逐个安装

安装完成后可通过 claude mcp list 查看已注册的 MCP 服务器。

手动测试认证头

# 测试不带 mcpId（返回基础认证头）
npx codefree-helper get-mcp-headers

# 测试带 mcpId（返回包含 mcpId 的认证头）
npx codefree-helper get-mcp-headers --mcp-id 123

# 或使用已安装的 CLI
cfh get-mcp-headers                # 不带 mcpId
cfh get-mcp-headers --mcp-id 123   # 带 mcpId

安装 Claude Code

本工具并不提供 Claude Code 的安装功能，可直接 npm 方式安装：

npm install -g @anthropic-ai/claude-code

其他安装方式可参考 Claude Code 官方文档：https://code.claude.com/docs/zh-CN/overview.

由于 SRDCloud API 提供的模型上下文有限，在 Claude Code 默认配置情况下使用可能出现 424 错误（Failed Dependency），解决方法是调整自动压缩阈值，通过修改环境变量 CLAUDE_AUTOCOMPACT_PCT_OVERRIDE 实现：

| 设置 | 说明 | |------|------| | 默认值 95 | 当输入占用上下文超过 95% 时才压缩 | | 30 到 40 | 使用GLM-4.7（88k）模型的情况下设置当输入占用上下文超过 30% 到 40% 时即压缩 | | 50 到 60 | GLM-5.1（128k）模型的情况下设置当输入占用上下文超过 50% 到 60% 时即压缩 |

可直接修改系统环境变量或者编辑 ~/.claude/settings.json 添加以下配置：

{
  "env": {
    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": 50
  }
}

以上上下文自动压缩比例是按照 200k 的模型上下文窗口来算，建议 Claude Code 2.1.50及以上版本设置环境变量 "CLAUDE_CODE_DISABLE_1M_CONTEXT": "1" 来禁用 100 万上下文窗口

已知问题

• 暂不支持 MCP 服务器覆盖安装（需要先手动删除再重新安装）

版本历史

• 1.2.1 - 支持模型GLM-5.1，更新 codefree-cli 默认版本号到0.3.6
• 1.2.0 - 迁移 npm 包组织到根目录
• 1.1.0 - 支持 MCP 服务器批量安装，使用 headersHelper 动态认证
• 1.0.x - 初始版本，支持 OAuth 授权和 CCR Transformer 安装