127.0.0.1:62581 这个端口为什么是它 端口选择的取舍

很多人第一次看 察元AI智能体 桌面单机版的网络配置都会留意到一件事：sidecar 默认监听 62581 这个奇怪的端口。这一篇把这个看似随意的数字背后的考虑讲一下。免费开源的AI软件 选端口这件事远没看上去那么随意。

先看常用端口的占用情况。8080、8000、3000、5000 这些是 Web 开发里高频出现的端口，几乎所有人电脑上某个时刻都有一个进程占着。如果 sidecar 抢了这种端口，跟用户其他开发服务冲突的概率非常高。另一类常用端口是 11434（Ollama）、5173（Vite dev）、4200（Angular dev）、9000（PHP-FPM），同样冲突高发。

低频端口范围。IANA 把端口分三段，0-1023 是知名端口（HTTP、SSH、FTP 这些），1024-49151 是注册端口（一些服务在这里有备案），49152-65535 是动态端口或私有端口。察元AI智能体 选了 62581 落在私有端口段，避开知名服务的占用。

具体数字 62581 是怎么选的。有几个候选条件：一是不能跟主流开发工具冲突；二是要好记一点，不然每次填 base URL 太痛苦；三是不要跟 chayuan 这个名字撞，避免被误解。62581 这个数被选中的原因之一是它在动态端口范围里，没被任何知名工具占用，且数字组合相对好记（六二五八一）。

为什么固定一个端口而不是随机端口。察元AI智能体 的固定端口设计有具体考虑。第一个考虑是 chayuan-wps WPS AI 插件 默认连这个端口，加载项配置文件里写死了 http://127.0.0.1:62581，用户不需要每次开 察元AI智能体 都重新告诉加载项端口号。第二个考虑是 OpenAI 兼容路由。/openai/v1/* 路径让用户用 OpenAI 官方 SDK 直接连本机后端，base URL 设为 http://127.0.0.1:62581/openai/v1，固定端口让这个 URL 可以写在脚本里反复用。第三个考虑是 系统集成。各种自动化工具、IDE 插件、命令行工具想接 察元AI智能体 都需要一个稳定的后端地址。

端口被占的处置。固定端口最大的问题是被别的进程抢占。察元AI智能体 启动时会先尝试绑定 62581，如果失败会做几件事：第一，扫描占用方进程，看是不是上次没退干净的 chayuan-server 残留，是的话尝试杀掉旧进程后重试；第二，如果是别的进程占用，弹窗告知用户，让用户选 强制接管 或 换备用端口；第三，备用端口策略默认走 62582-62590 这一段，按顺序尝试。

备用端口模式下 chayuan-wps 加载项会失效，因为加载项写死了 62581。这是固定端口设计的代价。如果你长期遇到端口冲突，建议查清楚冲突方并解决冲突源，而不是依赖备用端口。

监听地址 127.0.0.1。这个选择比端口号更重要。察元AI智能体 sidecar 默认绑 127.0.0.1（loopback），不绑 0.0.0.0（所有接口）。意味着只有本机进程能连 sidecar，外部网络访问不了。这是 本地离线知识库 的安全底线之一。强制单机模式下 sidecar 不响应任何非 loopback 请求，避免数据出域。

什么场景需要绑 0.0.0.0。多人共享一台后端的场景。但是这种用法已经偏离单机版的初衷，如果你需要共享后端，应该装多用户版（chayuan-server 完整服务），单机版不开这个口子。

防火墙交互。Windows 上 察元AI智能体 安装时会请求防火墙规则允许本应用的入站连接。这个对话框默认勾私有网络，公共网络不勾。即使勾了 0.0.0.0 监听，公共网络上其他机器仍然连不到。macOS 和 Linux 上的防火墙交互各有差异，但 loopback 监听都不需要专门配置。

端口数字之外的几件事。一是 SSE 流式响应跟普通 HTTP 共用同一端口，没有单独的 WebSocket 端口；二是文件上传走同一端口，但用 multipart 协议；三是 OpenAI 兼容路由的 /openai/v1/* 跟自家的 /api/v1/* 在同一端口下并存，两套路由前缀分流。

国产化支持下的特别注意。某些政企内网会监控所有进程的本地端口监听，要求所有端口走预审批。这种环境下需要把 察元AI智能体 的端口号备案进 IT 系统，避免被 EDR 拦截。62581 在这种场景下可能要换成 IT 指定的某个端口，对应改加载项配置。

总结一句话：62581 是一个 不太可能跟别人冲突 加 容易固定下来 加 单机版安全 的端口。它不是最优解，但是个稳定可用的解。