QwenPaw 2.2.2 配置参数详解

目标：讲清 QwenPaw 2.2.2 的配置文件结构、查看与修改方式、各段核心参数的真实默认值与改动影响，并给出一套可直接套用的生产配置模板。全部键值与默认值逐项采集自 Ubuntu 22.04 服务器上 qwenpaw init 生成的默认配置与命令实测回显。

一、环境信息

• 操作系统：Ubuntu 22.04.5 LTS（x86_64）
• QwenPaw 版本：2.2.2（PyPI 最新稳定版，发布于 2026-10-15）
• Python 环境：3.12.15（官方脚本安装，uv 托管虚拟环境）
• 安装目录：/root/.qwenpaw（虚拟环境 /root/.qwenpaw/venv，命令包装器 /root/.qwenpaw/bin/qwenpaw）
• 配置文件：/root/.qwenpaw/config.json（由 qwenpaw init --defaults --accept-security 生成）
• 服务端口：127.0.0.1:8088（qwenpaw app 默认值）
• 安装过程与 systemd 托管详见本系列《Ubuntu 22.04 安装 QwenPaw 2.2.2 指南》

二、前置条件

按《Ubuntu 22.04 安装 QwenPaw 2.2.2 指南》完成 0→1 部署，并确认以下状态（以下命令与回显均为实测）：

qwenpaw --version

实测输出：

QwenPaw, version 2.2.2

ls -la /root/.qwenpaw/config.json

实测输出：

-rw-r--r-- 1 root root 32159 Oct 22 16:31 /root/.qwenpaw/config.json

若文件不存在，执行 qwenpaw init --defaults --accept-security 生成默认配置后再继续（该命令的真实回显见《Ubuntu 22.04 安装 QwenPaw 2.2.2 指南》第四章）。

三、参数查看与修改方式

3.1 查看：config.json 全量读取

QwenPaw 的全部配置集中在一个 JSON 文件里。直接读取（文件约 50KB，建议格式化输出）：

/root/.qwenpaw/venv/bin/python -m json.tool /root/.qwenpaw/config.json | head -20

实测输出（节选，实测首部）：

