avivsinai/telclaude

GitHub: avivsinai/telclaude

一个具备 LLM 预筛查、分级权限和多层隔离机制的 Telegram-Claude 安全中继网关。

Stars: 2 | Forks: 0

# telclaude 隔离优先的 Telegram ⇄ Claude Code 中继，具备 LLM 预筛查、审批流程和分级权限。 [![CI](https://static.pigsec.cn/wp-content/uploads/repos/2026/03/2173286485044504.svg)](https://github.com/avivsinai/telclaude/actions/workflows/ci.yml) [![Gitleaks](https://static.pigsec.cn/wp-content/uploads/repos/2026/03/8224f08df5044505.svg)](https://github.com/avivsinai/telclaude/actions/workflows/gitleaks.yml) [![CodeQL](https://static.pigsec.cn/wp-content/uploads/repos/2026/03/ac9871bfd8044506.svg)](https://github.com/avivsinai/telclaude/actions/workflows/codeql.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) ## 亮点 - 强制隔离边界：原生模式下使用 SDK sandbox (Seatbelt/bubblewrap)，Docker 模式下使用 relay+agent 容器 + 防火墙。 - 凭证库：sidecar daemon 存储 API 密钥并将其注入请求 —— agent 永远不会看到原始凭证。 - 严格默认值：密钥脱敏（CORE 模式 + 熵检测）、速率限制、审计日志以及失败即关闭的聊天白名单。 - 软控制：Haiku 观察者、基于 nonce 的 FULL_ACCESS 审批工作流，以及可选的 TOTP 认证门控用于定期身份验证。 - 四个权限层级，映射到 Claude Agent SDK allowedTools：READ_ONLY, WRITE_LOCAL, SOCIAL, FULL_ACCESS。 - 通用社交服务集成（X/Twitter, Moltbook, Bluesky 等），通过配置驱动的 `SOCIAL` agent 上下文实现统一社交身份。 - 外部提供商 sidecar：Google Services (Gmail, Calendar, Drive, Contacts) 具备审批门控操作；可扩展模式用于添加新提供商。 - 面向家庭实验室服务（Home Assistant, NAS 等）的私有网络白名单及端口强制。 - 可在 macOS/Linux 本地运行，或通过 Docker Compose 栈运行（Windows 通过 WSL2）。 - 无遥测或分析；仅包含您在自己环境中启用的审计日志。 ## 文档导航 | 文档 | 用途 | |----------|---------| | 本 `README.md` | 概述、快速入门、配置 | | `examples/` | 配置示例（最小化、个人、团队）| | `CLAUDE.md` | Agent playbook（由 Claude Code 自动加载）| | `AGENTS.md` | Agents 指南指针 | | `docs/architecture.md` | 架构设计原理、安全模型、不变量 | | `docs/providers.md` | 提供商集成指南（sidecar 模式、添加新提供商）| | `docker/README.md` | 容器部署、防火墙、卷 | | `CHANGELOG.md` | 版本历史 | | `SECURITY.md` | 漏洞报告、威胁模型 | | `docs/soul.md` | Agent 身份、声音、兴趣 | ## 支持与节奏 - 状态：alpha —— 在 1.0 之前可能会有破坏性变更。 - 平台：macOS 14+ 或 Linux (bubblewrap+socat+rg) 原生模式；生产环境推荐 Docker/WSL。 - Issues/PR 分类：每周一次；安全报告在 48 小时内确认。 - 发布：alpha 期间随性发布；目标是每月一次。 - 安全联系人：通过 GitHub security advisory 联系项目维护者。 ## 权限层级（概览） | 层级 | 能力 | 保障措施 | | --- | --- | --- | | READ_ONLY | 读取文件、搜索、web fetch/search | 无写入；sandbox + 密钥过滤器 | | WRITE_LOCAL | READ_ONLY + 写入/编辑/bash | 阻止破坏性 bash (rm/chown/kill 等)；denyWrite 模式 | | SOCIAL | 文件工具 + Bash + WebFetch/WebSearch | Bash 受 actor 类型信任门控；WebFetch 宽松；阻止受保护路径 | | FULL_ACCESS | 所有工具 | 每个请求都需要人工批准；仍在 sandbox 中运行 | ## 架构 ``` Telegram │ ▼ ┌──────────────────────────────────────────────────────────────────┐ │ Security Layer │ │ ┌────────────┐ ┌────────────┐ ┌──────────┐ ┌──────────┐ │ │ │ Fast Path │──▶│ Observer │──▶│ Rate │──▶│ Approval │ │ │ │ (regex) │ │ (Haiku) │ │ Limit │ │ (human) │ │ │ └────────────┘ └────────────┘ └──────────┘ └──────────┘ │ └──────────────────────────────────────────────────────────────────┘ │ ▼ ┌──────────────────────────────────────────────────────────────────┐ │ Permission Tiers │ │ READ_ONLY WRITE_LOCAL SOCIAL FULL_ACCESS │ │ (5 tools) (8 tools) (trust-gated) (all, +approval) │ └──────────────────────────────────────────────────────────────────┘ │ ▼ ┌──────────────────────────────────────────────────────────────────┐ │ Isolation Boundary (mode-dependent) │ │ Docker: relay+agent + firewall │ Native: SDK sandbox │ │ (SDK sandbox off) │ (Seatbelt/bwrap) │ └──────────────────────────────────────────────────────────────────┘ │ ▼ Claude Agent SDK ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │ TOTP Daemon │ │ Vault Daemon │ │ Google Services │ │ (OS keychain) │ │ (credential │ │ (Gmail, Calendar │ └──────────────────┘ │ injection) │ │ Drive, Contacts)│ └──────────────────┘ └──────────────────┘ ``` ## 系统要求 - Node 20+, pnpm 9.x - Claude CLI (`brew install anthropic-ai/cli/claude`) —— 推荐。在 Docker 中，telclaude 通过 relay proxy 路由 Anthropic 访问；如果您使用 OAuth，请在 relay 容器中运行 `claude login` 并设置 `CLAUDE_CONFIG_DIR=/home/telclaude-auth`，以便 token 存储在专用认证配置中。 - 来自 @BotFather 的 Telegram bot token - 原生模式：macOS 14+ 或带有 `bubblewrap`、`socat` 和 `ripgrep` (需在 PATH 中可用) 的 Linux - Docker/WSL：Docker + Compose（不需要主机 bubblewrap） - 可选但推荐：TOTP daemon 使用 OS keychain (keytar) ## 第三方条款 - 本项目依赖于 `@anthropic-ai/claude-agent-sdk`，该 SDK 根据 Anthropic 的 Claude Code 法律协议分发（安装后请参阅 `node_modules/` 中的 `LICENSE.md`）。 ## 快速入门 (Docker, 生产环境推荐) ``` git clone https://github.com/avivsinai/telclaude.git cd telclaude/docker cp .env.example .env # set TELEGRAM_BOT_TOKEN, WORKSPACE_PATH, TOTP_ENCRYPTION_KEY, run `telclaude keygen telegram` and `telclaude keygen social` for RPC keys, ANTHROPIC_PROXY_TOKEN docker compose up -d --build docker compose exec -e CLAUDE_CONFIG_DIR=/home/telclaude-auth telclaude claude login # optional if not using ANTHROPIC_API_KEY ``` 有关防火墙、卷和升级详情，请参阅 `docker/README.md`。这将启动 6 个容器：`telclaude` (relay), `telclaude-agent` (private persona), `agent-social` (social persona), `google-services` (Google sidecar), `totp`, 和 `vault`。注意：Docker 使用共享的 **skills** 配置文件 (`/home/telclaude-skills`) 和仅限 relay 的 **auth** 配置文件 (`/home/telclaude-auth`)。Agents 通过 relay proxy 访问 Anthropic；凭证永远不会挂载到 agent 容器中。 ## 快速入门 (本地) 1. 克隆并安装 ``` git clone https://github.com/avivsinai/telclaude.git cd telclaude pnpm install ``` 2. 在 `~/.telclaude/telclaude.json` 创建配置 (JSON5) —— 白名单是必需的，否则 bot 将忽略所有聊天（失败即关闭）。 ``` { "telegram": { "botToken": "123456:ABC-DEF", "allowedChats": [123456789] // your Telegram numeric chat ID }, "security": { "profile": "strict", // simple | strict | test "permissions": { "users": { "tg:123456789": { "tier": "FULL_ACCESS" } } } } } ``` 注意：`defaultTier=FULL_ACCESS` 在运行时会被有意拒绝。对于原生安装，建议将 `botToken` 放在配置中；`TELEGRAM_BOT_TOKEN` 也可接受（主要用于 Docker）。 3. 认证 Claude ``` claude login # API key is not forwarded into sandboxed agent ``` 4. (推荐) 在另一个终端启动 TOTP daemon ``` pnpm dev totp-daemon ``` 5. 健康检查 ``` pnpm dev doctor --network --secrets ``` 6. 运行 relay ``` # 开发（原生：通过 @anthropic-ai/sandbox-runtime 的 SDK sandbox；如果不可用，请使用下面的 Docker） pnpm dev relay --profile simple # 推荐 / 生产环境：Docker 或带容器边界 + 防火墙的 WSL docker compose up -d --build docker compose exec telclaude pnpm start relay --profile strict ``` 7. 首次管理员认领 - 从允许的聊天中私信您的 bot；它会回复 `/approve

