Copaw 2.2.2 配置参数详解

目标：把 Copaw（现名 QwenPaw）的两层配置文件（全局 config.json 与智能体 agent.json）、敏感数据目录、环境变量注入机制与热加载规则讲透，所有字段以 2.2.2.post1 在 Ubuntu 24.04 服务器上的实测落盘内容为准，并给出生产配置模板。命令与回显均为逐条实测照抄。

一、环境信息

💡 提示：Copaw 已更名 QwenPaw，包名、命令、目录全部为 qwenpaw；选型背景见《Copaw 2.2.2 介绍与选型指南》。

二、前置条件

本文假设已完成 pip 安装与初始化。若尚未安装：

python3 -m venv /opt/qp-venv
/opt/qp-venv/bin/pip install "qwenpaw==2.2.2.post1"
source /opt/qp-venv/bin/activate
qwenpaw --version
# QwenPaw, version 2.2.2.post1

初始化（本文全部实测均在此之后）：

qwenpaw init --defaults --accept-security

⚠️ 实测坑：qwenpaw init --defaults 在非交互环境（脚本、CI、无 TTY）会因安全须知确认步骤直接失败：

Warning: Input is not a terminal (fd=0).
Aborted!

必须显式加 --accept-security 跳过确认才能全程非交互完成。

三、参数查看与修改方式

QwenPaw 的配置有四条操作通道，生效时机各不相同：

3.1 Web 控制台（图形化）

qwenpaw app 启动后浏览器打开 http://127.0.0.1:8088/：设置 → 模型（提供商/活跃模型）、频道、定时任务、技能、安全等大部分字段可视化编辑，保存即写回 config.json / agent.json。

3.2 CLI 子命令

qwenpaw models config-key dashscope   # 配提供商 API Key
qwenpaw env set KEY VALUE             # 工具环境变量
qwenpaw channels config               # 交互式启用/配置频道
qwenpaw daemon reload-config          # 重新读取并校验配置

3.3 直接编辑 JSON 文件

vi ~/.qwenpaw/config.json                    # 全局层
vi ~/.qwenpaw/workspaces/default/agent.json  # 智能体层

服务进程内置配置监视器（日志实测 AgentConfigWatcher started: poll=2.0s），agent.json 修改约 2 秒轮询自动热加载，无需重启（3.4 节实测）。全局结构性变更建议执行 qwenpaw daemon reload-config 校验。

3.4 热加载实测

在 agent.json 中把 approval_level 从 SMART 改为 OFF 后不重启服务，5 秒后经 API 查询运行时值：

$ curl -sS http://127.0.0.1:8088/api/agents/default | python3 -c "import json,sys;print('approval_level:',json.load(sys.stdin).get('approval_level'))"
approval_level: OFF

文件改动已被运行中的服务采纳，热加载成立。

3.5 环境变量注入（需重启）

QWENPAW_* 系列变量在进程启动时读取，修改后必须重启 qwenpaw app 才生效；它们只能以 shell 环境方式注入（如 systemd Environment= 或 profile），不可写入 config.json。

四、参数总览

4.1 目录结构（init 后实测）

/root/.qwenpaw/
├── config.json                    # 全局配置（实测 32 KB，含全量默认字段）
├── HEARTBEAT.md                   # 心跳自检清单
├── qwenpaw.log                    # 运行日志
├── .telemetry_collected
├── skill_scanner_blocked.json     # 被技能扫描器拦截的记录
├── plugins/                       # 插件
├── skill_pool/                    # 共享技能池
└── workspaces/
    ├── default/                   # 默认智能体工作区
    │   ├── agent.json             # 智能体配置（实测 13 KB）
    │   ├── chats.json             # 对话历史
    │   ├── jobs.json              # 定时任务
    │   ├── credentials.yaml       # 加密凭据库
    │   ├── MEMORY.md              # 长期记忆
    │   ├── AGENTS.md / SOUL.md / PROFILE.md / BOOTSTRAP.md  # 人设文件
    │   ├── skill.json             # 技能启用状态
    │   ├── skills/                # 工作区技能
    │   └── memory/                # 每日记忆文件
    └── QwenPaw_QA_Agent_0.2/      # init 自动创建的内置 QA 智能体

/root/.qwenpaw.secret/
├── auth.json                      # 控制台登录用户（启用认证时）
├── envs.json                      # 环境变量（加密存储）
├── .master_key                    # 主密钥（丢失则密文不可恢复）
└── providers/
    ├── active_model.json          # 当前活跃模型
    ├── builtin/                   # 已配置的内置提供商（每提供商一个 json）
    ├── custom/                    # 自定义提供商
    └── plugin/                    # 插件注册的提供商

