SMC AI Agent版客户端（公测）

功能特性

• AI 对话迁移：通过自然语言对话完成迁移源导入、迁移任务创建、状态查询、故障排除。

• SMC API 操作：内置 SMC 迁移技能，调用 SMC API 管理迁移源与迁移任务。

• 定时任务：对指定迁移任务跟踪监控迁移进度状态。

• 钉钉频道：通过钉钉企业机器人在移动端/桌面端 7×24 小时管理迁移任务。

• Web 控制台：提供 Dashboard，支持通过图形化界面进行 AI 对话、会话管理、频道配置、定时任务、模型配置、日志查看。

• 命令行 TUI：提供命令行交互界面，直接与 AI 助手对话。

• 命令审批：基于工具命令白名单，对风险命令提供安全审批机制。

与传统 SMC 客户端区别

适用场景

• 服务器迁移：完成本机服务器或远程服务器的迁移上云。

• 迁移进度监控：为指定迁移任务设置定时任务，监控迁进度。

• 迁移故障排除：咨询迁移问题及故障排除。

• 钉钉远程管理：通过钉钉机器人查看迁移状态、管理迁移任务。

步骤一：准备环境

1. 准备服务器。

   • Linux：具备公网访问能力，可访问阿里云 SMC 服务和所选大模型 API。x86_64 架构，内核 5.10 及以上，Python 3.9 及以上。推荐 Alibaba Cloud Linux 3、Ubuntu 22.04、Rocky Linux 9 或更高版本。

   • Windows：具备公网访问能力，可访问阿里云 SMC 服务和所选大模型 API。x86_64 架构，Windows Server 2016 及以上。推荐 Windows Server 2016、Windows 10 或更高版本。

2. 阿里云账号：已开通服务器迁移中心 SMC 服务。SMC 服务本身免费，但迁移过程中使用的中转实例、云盘和网络流量等云资源可能产生费用。

3. 大模型 API Key：准备一个大模型API Key，推荐使用阿里云（千问云）Token Plan 方案 或 Coding Plan 方案。

步骤二：下载并安装

步骤三：客户端基本配置

1. 配置大模型。

   Setup命令一键配置（推荐）

   以阿里云（千问云）中国站 Token Plan，使用qwen/qwen3.7-plus为例，更多方案及模型请参考更多模型配置。

   任选一种方案配置即可，避免在同一次 setup 中传入多个模型 Key。

   参数	说明
   <AccessToken ID>	SMC 激活码的 AccessToken ID。 获取方式参见获取激活码。
   <AccessToken Code>	SMC 激活码的 AccessToken Code。 获取方式参见获取激活码。
   <API_KEY>	阿里云（千问云）中国站的API KEY获取方式，请参考获取 API Key。
   --model	指定具体模型，模型格式为 provider/model，例如 --model "qwen/qwen3.7-plus"。

   smcclaw setup --qwen-token-plan-api-key-cn "<API_KEY>" --model "qwen/qwen3.7-plus" --accesstokenid "<AccessToken ID>" --accesstokencode "<AccessToken Code>"

   重要

   激活码属于敏感凭证。直接在命令中输入可能被 Shell 历史记录保存，请按实际安全要求管理凭据。

   Onboard 界面交互配置

   以阿里云（千问云）中国站 Token Plan，使用qwen/qwen3.7-plus为例。

   1. 进入界面交互配置。

      <AccessToken ID>及<AccessToken Code>可通过获取激活码获取。

      smcclaw onboard --accesstokenid "<AccessToken ID>" --accesstokencode "<AccessToken Code>"

      重要

      激活码属于敏感凭证。直接在命令中输入可能被 Shell 历史记录保存，请按实际安全要求管理凭据。

   2. 依照以下参数配置。

      • Setup mode：OneClick

      • Model/auth provider：Qwen Cloud（若无，则选择More）

      • Qwen Cloud auth method：Token Plan API Key for China

      • Enter Alibaba Cloud Model Studio Token Plan API key (China)：输入Token Plan API Key。

      • Default model：选择模型，如qwen/qwen3.7-plus。

2. 执行smcclaw gateway status，running表示 Gateway 服务已启动。

步骤四：开启对话

Gateway 默认监听 127.0.0.1:18789，提供三种对话入口。

smcclaw tui

首次迁移服务器

支持三种服务器环境迁移场景：

• 本机直接迁移：直接迁移 SMCClaw 所在服务器。

• 远程 SSH 迁移：通过 SSH 连接远程服务器进行迁移。

• 远程辅助迁移：提供手动导入脚本命令，需您辅助执行后进行迁移。

参考指令示例：

