by 运行时依赖
安装命令
点击复制技能文档
OpenClaw Telegram Bot — 构建和部署技能 在 OpenClaw 上构建生产级的 Telegram 机器人，而不重复 20 个常见的错误。
何时使用此技能 创建新的 OpenClaw Telegram 机器人 调试图像/媒体传递问题 将 OpenClaw 机器人部署到 Docker 设置代理安全（防止提示注入） 为新机器人编写 AGENTS.md 解决“图像生成但未传递”的问题
快速诊断 如果图像未在 Telegram 中显示，请按以下顺序检查：
- MEDIA 格式是否正确？
- 路径是否在 /tmp 下？
- exec.backgroundMs 是否足够高？
- 用户代理是否具有 auth-profiles.json？
- 是否设置了 GEMINI_API_KEY（而不仅仅是 GOOGLE_GENAI_API_KEY）？
核心规则（不可商量） 规则 1：MEDIA 协议 OpenClaw 通过 MEDIA 协议将本地文件提供给 Telegram。格式严格。 MEDIA:/absolute/path.png # 本地文件 MEDIA:https://cdn.example.com/x # 远程 URL 永远不要使用：MEDIA:image/png:/path（无 MIME 类型） MEDIA:file:///path（无 file:// 前缀） 消息发送媒体（使用纯文本 MEDIA 行）
规则 2：仅 /tmp 用于媒体 OpenClaw 只允许 /tmp 作为媒体提供目录。 /workspaces/ 不在白名单中。 # 总是使用 /tmp 作为生成输出 def get_output_dir(): output = Path("/tmp/your-bot-output") / datetime.now().strftime("%Y-%m-%d") output.mkdir(parents=True, exist_ok=True) return output 陷阱：/tmp 在容器重启时会被清除。如果需要持久性，请在提供服务后将其复制到卷中。
规则 3：在脚本中硬编码关键路径 LLM 代理（Gemini）即兴 CLI 参数。它可能使用 --output output/，即使 AGENTS.md 说 /tmp/your-bot/。永远不要相信代理以获取安全关键路径。 # 坏的 - 信任代理输入 def get_output_dir(base=None): return Path(base or "output") # 好的 - 忽略代理，总是正确 def get_output_dir(base=None): return Path("/tmp/your-bot-output")
规则 4：AGENTS.md 示例 = 代理行为 AGENTS.md 中的示例是最强的行为信号。代理几乎逐字复制它们。审计每个示例以确保其正确性。 MEDIA:/tmp/your-bot/2026-03-06/img_01.png 如果您的示例显示错误路径，代理将使用该错误路径。
规则 5：AGENTS.md 被缓存 代理在会话开始时读取 AGENTS.md 并缓存它。在运行的容器中编辑该文件直到用户发送 /new 以开始新会话之前无效。 含义：不要通过在生产环境中热修复 AGENTS.md 来进行调试。请在本地修复，重新构建，然后重新部署。
Docker 部署检查清单 在将 OpenClaw 机器人部署到 Docker 时，请验证以下所有内容： 环境变量 docker run -d --name your-bot \ -e TELEGRAM_BOT_TOKEN=... \ -e GEMINI_API_KEY=... # OpenClaw 读取此名称 -e GOOGLE_GENAI_API_KEY=... # 您的 Python 脚本可能读取此内容 -e FAL_KEY=... \ -e OPENAI_API_KEY=... \ -v bot_workspaces:/workspaces \ your-bot 在 entrypoint.sh 中映射： export GEMINI_API_KEY="${GEMINI_API_KEY:-$GOOGLE_GENAI_API_KEY}" openclaw.json 设置 { "exec": { "backgroundMs": 120000 }, "session": { "dmScope": "per-channel-peer" }, "channels": { "telegram": { "dmPolicy": "open" } } } backgroundMs：120000 — AI 图像生成需要 20-45 秒，默认 10 秒会杀死进程 dmScope：per-channel-peer — 每个 Telegram 用户都有隔离的会话 dmPolicy：open — 公共机器人，任何人都可以发送消息
多租户警告： OpenClaw 官方声明它不是一个敌对的多租户安全边界。 对于公共机器人：tools.fs.workspaceOnly：true 阻止文件系统工具，但不阻止 exec（shell 命令） sandbox.mode：“all” 和 scope：“agent” 为每个用户提供完整的 Docker 隔离（资源密集） 对于真正的对抗隔离：每个信任边界使用单独的网关
在 Docker 中启用 sandbox.mode：“all”（确认方法）： 如果您的 OpenClaw 机器人在 Docker 容器中运行，sandbox 需要 Docker-in-Docker。官方方法是挂载主机 Docker 套接字 —— 不是 Sysbox，也不是 --privileged： # docker run：添加两行 docker run -d --name your-bot \ -v /var/run/docker.sock:/var/run/docker.sock \ # ← 挂载主机 Docker 套接字 -e OPENCLAW_SANDBOX=1 \ # ← 告诉 OpenClaw 启用 sandbox -e TELEGRAM_BOT_TOKEN=... \ ... # Dockerfile：在容器中安装 Docker CLI RUN apt-get install -y docker.io // openclaw.json：每个代理的 sandbox 配置 { "agents": { "defaults": { "sandbox": { "mode": "all", "scope": "agent", "workspace"