--- name: tlbox description: 用 tlbox 命令行管理用户自己的 tlbox 后台：看名下的号和在线状态、以号的身份发消息和文件、看聊天记录、加删提醒和定时任务、改人设、管监听和 webhook、看自己上报的日志。用户提到 tlbox、他的聊天机器人/号、让号去群里发消息、设提醒、改人设时使用。 --- # tlbox tlbox 把 AI 助手接进用户的聊天工具（个人微信、微信ClawBot、飞书、Slack 等），每个接进来的账号叫一个"号"。 `tlbox` 命令行带着用户在后台生成的 API token，替用户做后台里能做的事。它只是后台接口的一层壳： 能做什么、不能做什么，以服务端的回复为准。 ## 准备 ```bash uv tool install https://tlbox-api.someget.xyz/agent/tlbox_cli-0.1.0-py3-none-any.whl # 或 pipx install 同一个地址 export TLBOX_TOKEN=tlb_... # 必填：后台"Agent 接入"页生成，只显示一次 export TLBOX_BOT=wxid_xxx # 可选：默认操作的号，省得每条命令都写 --bot export TLBOX_SERVER=https://tlbox-api.someget.xyz # 可选，默认就是这个 ``` 没有 `TLBOX_TOKEN` 时让用户去后台"Agent 接入"页生成，不要猜、不要自己编。 版本号以后台"Agent 接入"页给的安装命令为准；地址写错时 server 会回 404，并列出现在有的版本。 ## 约定（先读） - **先用 `--json`**：每个命令都认 `--json`，输出服务端返回的原始 `data`，解析它，别解析表格。 - **号**：大多数命令要指定号：`--bot <号>`，或者设了 `TLBOX_BOT`。不知道有哪些号就先 `tlbox bots list --json`， 里面的 `bot_id` 就是号，`platform` 是渠道，`capabilities` 里有 `listen` 的才有监听、微信程序管理和发消息功能。 - **接收者**：提醒、定时任务、webhook 里的"发给谁"（`--to`）写**接收者 ID**：从 `tlbox chats --bot <号> --json` 的 `chat_id` 取（不是 `chat_name`），或者 `tlbox receivers --bot <号> --json` 的 `uid`（不是 `name`）。个人微信（`platform` 是 `wechat`）的 ID 就是群名/好友昵称，可以直接写，没聊过的群也行。例子： - 个人微信：`--to "产品群"`、`--to "小明"` - 微信ClawBot（`weixin`）：`--to "o9cq8xxxx@im.wechat"`，只能发给给它发过消息的人 - 飞书（`lark`）：群 `--to "oc_xxxx"`，用户 `--to "ou_xxxx"` - Slack（`slack`）：频道 `--to "C0123ABCD"`，用户 `--to "U0123ABCD"` - **时间**：一律是带时区的 ISO-8601，如 `2026-10-12T09:00:00+08:00`；不带时区会被拒绝。用户说"明早 9 点"时，按用户所在时区换算。 - **危险操作要 `--yes`**：删提醒、删定时任务、删 webhook、删人设、退出/重启微信。不带 `--yes` 只打印将要做什么，退出码 2，什么都不做。 **先问用户确认，用户同意了再带 `--yes` 重跑**，不要自己直接加。 - **退出码**：0 成功；1 出错（服务端的原因或参数不对）；2 危险操作没带 `--yes`。 - **出错**：错误原因原样打在 stderr（中文），带 `--json` 时是 `{"code", "message", "data"}` （参数不对、本地文件读写不了这类不用问服务端的错误 `code` 是 null；没带 `--yes` 的预览 `data.reason` 是 `confirm`）。 直接把 `message` 转述给用户，不要重试同一个会失败的请求。常见的： - `code` 103 且 `data.reason` 是 `login`：token 无效或被删了，让用户到后台重新生成。 - `code` 103 且 `data.reason` 是 `forbidden`：这件事 token 不能做（管理 token、管理员功能），让用户登录后台自己操作。 - `code` 103 且 `data.reason` 是 `invite`：账号还没开通。 - "未登记的机器人"：号写错了，或者不是用户名下的号。 - "客户端没有连着""机器人没有回应"：个人微信的电脑客户端离线，让用户检查那台电脑。 - **token 一律是普通用户权限**：就算用户是管理员，token 也只能管他自己名下的号，调不了管理员功能（账号、模型、全局技能、 平台日志、发版），也不能生成、删除 API token。这些都让用户登录后台自己做。 ## 命令 ### 看号和状态 ```bash tlbox bots list --json # 名下所有号：bot_id、name、platform、status.online、today_messages、listen_count tlbox bots show --bot wxid_xxx --json # 一个号的详情 ``` ### 发消息、看聊天记录 ```bash tlbox send text --bot wxid_xxx --to "产品群" "今天下午 3 点开会" tlbox send text --bot wxid_xxx --to "产品群" --at "小明" --at "小红" "请看一下" echo "多行内容" | tlbox send text --bot wxid_xxx --to "小明" - # - 表示从标准输入读 tlbox send file --bot wxid_xxx --to "产品群" ./周报.pdf # 100MB 以内，--name 改对方看到的文件名 tlbox chats --bot wxid_xxx --json # 聊过的会话：chat_id、chat_name、count、last_at tlbox receivers --bot wxid_xxx --json # 能当接收者的群和人：uid（--to 写它）、name、kind、is_admin tlbox messages --bot wxid_xxx --chat "产品群" --json # 最近 40 条（--limit 最多 200） tlbox messages --bot wxid_xxx --chat "产品群" --keyword 周报 --json tlbox messages --bot wxid_xxx --chat "产品群" --before 1234 --json # 往前翻：用上一页的 next_tail_id ``` 发消息目前只有个人微信的号能用（`capabilities` 里有 `listen`）。`messages` 的 `--chat` 用 `chats` 里的 `chat_id`。 ### 提醒（到点由号发一条消息） ```bash tlbox reminders list --bot wxid_xxx --json # jobs：job_id、next_run_time、receiver、content、at_user tlbox reminders add --bot wxid_xxx --to "产品群" --time 2026-10-12T09:00:00+08:00 "记得交周报" tlbox reminders add --bot wxid_xxx --to "产品群" --at "小明" --time 2026-10-12T09:00:00+08:00 "该你值班了" tlbox reminders add --bot lark-cli_a1b2c3 --to oc_xxxx --time 2026-10-12T09:00:00+08:00 "记得交周报" # 飞书群：用 chat_id tlbox reminders add --bot 1a2b3c@im.bot --to o9cq8xxxx@im.wechat --time 2026-10-12T09:00:00+08:00 "喝水" # 微信ClawBot tlbox reminders rm --bot wxid_xxx reminder_产品群_1760000000 # 先问用户，同意后加 --yes ``` ### 定时任务（按时跑内置任务，比如早报） ```bash tlbox tasks options --json # jobs：可选的任务名；timezones：可选时区 tlbox tasks list --bot wxid_xxx --json # tasks：task_id、job_name、receivers、schedule、next_run_time tlbox tasks add --bot wxid_xxx --job <任务名> --to "产品群" --to "小明" --daily 08:30 # 每天，默认北京时间 tlbox tasks add --bot wxid_xxx --job <任务名> --to "产品群" --daily 08:30 --timezone America/Chicago tlbox tasks add --bot wxid_xxx --job <任务名> --to "产品群" --once 2026-10-12T09:00:00+08:00 # 只跑一次 tlbox tasks run --bot wxid_xxx task_xxx # 马上跑一次 tlbox tasks rm --bot wxid_xxx task_xxx # 先问用户，同意后加 --yes ``` 任务名只能从 `tasks options` 里选；有的任务不需要 `--to`。 ### 人设（号回复时用的 prompt 和语音风格） 三层，越具体越优先：号里某个群或人（`--chat`）→ 这个号的默认 → 名下所有号共用（`--all-bots`）。 ```bash tlbox persona get --bot wxid_xxx --json # personas 里每条：bot_id（"*" 表示名下所有号共用）、chat（空表示默认）、prompt、voice_style tlbox persona set --bot wxid_xxx --prompt "你是{name}，说话简短" # {name} 会换成号的昵称 tlbox persona set --bot wxid_xxx --chat "产品群" --prompt "这个群里只说正事" tlbox persona set --bot wxid_xxx --all-bots --prompt "..." # 改名下所有号共用的那份 tlbox persona set --bot wxid_xxx --voice-style "温柔" # 只改一项，另一项保持原样 tlbox persona rm --bot wxid_xxx --chat "产品群" # 删掉后回到上一层；先问用户，同意后加 --yes ``` 改人设会影响号以后的所有回复，改之前把新旧内容给用户看一眼。 ### 监听（只有个人微信：哪些群和人的消息交给 AI） ```bash tlbox listen list --bot wxid_xxx --json # listeners：chat、status（healthy / unhealthy）、reason tlbox listen add --bot wxid_xxx "产品群" tlbox listen rm --bot wxid_xxx "产品群" ``` ### 个人微信：电脑上的微信程序 ```bash tlbox wechat status --bot wxid_xxx --json # online、state、listening、wechat_version tlbox wechat launch --bot wxid_xxx # 打开微信 tlbox wechat relisten --bot wxid_xxx # 重新开始监听 tlbox wechat restart --bot wxid_xxx # 号会暂时掉线；先问用户，同意后加 --yes tlbox wechat quit --bot wxid_xxx # 号会掉线、要用户扫码才能重新登录；先问用户，同意后加 --yes ``` ### webhook（往一个地址 POST 文字，由号发给指定的群或人） ```bash tlbox webhooks list --json tlbox webhooks add --bot wxid_xxx --to "运维群" --name "部署通知" --json # 回的 url 只显示这一次，交给用户保存 tlbox webhooks add --bot slack-t0123-a0456 --to C0123ABCD --name "部署通知" --json # Slack 频道：用 chat_id tlbox webhooks rm h1a2b3c4d5e6 # 先问用户，同意后加 --yes ``` 用法：`curl -X POST '' -H 'Content-Type: application/json' -d '{"text": "部署成功"}'`。 ### 日志（用户自己从客户端上报的） ```bash tlbox logs list --json # uploads：id、created_at、bot_id、size tlbox logs get --tail 200 # 打印最后 200 行 tlbox logs get -o client.log.gz # 原样存下来 ``` ## 不能做的 - 生成、删除 API token；管理员功能（账号、模型、全局技能、平台日志、发版）：管理员的 token 也不行，让用户登录后台。 - 删号、接入新渠道（扫码、填应用凭据）：要用户本人在后台操作。 - 命令里没有的事别自己拼接口调，告诉用户去后台做。