ActivityWatch 0.14.1 配置参数详解

目标：逐项讲清 ActivityWatch 0.14.1 的全部配置载体与参数——服务器端 aw-server.toml（Python 版）与 config.toml（Rust 版）、托盘管理器 aw-qt.toml、各采集器配置、客户端 aw-client.toml，并给出可直接落地的生产配置模板。文中所有默认值与行为回显均在 Ubuntu 22.04（22.04.5 LTS）+ ActivityWatch v0.14.1 环境实测取得。

一、环境信息

• 操作系统：Ubuntu 22.04（22.04.5 LTS，x86_64）
• 软件版本：ActivityWatch v0.14.1（官方最新稳定版，查询日期 2026-10-22）
• 服务器实现：aw-server（Python/Flask，默认）与 aw-server-rust（Rust）双实现
• 配置根目录：~/.config/activitywatch/（本文以 root 运行为 /root/.config/activitywatch/）
• 数据目录：~/.local/share/activitywatch/
• 服务端口：默认 5600（testing 配置段 5666）
• 安装形态：官方 zip 全家桶解压至 /opt/activitywatch，systemd 托管（安装过程见《Ubuntu 22.04 安装 ActivityWatch 0.14.1 指南》）

二、前置条件

• 已按安装指南完成 aw-server 安装并可用 curl -s http://localhost:5600/api/0/info 取到版本信息（返回 {"hostname": ..., "version": "v0.14.1", ...}）；
• 已启动过至少一次 aw-server（配置文件在首次启动时自动生成，未启动过则不存在）；
• 修改配置需具备对 ~/.config/activitywatch/ 的写权限，systemd 托管方式下修改后要 systemctl restart aw-server 才生效。

三、参数查看与修改方式

3.1 配置文件的自动生成机制

aw-server（Python 版）首次启动时，若配置文件不存在，会把内置默认值以全注释形式写入 ~/.config/activitywatch/aw-server/aw-server.toml。实测首次启动后查看该文件：

cat /root/.config/activitywatch/aw-server/aw-server.toml

[server]
#host = "localhost"
#port = "5600"
#storage = "peewee"
#cors_origins = ""
## Cache query results for finished past periods in memory (see query_cache.py)
#query_cache = true

[server.custom_static]

[server.auth]
## Uncomment and set to enable API key authentication for /api/* endpoints.
## Clients must send: Authorization: Bearer <api_key>
## GET /api/0/info and OPTIONS preflight requests are always public.
## api_key = ""

[server-testing]
#host = "localhost"
#port = "5666"
#storage = "peewee"
#cors_origins = ""
#query_cache = true

[server-testing.custom_static]

[server-testing.auth]
#api_key = ""

解读三条规则：

• 注释即默认：所有键都以 # 注释列出，取消注释并改值即覆盖默认；保持注释则用内置默认；
• 配置段按 profile 划分：[server] 对应默认实例，[server-testing] 对应 --testing 实例（两者数据、端口完全隔离）；
• 嵌套表：[server.custom_static]、[server.auth] 是 [server] 的子表（TOML 点号嵌套）。

3.2 修改与生效流程

标准流程是「编辑 TOML → 重启服务 → 用回显验证」三步。以改绑定地址为例：

sed -i 's|^#host = "localhost"|host = "0.0.0.0"|' /root/.config/activitywatch/aw-server/aw-server.toml
systemctl restart aw-server
sleep 8
journalctl -u aw-server --no-pager -n 20 | grep "Running on"

 * Running on all addresses (0.0.0.0)
 * Running on http://127.0.0.1:5600
 * Running on http://10.89.59.2:5600  (werkzeug:187)

⚠️ 注意：上面的 sed 会把 [server-testing] 段里的同名注释一并替换（两段各有一行）。若只需要改默认实例，建议手工编辑文件只动 [server] 段；[server-testing] 段的 host 保持注释不影响正常使用（仅影响 --testing 模式）。

验证服务仍健康：

systemctl is-active aw-server
curl -s http://localhost:5600/api/0/info

