# claude-to-msg

**Repository Path**: yan_zhaoxin/claude-to-msg

## Basic Information

- **Project Name**: claude-to-msg
- **Description**: 通过 Telegram 远程控制 Claude Code 的机器人
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-04
- **Last Updated**: 2026-03-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ClaudeMsg - 多项目 Claude Telegram Bot

> 通过 Telegram 在手机上远程操作多个项目的 Claude Code

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node](https://img.shields.io/badge/Node-%3E=18.0.0-green.svg)](https://nodejs.org)

## ✨ 核心功能

- **多项目管理** - 同时管理多个项目，每个项目独立运行
- **Session 隔离** - 每个项目有独立的 Claude 上下文和对话记忆
- **简单启动** - `claudemsg start` 一键启动项目实例
- **手机操作** - 通过 Telegram 随时随地与项目对话
- **灵活切换** - `/project_<id>` 快速切换项目
- **多 API 支持** - 支持 Claude、GLM（智谱）、DashScope（通义）等

## 🚀 快速开始

### 1. 安装

```bash
git clone https://github.com/yourusername/claudemsg.git
cd claudemsg
npm run setup
```

### 2. 启动 Bot Server

```bash
claudemsg bot
```

首次运行会提示输入：
- **Telegram Bot Token** - 从 [@BotFather](https://t.me/BotFather) 获取
- **允许的用户 ID** - 留空表示允许所有人

配置会自动保存到 `~/.claudemsg/settings.json`

### 3. 启动项目实例

```bash
cd 你的项目目录
claudemsg start --name "我的项目"
```

首次使用建议先初始化配置文件：

```bash
claudemsg start --init    # 创建 .claudemsg/settings.json 模板
# 编辑配置文件设置 API Key
claudemsg start --name "我的项目"
```

### 4. 手机使用

在 Telegram 中：

```
/nowProject              # 查看所有项目
/project_<id>            # 切换项目
发送命令                 # 开始工作！
```

## 📖 使用示例

### 多项目管理

```bash
# 终端 1: 启动 Bot Server
claudemsg bot

# 终端 2: 启动项目 1
cd ~/projects/ecommerce
claudemsg start --id shop --name "电商后台"

# 终端 3: 启动项目 2
cd ~/projects/blog
claudemsg start --id blog --name "个人博客"

# 手机 Telegram:
/nowProject              # 查看所有项目
/project_shop            # 切换到电商项目
创建用户注册接口          # 在电商项目工作
/project_blog            # 切换到博客项目
添加评论功能             # 在博客项目工作
```

### Telegram 对话

```
你: /nowProject

Bot: 📋 运行中的项目:

• [shop] 电商后台
  📂 ~/projects/ecommerce
  ⏰ 刚刚
  💬 /project_shop <命令>

• [blog] 个人博客
  📂 ~/projects/blog
  ⏰ 2 分钟前
  💬 /project_blog <命令>

你: /project_shop
Bot: ✅ 已切换到项目: 电商后台

你: 帮我写一个用户注册接口
Bot: [Claude 生成的代码...]

你: 优化成使用 TypeScript
Bot: [Claude 优化后的代码...]  # 记得之前的上下文！
```

## 🏗️ 系统架构

```
┌─────────────────────────────────────────────────────────┐
│                  Bot Server (单例)                       │
│  • 管理 Telegram Bot                                     │
│  • 维护项目注册表 (SQLite)                                │
│  • 路由消息到对应项目                                     │
└─────────────────────────────────────────────────────────┘
                          ↓ HTTP
┌─────────────────────────────────────────────────────────┐
│                  项目实例 (多个)                         │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
│  │ proj001      │  │ proj002      │  │ proj003      │  │
│  │ 电商后台     │  │ 个人博客     │  │ 工具脚本     │  │
│  │              │  │              │  │              │  │
│  │ • 独立 port  │  │ • 独立 port  │  │ • 独立 port  │  │
│  │ • 独立 session│  │ • 独立 session│  │ • 独立 session│  │
│  └──────────────┘  └──────────────┘  └──────────────┘  │
└─────────────────────────────────────────────────────────┘
```

## 📋 命令说明

### CLI 命令

```bash
# 启动 Bot Server
claudemsg bot

# 启动项目实例
claudemsg start [options]
```

**start 命令选项:**

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `--id <id>` | 项目 ID | `proj_<timestamp>` |
| `--name <name>` | 项目名称 | 当前目录名 |
| `--port <port>` | 监听端口 | 自动分配 |
| `--bot-server <url>` | Bot Server 地址 | `http://localhost:4000` |
| `--init` | 初始化配置文件 | - |

### Telegram 命令

| 命令 | 说明 |
|------|------|
| `/nowProject` | 列出所有运行中的项目 |
| `/project_<id>` | 切换到指定项目 |
| `/help` | 显示帮助信息 |
| `/start` | 显示欢迎信息 |

## ⚙️ 配置指南

### 配置文件位置

| 文件 | 用途 | 优先级 |
|------|------|--------|
| `~/.claudemsg/settings.json` | 全局配置（Bot Token、用户ID等） | 低 |
| `./.claudemsg/settings.json` | 项目配置（API Key、模型等） | 高 |

### 配置优先级

1. CLI 参数（最高）
2. 项目目录 `.claudemsg/settings.json`
3. 全局 `~/.claudemsg/settings.json`
4. 环境变量（回退，不推荐）

### 最简配置

在项目目录创建 `.claudemsg/settings.json`：

```json
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "your_api_key_here"
  }
}
```

### 完整配置示例

```json
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "your_api_key_here",
    "ANTHROPIC_BASE_URL": "",
    "API_TIMEOUT_MS": 120000,
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": false
  },
  "model": {
    "name": "claude-sonnet-4-6",
    "allowedTools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebSearch", "WebFetch", "Task", "Skill"]
  },
  "server": {
    "telegramBotToken": "",
    "allowedUserIds": ""
  },
  "sandbox": {
    "enabled": true,
    "restrictToProject": true,
    "denyRead": [],
    "denyWrite": [],
    "allowRead": []
  }
}
```

### 多 API 提供商配置

#### Claude 官方 API

```json
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "sk-ant-xxx"
  },
  "model": {
    "name": "claude-sonnet-4-6"
  }
}
```

#### GLM（智谱）

```json
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "your_glm_key",
    "ANTHROPIC_BASE_URL": "https://open.bigmodel.cn/api/anthropic"
  },
  "model": {
    "name": "glm-4"
  }
}
```

#### DashScope（通义）

```json
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "your_dashscope_key",
    "ANTHROPIC_BASE_URL": "https://coding.dashscope.aliyuncs.com/apps/anthropic"
  },
  "model": {
    "name": "qwen3.5-plus"
  }
}
```

### 获取 Telegram Bot Token

1. 在 Telegram 中搜索 [@BotFather](https://t.me/BotFather)
2. 发送 `/newbot` 创建新机器人
3. 复制获得的 API Token

### 获取 User ID

向以下任一 Bot 发送任意消息：
- [@userinfobot](https://t.me/userinfobot)
- [@RawDataBot](https://t.me/RawDataBot)

## 🔧 常见问题

### Q: 项目显示不在线？

```bash
curl http://localhost:4000/health
curl http://localhost:3000/health
```

### Q: 如何停止项目？

在运行 `claudemsg` 的终端按 `Ctrl+C`

### Q: 端口冲突？

```bash
claudemsg start --port 3001
```

### Q: Claude 不记得之前的对话？

1. 检查是否使用同一个项目 ID
2. 确认项目实例还在运行
3. 查看用户状态是否正确

### Q: 如何卸载？

```bash
npm unlink -g claudemsg
rm -rf /path/to/claudemsg
rm -rf ~/.claudemsg
```

## 🛠️ 技术栈

- **Claude SDK**: `@anthropic-ai/claude-agent-sdk` - Claude 官方 SDK
- **Telegram**: `node-telegram-bot-api` - Telegram Bot API
- **HTTP**: `express` - Web 服务器
- **数据库**: `better-sqlite3` - SQLite 数据库
- **语言**: TypeScript

## 📦 项目结构

```
claudemsg/
├── bin/
│   └── claudemsg.cjs            # CLI 命令入口
├── src/
│   ├── cli.ts                   # CLI 入口
│   ├── commands/
│   │   ├── bot.ts               # bot 子命令
│   │   └── start.ts             # start 子命令
│   ├── bot-server/
│   │   ├── index.ts             # Bot Server 主程序
│   │   └── db.ts                # 数据库管理
│   ├── project-instance/
│   │   ├── index.ts             # 项目实例类
│   │   └── main.ts              # 入口文件
│   └── shared/
│       ├── config.ts            # 配置管理
│       └── port-utils.ts        # 端口工具
├── settings.json.example        # 完整配置模板
├── settings.json.minimal.example # 最简配置模板
└── package.json
```

## 🚀 部署

### 使用 PM2

```bash
npm install -g pm2
pm2 start dist/bot-server/index.js --name claudemsg-bot
pm2 save
pm2 startup
```

## 📚 文档

- [快速开始](docs/QUICKSTART.md) - 3 分钟上手指南
- [贡献指南](docs/CONTRIBUTING.md) - 如何参与开发
- [更新日志](docs/CHANGELOG.md) - 版本历史

## 📄 许可证

MIT License - 详见 [LICENSE](LICENSE)

## 🙏 致谢

- [Claude Code](https://claude.ai/code) - Anthropic 的 AI 编程助手
- [node-telegram-bot-api](https://github.com/yagop/node-telegram-bot-api) - Telegram Bot API 库
- [nanoclawd](https://github.com/nicholasxuu/nanoclawd) - 灵感来源

---

**Made with ❤️ for developers who love coding on the go**