1. neo4j-community 单机部署后 bolt 连不上的真实场景很多人把 neo4j-community 解压完、服务也跑起来了浏览器打开http://localhost:7474能登录就以为大功告成。结果本地 AI 编码工具一接立刻报Unable to connect to bolt://localhost:7687或者local proxy failed。这个问题的核心不在 Neo4j 本身而在neo4j.conf里 bolt 监听地址、端口和认证这三件事没对齐。neo4j-community 是 Neo4j 的社区单机版适合本地做知识图谱、图数据实验、给 AI 工具当外部记忆库。它能做什么一句话把实体和关系存成图用 Cypher 查询通过 bolt 协议对外提供连接。适合谁适合在本地跑 AI 编码助手、想让助手读写图数据库的开发者也适合刚接触图数据库、想先把单机链路跑通的小白。我这次的环境是 WindowsNeo4j 5.26.0解压目录d:\WinUser.dat\CursorMcp\neo4j-community-5.26.0。整个链路是这样的Neo4j 服务监听 bolt 7687本地 AI 工具通过统一 Key 通道拿到模型能力再用 bolt 驱动访问图数据库。这里有个容易忽略的点——AI 工具本身不直接连 Neo4j它需要模型来生成 Cypher 或理解图结构所以模型通道和数据库通道要分别配好。模型通道我用 TaoToken 统一 Key 来打通数据库通道就是这篇要重点调的neo4j.conf。先说结论bolt 连不上九成是下面三个原因之一。第一server.bolt.listen_address没配或配错默认只监听本地回环某些工具走 IPv6 或容器网络就找不到。第二server.bolt.tls_level设成了REQUIRED但客户端没带证书握手直接失败。第三认证没初始化neo4j-admin dbms set-initial-password没执行或者密码和客户端里写的不一致报 401。还有一个隐蔽的坑neo4j-community 5.x 默认把 bolt 和 http 的监听地址绑在localhost如果你在 WSL、Docker 或者别的网络命名空间里访问localhost指向的不是宿主机自然连不上。这时候要么改成0.0.0.0要么明确写宿主 IP。下面我把配置、初始化、验证、排障完整走一遍你照着抄就能通。2. TaoToken 统一 Key 前置让 AI 工具链有稳定的模型通道在调 Neo4j 之前得先把 AI 工具链的模型通道理顺。为什么因为本地 AI 编码工具要帮你写 Cypher、解释图结构、生成导入脚本这些都要调模型。如果模型通道不稳定你会在“数据库连不上”和“模型超时”之间反复横跳排障成本翻倍。TaoToken 在这里的角色是统一 Key 通道一个 Key 打通多个模型和工具不用每个工具单独配一套凭证。对做图数据库 AI 工具链的人来说这省掉的是“每个客户端都要重新填 Base URL 和 Key”的重复劳动。它的 API 地址是https://taotoken.net/api控制台在https://taotoken.net/consoleKey 管理在https://taotoken.net/api-keys。具体怎么拿 Key进控制台找到 API Keys 页面新建一个 Key复制出来。这个 Key 后面会填到 AI 编码工具的配置里。注意Key 只显示一次丢了就重建别截图发群里。拿到 Key 之后不同工具的填法不一样。以 Claude Code 这类工具为例需要配三件套Base URL、Key、Model ID。Base URL 填https://taotoken.net/apiKey 填刚复制的Model ID 按你用的模型填。如果是 Cline 或带 MCP 的工具配置里通常有baseUrl、apiKey、model三个字段一一对应。这里要强调TaoToken 是模型通道不是数据库代理。它不会替你连 Neo4j也不会把 bolt 流量转发出去。它的作用是让你的 AI 工具能稳定调到模型模型再去生成操作 Neo4j 的代码。所以两件事要分开配模型通道走 TaoToken数据库通道走neo4j.conf bolt。如果你只是想让 AI 工具帮你写 Cypher配好模型通道就够了。如果你想让工具真正执行查询、读写图数据那还得把 bolt 连通性调通这就是下一节的重点。我建议的顺序是先配 TaoToken 拿到模型能力再调 Neo4j 的 bolt最后在工具里把两者串起来。这样出问题时能快速定位是模型层还是数据库层。顺便说下 Coding Plan如果你长期做图数据库相关的编码和 Agent 任务可以考虑用它的长期编码方案Key 和通道是统一的省得每次换工具重配。入口在https://taotoken.net/coding-plan。模型对话调试在https://taotoken.net/model-chat接入文档在https://taotoken.net/doc。3. 可复制配置neo4j.conf 关键参数与 neo4j-admin 初始化这一节是核心直接给可复制的片段。配置文件路径d:\WinUser.dat\CursorMcp\neo4j-community-5.26.0\conf\neo4j.conf。用编辑器打开找到对应段落修改或者直接追加到文件末尾Neo4j 后出现的配置会覆盖前面的但为了清晰建议改原位置。先看网络和 bolt 相关的最小可用配置# 监听所有网卡方便 WSL/Docker/局域网访问 server.default_listen_address0.0.0.0 # Bolt 协议监听地址和端口AI 工具和驱动走这个 server.bolt.listen_address:7687 # HTTP 监听浏览器访问用 server.http.listen_address:7474 server.http.enabledtrue # 开发环境禁用 TLS避免客户端没证书握手失败 server.bolt.tls_levelDISABLED这里逐个解释。server.default_listen_address0.0.0.0是总开关允许所有网络接口访问。如果你只想本机访问改成127.0.0.1更安全。server.bolt.listen_address:7687里的冒号前面为空表示继承default_listen_address端口 7687 是 bolt 默认端口。server.bolt.tls_levelDISABLED在开发环境很关键很多客户端默认不带证书设成REQUIRED会直接握手失败。再看内存配置按机器内存选档# 小型机器 4GB RAM server.memory.heap.initial_size256m server.memory.heap.max_size512m server.memory.pagecache.size256m# 中型机器4-8GB RAM server.memory.heap.initial_size512m server.memory.heap.max_size1G server.memory.pagecache.size512m# 大型机器 8GB RAM server.memory.heap.initial_size1G server.memory.heap.max_size2G server.memory.pagecache.size1Gheap 是 JVM 堆pagecache 是图数据缓存。pagecache 越大查询越快但别超过物理内存的 50%。我实测下来中型档在 8GB 机器上跑知识图谱够用。配置改完下一步是初始化密码。用neo4j-admin工具进 bin 目录cd d:\WinUser.dat\CursorMcp\neo4j-community-5.26.0\bin .\neo4j-admin.bat dbms set-initial-password ne123456注意这个命令要在服务停止状态下执行否则会报数据库被占用。如果你已经启动过服务并登录改过密码这条命令会失败得先停服务。密码设完安装 Windows 服务.\neo4j.bat install-service Set-Service -Name neo4j -StartupType Automatic Start-Service -Name neo4j验证服务状态Get-Service -Name neo4j看到Running就对了。如果这里起不来先看logs\neo4j.log最后 50 行八成是端口占用或 Java 版本不对。Neo4j 5.26 要求 Java 17 或更高java -version确认一下。关于 AI 工具侧的配置如果你用带 MCP 的工具配置片段长这样以 JSON 为例{ mcpServers: { neo4j: { command: npx, args: [-y, neo4j/mcp-server], env: { NEO4J_URI: bolt://localhost:7687, NEO4J_USERNAME: neo4j, NEO4J_PASSWORD: ne123456 } } } }这里的NEO4J_URI就是 bolt 地址NEO4J_USERNAME和NEO4J_PASSWORD对应你初始化的凭证。模型通道的 Key 不在这里填它在工具的模型配置里单独填 TaoToken 的 Base URL 和 Key。两套配置别混。4. 验证请求cypher-shell 与驱动连通性实测配置写完别急着上 AI 工具先用cypher-shell验证 bolt 本身通不通。这是最干净的验证方式排除了模型层的干扰。进 bin 目录执行cd d:\WinUser.dat\CursorMcp\neo4j-community-5.26.0\bin .\cypher-shell.bat -a bolt://localhost:7687 -u neo4j -p ne123456 RETURN 1 AS ok;如果返回ok 1说明 bolt 连通、认证通过、Cypher 能执行。这一步过了数据库层就没问题。如果报Connection refused是端口没监听报Unauthorized是密码不对报TLS相关是tls_level没设成DISABLED。再用 Python 驱动验证一次因为很多 AI 工具底层用的是官方驱动from neo4j import GraphDatabase driver GraphDatabase.driver( bolt://localhost:7687, auth(neo4j, ne123456) ) driver.verify_connectivity() print(bolt connection ok) with driver.session() as session: result session.run(RETURN 1 AS ok) print(result.single()[ok]) driver.close()跑之前确认装了驱动pip install neo4j。输出bolt connection ok和1就对了。verify_connectivity()这个方法很实用它只验证连接不执行查询适合放在工具启动时做健康检查。再验证端口监听netstat -ano | findstr 7687 netstat -ano | findstr 7474应该看到LISTENING状态。如果 7687 没监听回去检查server.bolt.listen_address有没有写错或者服务根本没起来。浏览器侧验证打开http://localhost:7474用户名neo4j密码ne123456。登录后执行一条 CypherCREATE (n:Person {name: Jerry}) RETURN n;再查MATCH (n:Person) RETURN n;能看到节点就说明 HTTP 和 bolt 都正常。这一步过了你就可以在 AI 工具里让它生成 Cypher 了。比如让工具“帮我查所有 Person 节点”它会调模型生成查询再通过 bolt 执行。这里把模型通道和数据库通道串起来说清楚AI 工具收到你的自然语言请求先调 TaoToken 的模型通道生成 Cypher再通过 bolt 把 Cypher 发给 Neo4j 执行结果返回给工具展示。两个通道各司其职任何一个断了都会报错。所以验证时最好分开测先用cypher-shell确认 bolt 通再用模型对话确认模型通道通。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth这一节对照真实报错逐个拆。这些错我在调 Neo4j AI 工具链时基本都踩过。报错一401 Unauthorizedneo4j.exceptions.AuthError: The client is unauthorized due to authentication failure.原因密码不对或者密码没初始化。排查步骤先用cypher-shell手动连一次确认密码。如果cypher-shell也报 401说明密码错了重新执行neo4j-admin dbms set-initial-password记得先停服务。如果cypher-shell能连、只有 AI 工具报 401那是工具配置里的密码写错了检查NEO4J_PASSWORD字段。还有一种情况Neo4j 首次登录会强制改密码如果你在浏览器改过neo4j-admin设的旧密码就失效了得用新密码。报错二local proxy failedError: local proxy failed to connect to upstream这个错通常出现在 AI 工具的模型通道配置上不是 Neo4j 的问题。原因是工具的 Base URL 或 Key 配错了或者网络到不了https://taotoken.net/api。排查确认 Base URL 是https://taotoken.net/apiKey 是从https://taotoken.net/api-keys复制的完整 Key没有多余空格。如果工具支持测试连接先点测试。这个错和 bolt 无关别去改neo4j.conf。报错三reading choices 相关Error reading choices: unexpected end of JSON input这是模型返回格式解析失败常见于模型通道返回了非预期内容。排查确认 Model ID 填对了别填一个不存在的模型名。如果用的是 TaoToken 统一 Key确认 Key 有对应模型的权限。另外有些工具对返回格式敏感模型返回空内容也会触发这个错。可以先用模型对话页面https://taotoken.net/model-chat单独测一下模型能不能正常返回。报错四OAuth 相关OAuth token exchange failed这个错一般出现在需要 OAuth 的工具或 MCP 服务上。如果你用的是 API Key 模式不该出现 OAuth 流程。排查确认工具配置里用的是 API Key 而不是 OAuth 登录模式。有些工具默认走 OAuth需要手动切到 Key 模式。切完后 Base URL 和 Key 按前面说的填。报错五bolt 连接超时ServiceUnavailable: Failed to establish connection to bolt://localhost:7687排查顺序先netstat看 7687 有没有监听再看neo4j.conf里server.bolt.listen_address和tls_level然后看防火墙有没有拦 7687。Windows 上加防火墙规则New-NetFirewallRule -DisplayName Neo4j Bolt -Direction Inbound -Protocol TCP -LocalPort 7687 -Action Allow如果是在 WSL 或 Docker 里连宿主机localhost要换成宿主机 IP或者把default_listen_address设成0.0.0.0。报错六服务起不来日志报端口占用Web server failed to start. Port 7474 was already in use.排查netstat -ano | findstr 7474找到占用进程要么停掉要么改 Neo4j 端口。改端口的话server.http.listen_address:7475bolt 同理。把上面这些错对照一遍基本能覆盖 90% 的接入问题。核心原则模型通道的错别去改数据库配置数据库的错别去改模型配置先分层定位。6. 语义一致 CTA把模型通道和数据库通道都配稳整篇下来链路是清晰的TaoToken 统一 Key 负责模型通道neo4j.conf bolt 负责数据库通道两者在 AI 工具里汇合。你要做的就是把这两条通道分别配稳再串起来用。模型通道这边Key 在https://taotoken.net/api-keys管理接入文档在https://taotoken.net/doc调试模型用https://taotoken.net/model-chat。如果你长期做图数据库相关的编码和 Agent 任务Coding Plan 在https://taotoken.net/coding-plan通道和 Key 是统一的。Claude Code 相关接入看https://taotoken.net/claude-code-anthropic。数据库通道这边记住三个文件conf\neo4j.conf管配置bin\neo4j-admin.bat管初始化bin\cypher-shell.bat管验证。配置改完必须重启服务才生效Restart-Service -Name neo4j最后给个实用技巧把cypher-shell的验证命令写成一个.ps1脚本每次改完配置跑一遍比在 AI 工具里试错快得多。脚本内容就是前面那条RETURN 1 AS ok;返回 1 就说明数据库层没问题再去查模型层。这样排障路径最短不会在两层之间来回猜。