💡 说明：官方文档早期口径为 providers.json 单文件，2.2.2 实测已演进为 providers/ 目录（按提供商分文件 + active_model.json），以实测为准。

4.2 路径与行为覆盖变量

五、核心参数分类详解

5.1 全局 config.json

实测顶层键：agents、channels、mcp、tools、security、workspace、plugins、custom、last_api、show_tool_details、user_timezone（另含 browser、acp、telemetry 等扩展段）。

核心字段：

实测 agents 段（init --defaults 后）：

{
  "active_agent": "default",
  "profiles": {
    "default": {
      "id": "default", "name": "default",
      "description": "The default agent", "workspace_dir": "/root/.qwenpaw/workspaces/default",
      "enabled": true
    },
    "QwenPaw_QA_Agent_0.2": { "...": "内置 QA 智能体，init 时自动注册" }
  }
}

💡 提示：32 KB 的 config.json 里 channels/mcp/tools/security 顶层段是向后兼容残留——自 v0.1.0 多智能体起，频道/MCP/工具/安全的真实生效配置在各智能体的 agent.json 里，全局段仅作旧版本迁移兼容。别在全局 channels 里改配置，改了不生效。

其他扩展段实测摘录：

• browser：浏览器技能后端选择（backend/identity/engine/headless/viewport 等，多为 auto）；
• security.tool_guard：enabled: true、auto_denied_rules: ["SAFETY_CHECKS_DESTRUCTIVE_COMMAND"]、shell_evasion_checks（命令替换/混淆检测，默认关）；
• tools.builtin_tools：每个内置工具的 enabled/display_to_user/async_execution 开关；
• acp.agents：ACP 协议外部编码智能体注册（opencode、qwen_code 默认启用）。

5.2 智能体 agent.json

实测顶层键：id、name、description、workspace_dir、project_dirs、backend、backend_settings、channels、mcp、running、llm_routing、fallback_models、fallback_policy、thinking_level、language、approval_level、system_prompt_files、tools、security、acp、plan、coding_mode。

① 频道 channels（18 类全字段落盘）

实测键序：imessage, discord, dingtalk, feishu, qq, telegram, mattermost, mqtt, console, matrix, voice, sip, wecom, xiaoyi, yuanbao, wechat, slack, onebot。公共字段：

"console": {
  "enabled": true, "bot_prefix": "",
  "show_tool_calls": true, "show_tool_results": true,
  "tool_call_max_length": 200, "tool_result_max_length": 500,
  "show_thinking": true, "deny_message": ""
},
"discord": { "enabled": false, "...": "各频道另有专属凭据字段（token/secret 等）" }

② 运行时 running（实测默认值）

③ 模型路由与安全

④ 人设与工具：system_prompt_files（AGENTS.md/SOUL.md/PROFILE.md 等加载清单）、tools（工作区级工具开关）、mcp（该智能体的 MCP 客户端配置）、coding_mode/project_dirs（编码模式与绑定项目）。

5.3 敏感数据目录（secret）