{
    "channels": {
        "imessage": {
            "enabled": false,
            "bot_prefix": "",
            "show_tool_calls": true,
            "show_tool_results": true,
            "tool_call_max_length": 200,
            "tool_result_max_length": 500,
            "show_thinking": true,
            "dm_policy": "open",
            "group_policy": "open",
            "allow_from": [],
            "deny_message": "",
            "require_mention": false,
            "no_text_debounce": true,
            ...
        },

⚠️ 注意：不要在 QwenPaw 运行时用编辑器以外的方式重排整个文件（如 jq 重排序），只改动需要的键即可，避免大面积 diff 干扰后续排查。

3.2 修改方式一：直接编辑 config.json + 热重载

修改 JSON 后无需重启服务，用 daemon reload-config 重新加载：

/root/.qwenpaw/venv/bin/python -c "import json;p='/root/.qwenpaw/config.json';c=json.load(open(p));c['user_timezone']='Asia/Shanghai';json.dump(c,open(p,'w'),ensure_ascii=False,indent=2);print('user_timezone -> Asia/Shanghai')"

实测输出：

user_timezone -> Asia/Shanghai

qwenpaw daemon reload-config

实测输出：

**Config reloaded**

- load_config() re-invoked successfully.

如何确认改动已生效：以时区为例，新建一个定时任务，观察其继承的时区（新建 cron 会默认继承 user_timezone）：

qwenpaw cron create --type text --name "tz-check" --cron "0 8 * * *" --channel console --target-user root --target-session tz --text "hi"

实测输出（节选）：

  "id": "8ba3d57b-1a32-4cfe-925c-a88f73f36694",
    "timezone": "Asia/Shanghai",

时区已从默认 UTC 变为 Asia/Shanghai，证明热重载生效。验证后清理测试任务：

qwenpaw cron delete 8ba3d57b-1a32-4cfe-925c-a88f73f36694

实测输出：

{
  "deleted": true
}

3.3 修改方式二：Console 网页端

浏览器打开 http://127.0.0.1:8088/ 进入 Console，模型提供商（Settings → Models）、渠道、技能、定时任务均可在网页里改，落盘的仍是同一个 config.json。

3.4 修改方式三：CLI 子命令

适合脚本化运维的几个入口：

qwenpaw env set DASHSCOPE_API_KEY q1w2e3r4   # 写入环境变量（供 MCP/工具引用）
qwenpaw models config                         # 交互式配置模型提供商
qwenpaw channel config                        # 交互式配置 IM 渠道
qwenpaw skills config                         # 交互式配置技能

env set 实测输出：

✓ DASHSCOPE_API_KEY = q1w2e3r4

💡 技术拓展：qwenpaw env 管理的是 QwenPaw 自己的环境变量表（服务进程内注入），与 /etc/environment、systemd Environment= 是三个不同层次。API Key 这类第三方密钥建议走 systemd Environment= 或 env set，避免写进 config.json 随文件外泄。

四、参数总览

默认 config.json 的顶层结构（实测枚举）：

关键解读：channels 和 tools 是"面"上的开关（接什么渠道、给 Agent 哪些工具），agents 与 security 是"里"上的核心（行为与安全边界），改配置前先想清楚动的是哪一层。

五、核心参数分类详解

5.1 agents 段：Agent 档案与运行时行为

多 Agent 档案（实测默认值）：

"agents": {
  "active_agent": "default",
  "agent_order": ["default"],
  "profiles": {
    "default": {
      "id": "default",
      "workspace_dir": "/root/.qwenpaw/workspaces/default",
      "enabled": true,
      "pinned": false
    }
  },
  "language": "zh",
  ...
}

• active_agent：默认对话的 Agent；qwenpaw agent create 新增档案后此处可切换。
• profiles.<id>.workspace_dir：每个 Agent 独立工作区，记忆/技能/会话互不污染。
• agents.language / agents.installed_md_files_language：初始化文案语言，实测默认 zh。

心跳（HEARTBEAT）——QwenPaw 的"主动巡检"机制：

运行时循环与限流（agents.running.*，实测默认值节选）：

doom_loop（死循环检测）默认开启（window_size: 3、similarity_threshold: 1.0），连续 3 轮高度相似的动作会注入警告提示——跑无人值守任务时不要轻易关掉它。

记忆（agents.running.reme_light_memory_config.*）：

模型路由（agents.llm_routing.*）：默认 enabled: false、mode: "local_first"。开启后可给不同 Agent 指定本地/云端模型组合，v2.2.1 引入的 per-Agent 模型路由即落在此处。

5.2 channels 段：18 个渠道的通用键与渠道专属键

默认配置含 18 个渠道段（实测枚举）：imessage, discord, dingtalk, feishu, qq, telegram, mattermost, mqtt, console, matrix, voice, sip, wecom, xiaoyi, yuanbao, wechat, slack, onebot。

每个渠道共有的通用键（实测默认值）：

钉钉 dingtalk 专属键（实测默认值节选）：client_id（应用 Key）、client_secret（应用密钥）、robot_code（机器人编码）、message_type: "markdown"、cron_message_type: "markdown"、card_template_id（互动卡片模板）、endpoint（可自定义回调端点）。接入步骤：钉钉开放平台创建企业内部应用 → 拿到 client_id/client_secret 填入 → enabled: true → reload。

飞书 feishu 专属键：app_id、app_secret、encrypt_key、verification_token、domain: "feishu"（海外填 larksuite）。

Discord 专属键：bot_token、http_proxy（Discord 国内不可直连时在此填代理，与系统代理解耦）、accept_bot_messages。

5.3 security 段：五层防线

实测默认值与说明：

"security": {
  "tool_guard": {
    "enabled": true,
    "denied_tools": [],
    "auto_denied_rules": ["SAFETY_CHECKS_DESTRUCTIVE_COMMAND"],
    "shell_evasion_checks": {
      "command_substitution": false,
      "obfuscated_flags": false,
      "newlines": false, ...
    }
  },
  "file_guard": {
    "enabled": true,
    "sensitive_files": [],
    "allow_preview_outside_workspace": true
  },
  "skill_scanner": { "mode": "warn", "timeout": 30, "whitelist": [] },
  "sandbox_enabled": false,
  "allow_no_auth_hosts": ["127.0.0.1", "::1"],
  "trusted_proxies": []
}

5.4 tools 段：内置工具开关

tools.builtin_tools 下共 25 个工具条目（实测枚举），每条结构相同（name/enabled/description/display_to_user/async_execution/icon）。常用开关举例：

5.5 mcp 段：接入外部 MCP 工具

默认内置一个 anysearch 示例客户端（实测默认值）：

"mcp": {
  "clients": {
    "anysearch": {
      "name": "anysearch_mcp",
      "enabled": false,
      "transport": "streamable_http",
      "url": "https://api.anysearch.com/mcp",
      "headers": { "Authorization": "Bearer ${ANYSEARCH_API_KEY}" }
    }
  }
}

新增 MCP 工具即照此结构加客户端段：transport 支持 streamable_http 与 stdio 类（command/args 字段），tools 字段可白名单只暴露部分工具。${ANYSEARCH_API_KEY} 类引用取值来自 qwenpaw env set 写入的环境变量表。

5.6 browser 段：浏览器自动化

实测关键默认值：experimental: true（v2.2.2 默认走统一浏览器 beta，启动日志提示 Set browser.experimental=false to use the deprecated stable browser implementation）、backend: "auto"、headless: "auto"、cdp_url: null（可指向已有 Chrome 的调试端口）、proxy: null（浏览器出口代理，与 Discord 的 http_proxy 相互独立）、idle_ttl_seconds: 600（会话空闲回收）。

5.7 acp 段：外部编码 Agent 集成

实测默认内置四个 ACP Agent：

trusted: true 表示允许这些外部 Agent 在委托范围内执行；stdio_buffer_limit_bytes: 52428800 为 50MB 的进程输出缓冲上限。

5.8 全局杂项

• user_timezone：默认 UTC（Ubuntu 22.04 最小安装无时区配置时实测如此，启动日志有 Can not find any timezone configuration, defaulting to UTC 提示）。服务器在国内务必改成 Asia/Shanghai，否则心跳、cron 展示时间全是 UTC。
• show_tool_details：true，Console/TUI 里展示工具调用细节。
• skill_paths：[]，追加自定义技能目录（数组形式，可多个）。

六、生产配置模板

适用场景：8GB 内存个人/小团队服务器，Ubuntu 22.04，单人使用，接钉钉，安全加固优先。以下模板只列需要改动的键（其余保持默认），逐项给出实测验证过的写法：

{
  "user_timezone": "Asia/Shanghai",
  "channels": {
    "dingtalk": {
      "enabled": true,
      "client_id": "ding<你的应用Key>",
      "client_secret": "<你的应用密钥>",
      "robot_code": "<你的机器人编码>",
      "dm_policy": "allowlist",
      "allow_from": ["<你的钉钉userId>"],
      "group_policy": "allowlist",
      "require_mention": true,
      "streaming_enabled": true
    }
  },
  "agents": {
    "defaults": {
      "heartbeat": {
        "enabled": true,
        "every": "6h",
        "activeHours": { "start": "09:00", "end": "22:00" }
      }
    },
    "running": {
      "shell_command_timeout": 120.0,
      "llm_max_concurrent": 5
    }
  },
  "security": {
    "tool_guard": {
      "enabled": true,
      "shell_evasion_checks": {
        "command_substitution": true,
        "obfuscated_flags": true,
        "newlines": true
      }
    },
    "file_guard": {
      "enabled": true,
      "sensitive_files": ["/root/.ssh/", "/root/.aws/", "/root/.bashrc"]
    },
    "skill_scanner": { "mode": "block", "timeout": 30 },
    "allow_no_auth_hosts": ["127.0.0.1", "::1"]
  }
}

逐项说明：dm_policy/group_policy: allowlist + allow_from 把准入收敛到指定人（官方安全面板的首要建议）；require_mention: true 群内只响应 @消息；心跳限定 09:00–22:00 避免夜间打扰（activeHours 写成 {"start": "...", "end": "..."} 对象，不要写成数组）；Shell 混淆检测三项开启提高命令注入门槛；sensitive_files 里尾斜杠目录条目按前缀连文件带子目录一并拦截、普通条目精确匹配，挡住私钥与 Shell 配置；skill_scanner.mode: block 让高危技能直接拒装。修改后执行 qwenpaw daemon reload-config 热生效（回显见 3.2 节）。

⚠️ 注意：模板中 <你的应用Key> 类占位请替换为你自己在钉钉开放平台创建应用后拿到的真实值；这类第三方凭据不属于文档演示账号，不要把真实密钥写进任何文档或仓库。

七、常见问题

Q1：改了 config.json 没生效？ 必须热重载或重启：qwenpaw daemon reload-config（实测回显 "Config reloaded"）。若通过 systemd 托管，也可以 systemctl restart qwenpaw（实测 restart 后 systemctl is-active 返回 active）。JSON 语法错误会导致重载失败，改前先跑 qwenpaw doctor（实测会对 Config 段输出 OK — /root/.qwenpaw/config.json，语法错误时在此报错）。

Q2：init 时提示 make-skill 有 CRITICAL 发现？ 实测初始化日志出现 Skill 'make-skill' has 1 security finding(s) (max severity: CRITICAL) but blocking is disabled – proceeding anyway.——默认 skill_scanner.mode: warn 只警告不拦截。介意就把 security.skill_scanner.mode 改为 block，或用 security.skill_scanner.whitelist 精确放行。

Q3：时区为什么是 UTC？ Ubuntu 22.04 最小环境没有时区配置，QwenPaw 回退 UTC（启动日志实测警告）。改 user_timezone: "Asia/Shanghai" 并 reload，验证方法见 3.2 节的 cron 继承实测。

Q4：如何确认某个工具/渠道当前的实际配置？ 工具看 tools.builtin_tools.<name>.enabled；渠道用 qwenpaw channel list（实测按 Agent 列出每个渠道的全部键值，disabled 渠道同样完整展示）；模型与提供商用 qwenpaw models list。

Q5：能同时在多台机器共享一份 config.json 吗？ 不建议。config.json 里含工作区绝对路径（如 /root/.qwenpaw/workspaces/default）与渠道凭据，跨机复制易踩路径与密钥两坑。多实例需求用 v2.2.0 起的 qwenpaw hub 多用户形态。

八、参考链接

1. GitHub 仓库：https://github.com/agentscope-ai/QwenPaw （查询日期 2026-10-22）
2. 官方文档站：https://qwenpaw.agentscope.io/ （查询日期 2026-10-22）
3. PyPI 项目页：https://pypi.org/project/qwenpaw/ （查询日期 2026-10-22）
4. 本系列同版本篇目：《Ubuntu 22.04 安装 QwenPaw 2.2.2 指南》、《QwenPaw 2.2.2 常用 CLI 命令与工具详解》