`。
- 发送该命令以将聊天链接为管理员（FULL_ACCESS，需逐请求批准）。
- 在同一聊天中，运行 `/setup-2fa` 以绑定 TOTP 进行定期身份验证（daemon 必须正在运行）。允许使用 `/skip-totp` 但不推荐。
- 可选加固：设置 `TELCLAUDE_ADMIN_SECRET` 并以 `/claim ` 开始，以防止扫描 bot 抢先认领管理员（参见 `SECURITY.md`）。

## 配置

- 默认路径：`~/.telclaude/telclaude.json`（使用 `TELCLAUDE_CONFIG` 或 `--config` 覆盖）。
- 配置文件：
- `simple` (默认)：sandbox + 密钥过滤器 + 速率限制 + 审计。
- `strict`：添加 Haiku 观察者、审批工作流和分层工具门控。
- `test`：禁用所有强制执行；需要 `TELCLAUDE_ENABLE_TEST_PROFILE=1`。
- 权限层级：
- `READ_ONLY`：仅读取/搜索/web；无写入。
- `WRITE_LOCAL`：读取/写入/编辑/bash，阻止破坏性命令。
- `SOCIAL`：文件工具 + Bash + WebFetch/WebSearch；Bash 受 actor 信任门控；阻止受保护路径。
- `FULL_ACCESS`：工具无限制，但每个请求都需要人工批准。
- 在 `security.permissions.users` 下为每个用户设置；`defaultTier` 保持为 `READ_ONLY`。
- 可选群组护栏：
- `telegram.groupChat.requireMention: true` 以忽略群组/超级群组消息，除非它们提及 bot 或回复它。
- OpenAI/GitHub 密钥暴露（基于层级）：
- FULL_ACCESS 层级自动将配置的 API 密钥暴露给 sandbox。
- READ_ONLY 和 WRITE_LOCAL 层级永远不会获得密钥。
- 通过 `telclaude setup-openai` / `telclaude setup-git` 或环境变量配置密钥。
- **安全提示：** 密钥在 FULL_ACCESS 中会暴露给模型；如果担心，请使用受限密钥。
- 速率限制和审计日志默认开启；有关完整模式和选项，请参阅 `CLAUDE.md`。

## 凭证库

Vault daemon 存储 API 凭证并将其透明地注入 HTTP 请求中 —— agent 永远不会看到原始凭证。此功能主要为具有远程 agent 的 Docker 部署而设计。

**工作原理（Docker/远程 agent 模式）：**

1. Vault daemon 作为 sidecar 运行（Unix socket，除 OAuth 刷新外无网络）
2. Relay 上的 HTTP proxy (端口 8792) 拦截请求，如 `http://relay:8792/api.openai.com/v1/...`
3. Proxy 按主机查找凭证，注入 auth headers，转发到上游
4. Agent 接收响应而从未看到 API key

