15 分钟部署你自己的 Telegram AI 机器人

手把手教程：安装 FastClaw、接入模型供应商、为 Agent 设定人设、绑定 Telegram 机器人并与你的账号配对 —— 不需要公网地址，也不需要 Webhook。

FastClaw Team·2026年10月13日

想让真实用户用上你的 AI Agent，Telegram 是最简单的地方：机器人免费、一分钟就能创建、没有应用审核。难的是机器人背后的那一切 —— 记忆、工具、安全执行命令的环境，以及让每个聊天的历史互不干扰。

本教程带你在 FastClaw 上运行自己的 Telegram AI 机器人：从一台空机器开始，到一个已配对、能记住人、会用工具的机器人。你需要一台电脑（macOS、Linux 或 Windows）、一个模型供应商的 API Key，以及一个 Telegram 账号。

最终效果

一个拥有独立人设、记忆和技能的 FastClaw Agent。
一个接入该 Agent 的 Telegram 机器人，每个私聊和群组各自保留历史。
所有者配对：只有你的 Telegram 账号拥有所有者权限。
同一个 Agent 也能在网页控制台中使用，并通过 OpenAI 兼容 API 调用。

第 1 步：安装 FastClaw

FastClaw 是一个单二进制程序。在 macOS 或 Linux 上执行：

curl -fsSL https://raw.githubusercontent.com/fastclaw-ai/fastclaw/main/install.sh | bash

脚本会把 fastclaw 放到 ~/.local/bin 并加入 PATH。Windows 用户请改用 README 里的 PowerShell 安装命令。

第 2 步：首次运行并配置模型

在前台启动：

fastclaw

首次运行会打开设置向导。选择一个模型供应商 —— OpenAI、Anthropic、DeepSeek、OpenRouter、Ollama 或任意 OpenAI 兼容接口 —— 粘贴 Key，向导会帮你创建第一个 Agent。如果希望数据完全不出本机，也可以用 Ollama 跑本地模型。

向导完成后，打开 http://localhost:18953 登录控制台。

关闭终端后仍想保持运行：

fastclaw daemon start      # 后台运行
fastclaw daemon install    # 或注册为 launchd / systemd 服务

更喜欢命令行？fastclaw agents init 一条命令就能创建 Agent 并启动网关：

fastclaw agents init tgbot \
  --provider openai \
  --model openai/gpt-4o-mini \
  --api-key-env OPENAI_API_KEY

第 3 步：给 Agent 一个人设

一个听起来像通用助手的机器人很难让人记住。在控制台中打开 Agent，编辑它的文件：

SOUL.md —— Agent 是谁：语气、价值观、该做和不该做的事。
IDENTITY.md —— 名字和一句话自我介绍。
AGENTS.md —— 工作规则，比如在聊天中如何排版回复。

好的 Telegram SOUL.md 简短而具体。例如：用用户的语言回复；回答控制在几段以内；用列表代替表格（Telegram 对表格渲染很差）；拿不准时先提问，不要乱猜。

也可以用命令行上传：fastclaw agents files put tgbot SOUL.md ./SOUL.md。关于 Agent 文件的更多内容见 Agent。

第 4 步：在 Telegram 中创建机器人

在 Telegram 里打开与 @BotFather 的对话。
发送 /newbot，先取一个显示名称，再取一个以 bot 结尾的用户名。
BotFather 会回复一个 HTTP API Token。复制并妥善保管 —— 拿到它的人就能控制这个机器人。

可选但推荐：给 BotFather 发送 /setdescription 和 /setuserpic，让机器人看起来更完整。

第 5 步：把机器人绑定到 Agent

在控制台中打开你的 Agent，进入 渠道（Channels），选择 Telegram 并粘贴 Token。

FastClaw 在保存前会调用 Telegram 的 getMe 校验，填错或已吊销的 Token 会被立即拒绝，而不是变成一个默默不回话的机器人。它还会清除旧的 Webhook 并使用长轮询，这意味着你不需要公网地址、域名或开放端口。家里 Wi-Fi 下的笔记本也完全可以。

该渠道的更多细节见 Telegram 集成页。

第 6 步：与你的账号配对

接入机器人只能证明你掌握 Token，并不能证明哪个 Telegram 账号是你。所以刚接入的机器人会对所有人回复"尚未配对"的提示，不会把任何消息转给 Agent。

认领方法：

在控制台的渠道卡片上生成配对码，有效期 10 分钟。
在 Telegram 中与你的机器人私聊，发送控制台显示的命令，例如 /pair ABCD2345。
机器人回复 "Paired. This account is now the owner of this bot."，即配对成功。

配对只能在私聊中完成，群里无效；连续输错几次，当前配对码就会作废。如果要把机器人交给别人，在控制台解除配对，再用新账号重新配对即可。

配对之后，任何人都可以和机器人聊天，区别在于信任级别：你配对的账号是所有者，其他人都是访客，他们触发的命令会在沙箱中执行 —— 如果没有配置沙箱，则直接拒绝。

第 7 步：测试一下

在私聊里给机器人发条消息，然后试试：

告诉它一些关于你的事，过一会儿再问它 —— 记忆可以跨对话保留。
让它明天早上提醒你某件事。Agent 可以自己创建 cron 任务，你可以在 Agent 的定时任务页面查看或暂停。详见定时任务。
把它拉进一个群。在群里，机器人被 @ 时才会回复，群聊历史与你的私聊相互独立。

每个 Telegram 聊天 ID 都有自己的会话；同一个人在其他渠道上的会话也与 Telegram 分开。

面向陌生人时的安全措施

如果机器人要公开使用，请做好两件事：

开启沙箱。在设置 → 运行时中启用 Docker 或 E2B。访客的命令会在隔离容器中运行，Agent 的技能和工作区会自动同步进去。
彻底锁定。在自托管实例上设置 FASTCLAW_SANDBOX_ENFORCE=1，这样所有命令和文件操作都会被限制在沙箱内，所有者也不例外。

更进一步

从 ClawHub 或 GitHub 安装技能，给机器人新能力 —— 详见技能。
把同一个 Agent 绑定到 Discord、Slack、微信或 WhatsApp，详见渠道。
要给整个社区运营机器人？社区场景介绍了适合社区管理的配置方式。

按上面的方式自托管是免费的。如果你完全不想维护服务器，可以在定价页对比各种方案。