• providers/builtin/*.json：已配置提供商的完整定义（base_url、api_key、模型表）。实测 active_model.json：

{ "provider_id": "kilo", "model": "kilo-auto/free" }

• envs.json：加密存储的工具环境变量。qwenpaw env set TAVILY_API_KEY "tvly-demo123456" 后文件内容为 ENC:gAAAA...（Fernet 密文，密钥在 .master_key/钥匙串）；
• auth.json：启用 QWENPAW_AUTH_ENABLED 后自动注册的管理员凭据。

⚠️ 红线：.master_key 丢失 = 所有加密 API Key 与环境变量不可恢复。备份必须工作目录与 secret 目录成对进行。

5.4 环境变量管理实测

$ qwenpaw env set TAVILY_API_KEY "tvly-demo123456"
✓ Environment variable 'TAVILY_API_KEY' saved...

$ qwenpaw env list
Environment Variables (1 total):
  TAVILY_API_KEY
    tvly-demo123456

$ qwenpaw env delete TAVILY_API_KEY
✓ Environment variable 'TAVILY_API_KEY' deleted.

$ qwenpaw env list
No environment variables configured.

5.5 QWENPAW_WORKING_DIR 覆盖实测

$ QWENPAW_WORKING_DIR=/tmp/qp-alt qwenpaw daemon status
Agent: default
**Daemon Status**
- Config loaded: yes
- Max input length: 256000
- Working dir: /tmp/qp-alt/workspaces/default
- Memory manager: not attached

目录被即时创建、配置隔离——多套环境共存或测试实例的标准做法。

六、生产配置模板

① 服务单元（systemd 摘要，Environment 注入启动级变量）：

[Service]
User=qwenpaw
Environment=QWENPAW_WORKING_DIR=/srv/qwenpaw/working
Environment=QWENPAW_SECRET_DIR=/srv/qwenpaw/secret
Environment=QWENPAW_LOG_LEVEL=info
Environment=QWENPAW_AUTH_ENABLED=true
ExecStart=/opt/qp-venv/bin/qwenpaw app --host 127.0.0.1 --port 8088
Restart=always

② agent.json 生产建议片段：

{
  "approval_level": "SMART",
  "llm_routing": "cloud_only",
  "fallback_models": ["dashscope:qwen3.5-plus"],
  "fallback_policy": "sequential",
  "running": {
    "llm_retry_enabled": true, "llm_max_retries": 3,
    "llm_max_concurrent": 5, "llm_max_qpm": 300,
    "max_input_tokens": 256000
  },
  "security": {
    "file_guard": { "enabled": true },
    "tool_guard": { "enabled": true },
    "allow_no_auth_hosts": ["127.0.0.1"]
  }
}

③ 检查清单：

• 反向代理终结 TLS，服务保持 127.0.0.1 监听；
• QWENPAW_AUTH_ENABLED=true，allow_no_auth_hosts 不放行公网段；
• working 与 secret 目录每日成对备份（cron + qwenpaw cron 可用自家定时任务做）；
• user_timezone 显式设为 Asia/Shanghai；
• 技能扫描保持 warn/block，勿生产设 off；
• 升级前用 qwenpaw doctor fix --dry-run 预检目录结构。

七、常见问题

Q1：脚本里跑 qwenpaw init --defaults 直接 Aborted!？

非 TTY 下安全须知确认无法应答。加 --accept-security（实测可全程非交互完成）。

Q2：改了全局 config.json 的 channels 段，频道没反应？

多智能体版本起频道配置在 agent.json，全局段仅向后兼容。改 ~/.qwenpaw/workspaces/default/agent.json 的 channels，2 秒热加载生效（实测见 3.4）。

Q3：服务没启动时 doctor 报 API FAIL，正常吗？

正常。实测 app 停止状态下 qwenpaw doctor 其余各段（Environment/Config/Agents/Channels/MCP/Skills/Security/Cron/Working directory/Startup paths）全部 OK，仅末尾 API 段因无监听而失败：

=== API ===
FAIL — health not reachable (http://127.0.0.1:8088/api/healthz)
[Errno 111] Connection refused
Hint: start the server with `qwenpaw app` (default http://127.0.0.1:8088).

若 Config 段报缺失，则是未 init 或 QWENPAW_WORKING_DIR 指错（实测指向空目录时 Agents 段直接 FAIL：workspace_dir is not a directory: /tmp/qp-empty/workspaces/default）。生产上线前应把 FAIL/WARN 清零。

Q4：daemon reload-config 和热加载什么关系？

实测 app 停止时执行也成功——它只做本地 load_config() 重读校验，不依赖服务在线：

$ qwenpaw daemon reload-config
Agent: default

**Config reloaded**

- load_config() re-invoked successfully.

同理 daemon restart 在进程外只打印指引（Not running inside app. Run the app (e.g. qwenpaw app) and use /daemon restart in chat, or restart the process with systemd/supervisor/…）。频道/MCP 结构性变更要真正生效，需在对话中 /daemon restart 或重启进程；普通 agent.json 字段改动则 2 秒轮询自动热加载（见 3.4 实测）。

Q5：API Key 存哪了？为什么 envs.json 是一串 ENC: 乱码？

提供商 Key 在 secret/providers/{builtin,custom}/*.json，工具环境变量在 envs.json，后者经主密钥加密。手工编辑密文无效，请用 qwenpaw models config-key <provider> / qwenpaw env set 或控制台写入。

Q6：改 QWENPAW_LOG_LEVEL 等环境变量后为什么不生效？

此类变量进程启动时读取，热加载只覆盖 JSON 配置。重启 qwenpaw app（或 systemd restart）后生效。

Q7：多个实例如何共存？

每个实例独立设置 QWENPAW_WORKING_DIR + QWENPAW_SECRET_DIR（实测隔离生效，见 5.5），并用 --port 区分监听端口；主密钥账户名会随目录自动派生，互不覆盖。

八、参考链接

• 官方配置文档：https://qwenpaw.agentscope.io/docs/config.zh.md
• 官方模型文档：https://qwenpaw.agentscope.io/docs/models.zh.md
• 官方安全文档：https://qwenpaw.agentscope.io/docs/security.zh.md
• 站内：《Copaw 2.2.2 Docker Compose 部署指南》、《Copaw 2.2.2 常用 CLI 命令与工具详解》