配置说明

配置钩子密度、Claude Code 与 Codex、访问密码及其他设备连接。

钩子密度

密度决定监听事件的数量：

high：Claude Code 全部 14 个事件。
medium：默认 13 个事件，除 TeammateIdle 外全部启用，包括 SessionStart、UserPromptSubmit、PreToolUse、PostToolUse、PostToolUseFailure、PermissionRequest、Stop、Notification、SubagentStart、SubagentStop、TaskCompleted、PreCompact 和 SessionEnd。
low：SessionStart、UserPromptSubmit、PermissionRequest、Stop、SessionEnd 共 5 个事件。不包含工具事件与授权推断计时器，仍能直接收到 PermissionRequest。

在「设置 → HOOKS」选择并安装，或从源码运行：

npm run install-hooks -- --density low

也可设置 server-config.json 的 hookDensity。启动时会补充缺失事件，但不会移除已有事件；在界面降低密度后，也要同步配置以便重启后保留。

支持 Claude Code 与 Codex，暂不支持其他 CLI。Claude Code 最多 14 个事件，包含生命周期、授权与团队；Codex 所有密度都包含 SessionStart、UserPromptSubmit、PermissionRequest，中高密度额外包含 PreToolUse、PostToolUse、PreCompact、PostCompact；轮次结束通过 Codex 的 notify 回调到达。

{ "enabledClis": ["claude", "codex"] }

AASC 启动 Codex 时，会在所装版本支持的情况下添加 --no-daemon，以便将钩子匹配到终端进程。桌面「设置 → ADVANCED → Agent CLIs」和手机「More → Settings → Advanced」可查看与更新 CLI 版本。

服务配置文件

源码版：仓库内 data/server-config.json。
macOS：~/Library/Application Support/ai-agent-session-center/server-config.json。
Windows：%APPDATA%\ai-agent-session-center\server-config.json。
Linux：~/.config/ai-agent-session-center/server-config.json。

启动时读取一次，修改后需要重启。请保留文件内其他设置，不要覆盖整个文件。

port：默认 3333，HTTP 与 WebSocket 端口。
hookDensity：默认 medium，可选 high / medium / low。
debug：默认 false，是否启用详细日志。
processCheckInterval：默认 15000，检查会话进程是否存活的间隔，单位毫秒。
sessionHistoryHours：向导写入的保留选项，当前服务端不读取。
enabledClis：默认 ["claude"]，需要安装钩子的工具。
passwordHash：加盐 scrypt 密码哈希，使用 set-password 管理，不要手工编辑。
phonePairing：2.10.60 起默认开启，旧版默认关闭；环境变量 AASC_PHONE_PAIRING=1 或 0 优先。
mcp：中央会话配置，2.10.60 起默认关闭。

端口优先级

按 --port 参数 → PORT 环境变量 → 配置文件 → 默认 3333 的顺序决定。

npm start -- --port 8080
PORT=8080 npm start

现有服务在端口被占用时会强制结束占用进程再重试。运行第二个实例时，请显式使用其他端口。macOS/Linux 主要通过 /tmp/claude-session-center/ 文件队列接收钩子，不受端口变化影响；HTTP 备用路径固定指向 3333。

管理钩子

npm run install-hooks
npm run uninstall-hooks
npm run reset

分别安装、移除钩子和完整重置。安装器使用临时文件加重命名的原子写入。

重置作用于源码仓库的 data/：先备份到 data/backups/，再删除钩子、脚本、配置、sessions.db 和临时队列，并通知浏览器清理本地数据。不会重置桌面应用自己的目录。

身份验证

未设置密码时，仅本机可用；其他设备被拒绝（HTTP 403 / WebSocket 4003）。设置密码后，本机与远程 API、WebSocket 都需要登录。

npm run set-password
npm run set-password -- --status
npm run set-password -- --clear

密码通过交互输入，至少 8 字符，包含大小写字母、数字、特殊字符。使用加盐 scrypt 保存并恒定时间比较。同一地址 5 次错误后最多锁定 15 分钟。登录有效期为一小时，控制面板打开期间会刷新。

POST /api/hooks 仅接收本机请求，不需要登录，以便钩子持续工作。修改密码会撤销全部已配对手机，需要重新配对。

手机与其他设备

浏览器：打开 http://运行电脑地址:3333，使用密码登录，只能看到已共享会话。可见会话允许输入，最后输入的设备显示为操作者。请使用可信网络或 VPN。
手机应用：通过配对码连接。Android 下载与 iPhone TestFlight 状态见手机页面。
另一台电脑的 AASC：在目标电脑设备菜单选择 Pair a phone or computer → Copy link；在当前电脑选择 Remote computers → Add a computer 并粘贴。核对两端验证码后，在目标电脑允许。对方可随时撤销，权限与手机一样受共享范围限制。

配对手机可通过 Tailscale 连接。安装并登录 Tailscale 后，可在 RESOURCES → Cloud → Remote access 查看状态与最近连接。

会话默认不对其他设备显示。会话 Share 仅共享该会话；Share new sessions with my devices 共享以后新建的会话（默认关闭）；Share all open sessions now 共享当前已打开的会话。

配置说明

钩子密度#

同时使用多个 CLI#

服务配置文件#

端口优先级#

管理钩子#

身份验证#