cc-im

cc-im

多平台（飞书 & Telegram）机器人 ↔ Claude Code CLI 桥接服务。

用户在飞书或 Telegram 中发消息，服务器接收后调用 Claude Code 执行，并将输出实时流式推送回聊天窗口。

功能

• 多平台支持：飞书和 Telegram，可同时运行或单独使用
• 流式输出：飞书端使用 CardKit 打字机效果，Telegram 端通过 editMessage 实时更新
• 会话管理：每用户独立 session，支持 /new 重置
• 并发控制：同会话串行执行，不同会话可并发，最多排队 3 条消息
• 长消息分片：超长内容自动拆分为多条消息
• 权限确认：通过 Hook 机制实现工具调用的交互式审批
• 白名单：通过环境变量或配置文件控制访问
• 停止按钮：执行过程中可随时停止

快速开始

同时运行多个平台

可以同时启用飞书和 Telegram，只需配置两个平台的凭证即可：

export FEISHU_APP_ID=your_app_id
export FEISHU_APP_SECRET=your_app_secret
export TELEGRAM_BOT_TOKEN=your_bot_token
npx cc-im

服务会自动检测已配置的平台并启动对应的 bot。

Telegram 平台

• 通过 @BotFather 创建 Bot，获取 Token
• 配置并启动：

# 方式一：环境变量
export TELEGRAM_BOT_TOKEN=your_bot_token
npx cc-im

# 方式二：从源码运行
pnpm install
cp .env.example .env
# 编辑 .env，填入 TELEGRAM_BOT_TOKEN
pnpm dev

• 在 Telegram 中找到你的 Bot，发送 /start 开始使用

飞书平台

• 在飞书开放平台创建应用
• 开启机器人能力
• 添加权限：im:message、im:message:send_as_bot、im:message:patch_as_bot、cardkit:card
• 事件订阅中启用 长连接模式，订阅以下事件：
  • im.message.receive_v1 — 接收消息
  • card.action.trigger — 卡片交互（停止按钮）
• 发布应用
• 配置并启动：

export FEISHU_APP_ID=your_app_id
export FEISHU_APP_SECRET=your_app_secret
npx cc-im

从源码构建

git clone <repo-url>
cd cc-im
pnpm install
cp .env.example .env
# 编辑 .env 填入对应平台凭证

pnpm dev      # 开发模式
pnpm build    # 编译
pnpm start    # 生产模式

命令列表

命令	说明
/start	显示欢迎信息（Telegram）
/help	显示帮助信息
/new	开始新会话
/cd <path>	切换工作目录（同时重置会话）
/pwd	查看当前工作目录
/list	列出所有项目的工作区
/cost	查看 Claude API 用量和费用
/status	查看当前会话状态
/model [name]	查看或切换模型
/doctor	运行 Claude 诊断
/compact [topic]	压缩当前对话上下文
/todos	查看待办事项

权限相关命令

当 CLAUDE_SKIP_PERMISSIONS=false（默认）时，Claude Code 执行敏感操作（如 Bash 命令、写文件）会弹出权限确认卡片：

命令	说明
/allow 或 /y	允许当前待确认的操作
/deny 或 /n	拒绝当前待确认的操作
/allowall	允许所有待确认的操作
/pending	查看当前待确认的操作列表

环境变量

变量	说明	默认值
PLATFORM	平台选择（telegram 或 feishu），留空自动检测	自动检测
FEISHU_APP_ID	飞书应用 App ID	飞书平台必填
FEISHU_APP_SECRET	飞书应用 App Secret	飞书平台必填
TELEGRAM_BOT_TOKEN	Telegram Bot Token	Telegram 平台必填
ALLOWED_USER_IDS	白名单用户 ID，逗号分隔，留空不限制	空（不限制）
CLAUDE_CLI_PATH	Claude CLI 可执行文件路径	claude
CLAUDE_WORK_DIR	默认工作目录	当前目录
ALLOWED_BASE_DIRS	允许 /cd 切换的基础目录，逗号分隔	同 CLAUDE_WORK_DIR
CLAUDE_SKIP_PERMISSIONS	跳过权限检查（生产环境建议 false）	false
CLAUDE_TIMEOUT_MS	执行超时（毫秒）	300000（5分钟）
HOOK_SERVER_PORT	权限确认 Hook 服务端口	18900
LOG_DIR	日志文件存储目录	~/.cc-im/logs

