三省六部 Edict Windows 安装完全指南：从 PowerShell 一键安装到 Dashboard 故障排查

本文是 WINDOWS_INSTALL_CN.md 的完整展开版，面向 Windows 用户，讲解如何在 OpenClaw 环境下安装、配置、启动"三省六部"多 Agent 协作系统（Edict），并配套 install.ps1、run_loop.sh、agents.json、dashboard/server.py 等仓库源码级佐证，覆盖安装前后检查、常见报错（"请先启动服务器""Gateway 未启动"）的排查思路与推荐使用顺序。读完本文，你可以独立完成从零部署到日常巡检的全流程。

---

一、安装前置条件与文档适用前提

在开始之前，请先确认你的 Windows 环境满足以下条件：

• 已安装 OpenClaw（本文档默认你下载的是已经包含 Windows 兼容修复的版本，因此不需要再手动修改 Python 文件）；
• 已安装 Python 3（python 或 python3 均可，install.ps1 会依次探测两个命令，任一可用即可）；
• 已执行过 openclaw 完成初始化，确保 openclaw.json 配置文件存在——安装脚本会直接修改它；
• 推荐安装 Git Bash / MINGW64（用于运行 run_loop.sh 数据刷新循环）；
• 可选：Node.js 18+（用于构建 React 前端，未安装时安装脚本会跳过前端构建并给出提示）。

安装脚本 install.ps1 的第一步就是依赖检查（Check-Deps 函数）：依次查找 openclaw CLI、python/python3、openclaw.json，任何一项缺失都会直接退出并打印红色错误提示。脚本本身要求 PowerShell 5.1+（文件头部有 #Requires -Version 5.1），并设置了 $ErrorActionPreference = "Stop"，遇到错误会中断执行而不是静默跳过。

---

二、最简单版本：照着做就能装

1. 下载项目

把项目放到你自己的 OpenClaw workspace 里，例如：

C:\Users\<YOUR_USER>\.openclaw\workspace\skills\edict

你实际目录名可以不是 edict，但后面命令里的路径要对应修改。

2. 如果以前装过旧版本，先删除旧链接

如果你之前已经安装过旧版三省六部，请先检查并删除这些目录里的旧 data / scripts 链接：

C:\Users\<YOUR_USER>\.openclaw\workspace-taizi
C:\Users\<YOUR_USER>\.openclaw\workspace-zhongshu
C:\Users\<YOUR_USER>\.openclaw\workspace-menxia
C:\Users\<YOUR_USER>\.openclaw\workspace-shangshu
C:\Users\<YOUR_USER>\.openclaw\workspace-hubu
C:\Users\<YOUR_USER>\.openclaw\workspace-libu
C:\Users\<YOUR_USER>\.openclaw\workspace-bingbu
C:\Users\<YOUR_USER>\.openclaw\workspace-xingbu
C:\Users\<YOUR_USER>\.openclaw\workspace-gongbu
C:\Users\<YOUR_USER>\.openclaw\workspace-libu_hr
C:\Users\<YOUR_USER>\.openclaw\workspace-zaochao

重点删除里面已有的：

• data
• scripts

为什么必须清理？ 从源码看，安装脚本的 Link-Resources 函数会用 Windows mklink /J 为每个 workspace-<agent> 创建 data、scripts 两个 junction 目录链接，指向项目根目录下的真实 data/、scripts/。如果旧链接仍然存在且指向旧仓库，第一次运行安装脚本时，可能因为"链接已经存在"而失败；更隐蔽的问题是——脚本跑完了，但 workspace 实际仍然连着旧版本的数据。所以文档中反复强调："先删旧链接，再运行安装脚本"。

3. 运行安装脚本

在 PowerShell 里进入项目目录：

cd C:\Users\<YOUR_USER>\.openclaw\workspace\skills\edict
powershell -ExecutionPolicy Bypass -File .\install.ps1

-ExecutionPolicy Bypass 用于绕过 PowerShell 执行策略限制，确保脚本可以正常运行。安装脚本会依次执行以下步骤（对应 install.ps1 的 Main 流程）：

