1. 为什么我选 zeroclaw 而不是 openclawRust 智能助理的落地场景zeroclaw 是一个用 Rust 写的 AI Agent 框架能做什么简单说它把大模型对话、工具调用、定时任务、消息渠道钉钉、Telegram、Discord 等和技能模块skills打包成一个可本地运行的二进制程序。适合谁适合想在低配设备上跑一个常驻智能助理、又不想被 Python 运行时和 GC 拖累的开发者。我试过在 2 核 4G 的轻量服务器上跑内存占用稳定在 200MB 上下比同类 Python 方案省不少。这次的目标很明确在 Rust 环境下用 zeroclaw 接入 qwen 模型走阿里百炼的 OpenAI 兼容接口再挂上钉钉机器人最后加载 skills 技能模块让一条钉钉消息能端到端走通「钉钉 → zeroclaw → qwen → 回传钉钉」的完整链路。整个过程我会给出可复制的 config.toml 片段、依赖清单和启动命令你照着做就能复现。先说清楚架构。zeroclaw 的核心是一个 agent 循环收到消息后它把消息和上下文一起发给模型模型返回工具调用或文本zeroclaw 执行工具比如读文件、发邮件、查新闻再把结果喂回模型直到模型给出最终回复。钉钉在这里扮演的是「渠道」角色通过 webhook 或长连接把消息送进 zeroclaw 的 gateway再把回复推回钉钉群或单聊。skills 则是预置的工具包每个 skill 有自己的 SKILL.md 描述和可执行脚本zeroclaw 根据描述决定什么时候调用它。为什么不用 openclawopenclaw 生态更成熟但资源消耗确实大尤其在低配机器上跑久了容易吃满内存。zeroclaw 基于 Rust没有 GC 停顿启动快二进制体积小适合长期驻留。代价是文档和社区还在成长有些配置得自己翻源码。不过对于「钉钉 qwen skills」这个组合zeroclaw 的配置项已经够用了。还有一个现实问题token 消耗。网上有人说 zeroclaw 跑起来 token 烧得很快我实测下来如果 skills 开得多、上下文压缩没做好确实不到 10 次对话就能吃掉 100 万 token。所以后面我会重点讲怎么控制上下文和 skills 的加载范围避免无谓的消耗。这一节先把场景和选型讲清楚下一节开始动手装 Rust、拉代码、配模型。2. 前置准备Rust 环境、qwen 模型接入与 zeroclaw 编译在写配置之前得先把地基打好。这一节覆盖三件事Rust 工具链安装、qwen 模型 API Key 获取、zeroclaw 源码编译。每一步都有可复制的命令你按顺序执行即可。2.1 安装 Rust 工具链Ubuntu 22.04 为例zeroclaw 要求 Rust 1.75 以上。如果你机器上还没装 Rust用官方脚本最省事curl --proto https --tlsv1.2 -sSf https://sh.rustup.rs | sh source $HOME/.cargo/env rustc --version cargo --version装完后确认rustc和cargo都能输出版本号。如果网络拉取 crates.io 慢可以配一个国内镜像源在~/.cargo/config.toml里加[source.crates-io] replace-with ustc [source.ustc] registry sparsehttps://mirrors.ustc.edu.cn/crates.io-index/2.2 获取 qwen 模型 API Keyqwen 系列模型通过阿里百炼平台提供 OpenAI 兼容接口。你需要一个 API Key然后在 zeroclaw 里把default_provider指向百炼的兼容端点。百炼的兼容模式地址是https://dashscope.aliyuncs.com/compatible-mode/v1模型名可以选qwen-max、qwen-plus、qwen-coder-plus等。我这次用qwen-plus因为它在成本和能力之间比较平衡适合日常助理场景。如果你要跑代码相关的任务qwen-coder-plus更合适。拿到 Key 后先别急着写进 config.toml后面我会讲怎么用环境变量覆盖避免明文泄露。2.3 编译 zeroclaw拉源码并编译git clone https://github.com/zeroclaw-labs/zeroclaw.git cd zeroclaw cargo build --release --locked--locked保证依赖版本和 lock 文件一致避免因为依赖漂移导致编译失败。如果网络不好可以手动下载 release 包或者用cargo build --release不加--locked试试。编译完成后把二进制装到 PATHcargo install --path . --force --locked然后验证zeroclaw status如果输出了工作区路径和配置状态说明安装成功。接下来可以跑一次单次提问确认模型能通zeroclaw agent -m 用 Python 实现快速排序这一步会用到你后面配置的模型。如果还没配它会提示你缺 API Key。2.4 依赖清单zeroclaw 本身是 Rust 二进制运行时依赖不多。但 skills 里的脚本可能依赖 Python 3.11、jq、curl 等。建议提前装好sudo apt update sudo apt install -y python3 python3-pip jq curl python3 --versionPython 版本要 3.11 以上因为部分 skill 脚本用了tomllibPython 3.11 才进标准库。如果你系统自带的是 3.10需要自己升级或用 pyenv。这一节把环境铺好了下一节进入核心写 config.toml把 qwen、钉钉、skills 串起来。3. 可复制配置config.toml 里接入 qwen、钉钉与 skills 的完整片段zeroclaw 的配置文件默认在~/.zeroclaw/config.toml。你也可以用zeroclaw onboard --interactive交互式生成但手写更可控。下面这份配置是我实测能跑通的版本你直接复制后改几个字段即可。3.1 模型与 provider 配置api_key sk-你的百炼Key default_provider custom:https://dashscope.aliyuncs.com/compatible-mode/v1 default_model qwen-plus default_temperature 0.7 model_routes [] embedding_routes []这里的关键是default_provider用custom:前缀加完整 URL指向百炼的 OpenAI 兼容端点。default_model填qwen-plus你也可以换成qwen-max或qwen-coder-plus。api_key建议不要明文写后面用环境变量ZEROCLAW_API_KEY覆盖。3.2 钉钉渠道配置[channels_config] cli true message_timeout_secs 300 [channels_config.dingtalk] client_id 你的钉钉AppKey client_secret 你的钉钉AppSecret allowed_users [*]钉钉这边需要在开放平台创建一个应用拿到client_idAppKey和client_secretAppSecret。allowed_users [*]表示允许所有用户生产环境建议改成具体用户 ID。钉钉的消息通过 Stream 模式接入不需要公网 IP这点对本地部署很友好。3.3 自主性与安全策略[autonomy] level supervised workspace_only true allowed_commands [git, npm, cargo, ls, cat, grep, find, echo, pwd, wc, head, tail, curl, mkdir, jq, python3] forbidden_paths [/etc, /root, /home, /usr, /bin, /sbin, /lib, /opt, /boot, /dev, /proc, /sys, /var, /tmp, ~/.ssh, ~/.gnupg, ~/.aws, ~/.config] max_actions_per_hour 20 max_cost_per_day_cents 500 require_approval_for_medium_risk true block_high_risk_commands true auto_approve [file_read, file_write, memory_recall] always_ask []level supervised表示中等风险操作需要确认高风险直接拦截。workspace_only true限制 agent 只能在工作区内操作。allowed_commands是白名单只允许这些命令执行。forbidden_paths是黑名单防止 agent 读到敏感目录。这套组合下来即使模型被诱导也很难造成破坏。3.4 记忆与存储[memory] backend sqlite auto_save true hygiene_enabled true archive_after_days 7 purge_after_days 30 conversation_retention_days 30 embedding_provider none embedding_model text-embedding-3-small embedding_dimensions 1536 vector_weight 0.7 keyword_weight 0.3 min_relevance_score 0.4 embedding_cache_size 10000 chunk_max_tokens 512 response_cache_enabled false response_cache_ttl_minutes 60 response_cache_max_entries 5000 snapshot_enabled false snapshot_on_hygiene false auto_hydrate true记忆后端用 sqlite轻量且无需额外服务。embedding_provider none表示不做向量检索只用关键词匹配这样省 token 也省算力。如果你需要语义检索可以改成openai并配 embedding 模型但会额外消耗 token。3.5 网关与调度[gateway] port 3000 host 127.0.0.1 require_pairing false allow_public_bind false paired_tokens [] pair_rate_limit_per_minute 10 webhook_rate_limit_per_minute 60 trust_forwarded_headers false rate_limit_max_keys 10000 idempotency_ttl_secs 300 idempotency_max_keys 10000 [scheduler] enabled true max_tasks 64 max_concurrent 4 [cron] enabled true max_run_history 50网关默认绑127.0.0.1:3000不对外暴露。钉钉走 Stream 模式不需要网关公网可达。调度器和 cron 开着方便后面加定时任务。3.6 skills 加载skills 放在~/.zeroclaw/workspace/skills/目录下。每个 skill 是一个子目录里面有SKILL.md和可执行脚本。zeroclaw 启动时会扫描这个目录把 skill 描述注入到系统提示里模型根据描述决定是否调用。添加 skill 的命令npx skills add https://github.com/vikiboss/60s-skills --skill daily-news-60s或者手动下载后放到~/.zeroclaw/workspace/skills/下。注意 skills 不要开太多每个 skill 的描述都会占用上下文 token开十几个之后 token 消耗会明显上升。3.7 环境变量覆盖敏感信息不要把 API Key 和钉钉 Secret 明文写在 config.toml 里。用环境变量覆盖export ZEROCLAW_API_KEYsk-你的百炼Key export EMAIL_SMTP_PASSWORD你的授权码zeroclaw 会优先读ZEROCLAW_API_KEY和API_KEY环境变量。钉钉的 Secret 目前只能写在配置里建议把 config.toml 权限设为 600chmod 600 ~/.zeroclaw/config.toml这一节把配置写完了下一节启动并验证端到端链路。4. 启动与验证一条钉钉消息从 qwen 回传的端到端测试配置写好后启动 zeroclaw 并验证链路。这一节给出启动命令、验证步骤和预期结果。4.1 启动 gateway 和 daemon先启动 gateway它会加载配置并连接钉钉zeroclaw gateway如果一切正常你会看到类似输出[INFO] gateway listening on 127.0.0.1:3000 [INFO] dingtalk channel connected [INFO] loaded 3 skills如果钉钉连接失败检查client_id和client_secret是否正确以及钉钉应用是否开启了 Stream 模式。长期运行用 daemonzeroclaw daemondaemon 会在后台守护进程断线自动重连。4.2 验证模型连通性在钉钉发消息之前先用 CLI 验证模型zeroclaw agent -m 你好请用一句话介绍你自己预期返回 qwen 的回复。如果报 401说明 API Key 不对如果报连接超时检查default_provider的 URL 是否拼写正确。4.3 钉钉端到端测试在钉钉里给机器人发一条消息比如「今天有什么新闻」。预期流程钉钉把消息推给 zeroclaw 的 dingtalk channelzeroclaw 把消息和 skill 描述一起发给 qwenqwen 判断需要调用daily-news-60sskillzeroclaw 执行 skill 脚本拿到新闻数据把结果喂回 qwenqwen 整理成自然语言zeroclaw 把回复推回钉钉如果一切正常你会在钉钉里收到一条整理好的新闻摘要。如果 skill 没被调用检查SKILL.md里的description是否清晰模型靠这个描述决定是否调用。4.4 查看日志确认链路zeroclaw 的日志会记录每一步tail -f ~/.zeroclaw/logs/zeroclaw.log你会看到类似[INFO] received message from dingtalk userxxx [INFO] calling model qwen-plus [INFO] tool call: daily-news-60s [INFO] tool result: {...} [INFO] sending reply to dingtalk这条日志链就是端到端走通的证据。如果中间断了根据日志定位是哪一步失败。4.5 验证 skills 加载查看已加载的 skillsls ~/.zeroclaw/workspace/skills/每个目录下应该有SKILL.md。如果某个 skill 没被加载检查目录名和文件权限。zeroclaw 只加载有SKILL.md的目录。这一节验证了链路下一节讲常见报错和排查方法。5. 常见报错排查401、local proxy failed、reading choices 与 OAuth 问题部署过程中最容易卡在几个报错上。这一节按报错信息分类给出原因和解决方法。5.1 401 Unauthorized报错Error: 401 Unauthorized原因API Key 无效或未正确传递。排查步骤确认ZEROCLAW_API_KEY环境变量已设置且值以sk-开头确认default_provider的 URL 是https://dashscope.aliyuncs.com/compatible-mode/v1不要漏掉/v1确认default_model是百炼支持的模型名比如qwen-plus不要写成qwen3.5-plus这种不存在的名字如果用的是自定义 provider检查api_key字段是否被环境变量覆盖5.2 local proxy failed报错Error: local proxy failed: connection refused原因zeroclaw 尝试走本地代理但代理没启动。排查检查[proxy]段enabled false时不应该走代理如果确实需要代理确认代理地址和端口正确检查环境变量HTTP_PROXY/HTTPS_PROXY是否指向了一个不可用的地址5.3 reading choices 报错报错Error: reading choices: unexpected end of JSON input原因模型返回的响应不是预期的 OpenAI 格式。常见于 provider URL 配错或者模型名不被支持。排查确认default_provider指向的是 OpenAI 兼容端点不是原生 DashScope 端点用 curl 直接测试端点curl -X POST https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions \ -H Authorization: Bearer $ZEROCLAW_API_KEY \ -H Content-Type: application/json \ -d {model:qwen-plus,messages:[{role:user,content:hi}]}如果 curl 返回正常 JSON说明端点没问题问题在 zeroclaw 配置。5.4 OAuth 相关报错报错Error: OAuth token expired原因某些 provider 用 OAuth 认证token 过期。zeroclaw 目前对 OAuth 的支持有限建议用 API Key 认证。如果你用的是需要 OAuth 的 provider检查 token 刷新逻辑或者换成 API Key 方式。5.5 钉钉消息收不到回复如果钉钉发了消息但没回复排查检查allowed_users是否包含你的用户 ID检查钉钉应用是否开启了机器人能力查看日志里有没有received message from dingtalk如果没有说明消息没进来检查message_timeout_secs是否太短复杂任务需要更长时间5.6 skills 不生效如果模型不调用 skill排查检查SKILL.md的description是否清晰描述了 skill 的用途检查 skill 脚本是否有可执行权限chmod x script.py检查allowed_commands是否包含脚本需要的命令比如python3减少同时加载的 skill 数量太多 skill 会让模型难以选择这一节覆盖了主要报错下一节给出接入文档和 API Key 的获取入口。6. 接入文档与 API Key 获取把 qwen 和钉钉串起来的最后一步如果你还没拿到 qwen 的 API Key或者想确认 zeroclaw 的完整配置项可以从下面这些入口进入。TaoToken 的 API Key 管理页面在 console你可以在这里创建和管理 Key。接入文档在 doc里面有各模型的端点和参数说明。API 基础地址是https://taotoken.net/api在 zeroclaw 里配置default_provider时可以用这个地址加/v1后缀。如果你想先验证模型对话是否正常可以用 模型对话 页面直接测试。长期跑编码或 Agent 任务的话Coding Plan 更划算。API Key 的创建入口在 api-keys。配置 zeroclaw 时把default_provider写成default_provider custom:https://taotoken.net/api/v1 default_model qwen-plus然后把ZEROCLAW_API_KEY设成你在 console 里创建的 Key。这样 qwen 模型就能通过 TaoToken 的兼容端点接入 zeroclaw。钉钉这边开放平台的入口是https://open-dev.dingtalk.com/创建应用后拿到 AppKey 和 AppSecret填进[channels_config.dingtalk]段。钉钉的 Stream 模式不需要公网 IP本地机器就能跑。skills 的添加用npx skills add命令或者手动下载放到~/.zeroclaw/workspace/skills/下。每个 skill 的SKILL.md里要写清楚description模型靠这个决定是否调用。最后提醒一句token 消耗和 skills 数量、上下文长度直接相关。我实测下来开 3 个 skill、对话 10 轮左右qwen-plus 大概消耗 20 万 token。如果你发现消耗过快先检查max_history_messages和compact_context配置把历史消息数调小或者开启上下文压缩。zeroclaw 的[agent]段里有compact_context false改成true可以自动压缩长对话省 token 效果明显。