**注意：** HTTP 凭证 proxy 仅在配置了远程 agent (`TELCLAUDE_AGENT_URL`) 时启动。原生模式改为对 FULL_ACCESS 层级使用直接密钥暴露（请参阅配置部分）。

**支持的认证类型：** `bearer`, `api-key`, `basic`, `query`, `oauth2` (带自动 token 刷新)

**安全属性：**

- 凭证静态加密 (AES-256-GCM)
- 主机白名单防止注入到意外目的地
- 可选的每主机路径限制
- Socket 权限 0600

**快速设置：**


```
# 生成加密密钥

export VAULT_ENCRYPTION_KEY=$(openssl rand -base64 32)



# 启动 vault daemon

telclaude vault-daemon



# 添加凭证

telclaude vault add http api.openai.com --type bearer --label "OpenAI"

# （安全地提示输入 token）



# 列出凭证

telclaude vault list
```


有关 vault 设计原理，请参阅 `docs/architecture.md`。CLI 参考：`telclaude vault --help`。

## 私有网络白名单

对于本地服务（Home Assistant, NAS, Plex 等），配置显式的私有端点：


```
{

  "security": {

    "network": {

      "privateEndpoints": [

        { "label": "home-assistant", "host": "192.168.1.100", "ports": [8123] },

        { "label": "homelab", "cidr": "192.168.1.0/24", "ports": [80, 443] }

      ]

    }

  }

}
```


