读懂大模型量化标签：存储格式、计算精度与运行时内存

人工智能智能体

大模型文件里 8B、Q4_K_M、GGUF、BF16 这些标签各代表什么？按存储格式、计算精度、运行时内存分层读懂量化：权重编码、浮点格式、scale 与 zero point、Q4_K_M 预设，以及容量/速度/质量的验证方法。一个模型文件名里可能同时出现 ...

继续阅读 »

大模型文件里 8B、Q4_K_M、GGUF、BF16 这些标签各代表什么？按存储格式、计算精度、运行时内存分层读懂量化：权重编码、浮点格式、scale 与 zero point、Q4_K_M 预设，以及容量/速度/质量的验证方法。

一个模型文件名里可能同时出现 8B、Q4_K_M 和 GGUF，运行日志里又出现 BF16。若把这些字段当成同一层精度描述，容量和性能判断很容易出错。

更稳妥的做法，是沿着模型数据的生命周期分层阅读。

参数规模与权重编码

8B 表示约 80 亿个参数。忽略辅助信息时：

weight_bytes = parameters × bits_per_parameter / 8

16 位权重约 16GB，4 位编码约 4GB。真实文件还包含量化参数、未量化张量和元数据。

浮点格式不是只看总位数

FP16 与 BF16 都占 16 位。FP16 将更多位留给有效数字，BF16 将更多位留给指数范围。前者刻度更细，后者覆盖范围更宽。

因此，“BF16 比 FP16 更省内存”不是一个成立的判断。选择哪种格式，需要看硬件支持、算子实现和数值范围。

整数量化依赖 scale 与 zero point

常见仿射量化：

q = clip(round(x / scale + zero_point))
x_approx = scale × (q - zero_point)

整数只是刻度编号。per-tensor、per-channel 和 per-group 的差别，是多大范围共享一组量化参数。粒度更细通常能更好地适应局部数值范围，也会增加辅助数据与实现复杂度。

4 位编码只有 16 个值。GPTQ 使用校准输入和近似二阶信息，AWQ 根据激活分布保护重要权重通道，NF4 使用非均匀码本。它们都在解决有限刻度怎样分配的问题。

Q4_K_M 是预设，不是单一基础类型

llama.cpp 的 Q4_0 块包含 32 个 4 位权重和一个 FP16 scale，平均 4.5 bit/weight。Q4_K 块还包含 super-block 的 scale、min 和量化后的子块 scale，当前源码同样标注为有效 4.5 bit/weight。

Q4_K_M 以 Q4_K 为主，并为部分敏感张量选择 Q5_K 或 Q6_K。M 表示 Medium 预设。模型架构与实现版本会影响具体张量分配，文件整体不能按严格 4 位数组理解。

运行时是另一套类型系统

压缩权重可以按块解码后使用 BF16 或 FP16 计算。实现若能把解码、缩放与矩阵运算融合，便不必常驻完整的 16 位权重副本。

W4A16 描述权重与激活的位数，KV cache 则是独立的运行状态。缓存精度、上下文长度、batch、并发和模型结构都会改变运行时内存。

GGUF 和 safetensors 负责文件组织，不决定里面每个张量的编码。PTQ 与 QAT 描述量化发生在训练之后，还是训练时就模拟量化误差。把这些维度分开，文件名才读得完整。

容量、速度与质量分别验证

容量可以先按权重文件、KV cache、激活工作区和框架余量估算。速度至少分 prefill 与 decode；质量则用固定基础模型、提示词和采样设置，在真实任务集合上比较。

低位权重减少内存带宽，有机会提高速度。解包、缩放、设备间传输和后端内核也有成本，因此不存在“权重缩小 4 倍，推理必然快 4 倍”的通用关系。

配套数值脚本只复核位数、浮点舍入和均匀量化教学示例，不加载模型。

参考资料

量化对象和数字编码：Hugging Face 量化概念、量化公式与数字格式。
浮点范围：NVIDIA FP16 说明、Google Cloud BF16 说明。
Q4 块大小与混合预设：llama.cpp 块定义、量化实现。
存储、计算与缓存：bitsandbytes 配置、KV cache 文档。
量化方法：GPTQ 论文、AWQ 论文、QLoRA / NF4 论文。
文件容器：GGUF 官方规范。

转载自： https://www.cnblogs.com/nicksxs/p/23371427

收起阅读 »

大模型学习笔记 03：GPT 为什么能写文章？关键是不断预测下一个 Token

人工智能智能体

GPT 能写文章的本质：在已有上下文上不断预测下一个 Token。从训练目标、采样参数、预训练与微调的分工，到「流畅不等于正确」，一篇文章讲清大模型生成原理。看着 GPT 一口气写出一大段话，很容易以为它先在脑中拟好了完整答案。实际上，它通常是在已有上下文上预...

继续阅读 »

GPT 能写文章的本质：在已有上下文上不断预测下一个 Token。从训练目标、采样参数、预训练与微调的分工，到「流畅不等于正确」，一篇文章讲清大模型生成原理。

看着 GPT 一口气写出一大段话，很容易以为它先在脑中拟好了完整答案。实际上，它通常是在已有上下文上预测下一个 Token，选出来以后追加到上下文，再继续预测下一个。

上下文 -> 预测下一个 Token -> 追加 Token -> 新上下文 -> 再预测

预训练把大量文本转成 token 序列，让模型学习“给定前文，后一个 token 是什么”。训练目标可以理解为不断提高真实下一个 token 的概率。这个目标简单、数据易得，却能迫使模型压缩语言、事实关系、文体和任务模式等统计规律。

一个看似简单的目标，为什么能长出很多能力

要准确预测下一段文字，模型必须利用前文中的实体、语法、主题和潜在关系。例如回答一个问题时，后续文本常常包含答案；写代码时，后续 token 受语法和调用模式约束；续写故事时，人物和情节状态会影响接下来的内容。单一训练目标因此能支持多种行为，但“能续写”不等于每次都知道事实。

采样参数改变的是选择，不是知识

模型给出的不是唯一答案，而是概率分布。贪心解码每次选概率最高的 token，通常更稳定但可能重复；随机采样更有变化；temperature 会调整分布的尖锐程度。参数调节改变的是输出选择，不会凭空增加模型知识，也不能保证事实正确。

预训练和微调各自负责什么

预训练让模型形成通用表示和续写能力。后续监督微调用示例告诉模型“遇到某类指令，怎样组织回答”；偏好优化进一步影响不同候选回答的取舍。它们是在已有底座上塑造行为，不是从零开始写入一套可靠数据库。

流畅不等于正确

下一个 token 预测优化的是训练分布上的文本概率，不是外部世界中的真值。一个听起来连贯的回答，可能只是符合语言模式。需要最新信息、精确数字或可追责结论时，应引入可信来源、工具、校验或人工审核。

这也是大模型最有意思、也最容易让人误判的地方：同一个机制既让它能迁移到很多任务，也让它可能把“听起来合理”误当成“事实正确”。需要最新信息、精确数字或可追责结论时，还是要接入来源、工具和校验。

Token 也值得单独说一下。它不是“一个汉字”或“一个单词”的固定单位，而是 tokenizer 根据词表切出来的片段。中文、英文、代码和数字的切分方式可能完全不同，所以同样长度的两段文字，消耗的 token 数并不一样。上下文窗口、费用和限流，最后都按 token 计算，这也是为什么做应用时不能只用字符数估算成本。

再往前一步，生成过程还解释了为什么回答会有随机性。模型给出的只是概率分布，temperature、top-p 等参数改变的是我们如何从分布里取样。参数调低通常更稳定，调高可能更有变化，但它们都没有替模型接入新的事实来源。要解决事实问题，还是得从数据和工具链入手。

生成长度也会影响回答质量。模型每多生成一个 token，就多一次把自己的输出当作上下文的机会；一开始的小错误可能在后面被继续展开。限制最大输出、要求结构化格式、在关键步骤调用工具，都是降低错误扩散的办法。

我觉得“预测下一个 token”这个说法最容易让人低估模型。推理、写代码、总结和对话可以看起来很不同，但底层输出接口仍然是一串 token 的概率选择。理解这个共同底座，才能把不同应用放到同一张图里比较。

参考：《大规模语言模型：从理论到实践》，第 2 章 2.2 节，PDF 第 36-42 页。本文为学习整理与独立阐释。

转载自： https://www.cnblogs.com/hazy-star/p/23383091

收起阅读 »

大模型备案&算法备案，小团队做AI合规，最小成本是什么

人工智能智能体

小团队做大模型备案/算法备案的最小成本路径：备案报价参考、适用手续核对、自办与外部协助的组合方式，附备案流程要点。大模型&算法备案指导报价一览表项目价格说明大模型备案大模型备案4w，每增加一个模态+1.5w单个大模型备案4万，不区分模态类型大模型登记大...

继续阅读 »

小团队做大模型备案/算法备案的最小成本路径：备案报价参考、适用手续核对、自办与外部协助的组合方式，附备案流程要点。

大模型&算法备案指导报价一览表

项目	价格	说明
大模型备案	大模型备案4w，每增加一个模态+1.5w	单个大模型备案4万，不区分模态类型
大模型登记	大模型登记2.5w，每增加一个模态+1w	单个大模型上线登记2.5万，不区分模态类型
算法备案	算法备案6000，每增加一个模态1000	算法备案一个6千，加一个模态加1千

小团队要省成本，可以先缩小实际交付范围、复用已经核准的资料，把确有缺口的工作交给合适人员完成。需要履行的义务不能省，产品没有的措施不能靠报告补出来。对准备向境内公众提供生成式服务的团队，应先核适用手续和上线条件，再决定自办与外部协助怎样组合。

我们更建议从一张工作分配表开始。负责人掌握业务目标，技术掌握真实实现，运营掌握用户流程，这些信息很难全部由外部人员替你确认。钱应该花在哪些环节，要看现有人员能完成什么、哪些事实拿不到、哪些措施尚未实现。

少做重复工作，控制真实范围，保留必要验证。不能用少填功能、借用编号或虚构测试来降低成本。

下面依据官方规则整理内部执行建议，不提供通用于所有产品的最低价，也不把某种模型接入方式承诺为自动合规方案。

01 / XIYIN GUIDE

先开一次范围确认，暂时别急着买套餐

这次确认不需要先写长报告。把本次上线功能、入口、用户对象、运营主体、模型来源和部署区域列出来，让产品与技术一起核。已经开放的功能如实记录，远期想做的另列计划。业务负责人确认本次真正需要交付的范围，后面才好安排工作。

可以在合法和符合合同安排的前提下，暂缓没有准备好的非必要功能。减少一种输出或一个公开入口，可能减少对应实现和验证，但必须在真实产品中关闭或不开放。只从材料里删掉描述，用户仍然可以使用，属于改变表述，没有减少实际义务。

决定范围时也要留意客户已经确认的需求。合同里承诺语音生成，不能为了简化准备就悄悄改成只有文本。需要变更，应按双方约定处理；涉及现有用户的，还要核服务规则和告知安排。省成本的前提是范围真实、承诺可以履行。

核模型时，保存实际服务名称、版本、提供方和调用方式。使用已备案模型能力的应用，应继续核应用侧登记等事项。官方公告已经将模型服务和应用分开说明，采购上游能力不能当成购买了本企业全部合规结果。

02 / XIYIN GUIDE

企业自己先做事实整理，不把猜测外包出去

小团队可以先自己整理产品说明、功能截图、供应商合同和当前制度。它们通常掌握在企业手里，外部协助仍然需要企业提供。先按产品版本归档，可以减少后来反复寻找同一个文件、多人各答一个版本的时间。

事实表应记录每项内容的确认人。模型关系由技术核，公开功能由产品核，服务对象由运营与负责人核，协议与合同由对应人员核。资料还没有拿到，就标待确认，不让汇总人员依据宣传页补写训练情况或数据来源。

同一项准确事实，可以用于不同文件的基础说明，但不能把整份报告不加区分地复制。系统填报、技术说明、拟公示内容和用户协议，目的不同。保留共同事实，再按各自用途表达，既能减少重复核实，也能避免一处写自研、一处写外部调用。

供应商资料要早点要。商业授权、服务名称、必要安全说明、数据处理安排，可能需要不同部门提供。对外部掌握的信息，列所需资料、用途和预计取得时间。企业拿不到的信息应说明限制，不能以少付服务费为由自己编一个答案。

企业内部确认事实，外部协助组织方法，各自职责不能混同

03 / XIYIN GUIDE

外部协助，买到能补自己缺口的工作

若企业有人了解适用要求、能够组织真实材料并完成所需验证，可以评估自行办理。若欠缺的是事项判断、报告组织或测试能力，就围绕这些缺口询价。没有必要先把全部工作称为全包，再在实施时发现产品整改和内部确认仍要自己做。

请外部人员判断事项时，应交真实产品资料，请其明确依据、适用条件与待向属地确认的问题。只有一句你们都要办，或者一句这个肯定不用办，负责人仍然无法作出可执行安排。判断结论应说明对应哪项功能和对象，方便产品变化后重新核查。

请人整理报告时，应确认包含哪些文件、修改到什么阶段、哪些内容由企业提供、事实由谁签字确认。请人测试时，应确认对象、方法、记录、问题反馈与复测。范围明确，企业才知道拿到交付以后还剩哪些任务。

不要把外部服务等同于监管关系。服务商可以协助准备、核对和沟通，不能替主管部门承诺审核结果。以包过、特殊通道为主要卖点的报价，无法代替真实交付清单。采购时把可验收工作写清，比口头承诺有用。

涉及账号和资料权限，也应提前约定。优先采用必要、可控的协作方式，不随手共享管理员密码、完整用户数据或生产密钥。服务结束后收回不再需要的权限，拿回材料底稿、版本记录和后续待办。少留一份无法管理的权限，能减少后续处理工作。

04 / XIYIN GUIDE

技术措施先验能不能用，再谈做得多复杂

小团队可以根据真实服务规模选择合适人员和工具，但应保证适用措施有效。已有云服务、框架或供应商能力能够满足需要的，先核配置与覆盖范围；确有缺口，再安排新增开发。购买昂贵工具，不自动证明落实要求，自己写简单功能也不能免去验证。

权限检查可以从真实角色开始。普通用户能否访问别人的知识库，离职或取消授权的账号是否还可使用，导出功能会不会带出不应提供的内容。安排对应测试并保存结果，发现问题先处理。不要只因为正常账号能登录，就认定权限已经完成。