active
{"hostname": "aw-server01", "version": "v0.14.1", "testing": false, "device_id": "a34e4cfc-7992-4c03-a7a2-7422da090665", "profile": "default"}

3.3 命令行参数与配置文件的关系

aw-server --help（实测，含 PyInstaller 打包的固定告警行，节选）：

usage: aw-server [-h] [--testing] [--profile PROFILE] [--verbose] [--version]
                 [--log-json] [--host HOST] [--port PORT] [--storage STORAGE]
                 [--cors-origins CORS_ORIGINS] [--custom-static CUSTOM_STATIC]

Starts an ActivityWatch server

optional arguments:
  -h, --help            show this help message and exit
  --testing             Run aw-server in testing mode using different ports
                        and database (alias for --profile testing)
  --profile PROFILE     Named instance profile (data, config, port and
                        settings are isolated). --testing is an alias for
                        --profile testing.
  --verbose             Be chatty.
  --version             Print version and quit
  --log-json            Output the logs in JSON format
  --host HOST           Which host address to bind the server to
  --port PORT           Which port to run the server on
  --storage STORAGE     The method to use for storing data. Some methods (such
                        as MongoDB) require specific Python packages to be
                        available (in the MongoDB case: pymongo)
  --cors-origins CORS_ORIGINS
                        CORS origins to allow (as a comma separated list)
  --custom-static CUSTOM_STATIC
                        The custom static directories. Format:
                        watcher_name=path,watcher_name2=path2,...

命令行参数优先于配置文件。实测用 --port 5667 覆盖启动（不改任何配置）：

cd /opt/activitywatch && ./aw-server/aw-server --port 5667

 * Running on all addresses (0.0.0.0)
 * Running on http://127.0.0.1:5667
 * Running on http://10.89.59.2:5667  (werkzeug:187)

curl -s http://localhost:5667/api/0/info

{"hostname": "aw-server01", "version": "v0.14.1", "testing": false, "device_id": "a34e4cfc-7992-4c03-a7a2-7422da090665", "profile": "default"}

注意回显中 "testing": false——仅改端口不会切换 profile，数据仍读写默认库。运维建议：长期参数写配置文件（systemd 托管场景改动可追溯），命令行参数留给临时调试。

3.4 testing 与 profile 隔离机制

--testing 是 --profile testing 的别名。实测 --testing 启动后的三处隔离（完整回显）：

./aw-server/aw-server --testing

2026-10-22 16:36:41 [INFO ]: Using database file: /root/.local/share/activitywatch-testing/aw-server/peewee-sqlite.v2.db  (aw_datastore.storages.peewee:189)
 * Running on http://localhost:5666  (werkzeug:187)

curl -s http://localhost:5666/api/0/info

{
    "hostname": "aw-server01",
    "version": "v0.14.1",
    "testing": true,
    "device_id": "d7f4696c-19af-4631-a8c1-6e89917eef42",
    "profile": "testing"
}

三处隔离：端口（5666）、数据目录（~/.local/share/activitywatch-testing/）、设备 ID（重新生成）。配合 [server-testing] 配置段，testing 实例与生产实例互不影响。自定义命名 profile（--profile dev）会读 [server-dev] 段，并把配置/数据目录全部切到 activitywatch-dev 命名空间下。

四、参数总览

ActivityWatch 0.14.1 共有 5 个配置载体，作用域各不相同：

关键解读：没有集中配置——每个进程读自己的配置文件，这是「多进程松耦合」架构（见《ActivityWatch 0.14.1 介绍与选型指南》第三章）在配置面的体现；服务器形态（无桌面）只需要关心 aw-server.toml（或 Rust 版 config.toml）。

五、核心参数分类详解

5.1 [server] host —— 绑定地址

• 默认值："localhost"（只监听 127.0.0.1）
• 作用：aw-server HTTP 服务的绑定地址
• 实测：改为 host = "0.0.0.0" 后重启，日志变为 Running on all addresses (0.0.0.0) 并列出所有本机地址（见 3.2 回显）；REST API 与 Web UI 立即对外可达
• 建议：默认 localhost 最安全（配合 SSH 隧道远程访问，见安装指南 9.4）；确需对外时必须连同 5.6 的 api_key 一起启用