**CLI:**


```
telclaude network list

telclaude network add ha --host 192.168.1.100 --ports 8123

telclaude network test http://192.168.1.100:8123/api
```


无论白名单如何，元数据端点 (169.254.169.254) 和链路本地地址保持阻止状态。

## 外部提供商

Telclaude 通过 relay 代理的请求与私有 REST API sidecar 集成。Agents 永远不会直接调用提供商端点（在应用和防火墙层强制执行）。

**内置提供商：** Google Services (Gmail, Calendar, Drive, Contacts) —— 4 个服务，20 个带审批门控变更的操作。设置：`telclaude setup-google`。

**配置：**

- 将提供商添加到 `telclaude.json` 的 `providers[]` 下（id, baseUrl, services 列表）。
- 有关完整的集成指南，包括如何添加新提供商，请参阅 `docs/providers.md`。

**必需端点：**

| 端点 | 方法 | 用途 |

|----------|--------|---------|

| `/v1/health` | GET | 健康检查（返回带有 status 字段的 JSON）|

| `/v1/schema` | GET | 用于自动发现和技能文档的操作目录 |

| `/v1/fetch` | POST | 分发服务操作（body: `{ service, action, params }`）|

可选：`/v1/challenge/respond` (POST) 用于 OTP/2FA 完成。

## CLI 参考

### 核心

| 命令 | 描述 |

|---------|-------------|

| `telclaude relay [--profile simple\|strict\|test] [--dry-run]` | 启动 relay |

| `telclaude quickstart` | 交互式首次设置 |

| `telclaude doctor [--network] [--secrets]` | 健康检查 |

| `telclaude status [--json]` | 显示 relay 状态 |

### 认证与访问控制

| 命令 | 描述 |

|---------|-------------|

| `telclaude link  \| --list \| --remove ` | 管理身份链接 |

| `telclaude totp-daemon [--socket-path ]` | 启动 TOTP daemon |

| `telclaude totp-setup ` | 为用户设置 TOTP |

| `telclaude totp-disable ` | 为用户禁用 TOTP |

| `telclaude reset-auth [--force]` | 重置认证状态 |

| `telclaude ban  [-r ]` | 封禁聊天 |

| `telclaude unban ` | 恢复访问 |

| `telclaude force-reauth ` | 使 TOTP 会话失效 |

| `telclaude list-bans` | 显示被封禁的聊天 |

### 凭证库

| 命令 | 描述 |

|---------|-------------|

| `telclaude vault-daemon` | 启动 vault daemon |

| `telclaude vault list | 列出存储的凭证 |

| `telclaude vault add http  --type  [--label ]` | 添加凭证 |

| `telclaude vault remove http ` | 移除凭证 |

| `telclaude vault test http ` | 测试凭证注入 |

### API 密钥与服务设置

| 命令 | 描述 |

|---------|-------------|

| `telclaude setup-openai` | 配置 OpenAI API 密钥 |

| `telclaude setup-git` | 配置 Git 凭证 |

| `telclaude setup-github-app` | 配置 GitHub App |

| `telclaude setup-google` | 配置 Google OAuth 凭证（用于 Google Services sidecar）|

### 网络与提供商

| 命令 | 描述 |

|---------|-------------|

| `telclaude network list` | 列出私有端点 |

| `telclaude network add  (--host  \| --cidr ) [--ports ]` | 添加端点 |

| `telclaude network remove ` | 移除端点 |

| `telclaude network test ` | 测试端点访问 |

| `telclaude provider-query --provider  --service  --action ` | 查询外部提供商 |

| `telclaude provider-health [provider-id]` | 检查提供商健康状况 |

### 媒体与消息

| 命令 | 描述 |

|---------|-------------|

| `telclaude send  [message] [--media ] [--caption ]` | 发送消息/媒体 |

| `telclaude send-local-file --path  [--filename ]` | 将工作区文件发送到 Telegram |

| `telclaude send-attachment --ref ` | 通过 ref token 发送提供商附件 |

| `telclaude fetch-attachment --provider  --id ` | 下载提供商附件 |

| `telclaude generate-image  [-s ] [-q ]` | 生成图像（需要 OpenAI）|

| `telclaude text-to-speech  [-v ] [-f ]` | 文本转语音（需要 OpenAI）|

### 诊断

| 命令 | 描述 |

|---------|-------------|

| `telclaude diagnose-sandbox-network` | 调试 sandbox 网络问题 |

| `telclaude integration-test [--all] [--agents]` | 运行 SDK 集成测试（可选使用 `--agents` 进行直接 agent 传输检查）|

| `telclaude reset-db [--force]` | 删除 SQLite 数据库（需要 `TELCLAUDE_ENABLE_RESET_DB=1`）|

## 使用示例

使用审批和 TOTP 运行 strict 配置文件：


```
pnpm dev totp-daemon &