内容与异常处置需要看完整过程。检查发生在哪个环节，供应商接口失败时怎样处理，用户举报由谁收到，处理后怎样记录。团队人数少，可以明确一人承担多个合理职责，但不能让每项制度都写有专人，实际无人负责。

标识按输出方式检查，文本界面与可导出文件分别核。对现有工具的支持能力，使用真实输出验证，不能仅根据产品介绍推断。供应商更改配置、文件格式或模型以后，应核是否影响原有结果，避免每次都从头重复测试，也避免未经检查直接沿用。

05 / XIYIN GUIDE

用一个小的执行周期，检查方案是不是真的省事

分工以后，先让每位负责人处理自己能确认的事实与任务。汇总人记录缺项和依赖，技术安排真实产品工作，外部协助人员处理约定事项。不要让所有人同时修改同一份总报告，否则一轮下来难以分清哪些事实已确认、哪些只是换了措辞。

准备成果按照适用事项组织。2018年相关互联网信息服务安全评估规定允许自行或委托第三方实施，但具体项目涉及的其他评估、测试和方法要求仍需另核。不能把某一规则允许自评，扩大为所有AI相关工作都能随便写一份证明完成。

每项结束时，核对应证据。产品措施完成就看实际功能及验证，材料完成就看事实和附件对应，事项已提交就保存真实阶段记录。没有完成的继续列待办，不为了让项目表变成全绿，把计划执行改成已经执行。

先固定真实范围，再分工、验证与整理，顺序可按项目依赖调整

运行后的工作也需要纳入职责。模型变化、功能新增、投诉和安全问题，谁接收、谁判断影响、谁更新材料，都应明确。对算法备案信息变更等法定事项，按规定处理。不能因为服务商交付结束，就让本企业从此没有维护负责人。

下一次新增功能时，先核与现有产品的差别，保留能够复用的准确资料和验证结果，再补变化部分。是否需要重新测试、变更或另办事项，应根据真实影响确认。复用已有成果可以减少重复劳动，复制旧结论不能代替重新判断。

还可以建立共用资料目录。公司基础资料、已确认的模型信息、制度现行版和通用架构分别保存，由一个人维护有效版本。每个产品只引用适用部分，再补自己的功能和证据。这样能减少重复索取，但不能把不同产品的测试结果混在一起，共用一个未经核实的结论。

负责人也需要安排替补。经办人请假或离职以后，其他人能否找到申报账号管理方式、提交版本和待办反馈，应在交接中确认。底稿不能只留在个人聊天文件里。把资料放在有权限控制的企业目录，记录更新时间和维护人，可以减少后续重新整理的投入。

最低成本方案最后应当写成任务表。每项由谁做、用什么资料、怎样确认完成、何时需要外部协助，让团队能照着执行。先把这张表做出来，再决定买什么服务，避免买下低价套餐以后，才发现关键工作没有包含在内。

梳理小团队的准备任务

可以扫码发送产品功能、现有材料和团队可配合人员情况，备注任务分工。我们可协助核适用事项、整理材料任务与协作范围。实际措施和事实需企业落实确认，不承诺最低价或审核结果。

转载自： https://www.cnblogs.com/RoboXt/p/23387333

收起阅读 »

你的WorkBuddy不好用，大概率是这些配置没设置好

智能体人工智能 RPA

WorkBuddy 的 10 个基础设置：允许锁屏、存储位置、体验优化、回复风格、自定义指令、记忆与进化、技能自动更新、小程序 APP 联动、自定义模型、安全中心。几分钟配置完，让 Agent 更懂你。很多小伙伴装好 WorkBuddy 的第一反应，就是赶紧丢...

继续阅读 »

WorkBuddy 的 10 个基础设置：允许锁屏、存储位置、体验优化、回复风格、自定义指令、记忆与进化、技能自动更新、小程序 APP 联动、自定义模型、安全中心。几分钟配置完，让 Agent 更懂你。

很多小伙伴装好 WorkBuddy 的第一反应，就是赶紧丢个任务进去，看它干活利不利索。

我一开始也这样，用了小半个月，总觉得不对劲：任务跑着跑着就断了、文件不知道存哪儿了、总感觉不够聪明，回复又臭又长，口吻还特别官方。

后来才发现有一堆基础设置，我压根没设置好。

今天把这些设置一次性讲清楚，几分钟就能配置完。

1、允许锁屏

别让任务跑到一半就断了

这个我踩过坑，放第一个说。

有次我让 WorkBuddy 整理一批文件，估摸得跑十几分钟，就去倒了杯水。回来一看，屏幕锁了，任务停了。

WorkBuddy 是能干长活的 Agent，很多任务不是一两分钟能完事。如果「允许锁屏」没开，你一锁屏、电脑一待机，它可能就跟着罢工。

所以这个开关建议第一时间打开：进设置，找到「允许锁屏后继续运行」。以后锁屏去开会、去吃饭，它也能在后台把活干完。

2、更换存储位置

这个也容易被忽略。WorkBuddy 干活会不停产生交互文件，日志文件，会话记录、下载的资料、沉淀的技能，越用越多。

默认存在：C:\Users\用户\WorkBuddy下面

建议装好后先看一眼存储位置，空间紧张的，直接挪到别的盘。

3、体验优化计划

要不要把使用数据交出去

这个见仁见智，我讲清楚，你自己选。

「体验优化计划」说白了，就是你同不同意把匿名的使用数据发给官方，帮他们改进产品。开了，产品越做越好；不开，你的使用习惯完全留在本地。

我个人是关闭的，日常使用的数据不会用于大模型训练。

4、回复风格

有时候总嫌AI再说正确的废话，这时候我们就可以规定它说话的口吻。

WorkBuddy 回复你的时候，严谨点还是随性点，其实你说了算。

设置里有「回复风格」，一般有「专业严谨」「自然随和」「天马行空」几档。它不会让模型变聪明，但能让它说话更对你胃口。

我的用法是动态调：写报告查资料，选专业严谨；想点子写文案，切天马行空。别一个风格用到底。

5、自定义指令

省下重复交代的时间

这个我觉得最值，好好说说。

我们跟 AI 打交道，很大一部分时间浪费在反复交代同一件事上：每次都要它「口语化一点」「别啰嗦」「数字先核实」，说多了真的烦。

自定义指令就是干这个的：把这些长期不变的要求写进去，以后它每次开工前都先读一遍，等于提前把规矩立好。

进设置找到「给WorkBuddy的指令」，填一段就行，写具体点，比如你干啥的、喜欢啥风格、最烦啥习惯。

6、记忆与进化

让它一分钟认识你

这个也实用，尤其你以前用别的 AI 攒了不少上下文的话。

核心是「导入记忆」：官方给你一段提示词，丢给以前用过的 AI，比如 GPT，对方输出一份关于你的总结，粘回来导入，它就大致知道你谁、平时干啥了。

除了导入记忆，我们还可以修改记忆。

这里提个醒：导完或者长期对话后，需要定期检查一下记忆，有些记忆过时了，或者被理解偏了，该删删、该改改。

另外「对话记忆」也建议开，这样它能跨对话记住你，不用一直窝在一个对话框里聊，而且越用越懂你。

7、技能自动更新

我们在使用WorkBuddy这样的AI Agent,会慢慢沉淀和积累一些使用技能，越用越顺手。

「技能自动更新」建议打开。好的技能一直在迭代，开着它，你手头的技能自动升级到最新版，不用手动更新。

顺带「自动安装可信技能」、「套件自动更新」也建议开。

别人分享的优质技能或者一些非官方的技能，系统先跑一遍安全检查，过了就自动装，不用每次弹窗问你。

8、打通小程序和 APP 联动

最后一个，我最近才用上，挺香。

WorkBuddy 除了桌面端，还有微信小程序和手机 APP。打通以后，你在外面也能看到任务跑到哪了、有没有出岔子，甚至远程补一句指令。

对经常要离开电脑、又想让活继续跑的人来说，这个联动真顶用。设置里找到入口，扫个码或登录一下，绑定上就行。

9、自定义模型

如果你手里有别的模型的 API key，或者买了某个 Coding Plan、Token Plan，或者一些免费模型，就能在「自定义模型」这儿把它们接进来。

10、安全中心

前面几个设置，都在解决它怎么更懂你。接下来这个，直接关系到安全。

WorkBuddy 不是普通聊天机器人，它是能直接动你电脑的 Agent，能读写文件、执行命令。写错文案顶多重写，文件要是整错了，那可是一整批全废。

所以我建议第一次用的时候，进「安全中心」，至少看清楚两个地方。

一个是「沙箱安全」。你可以把它理解成给 WorkBuddy 套了层护栏，让它在受限制的环境里跑，读写、执行、上网都有一套规则管着。

另一个是「自动备份」，我叫它后悔药。让它改 Word、Excel、代码，或者批量处理一堆文件之前，它会先把原文件留一份备份，就算后面改岔了，还能退回来。不过要是那种特别重要、只有一份的资料，我还是建议自己先复制一份，双保险。

还有个「访问权限」，我的建议稍微激进点：直接开「允许完全访问」。开成默认审核的话，它每动一步都要你点确定，审到后面自己都看不动了，只能一路点确定，反而失了提效的本意。当然，要是让它动系统级的大改动，这时候再切回默认权限，谨慎点没错。

这 10个设置看着不少，刚装好WorkBudy的小伙伴，动手调一遍，十分钟都用不了。

调完以后，WorkBuddy 会明显更懂你、更省心。

我一直觉得，AI 好不好用，模型只是一部分。你怎么设置它、愿不愿意把习惯交给它，同样重要。

原文链接： https://www.cnblogs.com/xiezhr/p/23408411

收起阅读 »

用 WorkBuddy 管好供应商证照到期：一套可落地的实操方法

面向系统集成商的供应商证照到期管理实操：四个核对维度、WorkBuddy 落地四步、数据参考与分级推进建议。用 WorkBuddy 管好供应商证照到期：一套可落地的实操方法一、先看场景：证照过期，多半是"没人盯"而非"忘了"供应商的营业执照、ISO 体系认证、...

继续阅读 »

面向系统集成商的供应商证照到期管理实操：四个核对维度、WorkBuddy 落地四步、数据参考与分级推进建议。

用 WorkBuddy 管好供应商证照到期：一套可落地的实操方法

一、先看场景：证照过期，多半是"没人盯"而非"忘了"

供应商的营业执照、ISO 体系认证、原厂授权书，以及安防、涉密、建筑智能化等行业资质证书，平日里几乎无人过问，可一旦投标、验收或审计要用，问题全暴露在合同里。做系统集成的公司，手上常年有几十家供应商，每家三五份证照，到期时间分散在邮件、微信群和纸质档案盒里。

等到投标要用、验收要查、审计要看的时候，才发现某家的授权书已过期两个月。这时候补救相当被动：要么临时换供应商，要么向客户解释材料为何不齐。这类问题其实与技术水平无关，纯粹是"有没有人盯着"的差别。

二、证照管理要核对的四个维度

不少人以为证照管理就是"记一个到期日"，实际远不止。至少要对齐四层：

有效期：证件的起止日期，以及年检、换证的节点
主体一致性：证照上的公司名称、统一社会信用代码，与合同签约主体是否一致（公司改名、迁址、重组都可能导致不一致）
授权链条：原厂授权书能否一路追溯到最终厂商，中间代理层级是否完整、授权范围是否覆盖本次采购的产品线
原件与归档：复印件是否加盖公章、是否注明用途范围

缺任何一层，材料在审计眼里都算"不齐"。麻烦在于这四层分散在不同人手里：商务管合同、采购管授权、行政管公章，没有一个地方能一次看全。

三、WorkBuddy 落地证照管理的四个动作

把证照从"一堆文件"变成"可查询的记录"，是一切的基础。用 WorkBuddy 落地大致分四步：

字段抽取：把供应商发来的 PDF、JPG 证照丢进去，自动识别主体名称、证件类型、证件编号、发证机关、有效期起止、授权范围；扫描件角度不正、公章压住文字也能读出来。
台账生成：抽取的字段自动汇总成表，按"供应商 × 证件类型"一行一条，到期日单独成列，并自动计算剩余天数。
分级提醒：剩余 90 天提醒商务确认是否续期；剩余 30 天升级至采购负责人；剩余 7 天同时抄送项目经理——此时往往已有在谈项目。
复核留痕：续期时上传新证照，旧版自动归档、保留替换记录。审计追问"这家单位去年投标用的是哪一版授权书"时，可随时调出。

奇摩在为客户搭建这套流程时发现，抽字段节省的时间其实有限，真正省心的是第 3、4 步——把"谁该在什么时候做什么"固化下来，而不是靠人传人、人盯人。

四、数据参考：这件事占多少人力

按一家中型集成商的实际盘点：常年合作供应商约 40 家，平均每家 4.2 份有效证照，合计约 170 份；每份平均 1.5 个到期节点（证件有效期 + 年检），全年需要盯的节点约 250 个。

纯人工方式，一个人每月要花 6-8 小时在这上面，且时间主要耗在"翻找"而不是"判断"。改为台账 + 自动提醒后，同样的工作量压到每月 1 小时以内，漏检率明显下降。值得注意的是，很多漏检并非没人负责，而是负责人休假、岗位交接，或提醒静静躺在没人看的群里。

五、落地建议：先管关键少数

不必一开始就覆盖全部供应商，可行的推进顺序：

优先圈：正在投标、正在履约、涉及验收的供应商，先建台账
扩展圈：年度采购额靠前的 20 家，补齐授权链条和主体一致性核对
长尾圈：其余供应商只登记营业执照和基本资质，够用即可

说到底，证照管理不是归档工作，而是一套"提前量"机制：提前多久知道、提前多久动作，决定了它是例行公事还是救火。深圳市奇摩计算机有限公司在服务企业客户的过程中，见过不少"材料齐全但时间不对"的遗憾，也因此更愿意把这类流程固化成工具，而不是依赖某个人的记性。经验是：先把提醒发对人、把留痕做在动作发生的当下，这套流程才算真正立住了。

深圳市奇摩计算机有限公司已获国家高新技术企业认定，拥有华为五钻等 27 项原厂授权，服务客户超过二十年。作为 WorkBuddy 授权服务商，奇摩将 AI 编程能力融入企业日常开发流程，助力数字化转型落地。

收起阅读 »

OpenClaw 中文版完整部署手册（Eword版本）

智能体人工智能运维

OpenClaw 全平台部署完整手册：mirror-switcher 镜像加速、Docker 与原生 npm 双方案、初始化配置与企业微信渠道接入、生产化运维与升级、常见问题排查，附 Anaconda 源配置附录。OpenClaw 中文版完整部署手册（Ewor...