5.2 [server] port —— 监听端口

• 默认值："5600"（注意 TOML 里是带引号的字符串，实测保持原样即可）
• 作用：HTTP 监听端口；Web UI 与 REST API 同端口
• 关联：[server-testing] 段默认 5666，实测 --testing 启动即监听 5666
• 注意：改端口后，所有采集器与客户端默认仍连 5600，需同步修改（采集器可用 --port 参数，aw-client 改 aw-client.toml，见 5.10）

5.3 [server] storage —— 存储后端

• 默认值："peewee"（SQLite 封装）
• 可选值：peewee（唯一官方支持）、mongodb（需另装 pymongo，实验性）、raw sqlite 实验性。官方论坛答复明确：仅 peewee 是受官方支持的数据库后端，MongoDB/裸 SQLite 均为实验性、不推荐（来源：ActivityWatch 论坛官方回复，2026-10-22 查询）
• 数据落点：~/.local/share/activitywatch/aw-server/peewee-sqlite.v2.db（实测文件名，另有 -wal/-shm 伴生文件）
• 建议：保持 peewee 不动；不要在生产上切 MongoDB

5.4 [server] query_cache —— 查询缓存

• 默认值：true
• 作用：对「已完成的历史时段」的查询结果做内存缓存（配置文件注释原文：Cache query results for finished past periods in memory），重复刷新历史统计时显著降载
• 取舍：历史数据不再变化的场景缓存永远有效；调试自定义查询（改分类规则后想立即看到新结果）时若发现结果没变，可临时关闭再开，或重启服务清缓存

5.5 [server] cors_origins —— 跨域来源

• 默认值：""（空，仅允许同源）
• 作用：逗号分隔的额外 CORS 允许来源列表，供第三方 Web 前端跨域调用 REST API
• 实测注意：本机 Web UI（http://localhost:5600）始终同源可用；只有自建网页要直连服务器 API 时才需要配置

5.6 [server.auth] api_key —— REST API 认证