pnpm dev relay --profile strict

# 在 Telegram（允许的聊天）中：

# 1) bot 回复 /approve CODE 进行管理员认领

# 2) 运行 /setup-2fa 绑定 TOTP
```


在开发期间使用 `pnpm dev ` (tsx)。生产环境：`pnpm build && pnpm start ` (从 `dist/` 运行)。

## 部署

- **生产环境（强制）：Docker/WSL Compose stack** (`docker/README.md`)。Relay+agent 容器 + 防火墙；Docker 模式下禁用 SDK sandbox。在共享或多租户主机上使用此模式。
- **开发环境：** 带有 SDK sandbox (Seatbelt/bubblewrap) 的原生 macOS/Linux。SDK sandbox 为 Bash 提供 OS 级隔离；WebFetch/WebSearch 由 hooks/allowlists 过滤。保持 `~/.telclaude/telclaude.json` chmod 600。

## 开发

- Lint/格式化：`pnpm lint`, `pnpm format`
- 类型：`pnpm typecheck`
- 测试：`pnpm test` 或 `pnpm test:coverage`
- 构建：`pnpm build`
- 本地 CLI：`pnpm dev relay`, `pnpm dev doctor` 等。
- 密钥扫描：`brew install gitleaks`（或下载二进制文件）然后 `pnpm security:scan`（使用 `.gitleaks.toml`）

## 安全与报告

- 默认立场是失败即关闭（空 `allowedChats` 拒绝所有；拒绝 `defaultTier=FULL_ACCESS`）。
- 原生模式需要 SDK sandbox；如果 Seatbelt/bubblewrap（或 Linux 上的 socat）不可用，relay 将退出。Docker 模式需要防火墙（容器强制执行）。
- 漏洞：请遵循 `SECURITY.md` 进行协调披露。
- 安全联系人：通过 GitHub security advisory 联系项目维护者。

## 故障排除（快速）

| 症状 | 可能原因 | 修复 |

| --- | --- | --- |

| Bot 无响应/被拒绝 | `allowedChats` 为空或触发速率限制 | 添加您的 chat ID 并重新运行；检查 audit/doctor |

| Sandbox 不可用 (原生) | seatbelt/bubblewrap/rg/socat 缺失 | 安装依赖项（参见上方系统要求部分）|

| TOTP 失败 | Daemon 未运行或时钟漂移 | 启动 `pnpm dev totp-daemon`；同步设备时间 |

| SDK/观察者错误 | Claude CLI 缺失或未登录 | `brew install anthropic-ai/cli/claude && claude login` (Docker: `docker compose exec -e CLAUDE_CONFIG_DIR=/home/telclaude-auth telclaude claude login`) |

| Vault 未注入 | Daemon 未运行或主机未配置 | 启动 `telclaude vault-daemon`；检查 `vault list` |

## 社区

- Issues 与讨论：开启 GitHub issues；我们每周进行分类。
- 变更日志：请参阅 `CHANGELOG.md`。

## 致谢

灵感来自 [@steipete](https://github.com/steipete) 的 [Clawdis](https://github.com/steipete/clawdis)。

## 免责声明

按原样提供，仅供授权使用。使用风险自负。

## 许可证

MIT

标签：AI 代理, API 密钥管理, ChatOps, Claude AI, DLL 劫持, Docker, GNU通用公共许可证, JSONLines, MITM代理, Node.js, Python, Streamlit, Telegram 机器人, 中间件, 双因素认证, 命令过滤, 大语言模型, 安全网关, 安全防御评估, 审批流, 审计日志, 开源, 敏感信息过滤, 无后门, 智能家居, 权限控制, 社交媒体集成, 网络安全, 网络安全, 网络调试, 自动化, 自动化攻击, 访问控制, 请求拦截, 隐私保护, 隐私保护, 隔离沙箱, 零信任