步骤	内部函数	做了什么
0	Check-Deps	检查 openclaw / python / openclaw.json 依赖
0.5	Backup-Existing	自动备份已有 workspace-* 与 openclaw.json 到 ~\.openclaw\backups\pre-install-<时间戳>
1	Create-Workspaces	为 11 个 Agent 创建 workspace，写入 SOUL.md（替换 __REPO_DIR__ 占位符）与 AGENTS.md 工作协议
2	Register-Agents	备份 openclaw.json 后，用内嵌 Python 脚本把 11 个 Agent 注册进 agents.list，并写入各自的 subagents.allowAgents 权限矩阵
3	Init-Data	初始化项目 data/ 目录，预置 live_status.json、agent_config.json、model_change_log.json、pending_model_changes.json 等文件
3.3	Link-Resources	用 mklink /J 为每个 workspace 创建 data、scripts junction 链接
3.5	Setup-Visibility	执行 openclaw config set tools.sessions.visibility all
4	Build-Frontend	检测到 Node.js 时构建 React 前端到 dashboard\dist\，否则跳过并提示
5	First-Sync	依次运行 sync_agent_config.py、sync_officials_stats.py、refresh_live_data.py 完成首次数据同步
6	Restart-Gateway	执行 openclaw gateway restart 使配置生效

其中 Register-Agents 阶段写入的 subagents.allowAgents 权限矩阵，与 agents.json 模板完全一致：太子 taizi 只能调用中书省 zhongshu；中书省可调用门下省 menxia、尚书省 shangshu；尚书省 shangshu 可调用全部六部与吏部（hubu、libu、bingbu、xingbu、gongbu、libu_hr）等——这正是"三省六部"分权制衡在配置层面的落地。

4. 安装后检查两件事

A. 检查 agent / subagent 配置是否写进 openclaw.json

安装脚本正常情况下会写入，但建议你安装后自己确认一次。需要确认以下 11 个 Agent 都存在，且 subagents.allowAgents 正确：

• taizi
• zhongshu
• menxia
• shangshu
• hubu
• libu
• bingbu
• xingbu
• gongbu
• libu_hr
• zaochao

如果没有正确写进去，可以参考本仓库附带的 agents.json 脱敏模板。使用时请先把其中的 <YOUR_USER> 替换成你自己的系统用户名，再复制到对应配置中。

B. 检查 tools.sessions.visibility = all

安装脚本会尝试设置，但建议你手动确认一次。如果没有生效，执行：

openclaw config set tools.sessions.visibility all

为什么这个设置如此重要？ sessions.visibility = all 控制 Agent 之间 session 工具的可见性，对多 Agent 协同至关重要。如果该值未生效，Agent 之间将无法读取彼此会话，消息可能出现"发出去但对方不可达"的问题。安装脚本中 Setup-Visibility 函数用 try/catch 包裹了这条命令，失败时只打印黄色警告并提示手动执行——所以文档强调"安装后自己再确认一次"。

5. 启动后台刷新循环

在 Git Bash / MINGW64 里运行：

cd ~/.openclaw/workspace/skills/edict/scripts
bash run_loop.sh

这个脚本负责后台持续刷新数据。注意它和 dashboard 的倒计时是两回事（详见下文"第五节"）。

从源码看，scripts/run_loop.sh 是一个带单实例保护、日志轮转、超时控制的数据刷新循环：

• 刷新频率：默认每 15 秒一轮（INTERVAL="${1:-15}"，可用第一个参数覆盖）；
• 巡检频率：默认每 120 秒调用一次 POST http://127.0.0.1:7891/api/scheduler-scan 自动重试卡住的任务（SCAN_INTERVAL="${2:-120}"，可用第二个参数覆盖）；
• 单实例保护：通过 /tmp/sansheng_liubu_refresh.pid PID 文件防止重复启动，已有实例时直接退出；
• 日志：写入 /tmp/sansheng_liubu_refresh.log，超过 10MB 自动轮转；
• 超时保护：每个脚本最多执行 30 秒（SCRIPT_TIMEOUT=30），超时被 timeout 命令杀掉并记录告警日志。

每一轮循环会依次执行五个同步脚本：sync_from_openclaw_runtime.py、sync_agent_config.py、apply_model_changes.py、sync_officials_stats.py、refresh_live_data.py。

6. 启动 dashboard

在 PowerShell 里运行：

cd C:\Users\<YOUR_USER>\.openclaw\workspace\skills\edict
python dashboard\server.py

然后浏览器打开：

http://127.0.0.1:7891

