MateCode

MateCode 是一款 Claude Code 与 Telegram 的桥接工具，无需暴露公网 IP，通过纯 Polling 模式即可实现 Telegram 远程对话 Claude，还自带本地 SQLite 记忆系统，支持对话历史自动保存与召回，兼顾便捷性与隐私安全。

核心功能速览

1. Telegram 远程交互：直接在 Telegram 上与 Claude 对话，无需打开 Claude 客户端。
2. 本地长期记忆：基于 SQLite 构建记忆系统，对话历史自动保存，发送消息时智能召回相关上下文。
3. 便捷会话管理：支持清空、恢复、继续会话，灵活控制对话流程。
4. 代码优化展示：回复内容自动实现代码高亮与格式化，阅读体验更佳。
5. 安全无公网依赖：纯 Polling 模式（长轮询），仅向外发起连接，不接收入站请求，无需暴露公网，安全性更高。
6. 零外部 Python 依赖：基于 Python 标准库开发，无需额外安装第三方包，部署更简单。

前置准备

1. 运行环境：支持 macOS（文档默认）、Linux（兼容，步骤类似）；Python 3.8+（系统自带或手动安装）。
2. 必备工具：tmux（用于后台运行服务，避免终端关闭后进程终止）。
3. 关键凭证：Telegram Bot Token（从 @BotFather 获取）。
4. 前置软件：已安装 Claude Code（并配置完成，可正常使用）。

快速开始（macOS 优先，一步一步来）

步骤 1：安装必备工具 tmux

# Homebrew 安装 tmux（macOS 标配包管理器，未安装需先安装 Homebrew）
brew install tmux

步骤 2：获取并配置 Telegram Bot Token

1. 打开 Telegram，搜索 @BotFather，发送 /newbot 命令，按照提示创建一个新机器人。
2. 创建成功后，@BotFather 会返回一个 Bot Token（格式：123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11），复制该 Token 备用。
3. 配置环境变量（临时生效，若需永久生效，可添加到 ~/.zshrc 或 ~/.bashrc）：

   export TELEGRAM_BOT_TOKEN="你的 Bot Token"
   

步骤 3：启动 MateCode 服务

假设你已下载 MateCode 项目源码并进入项目根目录：

# 启动 MateCode 服务（后台运行，依赖 tmux）
./matecode.sh start

步骤 4：验证是否启动成功

1. 打开 Telegram，找到你刚创建的机器人，发送任意消息（如 hello）。
2. 若机器人能正常响应，或通过 ./matecode.sh status 查看状态为「运行中」，即表示启动成功。

提示：首次启动可能需要几秒初始化，耐心等待即可。

关键配置：Claude 钩子（实现 Claude 响应推送到 Telegram）

这一步是核心，用于将 Claude 的回复自动推送到 Telegram 机器人，完成双向桥接。

步骤 1：复制并配置钩子脚本

# 1. 复制钩子脚本到 Claude 钩子目录（若目录不存在，先创建：mkdir -p ~/.claude/hooks/）
cp hooks/send-to-telegram.sh ~/.claude/hooks/

# 2. 编辑钩子脚本，配置 Telegram Bot Token（替换为你的 Token）
nano ~/.claude/hooks/send-to-telegram.sh

# 3. 赋予脚本执行权限（必须，否则 Claude 无法调用）
chmod +x ~/.claude/hooks/send-to-telegram.sh

步骤 2：编辑 Claude 配置文件，添加钩子

1. 打开 Claude 配置文件 ~/.claude/settings.json（若不存在，先创建该文件）。
2. 添加 hooks 配置（确保 JSON 格式正确，无语法错误）：

   {
     "hooks": {
       "Stop": [
         {
           "hooks": [
             {
               "type": "command",
               "command": "~/.claude/hooks/send-to-telegram.sh"
             }
           ]
         }
       ]
     }
   }
   

3. 保存文件并退出，配置立即生效（Claude 会自动读取该配置）。

说明：Stop 钩子表示当 Claude 停止生成回复（即回复完成）时，触发该脚本，将回复内容推送到 Telegram。

核心操作指南

1. MateCode 服务管理命令（项目根目录执行）

# 查看所有可用命令
./matecode.sh

# 启动服务
./matecode.sh start

# 停止服务
./matecode.sh stop

# 重启服务
./matecode.sh restart

# 查看服务状态
./matecode.sh status

# 查看运行日志（排查故障必备）
./matecode.sh logs

2. Telegram 机器人命令（直接在 Telegram 发送给机器人）

3. 常用辅助命令（排查故障/手动操作）

# 进入 Claude 对应的 tmux 会话（查看实时运行日志）
tmux a -t claude

# 重新加载 tmux 配置文件
tmux source-file ~/.tmux.conf

# 跳过 Claude 权限检查（特殊场景使用，谨慎操作）
claude --dangerously-skip-permissions

# 终止 Claude 对应的 tmux 会话
tmux kill-session -t claude

# 关闭所有 MateCode 桥接相关进程（强制停止，无法正常停止时使用）
pkill -f "bridge\.py|bridge-polling\.py"

本地记忆功能详解（隐私优先，灵活配置）

MateCode 内置基于 SQLite FTS5 的本地记忆系统，所有数据均存储在 ~/.matecode/memory.db，不上传任何云端，保障隐私安全。

1. 核心特性

• 自动记忆：每次与 Claude 的对话都会自动保存到本地 SQLite 数据库。
• 智能召回：发送新消息时，会自动搜索记忆库中相关历史内容，注入到 Claude 上下文，实现长期对话连贯性。
• 手动管理：通过 /remember、/recall、/forget 命令灵活管理记忆。

2. 环境变量配置（自定义记忆行为）

# 启用/禁用记忆功能（默认启用，值为 false 则禁用）
export MEMORY_ENABLED=true

# 每次查询记忆库返回的最大结果数（默认 5 条）
export MEMORY_MAX_RESULTS=5

# 注入 Claude 上下文的记忆内容最大字符数（默认 2000，避免上下文过长）
export MEMORY_MAX_CONTEXT=2000

提示：若需永久生效，可将上述环境变量添加到 ~/.zshrc 或 ~/.bashrc，然后执行 source ~/.zshrc 生效。

技术细节与文件说明

1. 核心技术特点

• 纯 Python 标准库：无任何外部第三方依赖，无需 pip install，部署零门槛。
• 长轮询模式：30 秒超时机制，兼顾低延迟与低资源消耗，无需公网 IP 与端口映射。
• 实时响应：监控 Claude 生成的 transcript 文件，即时推送回复到 Telegram。
• 本地存储：记忆数据、对话历史均本地存储，无隐私泄露风险。

2. 项目文件用途（快速查阅）

常见问题排查小贴士

1. 机器人无响应：先执行 ./matecode.sh status 查看服务状态，再执行 ./matecode.sh logs 查看错误日志，重点检查 Bot Token 是否配置正确。
2. Claude 回复无法推送到 Telegram：检查钩子脚本权限（是否赋予 chmod +x）、settings.json 格式是否正确、脚本中的 Bot Token 是否配置无误。
3. 记忆功能失效：检查 ~/.matecode/memory.db 是否存在，环境变量 MEMORY_ENABLED 是否为 true，Python 是否支持 SQLite FTS5。
4. tmux 会话无法进入：检查 tmux 是否安装成功，执行 tmux ls 查看是否存在 claude 会话。