帮我迁移本机到阿里云北京地域。
需要迁移另一台云主机，可以通过 SSH 连接。
有一台线下 Windows 需要迁移，没远程连接方式。

迁移交互流程：

1. 识别迁移意图：AI 解析对话意图，确认迁移目标。

   迁移源注册、迁移演练和数据同步会占用 CPU、磁盘和网络资源；缩盘迁移需根据文件系统、分区布局、实际数据量和迁移演练结果综合判断。生产环境请在业务低峰期执行并提前完成备份。

2. 配置激活码：首次执行迁移时，若本机未保存 SMC 激活码，客户端会询问 AccessToken ID 和 AccessToken Code，可获取激活码后通过对话提供。

3. 注册/导入迁移源：AI 完成源端信息采集后导入迁移源，成功后给出迁移源基础信息。

4. 迁移分析与费用估算：AI 根据源端信息和云资源价格进行迁移分析与费用估算并展示。

   估算结果仅供参考，实际费用以阿里云账单为准。

5. 创建/启动迁移任务：确认费用后，AI将创建并启动迁移任务，同时设置迁移进度自动监控的定时任务。任务默认开启迁移演练，先做一次迁移可行性测试并输出演练报告，演练通过后自动进入正式迁移。

6. 迁移进度监控：迁移过程中，自动监控定时任务定期在当前会话发起进度查询并给出报告。

7. 迁移完成：迁移任务完成后，AI 会自动取消进度监控定时任务，给出迁移总结报告，等待下一步指令。

定时任务

迁移开始时默认创建指定迁移任务的自动监控定时任务。也可通过对话创建自定义定时任务：

今晚 22:00 开始迁移任务 j-bp1xxx，完成后通知我。
每天 9:00 检查所有迁移源状态，异常时告警。

创建的定时任务可在 Dashboard 控制台查看。

常用管理命令

#列出所有定时任务
smcclaw cron list

#查看某个任务的详细信息
smcclaw cron get <jobId>

#立即手动执行一次某个任务
smcclaw cron run <jobId>

#查看某个任务的执行历史记录
smcclaw cron runs --id <jobId>

#启用某个被禁用的任务
smcclaw cron enable <jobId>

#禁用某个任务（暂停，不删除）
smcclaw cron disable <jobId>

#永久删除某个任务
smcclaw cron remove <jobId>

常用 Cron 表达式

安全策略

• Gateway 绑定：Gateway 默认仅绑定本地回环地址；远程访问优先使用 SSH 隧道。

• 网关令牌：Gateway Token 及包含 Token 的 Dashboard URL 属于敏感凭证，不要分享或记录在未脱敏截图中。

• 激活码：SMC 激活码属于敏感凭证，仅在本机 TUI 或私有 Dashboard 会话中提供；文档、截图和日志定期清理。

• 钉钉机器人：发布前仅授权可信用户和群组。

• 命令来源：不向 AI 提交来源不明的命令；破坏性操作执行前核对完整命令和目标路径。

• 安全执行策略：默认开启 allowlist + on-miss，白名单外命令必须审批，建议保持开启。

可通过以下指令查看安全配置：

smcclaw config get tools.exec

启停服务

#开启服务
smcclaw gateway start

#停止服务
smcclaw gateway stop

#重启服务
smcclaw gateway restart

#查看服务状态
smcclaw gateway status

卸载客户端

• Linux：分别执行以下指令卸载客户端。

  #先移除 Gateway 服务
  smcclaw gateway uninstall
  
  #再删除程序文件
  bash /opt/smcclaw/install.sh --uninstall

  重要

  若安装时使用了自定义目录，卸载时必须指定相同的 --prefix 目录，否则无法正确清理。如bash /usr/local/smcclaw/install.sh --prefix /usr/local/smcclaw --uninstall

• Windows：执行smcclaw gateway uninstall卸载 Gateway 服务后，删除解压的 SMCClaw 目录即可。

配置与数据清理

执行以下指令备份并删除配置或工作目录：

smcclaw backup create
smcclaw uninstall --dry-run
smcclaw uninstall

smcclaw uninstall 会移除 Gateway 服务和所选本地数据，不删除 CLI 程序文件。删除 CLI 程序文件需执行卸载客户端操作。

状态查询与诊断

#查看smcclaw运行状态及配置信息
smcclaw status

#诊断自检，可排查运行环境是否正常
smcclaw doctor

#查看SMCClaw运行日志
smcclaw logs --follow

#查看SMCClaw 当前使用的 AI 模型配置状态
smcclaw models status

#查看SMCClaw 消息通道连接状态
smcclaw channels status

如何获取激活码？

1. 访问SMC控制台-服务器迁移。

