1. 为什么本地 Neo4j 跑通了Bolt 却连不上很多人第一次装 Neo4j Community浏览器打开http://localhost:7474看到登录界面心里就默认装好了。结果一写 Python 脚本bolt://localhost:7687直接抛ServiceUnavailable或者卡在Unable to retrieve routing information。这不是你代码写错了而是 Bolt 这条链路和 HTTP 那条链路是两套独立配置neo4j.conf里少一行、端口被占、TLS 级别对不上都会让 HTTP 正常、Bolt 挂掉。这篇就围绕 Neo4j Community 本地实例把neo4j.conf的关键项、Bolt 连接验证、Cypher 冒烟查询串成一条能跟做的路径。同时补一个容易被忽略的点当你在 Cursor、Cline 这类 AI 工具里挂 Neo4j 相关的 MCP 或自定义工具时模型侧 endpoint 如果散落在各个配置文件里Key 管理会很乱。把 AI 工具侧的 endpoint 统一改到 TaoTokenhttps://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content用一把 Key 管住模型调用Neo4j 本地实例专心跑图数据两边职责分开排障时不会互相甩锅。适合谁看刚接触图数据库、想在本机把 Neo4j Community 跑起来并验证 Bolt 的开发者已经在用 AI 编码工具、想把模型 Key 收拢到一处的同学。核心检索词就三个neo4j-community 本地配置、neo4j.conf Bolt 端口、Cypher 冒烟查询。下面从环境准备讲到连接检查每一步都给可复制的命令和配置。先说清楚一个概念Bolt 是 Neo4j 的二进制协议官方驱动Python、Java、JS默认都走它端口 7687。HTTP 的 7474 只服务浏览器和 REST两者互不影响。所以你看到 7474 能开不代表 7687 通。验证 Bolt 必须用驱动或cypher-shell不能靠浏览器。2. TaoToken 前置把 AI 工具侧 Key 收拢到一处在动 Neo4j 之前先把 AI 工具侧的接入理清楚因为后面调试图查询时你大概率会让模型帮你生成 Cypher模型 endpoint 配得乱排障时容易误判是 Neo4j 的问题。TaoToken 在这里的角色是统一模型调用的入口。你不需要在 Cursor、Cline、Codex 各自的配置里塞不同的 Key而是把 Base URL 指向 TaoToken 的 API 地址Key 用同一把模型 ID 按需选。这样 Neo4j 本地实例和模型调用是两条独立链路出问题时能快速定位是哪边。接入信息如下建议先记下来官网入口https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI Base URLhttps://taotoken.net/api模型对话页https://taotoken.net/api/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewriteCoding Planhttps://taotoken.net/api/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite控制台https://taotoken.net/api/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewriteAPI Keys 管理https://taotoken.net/api/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite接入文档https://taotoken.net/api/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewriteClaude Code 接入https://taotoken.net/api/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaude-code-anthropicutm_campaignrewrite拿到 Key 的路径是进 API Keys 页面创建复制出来。注意 Key 只在创建时完整显示一次丢了就重建。这一步不涉及任何网络工具就是普通的网页操作。为什么要在 Neo4j 教程里提这个因为实际调试时你可能会用 AI 工具生成 Cypher 语句、解释执行计划、或者把 Neo4j 的报错贴给模型分析。如果模型侧 Key 分散在多个工具里改一次要动好几处很容易漏。统一到 TaoToken 后Base URL 和 Key 就一套模型 ID 按场景换。下面第三节会给一份可直接复制的配置片段把 Base URL、Key、Model ID 三件套写全。需要提醒的是TaoToken 是模型调用入口不是 Neo4j 的代理也不替代任何编辑器或数据库。Neo4j 的数据、Bolt 连接、Cypher 执行全在你本地实例完成两者不要混为一谈。3. 可复制配置neo4j.conf 关键项与 AI 工具 settings这一节给两份配置一份是 Neo4j 的neo4j.conf一份是 AI 工具侧的 settings 片段。路径按你实际解压位置改我这里用D:\neo4j\neo4j-community-5.26.0举例。先看neo4j.conf位置在conf\neo4j.conf。Community 版默认很多项是注释掉的你需要显式打开或新增# 监听地址本地调试用 127.0.0.1 更安全要局域网访问再改 0.0.0.0 server.default_listen_address127.0.0.1 # Bolt 协议端口官方驱动走这个 server.bolt.listen_address:7687 server.bolt.advertised_address:7687 # HTTP 端口浏览器访问用 server.http.listen_address:7474 server.http.enabledtrue # 开发环境禁用 Bolt TLS避免驱动报证书错误 server.bolt.tls_levelDISABLED # 内存设置按机器调整4G 内存机器用下面这组 server.memory.heap.initial_size512m server.memory.heap.max_size1G server.memory.pagecache.size512m # 查询日志调试 Cypher 时很有用 dbms.logs.query.enabledtrue dbms.logs.query.threshold1s # 事务超时 db.transaction.timeout60s几个关键点解释一下。server.bolt.tls_levelDISABLED是本地调试最容易被忽略的一项默认如果开了 TLSPython 驱动连bolt://会报Certificate verification failed改成DISABLED或者驱动侧显式关验证都行本地用前者更省事。server.bolt.advertised_address在单机场景和 listen 一致即可集群才需要区分。改完配置后重启服务让配置生效# 管理员 PowerShell Stop-Service -Name neo4j Start-Service -Name neo4j Get-Service -Name neo4j看到Status是Running就继续。如果启动失败先看logs\neo4j.log最后 50 行八成是端口占用或配置语法错。再看 AI 工具侧的 settings 片段。以 Cline 的 MCP 配置为例路径通常在%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json把模型 endpoint 指向 TaoToken{ mcpServers: { neo4j-local: { command: npx, args: [-y, modelcontextprotocol/server-neo4j], env: { NEO4J_URI: bolt://localhost:7687, NEO4J_USERNAME: neo4j, NEO4J_PASSWORD: 你的密码, NEO4J_DATABASE: neo4j } } }, modelProvider: { baseUrl: https://taotoken.net/api, apiKey: 你的TaoToken Key, modelId: claude-sonnet-4-5 } }这里三件套齐全Base URL 是https://taotoken.net/apiKey 是你在 API Keys 页面创建的那把Model ID 按你实际可用的填。Neo4j 的连接信息放在 MCP server 的 env 里和模型 Key 分开职责清晰。如果你用的是 Codex配置在~/.codex/auth.json结构类似把 base URL 和 key 填进去即可。Claude Code 的话走claude-code-anthropic那个接入页按文档把 Base URL 和 Key 配好。不管哪个工具核心就一句模型侧 endpoint 统一到 TaoTokenNeo4j 侧连接信息留在本地 MCP 配置里。4. 验证请求Bolt 连接检查与 Cypher 冒烟查询配置改完必须验证 Bolt 真的通。分三步端口检查、驱动连接、Cypher 查询。第一步确认 7687 在监听netstat -ano | findstr 7687 Test-NetConnection -ComputerName localhost -Port 7687Test-NetConnection返回TcpTestSucceeded : True才算通。如果 False回去看服务状态和neo4j.conf的server.bolt.listen_address。第二步用 Python 驱动验证连接。先装驱动pip install neo4j然后跑一段最小验证from neo4j import GraphDatabase uri bolt://localhost:7687 auth (neo4j, 你的密码) driver GraphDatabase.driver(uri, authauth) try: driver.verify_connectivity() print(Bolt 连接成功) finally: driver.close()verify_connectivity()不报错就说明 Bolt 链路通了。如果报AuthError是密码不对报ServiceUnavailable是端口或服务问题报CertificateError回去检查tls_level。第三步跑 Cypher 冒烟查询确认读写都正常from neo4j import GraphDatabase driver GraphDatabase.driver(bolt://localhost:7687, auth(neo4j, 你的密码)) def smoke_test(tx): # 写入 tx.run(MERGE (p:Person {name: $name}) SET p.age $age, name小雨, age28) # 查询 result tx.run(MATCH (p:Person {name: $name}) RETURN p.name AS name, p.age AS age, name小雨) record result.single() return record[name], record[age] with driver.session(databaseneo4j) as session: name, age session.execute_write(smoke_test) print(f查询返回: {name}, {age}) driver.close()预期输出查询返回: 小雨, 28。这一步同时验证了写事务和读查询比单纯RETURN 1更有说服力。如果你不想写 Python用cypher-shell也行在bin目录下.\cypher-shell.bat -a bolt://localhost:7687 -u neo4j -p 你的密码 RETURN 1 AS ok返回ok列值为 1 就通了。cypher-shell走的就是 Bolt能连上说明协议层没问题。再补一个稍复杂的查询验证关系遍历CREATE (a:Person {name: 小雨})-[:KNOWS]-(b:Person {name: rainyxin}) RETURN a.name, b.name然后在浏览器http://localhost:7474里执行MATCH (a)-[r]-(b) RETURN a, r, b能看到图结构渲染出来说明数据写入和可视化都正常。5. 常见错排查401、local proxy failed、reading choices调试过程中有几类报错特别高频逐个对照。401 Unauthorized。这个在 Neo4j 侧通常是密码错在 AI 工具侧通常是 TaoToken Key 没填对或过期。区分方法看报错来自哪个请求。如果是neo4j.exceptions.AuthError去neo4j.conf确认没开dbms.security.auth_enabledfalse之外的怪配置或者用neo4j-admin dbms set-initial-password重置密码。如果是模型调用返回 401去 API Keys 页面确认 Key 状态重新复制一次填进 settings。local proxy failed。这个报错一般出现在 AI 工具发起模型请求时说明工具侧的网络配置或 Base URL 写错了。检查baseUrl是不是https://taotoken.net/api注意结尾不要多斜杠或少路径。有些工具要求 base URL 带/v1以接入文档为准。这个错和 Neo4j 无关别去翻neo4j.conf。reading choices 相关报错。典型的是Error reading choices或choices field missing这是模型返回结构不符合工具预期多半是 Model ID 填错或者工具用的协议和 TaoToken 返回的格式不匹配。去模型对话页确认你填的 Model ID 可用再对照接入文档检查请求格式。Neo4j 这边不受影响。Bolt 连接超时。neo4j.exceptions.ServiceUnavailable: Couldnt connect to localhost:7687。按顺序查服务是否 Running、7687 是否监听、防火墙是否拦、tls_level是否 DISABLED。Windows 上防火墙偶尔会拦 Java 进程加一条入站规则New-NetFirewallRule -DisplayName Neo4j Bolt -Direction Inbound -Protocol TCP -LocalPort 7687 -Action AllowOAuth 相关报错。如果你在 Claude Code 里看到 OAuth 报错说明认证方式没切到 API Key 模式。按claude-code-anthropic接入页的说明把认证改成 Key 方式Base URL 指向 TaoToken。这个和 Neo4j 完全无关别混在一起排查。Cypher 语法错但报错很模糊。比如Invalid input先看logs\query.log开了dbms.logs.query.enabledtrue后慢查询和失败查询都会记进去比控制台报错详细。排查原则就一条先确定报错来自 Neo4j 链路还是模型链路。Neo4j 的错带neo4j.exceptions前缀或出现在neo4j.log模型链路的错出现在 AI 工具的输出面板带 HTTP 状态码。分清楚再动手能省一半时间。6. 语义一致 CTA按场景选入口Neo4j 本地实例跑通后接下来看你的使用场景选入口。如果你是在排障或接入阶段需要查 Key、看接入文档走这两个API Keys 管理https://taotoken.net/api/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite接入文档https://taotoken.net/api/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite如果你只是想验证某个模型能不能用、返回格式对不对去模型对话页直接试模型对话https://taotoken.net/api/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite如果你是长期用 AI 工具写代码、跑 Agent需要稳定的编码额度看 Coding PlanCoding Planhttps://taotoken.net/api/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite控制台入口在这里方便你统一看用量控制台https://taotoken.net/api/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite最后给一个实操建议Neo4j 的neo4j.conf改完后养成先cypher-shell跑RETURN 1再写业务代码的习惯。Bolt 通了后面所有 Cypher 调试才有意义。模型侧同理先用模型对话页确认 Key 和 Model ID 可用再填进工具配置。两边各自验证出问题不互相干扰。