从源码看，dashboard/server.py 默认端口为 7891（_DASHBOARD_PORT = 7891），同时支持 --port 参数覆盖（parser.add_argument('--port', type=int, default=7891)）。它同时承担 API 服务器与静态文件服务：/、/dashboard、/dashboard.html 返回前端页面，/api/* 返回 JSON 数据。

---

三、安装完成后你应该看到什么

正常情况下：

• 面板可以打开
• 官员总览 能显示三省六部官员信息
• 模型配置 能显示 agent 列表
• 右上角 Gateway 状态正常
• 倒计时会持续刷新页面数据

如果以上五项全部正常，说明安装链路（Agent 注册 → 数据同步 → 前端构建 → 服务启动）已全部打通。

---

四、详细说明：为什么每一步都必不可少

1. 为什么要先删旧链接

如果你以前已经安装过旧版本，那么：

• workspace-*\data
• workspace-*\scripts

很可能还指向旧仓库。

这时你再运行新的 install.ps1，第一次可能出现：

• symlink / junction 创建失败
• 安装脚本看起来跑完了，但实际 workspace 仍然连着旧版本

从 install.ps1 的 Link-Resources 函数可以看到防御逻辑：只有当目录不存在或不是 ReparsePoint（符号链接/junction）时才会重建链接；如果旧目录是真实目录（非链接），脚本会先将其重命名为 *.bak.<时间戳> 再创建新链接。但这套逻辑无法覆盖"旧链接指向旧仓库"的场景——junction 本身存在且是链接，脚本不会动它。所以最稳妥的做法是：先删旧链接，再运行安装脚本。

2. 为什么安装后还要核对 agent / subagent 配置

在部分环境里，安装脚本可能没有把三省六部的 agent 配置完整落进 openclaw.json。

因此建议你安装后主动确认 taizi、zhongshu、menxia、shangshu、hubu、libu、bingbu、xingbu、gongbu、libu_hr、zaochao 这 11 个 agent 是否都存在，且 subagents.allowAgents 是否正确。

为什么会丢失？ 从 install.ps1 的 Register-Agents 函数看，注册逻辑是"增量合并"：遍历 AGENTS 列表，已存在的 agent 会打印 ~ exists: <id> (skipped) 并跳过，只有不存在的才会追加。这意味着如果你的 openclaw.json 里已有同 ID 的旧配置（如历史版本中的 main 兼容角色），脚本不会覆盖其 subagents，旧权限矩阵可能被保留。因此核对是必要的。

如果缺失，可以直接参考本仓库附带的 agents.json 脱敏模板；使用前请先把 <YOUR_USER> 替换成你自己的系统用户名。

3. agents.json 是干什么用的

本仓库附带了一个脱敏版的 agents.json。它保留了三省六部 agent 的配置结构，包括：

• id —— Agent 唯一标识（如 taizi、zhongshu）
• name —— 显示名称
• workspace —— 工作空间路径（C:\Users\<YOUR_USER>\.openclaw\workspace-<agent_id>）
• agentDir —— Agent 目录路径（C:\Users\<YOUR_USER>\.openclaw\agents\<agent_id>\agent）
• subagents.allowAgents —— 该 Agent 允许调用的子 Agent 白名单

其中路径部分已经用 <YOUR_USER> 做了脱敏处理。使用时请先把 <YOUR_USER> 替换成你自己的 Windows 用户名，再复制到对应配置中。

值得注意的是，模板中 11 个 Agent 的 subagents.allowAgents 与 README 中描述的权限矩阵完全对应：taizi → [zhongshu]、zhongshu → [menxia, shangshu]、menxia → [shangshu, zhongshu]、shangshu → [zhongshu, menxia, hubu, libu, bingbu, xingbu, gongbu, libu_hr]，其余六部与吏部均只允许回联 shangshu，zaochao 为空数组（早朝官只发不调）。

4. 为什么还要确认 tools.sessions.visibility = all

这个设置会影响 session 工具可见性，对多 agent 协同很重要。虽然安装脚本会尝试设置，但建议安装后自己再确认一次。如果没生效，手动执行：

openclaw config set tools.sessions.visibility all

这是多 Agent 之间消息可达的前提：三省六部的协作链路（太子 → 中书 → 门下 → 尚书 → 六部）本质上是 Agent 间的会话流转，一旦 session 对彼此不可见，流转就会断裂。

5. 为什么还要跑 run_loop.sh

dashboard 右上角虽然有一个 5 秒倒计时，但它只是：

• 每 5 秒重新读取一次现有 API 数据

它并不会自动帮你在后台持续生成数据。真正负责后台数据刷新的是：

bash run_loop.sh

它会持续执行同步脚本，更新：

• live_status.json
• officials_stats.json
• agent_config.json

（此外还会更新 model_change_log.json、last_model_change_result.json、tasks_source.json 等运行时文件，并定期触发 scheduler-scan 巡检。）

所以：

• dashboard 倒计时 = 读数据
• run_loop.sh = 产数据 / 刷数据

Windows 下也建议正常运行 run_loop.sh。如果系统里没有 Git Bash，也可以在 Windows 上安装 Git for Windows（自带 MINGW64）或 WSL 来运行该脚本。

6. 如果 dashboard 提示"请先启动服务器"怎么办

这句文案有时是误导性的。它不一定表示 dashboard/server.py 真没启动。从 dashboard/dashboard.html 源码看，该提示出现在 model-grid 数据加载失败的兜底分支（⚠️ 请先启动本地服务器：python3 dashboard/server.py），即前端请求 API 失败时展示的默认文案。

更常见的真实原因是：

• API 返回了空对象
• 读取到了旧仓库的数据
• 当前启动的不是你想要的那个 dashboard server（例如旧进程还占着 7891 端口）

排查时建议直接访问：

http://127.0.0.1:7891/api/officials-stats
http://127.0.0.1:7891/api/agent-config
http://127.0.0.1:7891/api/live-status

这三个端点在 dashboard/server.py 中分别读取 officials_stats.json、agent_config.json、live_status.json 并返回 JSON。如果这三个接口能正常返回 JSON，说明 server 没问题——问题多半出在数据侧（数据文件为空、指向旧仓库）或端口被旧进程占用。

7. 如果 dashboard 提示 Gateway 没启动怎么办

如果你使用的是本修复版，这个问题应该已经被修好。之前在 Windows 上误报的原因是 dashboard 的 Gateway 检测逻辑偏 Linux（依赖 pgrep 查进程），Windows 上没有 pgrep，导致检测结果恒为"未启动"。

修复后已改为优先使用端口 / probe 检测。从 dashboard/server.py 的 _check_gateway_alive() 源码可以看到完整的 Windows 兼容逻辑：

def _check_gateway_alive():
    """检测 Gateway 是否在运行。Windows 上不要依赖 pgrep；优先通过本地端口探测判断。"""
    if _check_gateway_probe():
        return True
    try:
        if os.name == 'nt':
            with socket.create_connection(('127.0.0.1', 18789), timeout=2):
                return True
            return False
        result = subprocess.run(['pgrep', '-f', 'openclaw-gateway'], ...)
        return result.returncode == 0
    except Exception:
        return False

即：Windows 上先尝试对 127.0.0.1:18789 做 TCP 端口探测，同时 _check_gateway_probe() 会对 http://127.0.0.1:18789/ 和 /healthz 发 HTTP 请求验证响应；只有非 Windows 环境才回退到 pgrep 进程匹配。

所以如果你仍然看到 Gateway 未启动：

• 先确认自己现在运行的是修复后的 dashboard/server.py（新版本代码包含上述 os.name == 'nt' 分支）
• 再确认浏览器访问的不是旧的本地 server 进程（重启浏览器或强制刷新，并确认 7891 端口上没有残留的旧 Python 进程）

---

五、推荐的完整使用顺序

第一步

清理旧 workspace-* 里的 data / scripts

第二步

运行：

powershell -ExecutionPolicy Bypass -File .\install.ps1

第三步

检查：

• agent / subagent 配置
• tools.sessions.visibility = all

必要时可参考：

agents.json

第四步

启动后台刷新循环：

bash run_loop.sh

第五步

启动 dashboard：

python dashboard\server.py

补充：首次安装的 API Key 配置

首次安装时（openclaw.json 中尚未配置任何 Agent 的 API Key），Agent 会因为缺少 Key 而报错。需要先执行：

openclaw agents add taizi

按提示配置 Anthropic API Key，然后重新运行 .\install.ps1，让脚本把 Key 同步到所有 Agent（安装脚本结束时也会打印这条"下一步"提示）。

---

六、一句话总结

Windows 用户最稳的做法就是：先清旧链接，再运行安装脚本；安装后检查 agent 配置和 tools.sessions.visibility = all；如有需要可参考 agents.json 脱敏模板并替换 <YOUR_USER>；最后启动 run_loop.sh 和 dashboard/server.py，即可在 http://127.0.0.1:7891 打开军机处看板。若遇到"请先启动服务器"或"Gateway 未启动"提示，优先通过三个 /api/* 接口与 18789 端口探测来定位是数据问题还是进程问题，而不是盲目重启服务。

---

延伸阅读

• 快速上手指南：新手从零体验完整流程
• 任务分发流转完整架构：三省六部任务状态机、权限矩阵与调度设计的必读文档
• scripts/run_loop.sh：数据刷新循环的完整实现（间隔、巡检、单实例保护）
• install.ps1：Windows 一键安装脚本源码
• agents.json：脱敏后的 Agent 注册模板
• dashboard/server.py：看板 API 服务器（含 Gateway 检测、/api/* 端点）