使用 free-claude-code 免费运行 Claude Code，绕不开一个现实问题：你的 API 密钥是否安全？这个轻量级代理（Proxy）将 Claude Code 的 Anthropic API 请求转发到 NVIDIA NIM、OpenRouter 或 LM Studio，需要你在.env文件中配置NVIDIA_NIM_API_KEY、OPENROUTER_API_KEY等密钥。本文结合源码，带你完整梳理 free-claude-code 的 6 大安全机制与 4 类部署风险，帮你把「免费跑 AI 编程助手」这件事做安全。

密钥存在哪里？先搞清楚密钥流转路径

所有敏感凭证都通过环境变量注入，统一由 config/settings.py 中的 Pydantic Settings 加载（读取.env文件，见.env.example）：

好消息：项目的 .gitignore 已将.env、agent_workspace、server.log全部排除，密钥文件不会被提交到版本库。

安全机制解析：项目内置了哪些防线？

1. 白名单访问控制（最关键的防线）

这是 Bot 模式的第一道闸门：

• Telegram：只有ALLOWED_TELEGRAM_USER_ID中指定的用户 ID 能发消息，其他用户会被直接静默拒绝并记录告警日志，实现见 messaging/platforms/telegram.py
• Discord：只有ALLOWED_DISCORD_CHANNELS中列出的频道才处理消息，列表为空 = 全部拒绝，实现见 messaging/platforms/discord.py

💡 注意：Telegram 的校验是「配置了才检查」，如果不填ALLOWED_TELEGRAM_USER_ID，任何人都能驱动你的 Bot——这是最大的配置陷阱。

2. 工作目录沙箱：ALLOWED_DIR

Bot 驱动 Claude CLI 时，代理会：

• 把 CLI 子进程的cwd锁定在ALLOWED_DIR指定的工作区（见 api/app.py）
• 通过--add-dir参数向 Claude Code 显式声明可访问目录（见 cli/session.py）

这样代理的文件操作被限定在你指定的项目根目录内，配合会话数据集中存放在CLAUDE_WORKSPACE（默认./agent_workspace，已被 gitignore 排除）。

3. 子代理失控拦截（Subagent Control）

Claude Code 的 Task 工具会派生后台子代理，容易「跑飞」烧光配额。free-claude-code 在响应流中拦截 Task 工具调用，强制改写run_in_background=False（见 providers/openai_compat.py），杜绝失控子代理。

4. 三层限流保护配额

providers/rate_limit.py 实现了完整的双向限流：

• 主动滚动窗口：严格保证任意 60 秒内最多 40 个请求（PROVIDER_RATE_LIMIT/PROVIDER_RATE_WINDOW），绝不突发
• 被动 429 熔断：一旦遇到限流错误，全局指数退避重试（含随机抖动）
• 并发上限：PROVIDER_MAX_CONCURRENCY（默认 5）限制同时打开的流数量

消息平台侧另有独立滑动窗口限流（messaging/limiter.py），防止高频消息打爆上游。

5. 进程生命周期兜底

每个 Claude CLI 子进程 PID 都会注册到 cli/process_registry.py，注册atexit钩子：即使服务被Ctrl+C中断导致清理逻辑没跑完，也会尽力杀掉自己派生的进程，不会误杀无关系统进程，避免遗留的 AI 进程在后台继续执行命令。

6. 全量可追溯日志

config/logging_config.py 将所有日志以 JSON Lines 写入server.log（50MB 自动轮转），并拦截未授权访问尝试（日志中出现Unauthorized access attempt from ...）。日志文件本身在.gitignore中，不会泄露到仓库。

部署风险清单：这 4 个坑必须避

风险一：代理端口对全网暴露 ⚠️

服务默认监听0.0.0.0:8082（见 config/settings.py）。代理端口本身没有鉴权——ANTHROPIC_AUTH_TOKEN="freecc"只是占位符。后果是：同一局域网内的人都能免费把你的 NIM 配额当公共 API 用。

✅对策：本机使用改为--host 127.0.0.1；多人共用场景建议加反向代理（Nginx + Basic Auth / 令牌校验）再转发到 8082。

风险二：--dangerously-skip-permissions是双刃剑

Bot 模式下 CLI 以--dangerously-skip-permissions启动（见 cli/session.py），意味着 AI 可免确认执行任意命令。此时安全性完全依赖第 1、2 节两道防线：白名单 +ALLOWED_DIR沙箱。

✅对策：务必配置ALLOWED_DIR指向专用工作目录，切勿指向你的家目录或包含密钥、凭证的项目目录；只信任的白名单用户才允许接入。

风险三：.env文件保管不当

.env是唯一同时存放 NIM 密钥、Bot 令牌、HF Token 的文件。常见事故：截图外传、打包备份时带上、放进共享网盘。

✅对策：

• 保持文件权限最小化，定期在 build.nvidia.com/settings/api-keys 轮换 NIM 密钥
• 若密钥泄露，第一时间重置对应平台密钥；Bot 令牌泄露则立即在 Developer Portal 重新生成

风险四：忽略 LM Studio 本地方案的隐私优势

对隐私要求高的场景，MODEL="lmstudio/..."走纯本地推理（localhost:1234），代码与上下文零出网、无需任何 API 密钥——这是从根源上消除密钥泄露风险的方案。

安全部署检查清单

部署前逐项打勾，5 分钟搞定：

• ALLOWED_TELEGRAM_USER_ID/ALLOWED_DISCORD_CHANNELS已配置且非空（Discord 空值 = 拒绝全部）
• ALLOWED_DIR指向专用工作目录，不含敏感文件
• 代理监听地址：仅本机用请改127.0.0.1，或加鉴权反向代理
• .env未提交 git、未截图外传、权限最小化
• 确认PROVIDER_RATE_LIMIT=40/PROVIDER_MAX_CONCURRENCY=5未随意调大
• 关注server.log中的Unauthorized告警记录

总结

free-claude-code 的安全设计思路可以概括为：「默认不信任外部，配额绝不失控」——白名单拒绝一切未授权用户、目录沙箱圈定 AI 操作范围、三层限流锁死配额消耗、进程兜底清理防止后台残留。真正的风险集中在部署层面：代理端口无鉴权 +--dangerously-skip-permissions免确认执行。只要按上文清单配置好监听地址、白名单与沙箱目录，免费使用 Claude Code 完全可以做到安全可控。🔐

想体验完整功能，可从项目仓库获取代码（git clone https://gitcode.com/gh_mirrors/fre/free-claude-code），然后阅读 README.md 快速上手。