2. 在服务器迁移页面，单击导入迁移源。

3. 在导入迁移源页面，选择客户端导入。

4. 在SMC控制台的导入说明中，选择操作系统类型后，单击生成激活码。

5. 复制生成的Access Token ID及Access Token Code。

Linux如何自定义客户端安装目录？

bash ./smcclaw-<version>-linux-x64/install.sh --prefix /usr/local/smcclaw

更多模型配置

推荐：阿里云（千问云/Qwen Cloud）

Qwen Provider 已内置，首次配置不会提示从 npm 下载插件。从曾自动下载 Qwen 插件的旧版本升级后，可先运行 smcclaw doctor --fix 清理旧插件安装记录。根据方案和站点选择任一命令：

其他主流模型

配置后检查：

smcclaw models status
smcclaw doctor

如何查看模型使用情况？

打开 Dashboard 使用情况页面 http://127.0.0.1:18789/usage，查看模型 API Token 使用量和成本。

Dashboard 显示无法连接怎么办？

显示“浏览器无法完成Gateway连接。重试凭据前请检查目标和传输方式”，需要检查网关令牌是否有误。

AI 回答失败，提示 Agent failed before reply怎么办？

需要核实模型配置是否正确，是否使用了错误的模型 API Key 或 provider/model 名称。

Gateway 连接失败怎么办？

1. 确认服务状态。

   smcclaw gateway status

   查看 Gateway 是否正在运行。

2. 检查监听端口。

   Gateway 默认监听 18789 端口。需检查端口是否被占用、是否被防火墙拦截，或 Gateway 未在该端口监听。

3. 执行环境自检。

   smcclaw doctor

   全面检测环境配置，查看是否存在异常。

4. 查看运行日志，排查连接失败原因。

   smcclaw logs --follow

模型调用失败怎么办？

1. 检查模型状态是否正常。

   smcclaw models status

2. 执行环境自检。

   smcclaw doctor

3. 查看运行日志。

   smcclaw logs --follow

4. 核验API Key。

   检查 AccessKey 是否有效,是否已过期或被禁用。

钉钉机器人无响应怎么办？

1. 检查钉钉通道连接。

   smcclaw channels status --channel dingtalk-connector --probe

2. 确认钉钉机器人的消息接收方式为Stream模式。

3. 核验钉钉卡片权限。

   SMCClaw 回复消息使用 AI 互动卡片（富文本消息格式）。应用未开启卡片权限时，消息无法发送。在钉钉开放平台确认应用已授权卡片相关权限。

4. 检查应用发布状态。

   钉钉应用需发布上线方可使用。应用处于“开发中”状态或已下架时，机器人不响应。在钉钉开放平台核查应用发布状态。

5. 核对 Client ID / Secret。

   Client ID 与 Secret 是钉钉应用的身份凭证。凭证填错、过期或被重置，均无法与钉钉建立连接。

6. 排查日志中的 AI Card 403 错误。

   日志出现 AI Card 403 错误，表明发送卡片消息被钉钉拒绝，通常源于权限不足。返回钉钉开放平台确认应用权限已配齐。

定时任务未执行怎么排查原因？

1. 查看任务清单。

   smcclaw cron list

   确认任务是否创建成功，是否启用，以及时间配置是否正确。

2. 查看单个任务详情。

   smcclaw cron get <jobId>

   用任务 ID 查看详细信息：调度规则、上次执行时间、下次计划执行时间、任务配置是否正确。

3. 确认 Gateway 状态。

   smcclaw gateway status

   定时任务由 Gateway 调度。Gateway 未运行或异常时，所有定时任务均不触发。

4. 核对服务器时区。

   任务执行时间依赖服务器时区。时区与预期不一致时，任务会在错误时间执行，表现为“未执行”。

5. 查看执行历史。

   smcclaw cron runs --id <jobId>

Windows如何将smcclaw加入系统PATH？

将 smcclaw 可执行文件路径添加至 PATH 环境变量，可实现命令行全局调用。

以Windows 2022为例。

1. 右键单击图标，选择系统。

2. 在左侧导航栏搜索并打开查看高级系统设置。

3. 在系统属性的高级页签中，单击环境变量。

4. 在系统变量区域查找Path变量。选中后，单击编辑，进入编辑环境变量页面后，再单击新建，添加C:\smcclaw\smcclaw-<version>-win32-x64\bin。

   将 <version> 替换为具体版本号，如 2026.9.5。

5. 测试环境变量是否配置成功。

   1. 右键单击图标，选择运行，输入PowerShell，新开PowerShell界面。

   2. 在界面中，执行smcclaw --version，若输出工具版本信息，则表示环境变量配置成功。