继续阅读 »

OpenClaw 全平台部署完整手册：mirror-switcher 镜像加速、Docker 与原生 npm 双方案、初始化配置与企业微信渠道接入、生产化运维与升级、常见问题排查，附 Anaconda 源配置附录。

OpenClaw 中文版完整部署手册（Eword版本）

转载请注明来源:https://www.cnblogs.com/eword/

Author：eword
Email:eword@139.com

前置总览与资源说明
前置统一工具：mirror-switcher 全平台镜像一键切换
方案一：Docker 容器化一键部署（全平台通用）
方案二：原生 npm 部署（分 macOS / Windows / 信创系统）
两种部署方案优劣对比与选型建议
配置详解：初始化向导、大模型与企业微信渠道接入
进阶运维与生产化部署
更新与升级
常见问题排查
附录 A：Anaconda / Miniconda 官方下载与源配置

1. 前置总览与资源说明

1.1 仓库镜像优先级（优先 Gitee）

原始 GitHub 地址	国内 Gitee 镜像地址（推荐）
https://github.com/OpenClawAI/OpenClaw.git	https://gitee.com/mirrors_ai/OpenClaw.git

1.2 部署环境说明

本手册提供两种独立部署方案，可按需二选一：

Docker 部署：零环境依赖，一条命令拉起，跨系统环境完全一致，适合快速部署、批量上线
原生 npm 部署：不使用容器，技术栈为 nvm（Node 版本管理）+ 原生 nrm 源管理 + Node.js + Anaconda（Python 可选环境）；OpenClaw 本身为 Node.js 全局工具，通过 npm 安装后直接使用 openclaw 命令，Python 环境用于插件与扩展能力

1.3 源管理双方案说明

推荐方案：使用 mirror-switcher 一键统一管理 npm/pip/conda/docker/git/apt/brew 全链路镜像，完整教程跳转：

《mirror-switcher（镜像切换工具 / Mirror Switcher）》https://www.cnblogs.com/eword/p/21636099

备选方案：保留原生独立 nrm 手动安装与源切换步骤，两种方式任选其一即可，无需重复配置。

1.4 适配操作系统

✅ macOS（Intel x86_64 / Apple Silicon M 系列 arm64）✅ Windows 10 / Windows 11（64 位）✅ 统信 UOS（AMD64 / ARM64 鲲鹏/飞腾）✅ 银河麒麟 V10（AMD64 / ARM64）

2. 前置统一工具：mirror-switcher 全平台镜像一键切换

2.1 工具说明

部署全程涉及 npm、pip、conda、docker、homebrew、git、系统 apt/yum 源，全部统一使用 mirror-switcher 工具一键切换国内镜像，无需手动修改各类配置文件。完整安装、命令、各生态源切换、国产系统适配、备份还原功能请查阅专属教程：

《mirror-switcher（镜像切换工具 / Mirror Switcher）》https://www.cnblogs.com/eword/p/21636099

2.2 部署 OpenClaw 核心切换命令速查

安装完成 mirror-switcher 并刷新终端环境后，执行以下命令完成全链路国内加速：

# 1. Node/npm 源切换淘宝镜像（替代 nrm）
switch-npm use tsinghua
# 2. Python pip 清华源
switch-pip use tsinghua
# 3. Anaconda/Miniconda conda 镜像
switch-conda use tsinghua
# 4. Docker 镜像加速器（ghcr.io 加速拉取）
switch-docker use 163
# 5. Git GitHub 代理加速（克隆 Gitee 无需，拉取 GitHub 仓库使用）
switch-git use ghproxy
# 6. macOS Homebrew 镜像（macOS 专属）
switch-brew use tsinghua
# 7. 国产信创系统（麒麟/统信）apt 软件源
switch-apt use tsinghua

2.3 快速安装入口

macOS / Linux（麒麟/统信）一键安装

