1. QClaw 到底解决什么问题从 OpenClaw 的“重”说起如果你用过 OpenClaw大概率经历过这样的场景装完之后先面对一堆配置项多租户、权限、Agent Teams、审计日志光是搞清楚哪些该关、哪些该留就要花掉半小时。对个人开发者来说这些企业级能力不是加分项而是负担。QClaw 就是在这个背景下出现的——它是 OpenClaw 的极简封装版把企业功能全部砍掉只保留个人最常用的三件事本地工具调用、聊天辅助、技能兼容。QClaw 是什么一句话说它是基于 OpenClaw 开源框架的轻量级社区衍生版安装包约 80MB空闲内存占用约 200MB比 OpenClaw 官方版降低约 60%。它能做什么能跑通 OpenClaw 的技能生态能接大模型做对话和代码辅助能访问你指定的工作目录做文件操作。适合谁适合不想折腾配置、只想快速有一个能用的本地 AI 助手的开发者尤其是机器配置一般、或者只想在服务器上跑一个轻量服务的场景。但 QClaw 本身不绑定模型供应商它需要一个统一的 Key/API 通道来接入大模型。这就是本篇要一起解决的第二个问题用 TaoToken 作为统一 Key 通道把模型接入这一步从“每个供应商配一遍”变成“配一次就通”。下面从下载安装开始一路走到连通性验证。2. 前置准备TaoToken 统一 Key 通道怎么开在装 QClaw 之前先把 Key 通道准备好这样安装完就能直接填配置不用来回切换页面。TaoToken 在这里扮演的角色是你不需要分别去每个模型厂商申请 Key、记不同的 Base URL而是用一套 Key 和统一的 API 地址在 QClaw 里完成接入。第一步打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册并登录。登录后进入控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 。控制台里能看到你的账户状态和用量概览。第二步创建 API Key。进入 API Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。点“创建新 Key”给它起个名字比如qclaw-local方便以后区分用途。创建后会显示一串以sk-开头的字符串复制下来这个只显示一次丢了就得重建。注意Key 不要直接写进会提交到 Git 的配置文件里。QClaw 支持从环境变量读取后面配置环节会用到这个方式。第三步确认 API 接入地址。TaoToken 的 API 端点是 https://taotoken.net/api 注意这个地址不带任何查询参数是纯粹的接口前缀。QClaw 的config.toml里填的就是这个值后面会给出完整骨架。如果你还想先验证一下 Key 是否可用可以打开模型对话页面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 随便发一句“你好”能正常回复就说明 Key 和账户状态都没问题。这一步不是必须的但能帮你把问题范围缩小——如果后面 QClaw 连不上至少知道 Key 本身是好的。3. 下载与安装 QClaw三种方式按场景选QClaw 的安装方式有三种按你的使用场景选一种就行不用全试。3.1 一键脚本安装Linux/macOS/WSL新手首选这是最省事的方式脚本会自动处理依赖和环境变量。在终端执行curl -fsSL https://qclaw.cn/install.sh | bashWindows 用户如果用 PowerShell先解锁执行权限再跑安装脚本Set-ExecutionPolicy RemoteSigned -Scope CurrentUser -Force iwr -useb https://qclaw.cn/install.ps1 | iex装完后验证版本qclaw --version正常输出类似QClaw v1.0.0。如果提示命令找不到检查一下~/.local/bin或 npm 全局路径是否在PATH里。3.2 Docker 部署服务器推荐QClaw 的 Docker 镜像只有 80MB 左右适合放在服务器上长期跑。先建目录mkdir -p /opt/qclaw cd /opt/qclaw然后创建docker-compose.ymlversion: 3.8 services: qclaw: image: qclawcommunity/qclaw:latest container_name: qclaw restart: unless-stopped ports: - 127.0.0.1:18790:18790 volumes: - qclaw-data:/root/.qclaw - ./workspace:/root/workspace environment: - TZAsia/Shanghai - TAOTOKEN_API_KEY${TAOTOKEN_API_KEY} volumes: qclaw-data: name: qclaw-data注意这里端口绑定的是127.0.0.1只允许本机访问避免暴露到公网。启动export TAOTOKEN_API_KEYsk-你的Key docker compose up -d3.3 便携版Windows/macOS解压即用不想装软件的话下载便携版压缩包解压后直接运行qclaw.exeWindows或拖到应用程序文件夹macOS。便携版的配置目录同样在~/.qclaw和安装版隔离互不影响。4. 可复制配置config.toml 骨架与 settings.json 关键字段QClaw 的配置分两个文件config.toml管模型接入和运行参数settings.json管界面和工作目录。两个文件都在~/.qclaw/下首次运行会自动生成你直接改就行。4.1 config.toml 完整骨架[server] host 127.0.0.1 port 18790 [model] provider openai-compatible base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY model_name claude-sonnet-4-20250514 max_tokens 4096 temperature 0.7 [workspace] root /root/workspace allow_write true [skills] enabled true auto_load [code-simplifier]几个关键点说明。base_url填 TaoToken 的 API 地址注意结尾不要加/v1或斜杠QClaw 会自己拼接路径。api_key_env指定从环境变量TAOTOKEN_API_KEY读取 Key这样配置文件本身不含敏感信息可以安全地放进版本管理。model_name按你实际要用的模型填TaoToken 支持多个模型具体名称可以在模型对话页面或文档里确认。4.2 settings.json 关键字段{ ui: { language: zh-CN, theme: light }, workspace: { directories: [ /root/workspace, /home/user/projects ], default: /root/workspace }, model: { timeout_seconds: 60, retry_count: 2 } }directories是 QClaw 允许访问的目录白名单不在列表里的路径它不会碰。timeout_seconds设 60 秒网络波动时给足重试空间。retry_count设 2配合 TaoToken 的通道稳定性基本不会因为偶发超时中断对话。4.3 环境变量注入Linux/macOS 下把 Key 写进 shell 配置echo export TAOTOKEN_API_KEYsk-你的Key ~/.bashrc source ~/.bashrcDocker 部署的话在docker-compose.yml同目录建一个.env文件TAOTOKEN_API_KEYsk-你的Keydocker compose会自动读取.env不用手动 export。5. 验证请求从启动到连通性确认配置改完后重启 QClaw 让配置生效qclaw restart然后检查服务状态qclaw status正常输出会包含三行确认服务运行地址、大模型连接状态、工作目录配置。如果大模型那行显示未连接先别急着改配置按下面的顺序排查。第一步确认环境变量真的被读到了echo $TAOTOKEN_API_KEY应该输出你的 Key。如果是空的说明 shell 配置没生效重新source一下。第二步直接用 curl 测 TaoToken 的 API 端点排除 QClaw 本身的问题curl -s https://taotoken.net/api/v1/models \ -H Authorization: Bearer $TAOTOKEN_API_KEY | head -c 500能返回模型列表 JSON 就说明 Key 和网络都通。如果返回 401检查 Key 是否复制完整返回超时检查服务器出网是否正常。第三步在 QClaw 聊天框里发一句你好介绍一下你自己能正常回复中文说明模型通道打通。再发一句列出当前工作区的所有文件如果它能列出你配置的目录下的文件说明文件系统访问也正常。这两步都过了QClaw 就算跑通了。如果你更习惯在网页端验证模型可用性也可以打开 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 发同样的测试消息对比两边结果能快速判断问题出在 QClaw 还是通道侧。6. 本篇常见错排查6.1 启动报错 “address already in use”端口 18790 被占了。改config.toml里的port比如改成 18791然后重启。Docker 部署的话同时改docker-compose.yml的端口映射。6.2 模型连接一直超时先确认base_url填的是https://taotoken.net/api没有多余路径。再确认服务器能访问外网。如果服务器有出网限制检查是否放行了 443 端口。另外timeout_seconds设太小也会导致误判建议不低于 30。6.3 技能安装后不生效QClaw 的技能目录在~/.qclaw/skills/装完后确认目录里有对应文件夹。如果config.toml里auto_load写了技能名但没加载检查名字是否和技能包里的manifest.json一致。手动加载可以用qclaw skills load code-simplifier6.4 工作目录访问被拒检查settings.json的directories列表是否包含你要访问的路径且路径是绝对路径。相对路径 QClaw 不认。另外确认运行 QClaw 的用户对该目录有读权限Docker 部署时注意容器内路径和宿主机路径的映射关系。6.5 升级后配置丢失QClaw 升级不会覆盖~/.qclaw/下的配置文件但如果你用的是便携版覆盖安装注意别把整个目录替换掉。升级命令qclaw updateDocker 部署的话cd /opt/qclaw docker compose pull docker compose up -d数据卷qclaw-data会保留配置不丢。7. 长期编码与 Agent 场景Coding Plan 与接入文档如果你不只是想跑通对话而是要把 QClaw 当成日常编码助手或者 Agent 底座来用建议把 Key 通道升级成 Coding Plan。Coding Plan 针对高频调用做了通道优化适合长时间、多轮次的编码会话。入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 开通后在 QClaw 的config.toml里不需要改base_urlKey 权限会自动覆盖。接入过程中遇到报错优先查接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。文档里按错误码分类比在聊天框里试错快得多。如果你用的是 Claude Code 类的工具链Anthropic 兼容接入的说明在 https://taotoken.net/claudecode-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecode-anthropicutm_campaignrewrite QClaw 的openai-compatible模式同样适用这套 Key。最后说一个实测下来的小技巧QClaw 的config.toml改完后不用重启整个服务qclaw reload就能热加载模型配置只有改端口和目录才需要restart。这样调参的时候省不少时间。
