workbuddy部署需按场景开放端口：本地客户端需确保8080（claw http）、18789（openclaw协议）在回环可用；集群部署须双向放行50051–50053（grpc及推理）；出站仅限tcp 443访问auth.codebuddy.cn与claw.codebuddy.cn；严禁开放80/443入站，集群须启用tls双向认证。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您尝试在本地或企业环境中部署WorkBuddy，但发现Claw远程控制、多平台接入或服务间通信异常，则可能是由于关键端口被防火墙或安全组策略拦截。以下是满足基础运行与最小化授权要求的端口开放方案：
一、客户端本地运行必需端口（Windows/macOS桌面版）
WorkBuddy桌面客户端默认以本地进程方式运行，不对外暴露HTTP服务，但需确保以下端口在本机回环接口（127.0.0.1）上可被内部组件自由绑定与通信，无需对外开放至局域网或公网。
1、8080端口：Claw本地HTTP服务监听端口，用于承载Webhook接收、前端调试面板及本地技能市场API调用；若该端口被其他进程占用，WorkBuddy将自动降级至8081，但首次配置阶段必须确保8080可用或显式指定备用端口。
2、18789端口：OpenClaw协议默认通信端口，用于QQ/飞书/钉钉等平台指令经由Claw网关转发至WorkBuddy执行引擎；若启用企业微信URL回调模式则不依赖此端口，但多平台并行时仍需保持监听。
二、集群部署专用端口（Kubernetes/Docker Swarm环境）
当采用workbuddy-cluster Helm Chart部署高可用集群时，gRPC通信链路严格依赖固定端口范围，所有Worker节点与Control Plane之间必须双向放行以下端口，且不可使用NAT或端口映射替代。
1、50051端口：Control Plane gRPC主服务端口，接收Claw调度请求与Agent心跳上报。
2、50052端口：Agent状态同步端口，用于Worker节点向etcd提交任务执行快照与Skills元数据变更。
3、50053端口：多模态推理代理端口，仅当workerGroup.gpu.enabled=true且挂载NVIDIA GPU时启用，用于传输图像/音频编码帧。
三、网络激活与认证必需出站端口
WorkBuddy首次启动需完成在线许可证校验与证书链同步，该过程为单向出站HTTPS连接，仅需允许本机向外发起TCP 443连接，无需开放任何入站端口。
1、TCP 443端口（出站）：必须允许访问域名auth.codebuddy.cn，用于腾讯云认证服务端点的身份核验与本地凭证生成。
2、TCP 443端口（出站）：必须允许访问域名claw.codebuddy.cn，用于拉取Claw插件索引、MCP Server注册及技能市场元数据更新。
四、安全策略最小化实施要点
遵循最小权限原则，所有端口开放策略应限制作用域、协议类型与目标地址，禁止宽泛放行或使用“any”通配符规则。
1、禁止开放80/443入站端口：WorkBuddy桌面版不提供Web服务，无需监听外部HTTP(S)请求；若误开将导致Claw调试面板暴露于局域网，构成未授权控制面风险。
2、集群节点间通信必须启用TLS双向认证：在values.yaml中设置controlPlane.tls.enabled=true，并注入CA证书与密钥，避免明文gRPC流量被中间人窃听或篡改。
3、出站443连接须限定SNI域名白名单：企业防火墙应配置仅允许对auth.codebuddy.cn与claw.codebuddy.cn的SNI标识发起TLS握手，拒绝其他域名的443出站请求，防止凭证泄露或C2信标外连。