白名单用户 ID 格式

• 飞书：open_id 格式，如 ou_xxxx
• Telegram：用户数字 ID，如 123456789（可通过 @userinfobot 获取）

配置文件

除环境变量外，也支持通过 ~/.cc-im/config.json 文件配置：

{
  "platform": "telegram",
  "telegramBotToken": "your_bot_token",
  "allowedUserIds": ["123456789"],
  "claudeCliPath": "/usr/local/bin/claude",
  "claudeWorkDir": "/home/user/projects",
  "allowedBaseDirs": ["/home/user/projects", "/tmp"],
  "claudeSkipPermissions": false,
  "claudeTimeoutMs": 300000,
  "logDir": "/var/log/cc-im"
}

环境变量优先级高于配置文件。

应用数据目录

默认数据目录：~/.cc-im（常量 APP_HOME）

~/.cc-im/
├── config.json          # 配置文件
├── data/
│   └── sessions.json    # 会话持久化数据
└── logs/                # 日志文件（可通过 LOG_DIR 自定义）
    ├── 2026-02-14.log
    └── 2026-02-15.log

权限确认机制

当 CLAUDE_SKIP_PERMISSIONS=false 时，系统会通过 PreToolUse Hook 拦截敏感操作：

• Claude Code 尝试调用工具（如执行 Bash 命令）
• Hook 脚本将请求发送到权限确认服务（端口由 HOOK_SERVER_PORT 指定）
• 服务向用户发送权限确认卡片/消息
• 用户回复 /allow 或 /deny
• 决定结果返回给 Claude Code，继续或中止操作

以下只读工具会自动放行，无需确认： Read、Glob、Grep、WebFetch、WebSearch、Task、TodoRead

项目结构

src/
├── index.ts                  # 入口，多平台并行初始化
├── config.ts                 # 配置加载（环境变量 + ~/.cc-im/config.json）
├── constants.ts              # 系统常量（节流、长度限制、错误码等）
├── logger.ts                 # 带标签的日志系统（自动脱敏）
├── sanitize.ts               # 日志脱敏规则
├── cli.ts                    # CLI 入口
├── access/
│   └── access-control.ts     # 白名单访问控制
├── claude/
│   ├── cli-runner.ts         # Claude CLI 子进程管理
│   ├── stream-parser.ts      # stream-json 格式解析
│   └── types.ts              # Claude 消息类型定义
├── commands/
│   └── handler.ts            # 平台无关的命令处理器
├── feishu/
│   ├── client.ts             # 飞书 SDK 初始化
│   ├── event-handler.ts      # 飞书事件处理
│   ├── message-sender.ts     # 飞书消息发送封装
│   ├── card-builder.ts       # 飞书卡片构建（JSON 1.0 + 2.0）
│   └── cardkit-manager.ts    # CardKit 卡片生命周期管理
├── telegram/
│   ├── client.ts             # Telegraf 初始化
│   ├── event-handler.ts      # Telegram 事件处理
│   └── message-sender.ts     # Telegram 消息发送
├── hook/
│   ├── permission-server.ts  # 权限确认 HTTP 服务
│   └── hook-script.ts        # Claude Code PreToolUse Hook
├── session/
│   └── session-manager.ts    # 会话管理（持久化到 data/sessions.json）
└── queue/
    └── request-queue.ts      # 请求队列与并发控制

License

MIT