bash <(curl -fsSL https://gitee.com/eword/mirror-switcher/raw/main/bootstrap.sh)
source ~/.zshrc  # zsh 终端
# source ~/.bashrc  # bash 终端

Windows PowerShell 一键安装

iwr -useb https://gitee.com/eword/mirror-switcher/raw/main/bootstrap.ps1 | iex

完整参数、指定工具安装、卸载、测速、备份还原、国产系统适配逻辑，详见博客：

https://www.cnblogs.com/eword/p/21636099

3. 方案一：Docker 容器化一键部署（全平台通用）

3.1 各系统 Docker 前置安装

macOS

安装 Docker Desktop 即可，界面语言不影响终端 CLI 命令执行。安装完成后执行前置工具切换镜像：

switch-docker use 163

Windows

安装 Docker Desktop，开启 WSL2 后端；安装 mirror-switcher 后执行：

switch-docker use 163

统信 UOS / 银河麒麟（信创 Linux）

sudo apt update
sudo apt install docker.io docker-compose -y
sudo systemctl enable --now docker
sudo usermod -aG docker $USER
newgrp docker
# 切换系统 apt 源 + docker 镜像加速器
switch-apt use tsinghua
switch-docker use 163

Docker 镜像加速器配置无需手动修改 daemon.json / Desktop 配置，统一使用 switch-docker 命令，用法详见第 2 章。

3.2 镜像拉取与验证

3.2.1 镜像地址说明

OpenClaw 中文版 Docker 镜像提供两个可用地址，国内环境优先使用 Docker Hub 源，拉取成功率更高：

镜像仓库	完整地址	适用场景
Docker Hub	1186258278/openclaw-zh:latest	国内网络、配置通用镜像加速器
GitHub Container Registry	ghcr.io/1186258278/openclaw-zh:latest	海外网络、已配置 GH 代理

3.2.2 提前拉取镜像（推荐执行）

正式部署前先单独执行拉取命令，确认镜像完整下载，避免初始化过程中因网络中断导致配置失败。

国内环境推荐命令：

docker pull 1186258278/openclaw-zh:latest

海外/直连环境命令：

docker pull ghcr.io/1186258278/openclaw-zh:latest

3.2.3 验证拉取结果

docker images | grep openclaw

正常输出示例：

1186258278/openclaw-zh   latest    abcdef123456   2 weeks ago   5.36GB

3.2.4 拉取失败排查

网络超时：先执行 switch-docker use 163 配置国内镜像加速器，重启 Docker 后重试
ghcr.io 无法访问：更换为 Docker Hub 地址 1186258278/openclaw-zh:latest
架构不匹配：Apple Silicon / ARM 信创主机需确认镜像支持 arm64 架构，当前 latest 标签已支持多架构自动适配
磁盘空间不足：镜像约 5.3GB，确保本地磁盘剩余空间大于 10GB

3.3 部署标准两步流程

步骤 1：首次交互式初始化（仅执行 1 次）

--rm 含义：退出交互式终端（exit/Ctrl+D/关闭窗口）后自动销毁当前临时容器；-v openclaw-data:/root/.openclaw 挂载独立数据卷，配置文件永久保存，不会随容器删除丢失。

若已提前拉取镜像，本条命令会直接启动容器，无需等待下载

docker run --rm -it -v openclaw-data:/root/.openclaw \
1186258278/openclaw-zh:latest openclaw onboard

执行后跟随向导填写大模型 API 密钥、用户名、存储路径、功能配置，配置完成输入 exit 退出终端，临时容器自动删除。

步骤 2：后台常驻启动网关服务（禁止添加 --rm）

添加 --rm 会导致容器停止即被删除，服务无法后台持久运行。

docker run -d --name openclaw \
-v openclaw-data:/root/.openclaw \
-p 18789:18789 \
1186258278/openclaw-zh:latest \
openclaw gateway --port 18789

3.4 服务访问地址

本机访问：http://localhost:18789
局域网其他设备访问：http://本机内网IP:18789

3.5 Docker 常用运维命令

# 停止服务
docker stop openclaw
# 重启服务
docker restart openclaw
# 实时查看运行日志
docker logs -f openclaw
# 查看本地镜像版本
docker images | grep openclaw
# 强制重新拉取最新镜像
docker pull 1186258278/openclaw-zh:latest
# 彻底卸载（删除容器+全部配置数据卷，数据不可恢复）
docker rm -f openclaw && docker volume rm openclaw-data
# 一键清理本机所有停止的废弃容器
docker container prune -f
# 清理无用旧镜像释放磁盘
docker image prune -f

4. 方案二：原生 npm 部署（分系统）

4.1 通用前置规范

二选一配置 npm 镜像源：

方案 A（推荐）：使用 switch-npm（mirror-switcher 工具）一键切换

方案 B：独立安装原生 nrm 手动管理镜像源
nvm 锁定 Node.js 20+ LTS 版本，规避版本兼容问题
（可选）Anaconda 创建 Python 环境，用于 OpenClaw 插件与脚本扩展
通过 npm 全局安装中文版 OpenClaw，安装完成后直接使用 openclaw 命令

4.2 macOS 原生部署

4.2.1 安装 Homebrew（无环境则执行）

/bin/bash -c "$(curl -fsSL https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/install.git/raw/HEAD/install.sh)"
# 切换 brew 国内镜像
switch-brew use tsinghua

4.2.2 国内 GHProxy 镜像安装 nvm

curl -o- https://mirror.ghproxy.com/https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
# 写入 zsh 终端环境变量
echo 'export NVM_DIR="$HOME/.nvm"' >> ~/.zshrc
echo '[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"' >> ~/.zshrc
source ~/.zshrc

# 安装并固定 Node 20 长期支持版
nvm install 20
nvm use 20
nvm alias default 20

4.2.3 原生 nrm 独立安装（可选）

# 全局安装原生 nrm
npm install -g nrm
# 查看可用镜像源列表
nrm ls
# 切换淘宝 npm 镜像源
nrm use taobao
# 如需切回官方源执行 nrm use npm

若已使用 switch-npm 完成源切换，可跳过本小节，两种工具功能重合无需重复配置。

4.2.4（可选）安装 Anaconda Python 环境

用于 OpenClaw Python 插件、脚本执行扩展。安装包下载地址详见附录 A。安装完成后初始化终端，切换 conda/pip 国内源：

conda init zsh
source ~/.zshrc
# conda 镜像切换
switch-conda use tsinghua
# pip 镜像切换
switch-pip use tsinghua

# 创建 OpenClaw 专属 Python 虚拟环境
conda create -n openclaw python=3.11 -y
conda activate openclaw

4.2.5 npm 全局安装 OpenClaw 中文版并部署启动

# 全局安装中文版 OpenClaw
npm install -g openclaw-zh@latest
# 验证安装
openclaw --version
# 首次初始化配置向导
openclaw onboard
# 前台启动网关服务
openclaw gateway --port 18789
# 后台常驻运行（日志写入文件）
nohup openclaw gateway --port 18789 > openclaw-run.log 2>&1 &

4.3 Windows 10/11 原生部署

4.3.1 nvm-windows 安装

安装包代理地址：https://mirror.ghproxy.com/https://github.com/coreybutler/nvm-windows/releases/download/1.1.12/nvm-setup.exe安装后打开 PowerShell/CMD 执行：

nvm install 20
nvm use 20
nvm alias default 20

4.3.2 原生 nrm 独立安装（可选）

npm install -g nrm
nrm ls
nrm use taobao

已使用 switch-npm 则可跳过。

4.3.3（可选）安装 Anaconda Python 环境

安装时勾选 Add Anaconda to my PATH environment variable，打开 Anaconda Prompt 终端：

switch-conda use tsinghua
switch-pip use tsinghua
conda create -n openclaw python=3.11 -y
conda activate openclaw

4.3.4 npm 全局安装 OpenClaw 中文版

npm install -g openclaw-zh@latest
openclaw --version
openclaw onboard
openclaw gateway --port 18789

4.4 统信 UOS / 银河麒麟（信创 Linux AMD64/ARM64 通用）

4.4.1 预装系统基础工具+切换系统源

sudo apt update && sudo apt install git curl wget -y
# 切换 apt 国产系统源
switch-apt use tsinghua

4.4.2 GHProxy 代理安装 nvm

curl -o- https://mirror.ghproxy.com/https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
echo 'export NVM_DIR="$HOME/.nvm"' >> ~/.bashrc
echo '[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"' >> ~/.bashrc
source ~/.bashrc

nvm install 20
nvm use 20
nvm alias default 20

4.4.3 原生 nrm 独立安装（可选）

npm install -g nrm
nrm ls
nrm use taobao

4.4.4（可选）安装 Anaconda Python 环境

安装包下载地址详见附录 A。

# 赋予执行权限并运行安装脚本
bash Anaconda3-xxx-Linux-xxx.sh
# 初始化 bash 终端
conda init bash
source ~/.bashrc
# 切换 conda、pip 国内镜像
switch-conda use tsinghua
switch-pip use tsinghua
# 创建专属虚拟环境
conda create -n openclaw python=3.11 -y
conda activate openclaw

4.4.5 npm 全局安装 OpenClaw 中文版并启动服务

npm install -g openclaw-zh@latest
openclaw --version
openclaw onboard
# 后台守护进程运行
nohup openclaw gateway --port 18789 > openclaw.log 2>&1 &

4.5 原生部署启停与彻底卸载

前台进程停止

快捷键 Ctrl + C 直接终止程序

后台 nohup 进程关闭

ps aux | grep "openclaw gateway"
kill -9 查到的进程 PID

一键清理卸载

# 卸载全局 openclaw 包
npm uninstall -g openclaw-zh
# 清理配置目录
rm -rf ~/.openclaw
# 可选：卸载 Python 虚拟环境
conda deactivate
conda remove -n openclaw --all -y
# 可选：卸载原生 nrm
npm uninstall -g nrm

5. 两种部署方案优劣对比与选型建议

部署方式	核心优点	短板	适用场景
Docker 容器部署	一键部署、环境强隔离、无依赖冲突、多设备部署一致性极强	额外占用少量磁盘存储空间	新手快速搭建、服务器批量部署、不想手动维护环境
原生 npm 部署	无容器额外开销、启动轻量、命令直接调用、插件扩展灵活	需要手动维护 Node 版本，系统环境差异可能导致兼容问题	日常开发使用、本地化定制、信创内网轻量化部署

6. 配置详解：初始化向导、大模型与企业微信渠道接入

6.1 配置文件路径全说明

6.1.1 主配置文件位置

OpenClaw 所有核心配置统一存放于用户主目录下的 .openclaw 目录中，不同系统路径如下：

操作系统	配置根目录	主配置文件
macOS / Linux（统信 UOS/银河麒麟）	~/.openclaw/	~/.openclaw/openclaw.json
Windows	%USERPROFILE%\.openclaw\	%USERPROFILE%\.openclaw\openclaw.json
Docker 容器内	/root/.openclaw/	/root/.openclaw/openclaw.json

6.1.2 目录结构说明

~/.openclaw/
├── openclaw.json          # 核心主配置文件（模型、渠道、网关、Agent等）
├── logs/                  # 运行日志目录
├── agents/                # 各智能体独立状态与记忆数据
├── workspaces/            # 工作空间文件与知识库向量数据
├── skills/                # 已安装技能插件
├── plugins/               # 已安装扩展插件
└── backups/               # 配置自动备份目录

6.1.3 配置修改生效方式

命令行修改（推荐）：执行 openclaw config set 键名值，自动热加载生效
手动编辑文件：修改 openclaw.json 后，执行 openclaw gateway restart 重启网关生效
Docker 部署：配置保存在 openclaw-data 数据卷中，可进入容器内部修改，或重启容器加载

6.2 初始化向导（openclaw onboard）全选项说明

执行 openclaw onboard 进入交互式初始化，各配置项说明如下：

配置项	可选值	说明与推荐选择
运行模式（Mode）	QuickStart / Advanced	QuickStart：快速启动，加载默认配置，新手推荐；Advanced：高级模式，逐项精细配置
模型提供商（Provider）	智谱 AI / 通义千问 / DeepSeek / Kimi / Ollama 等	选择你已获取 API Key 的大模型厂商，本文以智谱 AI 为例
默认模型（Default Model）	对应厂商下的模型列表	推荐选择轻量化高速模型，如智谱 glm-4-flash，日常交互响应快、成本低
API Key	字符串	填入对应模型厂商的 API 密钥，保存后加密存储
交互渠道（Channels）	Web 网关 / 企业微信 / 飞书 / 暂不配置	首次部署建议先选「暂不配置」，基础功能跑通后再追加渠道
基础技能（Skills）	启用 / 禁用	推荐启用，内置代码执行、文件读写、网络搜索等核心能力
技能安装源	npm / 本地	国内环境选 npm，配合镜像源加速安装
网关端口	默认 18789	可自定义，避免与本机其他服务端口冲突
访问控制	本地仅可访问 / 局域网可访问	生产环境建议先设为本地访问，配置反向代理后再开放局域网

初始化完成后，所有配置自动写入 openclaw.json，可随时通过命令或手动编辑修改。

6.3 大模型配置详解（以智谱 AI 为例）

6.3.1 前置准备

访问智谱 AI 开放平台：https://open.bigmodel.cn/
注册账号并完成实名认证
进入「API 密钥管理」页面，创建并复制 API Key

6.3.2 方式一：命令行一键配置（推荐）

# 启用智谱 AI 提供商
openclaw config set models.providers.zai.enabled true
# 配置 API 地址
openclaw config set models.providers.zai.baseUrl "https://open.bigmodel.cn/api/coding/paas/v4"
# 填入你的 API Key
openclaw config set models.providers.zai.apiKey "你的智谱 API Key"
# 设置默认主模型为 GLM-4-Flash
openclaw config set agents.defaults.model.primary "zai/glm-4-flash"
# 重启网关生效
openclaw gateway restart

6.3.3 方式二：配置文件完整示例

编辑 ~/.openclaw/openclaw.json，在 models 节点添加智谱配置：

{
  "models": {
    "mode": "merge",
    "providers": {
      "zai": {
        "enabled": true,
        "baseUrl": "https://open.bigmodel.cn/api/coding/paas/v4",
        "api": "openai-completions",
        "apiKey": "你的智谱 API Key",
        "models": [
          {
            "id": "glm-4-flash",
            "name": "GLM-4-Flash",
            "contextWindow": 128000,
            "maxTokens": 8192,
            "reasoning": false
          },
          {
            "id": "glm-4-plus",
            "name": "GLM-4-Plus",
            "contextWindow": 128000,
            "maxTokens": 4096,
            "reasoning": false
          },
          {
            "id": "glm-5",
            "name": "GLM-5",
            "contextWindow": 204800,
            "maxTokens": 131072,
            "reasoning": true
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "zai/glm-4-flash"
      }
    }
  }
}

保存后重启网关即可生效，支持同时配置多个模型，在 Web 界面可随时切换。

6.3.4 验证模型配置

# 查看已配置的所有模型列表
openclaw models ls
# 测试模型连通性
openclaw models test zai/glm-4-flash

6.4 企业微信渠道接入配置

OpenClaw 的企业微信能力以独立插件形式提供，需先通过 npx 安装插件再进行渠道配置。本章节优先推荐长连接 API 模式，配套全量命令行运维能力。

6.4.1 企业微信插件安装（前置必做）

##### 原生 npm 部署环境

前置条件：已完成 Node.js 环境配置，且已通过 switch-npm use taobao 切换国内 npm 镜像，加速插件包拉取。

镜像源统一管理工具用法参见第 2 章。

使用 Node.js 原生 npx 工具直接执行插件安装脚本，无需依赖 openclaw 内置 plugin 子命令，自动适配本地 OpenClaw 配置目录：

# npx 一键安装中文版企业微信官方插件
npx @openclaw-zh/plugin-wecom install

命令说明：

npx 为 Node.js 自带工具，无需额外安装，自动拉取最新稳定版插件包
安装程序自动识别本地 ~/.openclaw 配置目录，完成渠道能力注册
安装全程无额外依赖，适配 nvm 管理的多版本 Node 环境

验证安装结果：

# 查看插件安装状态与版本
npx @openclaw-zh/plugin-wecom status
# 或通过 openclaw 查看已支持的渠道列表，确认 wecom 渠道已加载
openclaw channel ls

##### Docker 容器部署环境

1186258278/openclaw-zh:latest 中文版镜像已预装企业微信插件，无需额外安装即可直接配置使用。若需手动更新/重新安装插件，进入容器后通过 npx 执行：

# 进入运行中的 openclaw 容器
docker exec -it openclaw bash
# npx 执行插件安装/更新
npx @openclaw-zh/plugin-wecom install
# 退出容器并重启服务生效
exit
docker restart openclaw

6.4.2 两种接入模式对比（长连接为首选推荐）

对比项	长连接 API 模式（推荐首选）	URL 回调模式（备选）
公网依赖	完全不需要，内网/本地部署即可用	必须有公网可访问的回调地址
核心凭证	Bot ID + Secret	CorpID + AgentID + Secret + Token + AESKey
连接方式	WebSocket 长连接，主动拉取消息	HTTP 回调，企业微信主动推送
适用场景	内网部署、信创环境、本地开发、无公网服务器	公网服务器部署、已有域名与 HTTPS
配置复杂度	低，两步完成配对	高，需配置回调地址、加密校验、可信 IP
消息延迟	极低，长连接实时推送	低，HTTP 实时回调

核心结论：90% 以上场景优先使用长连接模式；仅当必须使用自建应用、深度集成企业微信管理后台能力时，再使用回调模式。

6.4.3 长连接 API 模式（重点推荐）

长连接模式基于企业微信官方「智能机器人 API 模式」，通过 WebSocket 长连接主动订阅消息，无需公网 IP、无需配置回调 URL，是 OpenClaw 对接企业微信的标准方案。

##### 第一步：企业微信侧创建 API 机器人

打开企业微信客户端，进入「工作台」→「智能机器人」→「创建机器人」→「手动创建」
填写机器人名称、选择可见范围，拉到页面底部点击「API 模式创建」
在 API 配置页，连接方式默认勾选「使用长连接」
复制页面生成的两个核心凭证，妥善保存：

Bot ID：机器人唯一标识

Secret：机器人鉴权密钥，点击「获取」按钮生成并复制
点击「保存」完成机器人创建，可按需修改头像与简介

##### 第二步：OpenClaw 侧配置（命令行方式，推荐）

# 启用企业微信渠道
openclaw config set channels.wecom.enabled true
# 设置连接模式为长连接 websocket（默认值，显式声明更稳妥）
openclaw config set channels.wecom.connectionMode "websocket"
# 填入企业微信机器人 Bot ID
openclaw config set channels.wecom.botId "你的机器人 Bot ID"
# 填入机器人 Secret 密钥
openclaw config set channels.wecom.secret "你的机器人 Secret"
# 消息回复格式，支持 text / markdown
openclaw config set channels.wecom.messageType "markdown"
# 重启网关服务加载配置
openclaw gateway restart

##### 第三步：配置文件完整示例

编辑 ~/.openclaw/openclaw.json（Docker 部署对应容器内 /root/.openclaw/openclaw.json），在 channels 节点添加：

{
  "channels": {
    "wecom": {
      "enabled": true,
      "connectionMode": "websocket",
      "botId": "wx_bot_xxxxxxxxxxxx",
      "secret": "你的机器人 Secret 密钥",
      "messageType": "markdown",
      "dmPolicy": "open",
      "groupPolicy": "open",
      "streamReply": true
    }
  }
}

保存后重启网关生效。

##### 第四步：配对验证（长连接模式专属步骤）

打开企业微信客户端，在通讯录找到刚创建的机器人，进入聊天窗口
发送任意一条消息，机器人会自动回复一串配对码
回到部署终端，执行配对命令：

openclaw pairing approve wecom 收到的配对码

提示配对成功后，即可在企业微信内正常与 AI 对话，支持单聊与群聊 @机器人

PS : 强烈不建议使用npx安装时引导的扫二维码配对功能，因为扫二维码配对引导创建的机器人只能你自己使用，别人使用时是无法得到回复消息的，应该是企业微信的安全机制造成的，且无法找到配置入口。

##### 长连接模式核心优势

零公网依赖：本地电脑、内网服务器、信创国产化主机均可直接对接，无需申请公网 IP、域名备案
配置极简：仅需 Bot ID + Secret 两个参数，无需处理加密、回调校验、可信 IP 白名单
安全性高：主动向外建立 WebSocket 连接，无需开放任何入站端口，符合等保与内网安全规范
自动重连：网络波动时自动断线重连，无需人工干预，服务稳定性强
流式回复：原生支持 Markdown 流式输出，对话体验与 Web 端一致

6.4.4 URL 回调模式（备选方案）

适用于需要使用企业微信自建应用、深度集成组织架构与后台接口的场景，需公网服务器与回调地址。

##### 第一步：企业微信侧前置准备

登录企业微信管理后台：https://work.weixin.qq.com/
进入「应用管理」→「自建」→「创建应用」
填写应用名称、Logo，选择可见范围，创建完成
记录以下三个关键参数：

CorpID：企业 ID，在「我的企业」页面底部查看

AgentId：自建应用的应用 ID
Secret：应用密钥，在应用详情页获取
进入应用「接收消息」板块，点击「设置 API 接收」，记录：

Token：自定义，3-32 位字母数字组合

EncodingAESKey：点击随机生成，复制保存

##### 第二步：OpenClaw 侧配置（命令行方式）

# 启用企业微信渠道
openclaw config set channels.wecom.enabled true
# 设置连接模式为 webhook 回调
openclaw config set channels.wecom.connectionMode "webhook"
# 企业 ID
openclaw config set channels.wecom.corpId "你的企业 CorpID"
# 应用 AgentId
openclaw config set channels.wecom.agentId "你的应用 AgentId"
# 应用 Secret
openclaw config set channels.wecom.secret "你的应用 Secret"
# 消息校验 Token
openclaw config set channels.wecom.token "自定义的 Token"
# 消息加密密钥
openclaw config set channels.wecom.aesKey "生成的 EncodingAESKey"
# Webhook 回调路径
openclaw config set channels.wecom.webhookPath "/webhook/wecom"
# 重启网关生效
openclaw gateway restart

##### 第三步：配置文件完整示例

在 openclaw.json 的 channels 节点添加：

{
  "channels": {
    "wecom": {
      "enabled": true,
      "connectionMode": "webhook",
      "corpId": "wwxxxxxxxxxxxxxx",
      "agentId": "1000001",
      "secret": "你的应用 Secret",
      "token": "OpenClawWeCom2026",
      "aesKey": "你的 EncodingAESKey",
      "webhookPath": "/webhook/wecom",
      "dmPolicy": "open",
      "groupPolicy": "open",
      "messageType": "markdown"
    }
  }
}

##### 第四步：完成企业微信侧回调配置

回到企业微信管理后台「接收消息」设置页面
URL 填写：http://你的服务器公网IP:18789/webhook/wecom（生产环境建议用域名+HTTPS）
填入与 OpenClaw 配置一致的 Token 和 EncodingAESKey
点击「保存」，提示验证成功即完成接入

6.4.5 企业微信专属 CLI 命令大全

所有命令均可在终端直接执行，无需手动修改配置文件，覆盖日常运维、排障、测试全场景。

##### 一、渠道基础管理

# 查看所有已安装的渠道列表
openclaw channel ls
# 查看企业微信渠道实时运行状态（连接状态、在线时长、累计消息数）
openclaw channel status wecom
# 启用企业微信渠道
openclaw channel enable wecom
# 禁用企业微信渠道
openclaw channel disable wecom
# 重启企业微信渠道连接（配置修改后生效、异常断连重连时使用）
openclaw channel restart wecom

##### 二、配对管理（长连接模式专属）

# 查看所有待确认/已生效的配对设备列表
openclaw pairing ls wecom
# 批准用户配对请求（长连接模式首次对话必须执行）
openclaw pairing approve wecom 配对码
# 拒绝指定配对请求
openclaw pairing reject wecom 配对码
# 移除已生效的配对设备
openclaw pairing remove wecom 配对 ID

##### 三、消息测试与连通性校验

# 向指定企业微信用户发送测试消息，验证渠道连通性
openclaw channel test wecom --user "企业微信用户名" --content "OpenClaw渠道连通性测试消息"
# 向指定企业微信群聊发送测试消息
openclaw channel test wecom --group "群聊名称" --content "群聊测试消息"

##### 四、日志排查与问题定位

# 实时滚动查看企业微信渠道运行日志
openclaw channel logs wecom -f
# 导出最近 7 天的渠道日志到本地文件
openclaw channel logs wecom --days 7 > wecom-channel.log

##### 五、插件版本管理（npx 原生命令）

# 查看当前企业微信插件的详细信息与版本号
npx @openclaw-zh/plugin-wecom info
# 更新企业微信插件到最新中文版
npx @openclaw-zh/plugin-wecom update
# 卸载企业微信插件，清理配置注册信息
npx @openclaw-zh/plugin-wecom uninstall

6.4.6 通用渠道策略说明

两种模式共用以下策略配置项：

dmPolicy：私聊消息策略，open 表示所有可见范围内成员私聊都可触发 AI
groupPolicy：群聊消息策略，open 表示群内 @机器人即可触发对话
messageType：消息格式，支持 text 纯文本和 markdown 富文本，推荐 markdown
streamReply：是否开启流式回复，长连接模式默认开启，体验更佳

6.5 常用配置命令速查

# 查看当前全部配置
openclaw config ls
# 查看指定配置项
openclaw config get models.providers.zai.apiKey
# 修改单个配置项
openclaw config set gateway.port 18790
# 备份当前配置
openclaw config backup
# 从备份恢复
openclaw config restore
# 重置为默认配置
openclaw config reset

7. 进阶运维与生产化部署

7.1 开机自启配置（全平台）

7.1.1 macOS 开机自启（LaunchDaemon 原生方式）

适用于 macOS 12+，系统级守护进程，用户未登录也可后台运行。

创建守护进程配置文件：

sudo tee /Library/LaunchDaemons/com.openclaw.gateway.plist << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.openclaw.gateway</string>
    <key>ProgramArguments</key>
    <array>
        <string>/bin/zsh</string>
        <string>-c</string>
        <string>source ~/.zshrc && openclaw gateway --port 18789</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>~/.openclaw/logs/daemon.log</string>
    <key>StandardErrorPath</key>
    <string>~/.openclaw/logs/daemon-error.log</string>
    <key>UserName</key>
    <string>root</string>
</dict>
</plist>
EOF

加载并启用自启：

# 创建日志目录
mkdir -p ~/.openclaw/logs
# 加载守护进程
sudo launchctl load -w /Library/LaunchDaemons/com.openclaw.gateway.plist
# 验证运行状态
sudo launchctl list | grep openclaw

关闭自启：

sudo launchctl unload -w /Library/LaunchDaemons/com.openclaw.gateway.plist

7.1.2 Windows 开机自启（服务方式）

推荐使用 nssm 将 OpenClaw 注册为系统服务，崩溃自动重启。

安装 nssm（已配置 mirror-switcher 可直接 scoop install nssm）
打开管理员 PowerShell 执行：

nssm install OpenClawGateway

在弹出窗口中配置：
Path：C:\Users\你的用户名\AppData\Roaming\npm\openclaw.cmd
Arguments：gateway --port 18789
Startup directory：C:\Users\你的用户名\.openclaw
启动服务：

nssm start OpenClawGateway

7.1.3 统信 UOS / 银河麒麟（Linux systemd 自启）

信创系统通用，标准 systemd 服务配置。

创建服务文件：

sudo tee /etc/systemd/system/openclaw.service << 'EOF'
[Unit]
Description=OpenClaw AI Gateway Service
After=network.target

[Service]
Type=simple
User=root
ExecStart=/bin/bash -c "source ~/.bashrc && openclaw gateway --port 18789"
Restart=always
RestartSec=5
StandardOutput=append:/root/.openclaw/logs/service.log
StandardError=append:/root/.openclaw/logs/service-error.log

[Install]
WantedBy=multi-user.target
EOF

启用并启动：

mkdir -p ~/.openclaw/logs
sudo systemctl daemon-reload
sudo systemctl enable --now openclaw
# 查看运行状态
sudo systemctl status openclaw

停止与禁用：

sudo systemctl stop openclaw
sudo systemctl disable openclaw

7.2 Nginx 反向代理与域名访问

适用于绑定内网域名、配置统一入口、多服务共用 80/443 端口。

前置条件

已安装 Nginx（信创系统 sudo apt install nginx，macOS brew install nginx）
已配置好内网 DNS 或 hosts 解析，例如 openclaw.internal.com 指向部署主机 IP

Nginx 配置示例

server {
    listen 80;
    server_name openclaw.internal.com;

    # 客户端请求体大小限制
    client_max_body_size 100M;

    location / {
        proxy_pass http://127.0.0.1:18789;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        # WebSocket 支持
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        
        # 超时配置
        proxy_connect_timeout 60s;
        proxy_read_timeout 300s;
        proxy_send_timeout 300s;
    }
}

生效操作

# 配置语法检查
nginx -t
# 重载配置
nginx -s reload

配置完成后，浏览器访问 http://openclaw.internal.com 即可进入 OpenClaw 界面。

7.3 HTTPS 加密访问配置

基于 Nginx 配置 SSL 证书，实现内网 HTTPS 加密访问。

配置示例（续接上方反向代理）

server {
    listen 443 ssl http2;
    server_name openclaw.internal.com;

    # SSL 证书路径
    ssl_certificate /etc/nginx/cert/openclaw.crt;
    ssl_certificate_key /etc/nginx/cert/openclaw.key;

    # SSL 安全配置
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;
    ssl_prefer_server_ciphers on;
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 10m;

    client_max_body_size 100M;

    location / {
        proxy_pass http://127.0.0.1:18789;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

# 80 端口强制跳转 HTTPS
server {
    listen 80;
    server_name openclaw.internal.com;
    return 301 https://$host$request_uri;
}

内网自签证书快速生成

mkdir -p /etc/nginx/cert
openssl req -x509 -nodes -days 3650 -newkey rsa:2048 \
  -keyout /etc/nginx/cert/openclaw.key \
  -out /etc/nginx/cert/openclaw.crt \
  -subj "/CN=openclaw.internal.com"

7.4 多实例并行部署方案

同一台主机部署多个 OpenClaw 实例，分别使用不同配置、不同端口，适用于测试/生产环境隔离。

核心原理

通过指定不同的配置目录与端口，实现多实例独立运行，互不干扰。

部署步骤

创建实例 1（生产环境，端口 18789）：

# 初始化生产配置
OPENCLAW_HOME=~/.openclaw-prod openclaw onboard
# 后台启动
nohup openclaw gateway --port 18789 --home ~/.openclaw-prod > openclaw-prod.log 2>&1 &

创建实例 2（测试环境，端口 18790）：

# 初始化测试配置
OPENCLAW_HOME=~/.openclaw-test openclaw onboard
# 后台启动
nohup openclaw gateway --port 18790 --home ~/.openclaw-test > openclaw-test.log 2>&1 &

systemd 多实例服务配置（Linux 信创）

分别创建 openclaw-prod.service 与 openclaw-test.service 服务文件，修改对应端口与配置目录即可，配置模板参考 7.1.3 小节。

7.5 内网离线部署方案

适用于完全断网的信创内网环境，提前在联网机打包依赖，离线拷贝部署。

第一步：联网机准备离线包

安装好 Node.js 20.x、nrm、OpenClaw 全局包
导出 npm 全局离线包：

# 创建离线包目录
mkdir -p ~/openclaw-offline/node-packages
# 导出全局安装包
npm pack openclaw-zh --pack-destination ~/openclaw-offline/node-packages

打包 Node.js 运行时：

# 复制 node 二进制文件
cp $(which node) ~/openclaw-offline/
cp $(which npm) ~/openclaw-offline/

将整个 openclaw-offline 目录打包为 tar.gz。

第二步：离线目标机部署

解压离线包，配置 Node.js 环境变量
本地安装 OpenClaw：

npm install -g ./openclaw-zh-xxx.tgz

执行初始化与启动：

openclaw onboard
openclaw gateway --port 18789

7.6 数据备份与迁移指南

配置数据目录

OpenClaw 所有配置、模型密钥、会话数据默认存放于：

macOS/Linux：~/.openclaw/
Windows：C:\Users\用户名\.openclaw\

手动备份

# 全量备份配置目录
tar -czf openclaw-backup-$(date +%Y%m%d).tar.gz ~/.openclaw

迁移到新机器

在新机器完成 OpenClaw 基础安装
将备份包解压到对应用户目录下
重启 OpenClaw 服务即可完整恢复所有配置

Docker 部署数据备份

# 备份数据卷到本地 tar 包
docker run --rm -v openclaw-data:/data -v $(pwd):/backup alpine tar czf /backup/openclaw-data.tar.gz -C /data .

# 恢复数据卷
docker run --rm -v openclaw-data:/data -v $(pwd):/backup alpine tar xzf /backup/openclaw-data.tar.gz -C /data

8. 更新与升级

8.1 原生 npm 部署升级

# 查看当前版本
openclaw --version
# 升级到最新中文版
npm update -g openclaw-zh
# 重启网关服务生效

8.2 Docker 部署升级

# 拉取最新镜像
docker pull 1186258278/openclaw-zh:latest
# 删除旧容器（数据卷保留，配置不丢失）
docker rm -f openclaw
# 使用新镜像重新启动
docker run -d --name openclaw \
-v openclaw-data:/root/.openclaw \
-p 18789:18789 \
1186258278/openclaw-zh:latest \
openclaw gateway --port 18789

镜像加速配置统一使用 switch-docker 工具，完整用法参见第 2 章。

9. 常见问题排查

git clone Gitee 仓库超时

切换手机热点重试；或前往 Gitee 仓库页面手动下载 ZIP 压缩包解压后使用。如需拉取 GitHub 源码，执行 switch-git use ghproxy 开启代理加速，工具详情见第 2 章。

nvm 下载 Node.js 缓慢

提前设置 nvm 国内镜像环境变量再执行安装：

export NVM_NODEJS_ORG_MIRROR=https://npmmirror.com/mirrors/node
nvm install 20

npm 下载依赖缓慢二选一：

方式 1：switch-npm use taobao
方式 2：nrm use taobao
macOS Docker 提示权限拒绝

完全退出 Docker Desktop，打开「系统设置 → 隐私与安全性 → 完全磁盘访问权限」，添加 Docker.app 授权；Docker 镜像拉取慢执行 switch-docker use 163。

信创 ARM 架构 pip 依赖编译失败

switch-pip use huawei

switch-pip 内置华为云 ARM 专属镜像源，详细用法见第 2 章。

初始化向导 openclaw onboard 闪退

检查 Node.js 版本是否满足 20+，执行 node --version 确认；执行 switch-npm use taobao 修复 npm 包安装失败问题。

各类源配置错乱、需要恢复官方源
mirror-switcher 工具：统一执行 switch-xxx use official 一键恢复官方配置
原生 nrm 工具：nrm use npm 切回官方 npm 源

支持配置备份/还原，完整功能查看第 2 章引用博客。

10. 附录 A：Anaconda / Miniconda 官方下载与源配置

10.1 官方核心入口

Anaconda 全球官网首页：https://www.anaconda.com/download
官方归档仓库（所有历史版本根目录）：https://repo.anaconda.com/archive/
中文官方文档站点（国内访问更稳定）：https://docs.anaconda.net.cn/anaconda/install/

10.2 分系统官方直链（最新稳定版 Anaconda3-2025.12-2）

Windows x86_64（Win10/11 64 位）

https://repo.anaconda.com/archive/Anaconda3-2025.12-2-Windows-x86_64.exe

macOS

Apple Silicon M 系列 arm64 图形化 pkg 安装包

https://repo.anaconda.com/archive/Anaconda3-2025.12-2-MacOSX-arm64.pkg

Apple Silicon 终端 sh 脚本

https://repo.anaconda.com/archive/Anaconda3-2025.12-2-MacOSX-arm64.sh

Intel 老款 Mac x86_64

https://repo.anaconda.com/archive/Anaconda3-2025.12-2-MacOSX-x86_64.pkg

Linux（麒麟/统信/服务器）

AMD64/x86_64 通用服务器/台式机

https://repo.anaconda.com/archive/Anaconda3-2025.12-2-Linux-x86_64.sh

ARM64/aarch64 鲲鹏、飞腾信创国产主机

https://repo.anaconda.com/archive/Anaconda3-2025.12-2-Linux-aarch64.sh

10.3 清华大学国内高速镜像（优先推荐，无需FQ）

Anaconda 完整版镜像归档页

https://mirrors.tuna.tsinghua.edu.cn/anaconda/archive/替换规则：将官方链接域名 repo.anaconda.com 改为 mirrors.tuna.tsinghua.edu.cn/anaconda 即可高速下载。

Miniconda 轻量化极简版（推荐服务器/信创使用，体积仅 50MB）

Miniconda 仅包含 conda 环境管理器+基础 Python，无预装冗余数据分析包，资源占用更小：

官方下载页：https://docs.conda.io/en/latest/miniconda.html
清华镜像归档页：https://mirrors.tuna.tsinghua.edu.cn/anaconda/miniconda/

10.4 conda 源切换统一工具

安装完成 mirror-switcher 后一条命令切换清华源：

switch-conda use tsinghua

备份、还原、自定义私有 conda 源、测速功能，参考第 2 章引用博客。

10.5 OpenClaw Python 扩展环境固定创建命令

conda create -n openclaw python=3.11 -y
conda activate openclaw

收起阅读 »

把浏览器自动化交给 Playwright MCP：一次从登录巡检到发文的落地记录

用 Playwright MCP 替代固定选择器脚本：会话复用、ref 定位、多字段一次提交，以及 iframe、渲染时序、下拉菜单等实战踩坑与操作纪律。背景内部有套系统只提供页面，没有 API：待办清单、审批、发布记录，全靠人点。每天重复的点击累积起来很可观...

继续阅读 »

用 Playwright MCP 替代固定选择器脚本：会话复用、ref 定位、多字段一次提交，以及 iframe、渲染时序、下拉菜单等实战踩坑与操作纪律。

背景

内部有套系统只提供页面，没有 API：待办清单、审批、发布记录，全靠人点。每天重复的点击累积起来很可观，于是想把它交给自动化。

一开始写的是传统脚本：Playwright + 固定选择器。跑了两周，问题很集中——页面一改版，page.click('#submit-btn') 就全部失效，维护成本比手点还高。

后来换成 Playwright MCP：不再硬编码选择器，而是让模型读页面的可访问性快照，自己判断「点哪个」。

环境准备

MCP 的注册只有几行配置，写在 mcp.json 的 mcpServers 下面：

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}

写完之后不会自动生效，需要在客户端的连接器管理里手动「信任」一次。

三个真正省时间的点

1. 会话可以复用

浏览器配置目录持久化之后，登录态就留在里面了。第一次登录，后面几次直接进后台——页面上能看到「我的博客」「退出登录」这些入口，说明会话还在。

这一步的意义比看起来大：省掉的不只是敲密码，而是验证码、二次确认那一整串等待。

2. 定位用 ref，不用 CSS

MCP 给出的元素引用（ref）是从当前快照里生成的一次性编号：

textbox "标题" [ref=f2e132]
button "编辑器: Markdown" [ref=f2e874]

先取快照、再按 ref 操作，元素即使换了 class、换了层级，只要它在语义上还在那儿，就还能被找到。这和「选择器考古」完全是两种工作方式。

3. 一次填多个字段

表单类操作可以一次提交多个字段，减少来回往返；而像「切换编辑器」这种需要先点开下拉、拿到菜单项 ref、再点的交互，模型也能自己走完。

踩过的坑

iframe 里的富文本编辑器：快照只到 iframe 一层，里面是空的。要么切到 Markdown 编辑器（纯 textarea，最好处理），要么用代码片段进 frame 内部操作。
前端框架的渲染时序：单页应用刚打开时快照可能是半成品，等一拍再取才完整。
下拉菜单要先展开：菜单项在展开前根本不在快照里，不存在「提前把 ref 记下来」这回事。
截图和快照分工不同：截图给人看，快照给模型用。拿截图去推元素位置，是给自己找麻烦。

纪律比技巧重要

自动化能碰到的都是真实账号和真实数据，所以给自己定了几条：

只读操作随便跑，写操作（提交、发布、发送）必须明确授权；
发布、发信这类外部动作，先看结果再确认，不静默执行；
AI 参与生成的内容，按平台要求如实声明。

小结

Playwright MCP 并没有让浏览器自动化变简单，它改变的是「谁来应对变化」：以前是写脚本的人不断改选择器，现在是模型每次看一遍页面重新判断。

真正需要人管的，从「元素怎么写」变成了「允许它做什么」。后一件事，其实更该由人盯着。

本文来自博客园，作者：戴维冀，转载请注明原文链接：https://www.cnblogs.com/jichengwei/p/22937897

收起阅读 »

让数字员工走进项目协作：基于 QoderWake 的值班助手落地实践

用 QoderWake 本地运行引擎把 AI Agent 变成值班数字员工：计算巢一键部署、钉钉渠道配置、Waker 创建与告警接入，全程图文实操。一、什么是值班助手？什么是 QoderWake？1.1 值班助手值班助手（On-Call Assistant）是...

继续阅读 »

用 QoderWake 本地运行引擎把 AI Agent 变成值班数字员工：计算巢一键部署、钉钉渠道配置、Waker 创建与告警接入，全程图文实操。

一、什么是值班助手？什么是 QoderWake？

1.1 值班助手

值班助手（On-Call Assistant）是 QoderWake 中面向值班、告警、事件响应场景的数字员工。它不只是能在群里回复消息的机器人，而是能：

能力	说明
接收告警/事件	在钉钉群被 @，或对接告警系统收到事件推送
查询知识库	基于历史值班记录、SOP、服务文档、故障手册做 RAG 检索
辅助定位	根据告警内容给出可能根因、排查命令、关联服务
记录与交接	自动生成值班纪要、处理时间线，沉淀到知识库
升级与协同	必要时 @ 相关责任人、创建工单或移交二线

简单说，值班助手 = Agent + 值班身份 + 运维技能 + 知识库 + 工作目录。你可以把它理解为一位“不会疲劳、熟悉历史案例、能随时被 @”的虚拟值班同事。

1.2 QoderWake 是什么？

QoderWake 是 Qoder 生态中的本地运行引擎，负责把 AI Agent 部署到你的服务器或本地机器，并让它们与外部系统（如钉钉、邮件、代码仓库等）建立连接。

它提供：

一个常驻运行的 Daemon（守护进程）；
一个通过浏览器访问的 Web 控制台；
标准化的 IM 连接能力，让 Agent 以“真实用户”或“机器人”身份进入钉钉群聊。

一句话：QoderWake 是数字员工的“工位”，云就是这个工位所在的机房。

二、值班助手落地后的典型效果

把值班助手接进群聊和告警流程后，主要带来六方面变化：

响应更快：常见告警自动给出标准处置步骤，减少翻文档时间。
上手更快：处理流程、命令模板都沉淀在知识库，新人随时问、随时学。
负担更轻：重复性问题由助手先兜底，值班人员只需确认关键动作。
风险更低：高危操作建议附带风险提示，关键动作需人工确认。
经验沉淀：每次事件处理过程自动生成值班纪要，回收到知识库，形成可复用的故障案例。
协同更顺：一个群里可同时存在值班、代码审查、文档等助手，复杂故障可接力处理。

三、为什么值班助手必须部署到云上？

值班助手需要长期在线、稳定收发消息，并被团队共享访问。核心原因有三点：

7×24 小时运行：它是守护进程，个人电脑关机就“下班”。
稳定的网络入口：接收钉钉事件、开放 Web UI，云上固定 IP 更可靠。
团队共享：配置、会话状态和知识库需要多人通过浏览器统一访问。
部署和运维更简单：计算巢等方案能一键完成环境准备，省去自己配 ECS、安全组、代理的麻烦。

四、QoderWake 的核心价值

价值	说明
本地化部署	数据和运行环境都在你自己的机器上，满足企业对数据可控的要求
IM 原生集成	通过钉钉用户/机器人模式，让 AI 无缝进入现有工作流
多 Waker 协同	一个群里可以有多个数字员工，各自负责不同领域
Skill 生态扩展	通过 Skill 让 Waker 获得特定能力，无需重复开发
统一控制台	在 Web UI 中管理认证、连接、会话和状态

五、值班助手部署流程

整个流程分为 4 步：

通过计算巢部署 → 初始化配置 →  配置钉钉渠道 → 创建值班助手 Waker

5.1 通过计算巢部署

推荐通过阿里云计算巢一键部署 QoderWake，无需自己准备 ECS、配置安全组、安装依赖。

计算巢部署完成后，会自动创建好运行环境，接下来只需要进入实例执行初始化配置即可。

5.2 初始化配置

计算巢部署完成后，参考以下步骤完成初始化：

登录实例并启动 qodercli

sudo su
cd /root
source /root/.profile
qodercli

在交互式界面完成授权

启动 qodercli 后，选择 Login with Qoder Platform (Browser)，复制完整的授权链接在浏览器中打开并批准登录。

退出 qodercli，启动 qoderwake 服务

登录完成后，按 Ctrl+C 退出 qodercli，然后执行：

qoderwake start --host 0.0.0.0 -y
nohup socat TCP-LISTEN:19821,fork,reuseaddr TCP:127.0.0.1:19820 >/dev/null 2>&1 &

服务启动后，通过计算巢提供的安全代理或公网入口访问 Web UI（建议全屏显示），即可进入 QoderWake 控制台。进入后需二次登录。

5.3 配置钉钉渠道

进入 QoderWake 控制台 → IM 连接，点击添加机器人。

步骤一：配置 IM 连接

首次点击“安装并登录”后，“已安装”会变为绿色，但“已认证”仍为红色，但已认证将仍然会是红色，使用钉钉扫描二维码：

在手机端授权：

再次点击安装并登录，将会跳转设备授权页面，授权码请回到qoderwake页面：

按照提示授权，最终完成：

点击“重新检查”，即可看到配置完成（若始终无法检测认证完成，请参考步骤二设置 CLI 权限）。

点击保存。

步骤二：开启钉钉组织 CLI 权限（可选）

如果步骤一中认证失败或无法收到消息，需要让组织管理员登录钉钉开放平台，进入基本信息 → CLI 设置，确保：

允许成员通过 CLI 访问个人数据开关已打开；
使用范围管理中选择“全员可用”或“指定人员范围可用”，并将目标成员加入。

否则即使个人授权成功，DWS CLI 也无法读取组织内的消息数据。

5.4 创建值班助手 Waker

进入‘我的Wakers’，点击新建Wakers，选择群聊答疑专员

依据提示创建Waker：

页面将会跳转到快速上手，依据提示配置即可，这里可选择手动配对，选择所需群聊：

群聊选择完成后，点击下一步

前往绑定知识库、专家配置等内容。

最后，将机器人添加至群聊（需要在群聊中添加机器人），即可实现自动答疑：

5.5 接入告警/事件推送（可选进阶）

除了被 @ 之外，值班助手还可以对接告警系统：

通过钉钉群机器人 Webhook 把告警消息发到群里；
或者通过 Prometheus Alertmanager / 内部事件平台把事件推送到 QoderWake 的 API；
助手收到事件后自动检索知识库并给出初步响应。

这一步根据你现有的监控体系灵活接入即可。

六、总结

QoderWake 让 AI Agent 从“工具”变成了“员工”，而值班助手是其中最容易快速见效的场景之一：

它以本地化引擎的形式承载 Agent 运行；
以“数字员工”的形态进入企业协作场景；
通过知识库让历史经验被持续复用；
通过标准化流程完成认证、接入、响应和沉淀。

对企业而言，部署一个值班助手的本质流程可以归纳为：

通过计算巢部署 → 初始化配置 → 配置钉钉渠道 → 创建值班助手 Waker → 挂载知识库 → 测试验证

一旦跑通，你就可以继续复制出代码审查助手、文档助手、运维值班助手等不同类型的数字员工，让他们在群聊中协同工作，持续沉淀团队知识。

收起阅读 »

微擎安装和模块安装使用教程

从零开始：域名解析、服务器环境准备、微擎源码部署安装，再到模块安装与多平台（公众号/小程序/App）创建配置的完整图文教程。1、解析一个域名、开启SSL、创建一个新的数据库，常规操作2、把文件上传至网站根目录，解压3、直接访问域名，进入安装向导，填写数据库信息...

继续阅读 »

从零开始：域名解析、服务器环境准备、微擎源码部署安装，再到模块安装与多平台（公众号/小程序/App）创建配置的完整图文教程。

1、解析一个域名、开启SSL、创建一个新的数据库，常规操作

2、把文件上传至网站根目录，解压

3、直接访问域名，进入安装向导，填写数据库信息，账号信息，安装

安装完成重新访问域名登录系统

4、现在可以安装模块了，回到根目录下，找到addons

所有的微擎模块都是安装在这个目录下。

这里以【云贝】模块为例子

将模块文件上传到addons里

回到微擎系统，应用管理，未安装应用，这里就出现了刚刚上传的两个模块

直接一路点击安装

安装完应用，就可以创建平台，点击平台管理，新增平台

选择创建的类型

填写小程序信息，安装即可

【关于应用和平台的概念：微擎里面的每一个程序都称为《应用》，安装完一个应用后，可以创建出很多个平台，比如你想用云贝做两套小程序，那么你就创建两个平台。类似我们手机安装一个APP，然后在这个APP里申请一个、两个、三个账号…】

安装完成，在平台管理，进入小程序

点击应用

就进入了后台管理界面了

接下来是前端配置，微擎所有的前端参数配置都是一样的

在前端文件找到siteinfo.js文件

这里需要替换3个参数，uniacid、acid以及siteroot域名

域名没什么好说的

uniacid、acid的获取方式如下，进入对应的模块管理页面，在浏览器上方查看参数

这样前端就配置好了。后台添加好数据，就可以在前端看到效果。

部分前端还需要添加一些插件，否则会报错，运行部了，像这样

直接点击添加即可

不想添加的或者添加不了的插件，（一般是直播类插件）也可以删除掉

删除后是这样

这样就没什么问题了，去后端愉快的添加数据了。

更多小程序教程，请查看个人主页

收起阅读 »

网络安装验收与测试：链路测试、环境检查与文档交付

网络验收链路测试综合布线

网络安装验收的完整清单：前置条件、器材与安装检查、铜缆/光纤链路测试项目、环境要求、交付文档与常见不合格项。网络安装验收与测试：链路测试、环境检查与文档交付网络安装做完不等于交付完成。真正决定能不能验收的，是测试数据、环境条件和交付文档。本文给出一套可直接照做...

继续阅读 »

网络安装验收的完整清单：前置条件、器材与安装检查、铜缆/光纤链路测试项目、环境要求、交付文档与常见不合格项。

网络安装验收与测试：链路测试、环境检查与文档交付

网络安装做完不等于交付完成。真正决定能不能验收的，是测试数据、环境条件和交付文档。本文给出一套可直接照做的验收清单，帮助施工方自检、甲方验收。

一、验收前的三个前置条件

1. 土建与装饰已完成

交接间、设备间、工作区的土建工程应全部完工：地面平整光洁、门洞尺寸满足设备搬运、门锁钥匙齐全。预埋地槽、暗管、孔洞和竖井的位置、数量、尺寸符合设计。

2. 环境条件达标

铺设活动地板的区域，防静电接地符合设计；
交接间、设备间提供 220V 单相带地电源插座；
接地装置可靠，接地电阻符合设计要求；
面积、通风、温湿度满足设备运行条件。

3. 隐蔽工程已签证

暗管、吊顶内桥架、穿墙封堵等隐蔽工程，必须在封闭前完成检查与签证。封板后再发现问题，只能拆。

二、器材与安装检查

器材检查

线缆、器材的型号、规格、数量与合同一致；
有出厂检验证明，外观无损伤；
光缆开盘检查端头封装，必要时测试衰减与长度；
接插件完整，光纤跳线端面有保护帽、类型标记清晰；
不合格器件单独存放，不得使用。

安装检查

项目	要求
机柜、机架	垂直偏差 ≤ 3 mm，零件齐全、标志清晰、固定牢固
配线部件	完整就位、螺丝拧紧、面板齐平
信息插座	固定于接线盒内，防水防尘，面板标识清晰，高度符合设计
桥架、线槽	位置偏差 ≤ 50 mm，水平度每米 ≤ 2 mm，垂直度 ≤ 3 mm
接地	就近接地，电气连接良好，接地电阻符合设计

三、链路测试：验收的核心证据

「能上网」不是验收标准，链路指标才是。建议按以下项目逐条测试并留存记录：

铜缆链路

接线图（Wire Map）——检查线序与错接、短路、开路；
长度——确认未超长；
衰减（Insertion Loss）——信号沿链路损失；
近端串扰（NEXT）——线对之间的干扰；
回波损耗（Return Loss）——阻抗不匹配程度；
直流电阻——检查线缆与接头质量；
传输时延与时延偏差。

光纤链路

衰减测试——使用光纤测试仪，结果与出厂数据偏差过大时用光功率计复核；
长度测试——每根光纤逐条测试，同一盘光缆长度差异过大时从另一端复测或做通光检查；
端面清洁与连接器检查。

判定原则

先排查端接与跳线，再判断线缆本体。测试不合格的链路整改后必须复测，复测记录随报告归档。

四、环境与配套检查

温度 18～27℃，湿度 30%～50%；
室内照明不低于 150Lx；
通风良好、清洁，远离有害气体、腐蚀与易燃易爆物；
设备间消防系统符合规范，装修材料满足防火要求；
UPS 供电可靠，每个电源插座容量满足设备需求；
配线间接地：机柜用规定截面铜线连接接地端，单独接地电阻不大于 4 欧姆，联合接地不大于 1 欧姆。

五、交付文档清单

验收时建议逐项核对，缺一不可：

竣工图：标注实际路由、点位、桥架走向；
点位表：编号、位置、用途、对应配线架端口；
链路测试报告：逐条链路的测试数据与结论；
设备清单：型号、数量、序列号、安装位置；
标签对照表：两端标签与端口映射；
隐蔽工程记录：照片、签证单；
操作维护说明：日常巡检、故障处理、扩容方法；
质保与响应约定：质保范围、响应时限。

六、常见验收不合格项

不合格项	常见原因	整改方式
链路测试不通过	端接开绞过长、跳线质量差	重新端接、更换跳线后复测
标签缺失或错乱	施工赶工、无统一规则	按编码规则补打标签并核对
桥架未封堵	隐蔽工程漏项	逐孔用不燃材料封堵并拍照
接地电阻超标	接地体施工不到位	增设接地极、复测电阻
信息插座高度不一	未按标高施工	调整底盒位置，统一标高
文档不全	过程资料未归档	补齐竣工图、测试报告与签证单

验收的本质，是用数据和文档证明工程可用、可维护。测试报告齐全、标签清晰、图纸准确，后续运维才能少走弯路；反之，交付当天省下的时间，都会在故障排查时加倍还回来。

收起阅读 »

综合布线施工要点：缆线敷设、端接与桥架安装

综合布线网络安装施工工艺

桥架路由、缆线敷设、端接工艺三大环节的实操要点与常见质量问题，附桥架与管线净距、弯曲半径等关键数据。综合布线施工要点：缆线敷设、端接与桥架安装综合布线是网络安装的「地基」。地基做不好，后面换交换机、加带宽都救不回来。本文把施工中最容易出问题的三个环节——桥架、...

继续阅读 »

桥架路由、缆线敷设、端接工艺三大环节的实操要点与常见质量问题，附桥架与管线净距、弯曲半径等关键数据。

综合布线施工要点：缆线敷设、端接与桥架安装

综合布线是网络安装的「地基」。地基做不好，后面换交换机、加带宽都救不回来。本文把施工中最容易出问题的三个环节——桥架、敷设、端接——拆开讲清楚，并给出可落地的工艺要求。

一、桥架与线槽：先定路由，再谈工艺

桥架是线缆的「高速公路」，路由没定好，后面全是返工。

安装位置与偏差

桥架、线槽的位置按施工图执行，左右偏差不超过 50 毫米；
水平度每米偏差不超过 2 毫米；
垂直段与地面保持垂直，垂直度偏差不超过 3 毫米；
截断与拼接处打磨平滑，不得有毛刺；
吊架、支架保持垂直、整齐牢固，不得歪斜。

与其他管线的距离

桥架不能「见缝就钻」，与各类管道要保持净距：

相邻管线	平行敷设最小净距	交叉最小净距
一般工艺管道	400 mm	300 mm
腐蚀性液体管道	500 mm（且加隔板）	500 mm（加防腐盖板）
热力管道（有保温层）	500 mm	500 mm（加隔热板）
热力管道（无保温层）	1000 mm	1000 mm（加隔热板）

无法避免交叉时，按上表加装隔板或保护盖板，盖板长度一般不小于管道外径加 2000 毫米。

细节要求

直线长度超过 30 米设伸缩节或预留 20 毫米伸缩缝；
跨越建筑变形缝处加装补偿装置；
悬臂段一般不超过 1000 毫米；
金属槽内电线电缆不得有接头；
穿墙、穿楼板孔洞用不燃材料严密封堵；
由室内穿至室外时做防雨弯，防止雨水顺桥架倒灌。

二、缆线敷设：力度、弯曲半径与冗余

敷设前

核对线缆规格、型号、路由与长度，确认与设计一致；
两端贴标签，标明起点与终点，字迹清晰、不易脱落；
强电线路与弱电线缆分开布放，保持规范净距。

敷设中

线缆自然平直，不得扭绞、打圈、受外力挤压；
牵引力小于线缆允许张力的 80%；光缆瞬间最大牵引力不得超过允许值，牵引力应加在加强芯上；
弯曲半径要求：
非屏蔽 4 对对绞线：不小于外径 4 倍；
屏蔽对绞线：不小于外径 6～10 倍；
主干大对数对绞线：不小于外径 10 倍；
光缆：不小于外径 15 倍。
线槽内线缆顺直、不溢出，进出槽口与转弯处绑扎固定，绑扣间距均匀、松紧适度。

冗余预留

位置	建议预留
交接间、设备间（对绞线）	3～6 米
工作区	0.3～0.6 米
光缆（设备端）	3～6 米（盘留 3～5 米）

预留不是浪费，是为了后期重新端接、跳线和故障切换。

三、端接：细节决定链路指标

对绞线端接

端接前核对标签颜色与数字含义，按顺序施工；
线缆中间不得有接头；
认准线号、线位色标，不得颠倒错接；
每对对绞线尽量保持绞结形态，减少开绞长度；
与信息插座、配线架卡接时，按色标与线对顺序操作，卡接牢固、接触良好；
端接完成后做通断与接线图测试。

光缆端接

使用光纤连接盒完成接续与保护，盒内保证足够弯曲半径；
连接盒面板附加清晰标识，按设计跳线；
接续损耗符合规定；
跳线类型、长度符合设计，光缆跳线一般不超过 10 米。

四、机柜、配线架与信息插座

机柜安装牢固，垂直偏差不大于 3 毫米，前后留出操作与散热空间；
配线架模块完整、螺丝拧紧、面板齐平；
信息插座固定于接线盒内，防水防尘，面板标识终端类型与位置；
插座安装高度按设计执行，一般距地 0.3 米；
配线架预留 20%～25% 端口裕量。

五、常见质量问题与规避

问题	后果	规避方法
弯曲半径不足	衰减增大、光纤断纤	施工前做样板，转弯处用大弯
牵引力过大	线缆拉伸、性能下降	控制牵引速度，光缆拉加强芯
强弱电同槽	干扰、丢包	分开敷设，交叉保持净距
标签缺失或重复	运维找不到端口	统一编码规则，两端一致
端接开绞过长	近端串扰超标	控制开绞长度，按色标卡接
桥架未做防火封堵	火灾蔓延风险	穿墙穿楼板逐孔封堵

综合布线的质量，最终都会体现在测试数据上。桥架规整、敷设规范、端接细致，测试自然容易过；任何一步图省事，后面都要用返工来补。

收起阅读 »

网络安装工程全流程指南：从现场勘察到验收交付

网络安装综合布线弱电工程

从现场勘察、材料核验、施工组织，到桥架敷设、端接、测试验收与交付，一篇讲清网络安装工程的完整流程与关键控制点。网络安装工程全流程指南：从现场勘察到验收交付网络安装不是「拉几根网线」这么简单。它是一套从勘察、设计、施工到测试验收的完整工程流程，任何一环偷工减料，...

继续阅读 »

从现场勘察、材料核验、施工组织，到桥架敷设、端接、测试验收与交付，一篇讲清网络安装工程的完整流程与关键控制点。

网络安装工程全流程指南：从现场勘察到验收交付

网络安装不是「拉几根网线」这么简单。它是一套从勘察、设计、施工到测试验收的完整工程流程，任何一环偷工减料，都会在后期以掉线、卡顿、返工的形式还回来。本文按实际施工顺序，把网络安装工程拆成可执行的步骤。

一、开工前：三件事决定成败

1. 现场勘察要「走到位」

勘察不是看一眼机房就完事，重点确认：

弱电井位置、楼层高度、桥架走向是否与图纸一致；
强电、水管、消防管道的实际位置，避免布线时冲突；
墙体材质（承重墙、轻质墙、玻璃隔断），决定开孔与固定方式；
机房面积、承重、空调与消防条件；
已有线路的占用情况，判断是新建还是改造。

勘察记录要落到纸面：拍照、标注尺寸、记录障碍点，作为后续变更的依据。

2. 图纸会审要「对得上」

把施工图与现场逐项核对，重点看信息点位置、桥架标高、管径与弯曲半径是否满足线缆要求。发现冲突当场提出，不要等到施工中再改——返工成本远高于前期沟通。

3. 材料核验要「先检后用」

线缆、模块、配线架、面板、桥架进场后，先核对型号、规格、数量与合同是否一致，检查外包装、合格证与出厂检测数据。不合格材料单独存放，不得混入施工。

二、施工组织：工序衔接比速度更重要

合理的顺序是：桥架与线槽 → 穿管与预埋 → 缆线敷设 → 端接 → 机柜与设备安装 → 标识 → 测试。

几个容易被忽略的衔接点：

土建与装饰未完成时不要提前穿线，避免粉尘、潮气损伤线缆；
强电与弱电分开敷设，交叉处保持规范要求的净距；
隐蔽工程（暗管、吊顶内桥架）必须在封板前完成检查与签证；
每道工序完成后做一次自检，问题留在本工序解决，不要带到下一道。

三、安装实施：五个关键环节

1. 桥架与线槽

水平段支架间距一般不超过 1.5 米，垂直段不大于 1 米；
直线长度超过 30 米时设置伸缩节或预留伸缩缝；
与热力管道、腐蚀性管道保持规范净距，无法避免时加装隔板；
穿墙、穿楼板处用不燃材料封堵，室外段做好防雨与防水弯。

2. 缆线敷设

布放前核对规格、路由与长度，两端贴好标签；
线缆保持平直，不得扭绞、打圈、受挤压；
牵引力不超过线缆允许张力的 80%，光缆牵引力应加在加强芯上；
弯曲半径：非屏蔽对绞线不小于外径 4 倍，主干对绞线不小于 10 倍，光缆不小于 15 倍；
交接间、设备间预留 3～6 米，工作区预留 0.3～0.6 米，光缆盘留 3～5 米。

3. 端接

端接前核对线号、线位与色标，按顺序卡接，不得颠倒；
线缆中间不得有接头；
对绞线端接时尽量保持绞结形态，开绞长度越短越好；
光缆熔接使用连接盒保护，保证足够弯曲半径，接续损耗符合设计要求；
跳线长度一般对绞线不超过 5 米、光缆不超过 10 米。

4. 机柜与信息插座

机柜安装牢固，垂直偏差控制在 3 毫米以内，前后预留操作空间；
信息插座固定在接线盒内，做好防水防尘，面板标识清晰；
插座安装高度按设计执行，一般距地 0.3 米；
配线架预留 20%～25% 的端口裕量，方便扩容与故障切换。

5. 标识与理线

标签是后期运维的生命线。建议统一规则：楼层—区域—机柜—端口，两端一致、字迹耐久。机柜内强弱电分槽走线，跳线横平竖直，避免「蜘蛛网」。

四、测试与验收：用数据说话

施工完成后不能只看「能上网」，要按标准做链路测试：

接线图与长度；
衰减、近端串扰、回波损耗；
直流电阻、传输时延；
光纤衰减与长度（必要时双向测试）。

测试不合格的链路先排查端接与跳线，再判断是否线缆损伤。全部合格后整理测试报告，作为验收依据。

环境方面同时检查：机房温度 18～27℃、湿度 30%～50%、照明不低于 150Lx、接地电阻符合规范、UPS 供电可靠。

五、交付：文档比口头承诺有用

交付时至少提供：

竣工图与点位表；
链路测试报告；
设备清单与序列号；
标签对照表；
操作与维护说明；
质保与响应约定。

常见问题

Q：能先布线后改图纸吗？
不建议。路由一变，长度、标签、测试全部要重做，返工成本最高。

Q：网线可以和大功率电缆同槽吗？
不可以。强弱电必须分开敷设，交叉时保持规范净距，否则干扰会导致丢包和速率下降。

Q：为什么必须做链路测试？
「能通」不等于「达标」。衰减和串扰超标时，短距离可能正常，长距离或高负载时就会掉速、断连。

Q：旧线路改造要注意什么？
先做存量普查，确认哪些线可用、哪些必须更换；新旧标签体系要统一，避免后期找不到端口。

网络安装工程的核心不是快，而是可测试、可追溯、可维护。把勘察、材料、工序、测试、文档五件事做扎实，网络才能真正稳定运行。

收起阅读 »

Paiway-AHA（AHA Music 音乐识别）Chrome 插件使用教程

浏览器插件音乐识别听歌识曲

浏览器里的「听歌识曲」雷达 —— 识别浏览器里正在播放的任何歌曲，自动给出歌名、歌手、封面，并可跳转平台在线播放。类似网页版 Shazam。插件名称AHA Music - Song Finder for Browser当前版本v2.0.4适用平台Chrome运...

继续阅读 »

浏览器里的「听歌识曲」雷达 —— 识别浏览器里正在播放的任何歌曲，自动给出歌名、歌手、封面，并可跳转平台在线播放。类似网页版 Shazam。

插件名称	AHA Music - Song Finder for Browser
当前版本	v2.0.4
适用平台	Chrome
运行环境	Chrome 88+

Paiway-AHA（AHA Music 音乐识别）Chrome 插件使用教程

一句话定位：浏览器里的「听歌识曲」雷达 —— 识别浏览器里正在播放的任何歌曲，自动给出歌名、歌手、封面，并可跳转平台在线播放。类似网页版 Shazam。

插件名称：AHA Music - Song Finder for Browser
版本：v2.0.4（MV3，最低 Chrome 88+）
官方网站：https://www.aha-music.com
识别引擎：ACRCloud（https://www.acrcloud.com）
开发者：qiuxuewen（个人开发者，支持 BuyMeACoffee 打赏）
打包来源：派为资料整理（网址导航 http://nav.paiwayinfo.com/）

1. 安装方法（Chrome 加载已解压的扩展）

打开 Chrome，地址栏输入 chrome://extensions 回车；
打开右上角 「开发者模式」 开关；
点击左上角 「加载已解压的扩展程序」；
选择插件文件夹：D:\TONGBU-NAS\网盘整理(新)\浏览器插件\paiway-aha；
安装成功后工具栏出现 AHA Music 图标（被折叠就点拼图图标找到并「固定」）。

2. 快速上手（听歌识曲 3 步）

打开正在播放音乐的标签页（任意网站都行：YouTube、B站、视频站、在线电台、MV 网页……只要是标签页里发出的声音）；
点击工具栏的 AHA Music 图标 打开弹窗；
点击 「识别」（Identify）按钮，等 3~8 秒，就能看到识别结果：

歌曲名、歌手、专辑、封面图；
可点击跳转到 YouTube / Spotify 等平台直接播放或收藏。

💡 浏览器首次识别会弹「是否允许捕获标签页音频」的授权提示，点允许，否则识别不了声音。

3. 功能详解

3.1 识别范围（不是只听视频网站）

AHA Music 捕获的是当前标签页输出的全部音频，所以适用场景很广：

视频网站的 BGM（YouTube、B站、抖音网页版、MV 等）；
在线电台 / 音乐流媒体里不认识但喜欢的一首；
网页游戏、直播、在线课里的背景音乐；
甚至可以用它识别自己电脑里正在播放的声音（如果是从网页播的）。

3.2 识别历史（History）

每次成功识别都会自动记录：歌曲名、歌手、识别时间；
历史记录保存在本地（浏览器 storage），不占服务器资源；
翻历史时点开就能看到结果并可跳转播放。

3.3 平台联动跳转

识别结果卡片提供到主流平台的直达链接（YouTube、Spotify 等），点一下就能在原平台听完整版。

3.4 Google 账号登录（可选）

插件支持用 Google 账号登录（manifest 已配置 OAuth）；
登录与否都不影响核心识别功能，属于可选增强（用于保存偏好/历史等）。

3.5 识别接口说明

识别走的是插件后端 extension.doreso.com/v1/aha-music/identify + ACRCloud 指纹库，所以识别时必须联网，结果准确率取决于音频清晰度和歌曲库覆盖率。

4. 使用技巧

场景	建议
识别不准	等歌曲主歌/副歌部分再识别；把音量调大、暂停其他杂音
网页里有多个音频	确保要识别的那个标签页是当前活动标签页
识别历史太多	定期清理历史记录，释放本地空间
提示无法捕获音频	检查标签页是否真的在出声；刷新页面后重试

5. 常见问题（FAQ）

Q1：点识别没反应/一直转圈？
大概率没联网或网络被墙（识别服务在境外）。检查网络；国内网络访问识别接口不稳定时可尝试科学上网后重试。

Q2：提示需要授权捕获标签页音频？
浏览器安全机制，点「允许」即可。如果之前点过「拒绝」，到 chrome://extensions → 该插件 → 权限，重新授权。

Q3：识别结果错误 / 识别不出？
ACRCloud 库覆盖广但不是万能的：纯音乐、改编版、现场版、过于嘈杂的音频识别率会下降。可等歌曲高潮段重试。

Q4：支持哪些网站？
几乎所有网页。只要是标签页里播放的声音都能捕获，不限于视频网站。

Q5：识别历史存在哪？
本地浏览器存储（storage + unlimitedStorage），不上传服务器，重装插件或清浏览器数据会丢失。

Q6：需要注册/付费吗？
核心识别免费（走插件作者的后端额度）。作者接受 BuyMeACoffee 打赏支持；Google 登录可选。

6. 其他信息

权限说明：tabCapture（捕获标签页音频，核心权限）；identity / identity.email（Google 登录）；storage + unlimitedStorage（历史记录本地存储）；activeTab（读取当前页）。
技术特性：MV3 架构 + 沙箱 WASM 指纹模块（sandbox.html），识别计算在插件内部完成。
更新渠道：商店版走 update_url 自动更新；本地加载版更新需重新加载扩展目录。

教程基于插件 2.0.4 源码整理，2026-10-23。

AHA Music - Song Finder for Browser 官方入口

访问官网

收起阅读 »

Paiway-Eudic（欧路翻译）Chrome 插件使用教程

浏览器插件翻译工具欧路翻译

欧路词典出品的沉浸式网页翻译工具 —— 划词查词、全文逐段对照翻译、视频字幕翻译、PDF 文献翻译，多翻译引擎可切换，还能与欧路词典生态联动。插件名称Paiway-Eudic（欧路翻译）当前版本v26.8.0适用平台Chrome运行环境Chrome 88+Pa...

继续阅读 »

欧路词典出品的沉浸式网页翻译工具 —— 划词查词、全文逐段对照翻译、视频字幕翻译、PDF 文献翻译，多翻译引擎可切换，还能与欧路词典生态联动。

插件名称	Paiway-Eudic（欧路翻译）
当前版本	v26.8.0
适用平台	Chrome
运行环境	Chrome 88+

Paiway-Eudic（欧路翻译）Chrome 插件使用教程

一句话定位：欧路词典出品的沉浸式网页翻译工具 —— 划词查词、全文逐段对照翻译、视频字幕翻译、PDF 文献翻译，多翻译引擎可切换，还能与欧路词典生态联动。

插件名称：欧路翻译（paiway-eudic）
版本：v26.8.0（最低要求 Chrome 88+）
官方：欧路词典（Eudic）—— eudic.net
多语言品牌：中文「欧路翻译」/ 法语「法语助手」/ 德语「德语助手」/ 西语「西语助手」
打包来源：派为资料整理（网址导航 http://nav.paiwayinfo.com/）

1. 安装方法（Chrome 加载已解压的扩展）

打开 Chrome，地址栏输入 chrome://extensions 回车；
打开右上角 「开发者模式」 开关；
点击左上角 「加载已解压的扩展程序」；
选择插件文件夹：D:\TONGBU-NAS\网盘整理(新)\浏览器插件\paiway-eudic；
安装成功后工具栏出现欧路图标（被折叠就点拼图图标找到并「固定」）。

💡 更新时在扩展页点「刷新」即可；建议再到 chrome://extensions/shortcuts 把常用命令配上快捷键。

2. 快速上手（3 个核心动作）

动作	操作	效果
划词查词	用鼠标选中网页里的单词/句子	弹出翻译卡片，可听发音、看详细释义、加入生词
全文翻译	按 Alt+T	整个网页逐段变成「原文 + 译文」对照，再按一次恢复
朗读句子	选中句子后按 Alt+R	用 TTS 朗读选中的句子

打开弹窗：按 Alt+N 或点工具栏图标。

3. 功能详解

3.1 划词翻译 / 查词

选中任意文字立即弹出翻译结果卡片：

查看翻译与发音（英式/美式音标）；
点「详细」查看词典释义；
支持「在线搜索」跳转查询；
可与欧路词典客户端联动（在对应 App 中打开查词）。

3.2 全文逐段对照翻译（核心功能）

按 Alt+T 开启：页面按段落渲染「原文 + 译文」，阅读外文网页神器；
某段翻译失败会标红提示，可单独「重试」或一键「重试所有失败段落」；
「仅显示译文」模式（toggleShowTranslateOnly）：只看译文隐藏原文，适合沉浸阅读。

3.3 重点单词

开启「重点单词」模式（toggleWordHintPage），网页中的重点单词会被高亮标记，辅助精读。

3.4 句子朗读（TTS）

选中任意句子按 Alt+R 朗读，练听力/跟读很好用。

3.5 视频字幕翻译

在播放视频的页面（如外语影视、课程），插件会捕获并翻译字幕：

显示模式 5 选 1：原文+译文 / 仅原文 / 仅译文 / 原文+模糊译文 / 隐藏字幕；
字幕样式全可自定义：字体（系列/颜色/大小）、译文独立字体大小、背景色与不透明度、字体不透明度、文字描边（无/阴影/凸起/下沉）。

3.6 PDF 文件翻译（文件阅读器）

内置 PDF 查看器，打开 PDF 文献即可像网页一样逐段翻译，科研读文献利器；
注意：若提示「暂无权限直接读取 PDF 文件」，需点击查看器重新手动选择该文件（浏览器文件权限问题）。

3.7 翻译引擎设置（弹窗/设置页 → 引擎设置）

支持多引擎切换与自定义：

欧路翻译引擎：需登录欧路账号使用；
OpenAI / GPT 引擎：需在设置里填入自己的 API Key；
Bing / Google 等内置引擎：开箱即用；
可自定义引擎参数、随时「切换引擎」。

4. 快捷键一览（chrome://extensions/shortcuts 可改）

命令	默认快捷键	功能
打开弹窗	Alt+N	打开扩展 popup
切换页面翻译	Alt+T	开启/关闭全文逐段翻译
朗读选中句子	Alt+R	TTS 朗读选中的句子
开启/关闭重点单词	未绑定	高亮网页重点单词
添加/删除自定义词	未绑定	自定义生词管理
划词取词	未绑定	选中即查
悬浮翻译整行	未绑定	鼠标悬浮翻译所在行
切换仅显示译文	未绑定	原文/译文显示模式切换

建议至少给「划词取词」「悬浮翻译行」配上顺手快捷键。

5. 常见问题（FAQ）

Q1：翻译失败/整页没反应？
先确认网络正常；全文翻译可对失败段落点「重试」或「重试所有失败段落」。若弹「翻译服务或网络可能出现问题」，通常是引擎超时，重试即可。

Q2：用 GPT 引擎提示「需要输入正确的 API Key」？
插件不会替你保存密钥，需到设置 → 引擎设置，填入你自己的 OpenAI API Key 才能用该引擎。

Q3：用欧路引擎提示「需要登录」？
欧路翻译引擎需要欧路账号（eudic.net）登录后才可使用。

Q4：PDF 提示「暂无权限直接读取」？
浏览器限制了自动读文件权限，按提示在 PDF 查看器里重新选择该文件即可。

Q5：字幕翻译不显示？
确认视频播放中、字幕可被捕获；检查字幕「显示设置」里是否误选了「隐藏字幕」。

Q6：快捷键失效？
到 chrome://extensions/shortcuts 查看是否被其他扩展占用，重新绑定即可。

Q7：划词没弹翻译卡片？
部分网站（如后台编辑器、受保护页面）会拦截注入；刷新页面重试，或改用「悬浮翻译整行」命令。

6. 其他信息

生态联动：与欧路词典客户端 / eudic.net 账号联动（查词、生词、每日英语听力、AI 写作等品牌互通）。
权限说明：<all_urls> 全站注入（划词/翻译/字幕需要）；storage（设置与词库）；sidePanel（侧边栏）。
入口汇总：弹窗 #/popup、设置页 #/options、侧边栏 side-panel/index.html。
v26.8.0 亮点：逐段对照翻译 + 失败重试、字幕翻译样式自定义、PDF 阅读器、多引擎（欧路/OpenAI/Bing/Google）。

教程基于插件 26.8.0 源码整理，2026-10-23。

Paiway-Eudic（欧路翻译）官方入口

访问官网

收起阅读 »

PaiwayFlow v1.1.4（Chrome）使用教程

浏览器插件下载工具视频下载

万能网页视频/音频/图片下载器，自动嗅探 M3U8/HLS，一键保存到本地。插件名称PaiwayFlow当前版本v1.1.4适用平台Chrome运行环境Chrome 102+一、安装方法PaiwayFlow 是一款 Chrome 浏览器扩展，安装方式与常规扩展...

继续阅读 »

万能网页视频/音频/图片下载器，自动嗅探 M3U8/HLS，一键保存到本地。

插件名称	PaiwayFlow
当前版本	v1.1.4
适用平台	Chrome
运行环境	Chrome 102+

一、安装方法

PaiwayFlow 是一款 Chrome 浏览器扩展，安装方式与常规扩展一致，全程约 1 分钟。

打开 Chrome 浏览器，访问插件官方地址 https://flowpick.net 。
点击页面上的「添加到 Chrome」按钮，浏览器右上角会弹出安装确认框。
在弹窗中点击「添加扩展程序」，等待几秒后提示安装完成。
点击浏览器工具栏的拼图图标，把 PaiwayFlow 固定到工具栏，方便随时调用。

若企业网络限制了扩展商店访问，可在官网下载 .crx 离线安装包，打开 chrome://extensions/ 并开启「开发者模式」，把安装包拖入页面即可。

二、功能详解

1. 自动嗅探媒体资源

插件会在页面加载时自动扫描网络请求，识别视频、音频、图片的真实地址，无需手动复制链接。对常见的 M3U8、HLS 分片流同样有效。

2. 多清晰度选择

嗅探到资源后，插件会列出可选清晰度与码率，支持 1080P、720P、480P 等档位，也可只提取纯音频。

3. 批量与队列下载

一次可以勾选多个资源加入下载队列，插件会自动串行下载并合并分片，避免同时请求过多导致失败。

4. 图片与素材提取

除音视频外，还能提取页面中的大图、图集和背景图，适合做素材收集与竞品分析。

三、使用步骤

步骤 1：打开目标页面

在 Chrome 中打开包含目标视频或图片的网页，正常播放几秒，让页面完成资源加载。

步骤 2：唤起插件面板

点击工具栏中的 PaiwayFlow 图标，面板会列出当前页面已嗅探到的全部媒体资源，并标注类型、清晰度与体积。

步骤 3：选择并下载

勾选需要的资源，选择保存清晰度，点击「开始下载」。下载完成后可在面板的「已完成」列表中直接打开文件所在目录。

步骤 4：处理分片流

遇到 M3U8 分片流时，插件会自动下载全部分片并合成完整文件，过程中请保持页面标签不要关闭。

四、使用建议

下载前先让视频完整播放一遍，可显著提高嗅探成功率。
遇到加密流（DRM）时插件无法解密，这属于版权保护机制，请遵守相关规定。
批量下载建议一次不超过 10 个任务，避免带宽被占满导致分片丢失。
定期在 chrome://extensions/ 中检查更新，新版本会适配更多站点结构。

常见问题

Q1：插件安装后图标是灰色的，点不开怎么办？

先在普通网页（非 Chrome 内置页面）中点击图标。chrome:// 开头的页面和扩展商店页面禁止扩展运行，属于浏览器限制。

Q2：为什么有的视频嗅探不到？

部分站点使用加密流或把视频放在 iframe 深层页面中。请先完整播放视频，再打开插件面板；若仍无结果，可尝试在 iframe 内单独打开页面后再嗅探。

Q3：下载的分片视频无法播放？

分片流需要合并为完整文件。请确认下载任务显示「已完成」而非「下载中」，未完成时提前关闭标签页会导致分片缺失。

Q4：支持 Edge、Firefox 吗？

当前主版本面向 Chrome 及同内核浏览器（Edge、Brave、360 极速模式等）。其他内核版本在规划中。

版本与更新

v1.1.4　
优化 M3U8 分片合并速度；修复部分站点嗅探不到音频轨的问题；面板新增清晰度筛选。
v1.1.0　
新增批量下载队列；支持图片素材一键提取；修复长文件名保存失败。

PaiwayFlow 官方入口

访问官网立即下载

收起阅读 »