agent 卡在 bootstrapping 状态说明初始化阻塞于依赖加载或配置校验。需依次检查服务状态与日志、验证模型 api 配置、重置 agent 运行时环境、排查 macos imessage 权限，并可选用阿里云 moltbot 镜像绕过本地初始化。
如果您启动 Clawdbot 后，终端或日志中持续显示 Agent 一直处于 bootstrapping 状态，而 Gateway 正常运行、Telegram 通道连接正常但无 token 消耗，则说明 Agent 初始化流程卡在依赖加载或配置校验环节。以下是解决此问题的步骤：
一、检查基础服务状态与日志输出
该步骤用于确认当前运行状态是否真实异常，排除假性卡顿或日志延迟干扰。Clawdbot 的 bootstrapping 阶段包含模型加载、通道握手、权限验证等异步操作，部分环节需等待外部响应，因此需结合实时日志交叉判断。
1、执行全状态检查命令，观察各组件实际运行态：
clawdbot status --all
2、实时追踪网关错误日志，聚焦初始化失败源头：
clawdbot logs --follow --tail 100
3、若日志中反复出现 TypeError: fetch failed 或 401 invalid api key，说明模型认证环节中断；若出现 404 page not found，则指向 API endpoint 配置错误。
二、验证并修复模型 API 配置
Agent 初始化失败最常见原因是模型提供商配置不合法，导致无法完成首次 handshake。Clawdbot 在 bootstrapping 阶段会主动调用模型 provider 的健康检查接口，任一失败即阻塞后续流程。
1、查看当前模型配置内容：
cat ~/.clawdbot/clawdbot.json | jq '.models.providers'
2、针对 MiniMax 用户：确认 baseUrl 是否为 https://api.minimax.chat（非 .io 域名），且 endpoint 路径是否为 /v1/text/chatcompletion_v2 或 /anthropic/v1/messages；原始配置中误写为 https://api.minimax.io/anthropic 将直接触发 404。
3、针对 OpenAI 用户：确认 apiKey 是否已通过 clawdbot models auth paste-token --provider openai 正确注入，且未被空格或换行符污染。
4、执行模型状态验证：
clawdbot models status
三、重置并重建 Agent 运行时环境
当配置修复后仍卡在 bootstrapping，说明本地 Agent 运行时缓存或 session 文件存在状态不一致。Clawdbot 的 Agent 使用持久化 session 日志（.jsonl 格式）记录初始化进度，损坏文件会导致状态机停滞。
1、定位并清除当前 Agent 的 session 日志目录：
rm -rf ~/.clawdbot/agents/main/sessions/*
2、停止所有后台服务：
clawdbot gateway stop && clawdbot agent stop
3、强制重启 Agent 并启用调试模式输出详细流程：
clawdbot agent start --debug
4、观察控制台输出是否出现 bootstrapping → ready 状态跃迁；若仍停滞，检查输出中首个失败模块名称（如 “model-loader” 或 “channel-imessage”）。
四、排查 iMessage 通道权限缺失（仅 macOS 用户）
即使 Gateway 启动成功，iMessage 通道若未获系统级权限，Agent 在初始化阶段尝试读取 chat.db 时将静默失败，并持续重试导致 bootstrapping 卡死。该问题特征为日志中无显式报错，但 imsg 命令在终端可正常执行。
1、打开「系统设置」→「隐私与安全性」→「完全磁盘访问权限」
2、点击右下角「+」号，添加 Node.js 二进制路径（例如：/usr/local/opt/node@22/bin/node）
3、同时确保「自动化」权限中已勾选「终端」对「信息」的控制权限
4、重启 Gateway：
clawdbot gateway restart
5、手动验证权限是否生效：
imsg chats --limit 1
五、切换至镜像免配置模式绕过本地初始化
当上述方法均无法快速恢复时，可采用阿里云官方提供的 Moltbot（Clawdbot）轻量应用服务器镜像方案。该镜像预置完整运行时、Qwen3-32B 模型及钉钉/iMessage 通道驱动，彻底跳过本地 bootstrapping 流程，实现开箱即用。
1、登录阿里云控制台，进入「轻量应用服务器」市场页
2、搜索并选择 Moltbot 官方镜像（2026-Q1 版本）
3、创建实例后，通过浏览器访问 http://[服务器IP]:8080，直接进入 Chat UI
4、在界面中绑定钉钉或配置 iMessage 推送地址，无需执行 clawdbot onboard 或任何 CLI 初始化命令