• 默认值：""（空，不启用认证）
• 作用：设置后，除 GET /api/0/info 与 OPTIONS 预检外，所有 /api/* 请求必须携带 Authorization: Bearer <key> 头（配置注释原文与实测一致）
• 实测行为（设 api_key = "q1w2e3r4" 后重启）：

curl -s -o /dev/null -w "%{http_code}\n" http://localhost:5600/api/0/buckets/

401

curl -s http://localhost:5600/api/0/buckets/

{"message": "Missing or invalid API key. Set Authorization: Bearer <key> header."}

curl -s -H "Authorization: Bearer q1w2e3r4" http://localhost:5600/api/0/buckets/

{"test-bucket": {"id": "test-bucket", ...}}

（第三个回显为节选；带正确 Key 的请求正常返回桶列表。）

• 注意：GET /api/0/info 恒为公开（实测 200），版本信息不算敏感；host = "0.0.0.0" 对外暴露时 api_key 是必选项而非可选项

5.7 [server.custom_static] —— 自定义静态资源

• 默认值：空表
• 作用：为指定 watcher 前端提供自定义静态目录，键为 watcher 名、值为路径；对应命令行 --custom-static watcher_name=path,watcher_name2=path2（--help 原文）
• 适用：仅自研 watcher 带网页前端时使用，普通部署保持默认

5.8 [server-testing] 段 —— testing 实例参数

键与 [server] 一致（host/port/storage/cors_origins/query_cache），默认端口 5666、数据目录独立（见 3.4 实测）。该段只被 --testing/--profile testing 实例读取，日常不碰；[server-testing.auth] api_key 同理保护 testing API。

5.9 Rust 版 config.toml 参数（aw-server-rust）

Rust 版配置路径与键名自成一套：~/.config/activitywatch/aw-server-rust/config.toml，首次启动自动生成（实测原文）：

### DEFAULT SETTINGS ###
#address = "127.0.0.1"
#port = 5600
#cors = []
#cors_regex = []
#query_cache = true
#
#[auth]
#
#[custom_static]

关键解读：Rust 版数据库独立于 Python 版（~/.local/share/activitywatch/aw-server-rust/sqlite.db），但首次启动会自动导入 Python 版遗留库（实测日志 Found legacy database ... Successfully imported legacy database）。两套实现不要同时启动（5600 端口冲突）。

5.10 aw-qt.toml —— 托盘管理器（桌面形态）

实测自动生成内容：

[aw-qt]
#autostart_modules = ["aw-server", "aw-watcher-afk", "aw-watcher-window"]
## Enable OS-level start-at-login on first launch (Research Edition builds
## flip this to true; the user can still disable it from the tray afterwards).
#autostart_on_first_run = false

[aw-qt-testing]
#autostart_modules = ["aw-server", "aw-watcher-afk", "aw-watcher-window"]
#autostart_on_first_run = false

• autostart_modules：aw-qt 启动时拉起的模块清单，默认三件套（server + afk + window）；不想采集输入可在此增删（aw-watcher-input 也以模块形式被识别，实测 aw-qt 启动日志报 Found 7 bundled modules）
• autostart_on_first_run：首次运行是否注册系统级自启动（默认 false）
• 服务器形态不使用 aw-qt：此文件仅在有桌面会话的机器上有意义

5.11 aw-watcher-afk.toml —— AFK 采集器

[aw-watcher-afk]
#timeout = 180
#poll_time = 5

[aw-watcher-afk-testing]
#timeout = 20
#poll_time = 1

• timeout = 180：键鼠空闲多少秒判定为 AFK（离开）；
• poll_time = 5：每 5 秒采样一次空闲时长；
• 判定 AFK 后窗口时长统计会在分析层与 AFK 时间做交集，避免"人走了屏幕还亮"的虚增时长。
• 命令行等价参数（实测 --help）：--timeout TIMEOUT、--poll-time POLL_TIME、--host HOST、--port PORT。

5.12 aw-watcher-window.toml —— 窗口采集器

[aw-watcher-window]
#exclude_title = false
#exclude_titles = []
#poll_time = 1.0
#strategy_macos = "swift"

• exclude_title = false：是否完全不记录窗口标题（隐私敏感场景设 true，只记应用名）；
• exclude_titles = []：按正则排除特定标题的窗口（列表，支持多值）；
• poll_time = 1.0：每 1 秒取一次前台窗口；
• strategy_macos = "swift"：macOS 取窗策略（swift/applescript/jxa），Linux 不涉及；
• 命令行等价参数（实测 --help）：--exclude-title、--exclude-titles EXCLUDE_TITLES [EXCLUDE_TITLES ...]（可多次指定）、--poll-time POLL_TIME、--research（Research Edition 模式开关）。

5.13 aw-client.toml —— Python 客户端库

实测自动生成内容：

[server]
#hostname = "127.0.0.1"
#port = "5600"

[client]
#commit_interval = 10

[server-testing]
#hostname = "127.0.0.1"
#port = "5666"

[client-testing]
#commit_interval = 5

• hostname/port：客户端默认连接的 aw-server 地址（与服务器配置呼应）；
• commit_interval = 10：客户端队列每 10 秒向服务器批量提交一次缓存事件（服务器不可达时事件先入队，恢复后续传——这正是官方 FAQ 说的"服务器挂了 watcher 会排队"的行为基础）。

六、生产配置模板

6.1 服务器形态模板（2GB 内存 / 任意磁盘 / 自托管 Web UI + 受控内网访问）

适用：Ubuntu 22.04 服务器、无桌面、内网跳板访问，开启 API Key。

[server]
host = "0.0.0.0"
#port = "5600"
#storage = "peewee"
#cors_origins = ""
#query_cache = true

[server.custom_static]

[server.auth]
api_key = "q1w2e3r4"

[server-testing]
#host = "localhost"
#port = "5666"
#storage = "peewee"
#cors_origins = ""
#query_cache = true

[server-testing.custom_static]

[server-testing.auth]
#api_key = ""

逐项说明：仅放开 host（对内网提供 Web UI）与 api_key（示例演示口令，生产请换成自己的强随机值）；storage/query_cache/cors_origins 保持默认——SQLite 单机存储实测服务器驻留内存约 35MB（安装指南 4.7 实测 status 回显），2GB 内存绰绰有余；磁盘占用与追踪历史线性相关（SQLite 单文件），按年 GB 级即可。改完执行 systemctl restart aw-server，并按 5.6 的 curl 命令验证 401/200 行为。

6.2 桌面形态模板（本机使用 / 最保守隐私）

适用：个人电脑 aw-qt 托管全家桶，只改隐私项。

[aw-watcher-window]
exclude_title = false
exclude_titles = ["密码|token|secret"]
#poll_time = 1.0
#strategy_macos = "swift"

[aw-watcher-afk]
#timeout = 180
#poll_time = 5

说明：exclude_titles 用正则把含敏感词的窗口标题排除出记录（服务器端配置文件与命令行参数均可，此处为配置文件写法）；其余保持默认。桌面机服务器端 aw-server.toml 无需改动（本机 localhost 访问，无需开认证）。

七、常见问题（FAQ）

Q1：改了配置完全没生效？

先核对路径：配置必须改在 ~/.config/activitywatch/aw-server/aw-server.toml（目录名是 activitywatch）。实测把配置写到 ~/.config/aw-server/（旧版 aw-server.ini 时代的路径，网上老教程常见）重启后日志仍是 Running on http://localhost:5600，改写正确路径后立即生效（Running on all addresses (0.0.0.0)）。快速核对命令：

find /root/.config -name "aw-server.toml"

/root/.config/activitywatch/aw-server/aw-server.toml

（若同时出现 /root/.config/aw-server/aw-server.toml，那是被误创建的无效文件，可删。）

Q2：TOML 写错导致服务起不来？

TOML 语法错误会让 aw-server 直接退出。实测把 host = 0.0.0.0（漏了引号，被解析为非法数字）写入后启动：

tomlkit.exceptions.InvalidNumberError: Invalid number at line 2 col 14
[PYI-4494:ERROR] Failed to execute script '__main__' due to unhandled exception!

进程 exit=1。排障方法：看 journald 报错行号（line 2 col 14），修正引号/表头后重启即可。改配置前先备份，或用 python3 -c "import tomlkit;tomlkit.parse(open('/root/.config/activitywatch/aw-server/aw-server.toml').read())" 预检语法。

Q3：改了端口后 Web UI 能开，但客户端/采集器连不上？

各客户端默认连 5600：采集器要加 --port <新端口> 参数（aw-qt 场景写在 aw-qt.toml 的模块参数里），Python 客户端库改 aw-client.toml 的 [server] port。服务器端只负责监听，不会通知客户端。

Q4：设置 api_key 后 Web UI 打不开数据？

浏览器访问 Web UI 时页面会弹出 Key 输入框，填入配置的 api_key 即可；直接调 REST API 的脚本必须带 Authorization: Bearer <key> 头（见 5.6 实测回显，缺头返回 401 与提示 JSON）。另外注意 GET /api/0/info 不需要 Key（设计如此，版本信息公开）。

Q5：query_cache 开着，改了分类规则怎么结果没变？

query_cache 只缓存「已完成的历史时段」，当天与最近时段不受影响；若确需强制刷新历史统计，临时把 query_cache = false 重启后再改回 true（重启本身会清空内存缓存）。

八、参考链接

• 官方配置文档：https://docs.activitywatch.net/en/latest/config.html
• aw-server 仓库（配置源码 config.py/default_config）：https://github.com/ActivityWatch/aw-server
• aw-server-rust 仓库：https://github.com/ActivityWatch/aw-server-rust
• aw-qt 仓库：https://github.com/ActivityWatch/aw-qt
• 官方论坛（存储后端官方答复）：https://forum.activitywatch.net/t/use-aw-server-with-mysql-backend/154
• 本专栏相关：《Ubuntu 22.04 安装 ActivityWatch 0.14.1 指南》、《ActivityWatch 0.14.1 介绍与选型指南》、《ActivityWatch 0.14.1 API 使用详解》