OpenClaw与Claude CLI协议桥接：构建智能体专属API网关-深圳市維司達科技有限公司

1. 项目概述：为OpenClaw智能体搭建通往Claude的专属桥梁

如果你正在使用OpenClaw框架来构建Discord或Telegram上的AI智能体，并且希望让这些智能体拥有Claude的强大推理和工具调用能力，那么你很可能已经遇到了一个核心难题：OpenClaw遵循OpenAI的API格式，而Claude Code CLI（命令行工具）则使用一套完全不同的交互协议。直接让它们对话，就像让一个说英语的人和一个说中文的人直接沟通一样困难。openclaw-claude-bridge这个项目，就是为了解决这个“语言不通”的问题而生的。

简单来说，它是一个轻量级的HTTP代理服务器，扮演着“翻译官”和“调度员”的角色。它接收来自OpenClaw智能体的、符合OpenAI API标准的请求，将其“翻译”成Claude CLI能理解的指令，然后启动或复用Claude CLI进程来处理请求。接着，它再将Claude CLI返回的、可能包含特殊XML格式工具调用的结果流，实时“翻译”回OpenAI API的格式，并流式传输给OpenClaw。整个过程对两端都是透明的，OpenClaw智能体以为自己正在调用一个标准的GPT-4接口，而Claude CLI则以为自己在一个普通的终端会话中工作。

这个项目的核心价值在于，它让你无需修改OpenClaw或Claude CLI的任何一行代码，就能无缝地将Claude模型集成到你的智能体工作流中。这意味着你可以立即享受到Claude模型（如Opus、Sonnet、Haiku）在复杂推理、代码生成和长上下文处理方面的优势，同时继续使用OpenClaw成熟的工具调用、会话管理和多平台（Discord/Telegram）集成能力。对于已经基于OpenAI API构建了复杂智能体生态的开发者来说，这无疑是一个低成本、高效率的扩展方案。

2. 核心架构与设计思路拆解

2.1 为什么需要一座“桥”？协议差异的本质

要理解这座桥的设计，首先得看清两端的“语言”差异有多大。OpenAI的Chat Completion API是一个基于HTTP/JSON的请求-响应（或流式响应）接口。它高度结构化，请求体里明确包含了messages数组（包含role和content）、可选的tools数组（定义工具规格），以及tool_choice等参数。响应体同样结构化，对于工具调用，会返回一个包含tool_calls数组的message对象。

而Claude Code CLI是一个本地命令行工具。你通过标准输入（stdin）向它发送纯文本（或包含特定格式指令的文本），它通过标准输出（stdout）流式地返回响应。它的“系统提示”、“工具调用协议”都需要通过特定的命令行参数（如--system，--tools）或在输入文本中嵌入XML标签（如<thinking>，<tool_call>）来传达。它没有内置的HTTP服务器，也不理解JSON格式的聊天历史。

这种差异导致了几个关键挑战：

协议转换：如何将结构化的JSON消息历史，转换成一段连贯的、包含上下文和工具调用指令的纯文本提示？
会话保持：HTTP是无状态的，但Claude CLI会话是有状态的（它会在本地保存会话文件以实现记忆）。如何将多个独立的HTTP请求关联到同一个持久的CLI会话？
流式交互：OpenAI API支持Server-Sent Events（SSE）流式返回。如何将Claude CLI的stdout流实时地、分块地转换成SSE事件流？
工具调用循环：OpenAI格式中，模型一次响应可以包含多个并行工具调用。Claude CLI的工具调用是嵌入在文本流中的XML块。如何准确解析并转换，并确保工具执行结果能正确地反馈给下一轮对话？

openclaw-claude-bridge的架构正是围绕解决这些挑战而设计的。它不是一个简单的请求转发器，而是一个有状态的、具备协议翻译和会话管理能力的中间层。

2.2 核心工作流程与数据流转

让我们跟随一个典型的用户提问到AI响应的全过程，来理解这座桥的内部运作：

请求接收与解析：OpenClaw智能体在Discord频道中收到用户消息。它根据配置，向http://localhost:3456/v1/chat/completions发送一个POST请求。这个请求的格式与调用gpt-4完全一致，包含了当前对话历史（messages）和可用的工具定义（tools）。桥接服务（运行在3456端口）的server.js接收到这个请求。
会话路由与查找：这是状态管理的核心。桥接器需要为每个“智能体+对话频道”的组合维护一个独立的Claude CLI会话，以实现记忆功能。它使用channel_id + agent_name作为路由键，在内存中和持久化的state.json文件里查找是否已存在活跃会话。如果找到，则“恢复”该会话；如果没找到，则创建一个新的会话ID，并准备启动一个新的Claude CLI进程。
请求翻译与组装：convert.js模块开始工作。它将OpenAI格式的messages数组（系统消息、用户消息、助手消息、工具消息）转换成一个单一的、格式化的文本字符串。这个字符串会模拟一个连贯的对话历史。同时，tools.js模块会动态分析请求中的tools数组，生成一段详细的、自然语言描述的工具使用说明书。这段说明书会被注入到系统提示（通过--system参数）或对话上下文的开头，告诉Claude“你现在拥有这些工具，请按特定XML格式调用它们”。
启动/交互CLI进程：claude.js模块负责与Claude CLI二进制文件交互。如果是一个新会话，它会使用child_process.spawn启动一个Claude CLI子进程，并传递一系列参数：
- --model：根据请求中的模型字段映射（如claude-opus-latest映射为opus）。
- --system：包含动态生成工具说明的系统提示。
- --tools ""：这是一个关键的安全设置。它禁用了Claude CLI所有原生的、可能具有潜在风险的工具（如直接执行Bash命令、读写文件），强制Claude只能通过我们定义的、由OpenClaw管理的工具协议来调用功能。
- --dangerously-skip-permissions：由于我们禁用了原生工具，这个参数是安全的，它允许CLI在无头（无终端交互）模式下运行。
- --session：指定会话文件路径，实现持久化记忆。
- --effort：根据OpenAI请求中的reasoning_effort参数，映射为Claude的思考强度（low，medium，high）。
流式响应解析与转换：桥接器将组装好的提示文本通过stdin发送给Claude CLI进程。然后，它开始实时读取CLI的stdout输出流。claude.js中的解析器会严密监控输出流，区分以下几种内容：
- 普通文本：直接清洗后，通过SSE以data: {"choices":[{"delta":{"content":"..."}}]}\n\n的格式流式返回给OpenClaw。
- 思考过程（<thinking>...</thinking>）：如果思考功能开启，这部分内容可以被选择性地转发或用于内部调试，但通常不会作为最终响应返回给用户。
- 工具调用（<tool_call id="..." name="...">{...}</tool_call>）：这是关键时刻。解析器会捕获完整的XML块，将其解析，并转换成OpenAI格式的tool_calls数组。然后，桥接器会立即结束当前流，将一个包含tool_calls的完整message对象返回给OpenClaw。桥接器至此任务完成，它不执行工具。
完成循环：OpenClaw收到包含tool_calls的响应后，会用自己的工具执行器（Gateway）去运行这些工具，获取结果。然后，OpenClaw会构造一个新的请求，其中messages数组会追加一条role为tool的消息，包含工具执行的结果。这个新请求再次发送给桥接器。桥接器通过相同的会话路由键找到之前的Claude CLI会话，将工具执行结果作为新的输入追加进去，Claude CLI便能基于之前的上下文和工具结果继续思考或回复。如此循环，直至Claude返回纯文本答案，OpenClaw再将其呈现给终端用户。

关键设计原则：这座桥的职责严格限定在协议转换和会话管理。它绝不越界去执行工具或处理业务逻辑，这保证了架构的清晰和安全，也使得OpenClaw能够完全掌控工具执行的权限和环境。

3. 核心模块深度解析与实操要点

3.1 会话管理：状态、记忆与生命周期的艺术

会话管理是桥接器稳定性的基石。它必须高效、准确地在无状态的HTTP世界和有状态的CLI进程世界之间建立映射。

三级会话查找策略：桥接器采用了一个精细的三级查找策略来定位会话，确保在异常情况下（如进程崩溃、服务重启）也能最大程度保持会话连续性：

内存映射（第一优先）：在服务运行时，一个全局的Map对象维护着路由键 -> CLI进程句柄/会话信息的映射。这是最快的查找方式。
持久化状态文件（第二优先）：所有会话的元数据（路由键、会话ID、创建时间、最后活动时间、token使用统计等）会定期保存到项目根目录的state.json文件中。当服务重启时，会从这里加载历史会话记录。
磁盘会话文件校验（最终保障）：仅仅在state.json中有记录还不够。在尝试恢复一个会话前，桥接器会检查对应的Claude CLI会话文件（通常位于~/.config/claude/sessions/）是否真实存在。如果文件丢失（可能被手动清理或CLI异常退出），桥接器会认为该会话已失效，自动将其从状态中清除，并为此路由键创建一个全新的会话。这避免了因状态不一致导致的错误。

会话清理与资源回收： Claude CLI会话文件会占用磁盘空间。桥接器提供了两种清理机制：

自动修剪：在内部状态维护时，会定期检查并移除那些在磁盘上已不存在的会话记录（“僵尸”会话）。
手动清理：通过Dashboard的“清理会话”按钮或调用/cleanupAPI，可以删除所有超过24小时的CLI会话文件。请注意：这只会删除CLI的会话文件，桥接器自身的state.json中的记录会在下次尝试恢复时因文件不存在而被自动清理。

实操心得：会话隔离的妙用：由于会话键是channel_id + agent_name，这意味着在同一个Discord频道里，你可以部署多个不同职能的智能体（比如一个“研究助手”和一个“代码审查员”），它们彼此拥有完全独立的记忆上下文，互不干扰。这为构建复杂的多智能体协作场景提供了基础。

3.2 工具调用协议：动态注入与安全隔离

让Claude能够理解并调用OpenClaw定义的工具，是整个项目最精妙的部分之一。其核心在于“动态提示词工程”。

动态工具协议生成：当桥接器收到一个包含tools数组的请求时，tools.js模块会将其转换成一段清晰的自然语言描述。例如，一个“获取天气”的工具定义：

{ "type": "function", "function": { "name": "get_weather", "description": "Get the current weather for a city.", "parameters": {...} } }

会被转换成类似这样的文本，并插入到系统提示中：

你拥有以下可以调用的工具。当你需要使用时，请严格按照此格式输出： <tool_call id="一个随机UUID" name="get_weather"> {"city": "北京"} </tool_call> 工具说明：get_weather - Get the current weather for a city. 参数：city (string, required): The city name.

这个过程是完全动态的。无论OpenClaw那边新增、修改或删除了什么工具，桥接器都无需更新代码，下次请求时自动就会包含最新的工具说明。这实现了与OpenClaw工具生态的松耦合集成。

原生工具的安全禁用： Claude CLI本身内置了一些强大的工具，如bash（执行Shell命令）、read、write（读写文件）。在桥接场景下，允许直接使用这些工具是极其危险的，因为桥接器通常以服务形式运行，权限较高。因此，启动Claude CLI时，必须加上--tools ""参数。这个参数将CLI的原生工具列表设置为空，从根本上关闭了这扇风险之门。Claude只能通过我们注入的、受控的协议来调用由OpenClaw Gateway管理和鉴权的工具，从而将安全边界牢牢限定在OpenClaw体系内。

3.3 流式处理与性能优化

为了提供与原生OpenAI API相近的流畅体验，桥接器实现了完整的流式响应。

非阻塞I/O与背压处理： Node.js的child_process模块允许我们以非阻塞方式与子进程（Claude CLI）交互。桥接器将CLI的stdout管道连接到可读流，并监听data事件。一旦有数据块到达，解析器立即工作，识别出完整的文本行或XML标签边界，然后将其转换为SSE格式，通过HTTP响应流写入。这里的关键是处理好背压（backpressure）——如果HTTP客户端（OpenClaw）接收速度慢，需要适当缓冲或暂停从CLI stdout读取数据，防止内存溢出。项目通常利用Node.js流自身的暂停/恢复机制来实现这一点。

思考过程（Reasoning Effort）的处理： Claude的“思考过程”是一个强大的功能。桥接器通过reasoning_effort参数控制它。在内部，这个参数被映射为Claude CLI的--effort参数（low，medium，high）和一个环境变量MAX_THINKING_TOKENS。当思考开启时，Claude的输出会包含<thinking>...</thinking>标签。桥接器可以配置是丢弃这部分内容（仅内部日志可见），还是将其作为元数据附加在响应中。对于最终用户体验而言，思考过程通常是不可见的，它只是模型内部推理的痕迹，最终呈现给用户的是思考后的结论。

超时与僵尸进程管理： Claude CLI进程可能因为网络问题、模型负载或复杂推理而长时间无响应。桥接器设置了IDLE_TIMEOUT_MS（默认2分钟）。如果在设定时间内没有从CLI的stdout收到任何新数据，桥接器会认为该进程已挂起，并强制终止（SIGKILL）该子进程，释放资源，同时向客户端返回一个超时错误。这保证了系统的自我修复能力。

4. 从零到一的完整部署与配置实操

4.1 环境准备与依赖安装

在开始之前，请确保你的系统满足以下条件：

操作系统：macOS（Intel或Apple Silicon）或 Linux（x86_64或ARM）。Windows系统理论上可通过WSL2运行，但非官方支持。
Node.js：版本18或更高。推荐使用nvm进行版本管理。
Claude Code CLI：已安装并完成登录认证。这是前置必要条件。
OpenClaw：已安装并配置好Discord/Telegram网关，且网关服务正在运行（默认端口18789）。

第一步：安装Claude Code CLI如果你还没有安装，请访问Anthropic官方文档获取安装指令。通常可以通过包管理器安装：

# macOS (Homebrew) brew install claude # Linux (部分发行版) # 请参考官方文档下载对应架构的二进制文件

安装后，在终端执行claude auth login，按照指引完成浏览器登录认证。完成后，运行claude --version和claude auth status确认安装和登录成功。

第二步：获取并初始化桥接器

# 克隆项目代码 git clone https://github.com/shinglokto/openclaw-claude-bridge.git cd openclaw-claude-bridge # 安装Node.js依赖（这会自动构建Dashboard前端） npm install

npm install命令不仅会安装后端依赖，还会自动进入dashboard/目录，安装前端依赖并执行构建，将生成好的静态文件放入dashboard/dist/。如果前端构建失败，你可以手动进入dashboard/目录运行npm install && npm run build。

第三步：配置环境变量项目使用.env文件管理配置。首先复制示例文件：

cp .env.example .env

现在，用文本编辑器打开.env文件。以下是一些关键配置项的说明：

# 仪表盘密码（重要！）。设置后，访问 http://your-ip:3458 需要输入用户名 admin 和此密码。 # 如果不设置，仪表盘将对局域网开放，无密码保护。 DASHBOARD_PASS=your_strong_password_here # Claude CLI模型别名映射。如果你订阅了Claude API并配置了自定义模型别名，可以在这里修改。 # 例如，如果你将100万上下文的Opus模型别名为“opus-1m”，就在这里修改。 OPUS_MODEL=opus SONNET_MODEL=sonnet HAIKU_MODEL=haiku # 并发控制。防止单个频道或全局请求过多导致资源耗尽。 MAX_PER_CHANNEL=2 # 每个频道（channel_id）同时最多处理2个请求 MAX_GLOBAL=20 # 全局同时最多处理20个请求 # CLI进程超时（毫秒）。如果Claude CLI在120秒内没有输出任何内容，进程将被终止。 IDLE_TIMEOUT_MS=120000 # 服务端口 OPENCLAW_BRIDGE_PORT=3456 # API服务端口，仅绑定到localhost OPENCLAW_BRIDGE_STATUS_PORT=3458 # 仪表盘端口，绑定到所有网络接口（0.0.0.0）

根据你的网络环境和安全需求调整这些值，尤其是DASHBOARD_PASS。

4.2 启动服务与基础测试

配置完成后，可以启动服务进行测试：

# 开发模式启动（带日志输出） npm start # 或者，以后台进程方式启动（使用pm2，需额外安装） # npm install -g pm2 # pm2 start src/index.js --name claude-bridge

如果一切正常，你将在终端看到服务器启动的日志，包括API和Dashboard的监听地址。

执行健康检查：打开另一个终端，运行：

curl http://localhost:3456/health

如果返回{"status":"ok"}，说明API服务运行正常。

访问仪表盘：在浏览器中打开http://localhost:3458（如果在本机）。如果你设置了DASHBOARD_PASS，会弹出HTTP Basic认证窗口，输入用户名admin和你设置的密码。首次进入，仪表盘可能是空的，因为没有流量经过。界面顶部的状态栏应显示“在线”和正常运行时间。

4.3 配置OpenClaw以使用桥接器

桥接器就绪后，需要告诉OpenClaw它的存在。编辑你的OpenClaw主配置文件（通常位于~/.openclaw/openclaw.json）：

在models.providers部分，添加一个新的提供商，命名为claude-bridge。
设置baseUrl为桥接器的API地址（http://localhost:3456/v1）。
apiKey可以任意填写一个非空字符串（如not-needed），因为桥接器目前不进行API密钥验证。
在models数组下，定义你希望通过桥接器使用的Claude模型。id字段是OpenClaw内部使用的模型标识符，name是显示名称。contextWindow和maxTokens请根据你实际使用的Claude模型版本设置（例如，Opus 1M上下文版本对应100万）。

一个完整的配置示例如下：

{ "models": { "providers": { "claude-bridge": { "baseUrl": "http://localhost:3456/v1", "apiKey": "not-needed", "api": "openai-completions", "models": [ { "id": "claude-opus-latest", "name": "Claude Opus (via Bridge)", "contextWindow": 1000000, "maxTokens": 128000, "reasoning": true }, { "id": "claude-sonnet-latest", "name": "Claude Sonnet (via Bridge)", "contextWindow": 1000000, "maxTokens": 64000, "reasoning": true }, { "id": "claude-haiku-latest", "name": "Claude Haiku (via Bridge)", "contextWindow": 1000000, "maxTokens": 64000, "reasoning": false } ] } } } }

保存配置文件后，重启OpenClaw网关服务，使配置生效。

4.4 配置Discord/Telegram智能体使用Claude模型

最后一步，修改你的智能体定义，让其使用我们刚刚配置的模型。在你的智能体配置文件（例如my_agent.json）中，找到model字段，将其值改为你在上一步中定义的id，例如claude-opus-latest。

{ "name": "我的Claude助手", "model": "claude-opus-latest", // 指向桥接器提供的模型 "system_prompt": "你是一个乐于助人的助手...", // ... 其他配置 }

完成以上所有步骤后，当你的智能体在Discord或Telegram中被触发时，它就会将请求发送到本地的桥接器，桥接器再驱动Claude CLI生成响应。你可以立即在Discord频道中与智能体对话，测试工具调用，并同时在桥接器的仪表盘上观察实时请求、会话状态和资源使用情况。

5. 高级配置、监控与故障排查实录

5.1 仪表盘：你的全景监控中心

桥接器内置的React仪表盘是一个强大的运维工具，它提供了近乎实时的系统状态可视化。理解每个面板的用途，能让你在出现问题时快速定位。

头部状态栏：提供全局概览。关注“活跃请求数”是否长期居高不下（可能并发过高），“错误计数”是否持续增长，“会话磁盘大小”是否异常膨胀（可能需要手动清理）。
智能体侧边栏：列出了所有活跃过的智能体。颜色标识其活跃度：绿色（5分钟内有活动）、琥珀色（30分钟内）、灰色（闲置）。点击任一智能体可以过滤下方所有面板的数据，这在多智能体环境下排查特定问题非常有用。
实时活动流：这是最动态的面板。它以日志流的形式展示每一个关键事件，并配有表情符号：
- 🧠思考：Claude开启了内部推理。
- 🔧工具调用：Claude请求调用一个工具。
- 🔄恢复会话：请求成功关联到了一个已存在的持久化会话。
- ♻️刷新上下文：因上下文长度限制，会话被重置（新建）。
- ✅完成：请求成功处理完毕。
- ❌错误：处理过程中发生错误（如CLI进程崩溃、解析失败）。
上下文卡片：以进度条形式展示每个会话的令牌使用情况。颜色从绿（<40%）到黄（40-65%）再到红（>65%）。红色警告你该会话可能很快会触及上下文窗口限制，导致性能下降或需要昂贵的上下文刷新。
请求详情表：这是进行深度分析的地方。表格列出了每一个历史请求，包含时间、频道、会话ID、恢复方式、提示大小、模型、思考级别、输入/输出令牌数、估算成本、缓存命中率、耗时和状态。你可以点击行展开，查看该请求的详细活动日志和任何错误信息。支持按频道和恢复方式筛选，是排查频道特定问题或工具调用问题的利器。

5.2 系统服务化：实现开机自启

对于生产环境，你需要将桥接器设置为系统服务，确保它在服务器重启后能自动运行。

macOS (使用 launchd)：项目提供了便捷的安装脚本：

cd openclaw-claude-bridge ./service/install-mac.sh

这个脚本会自动检测Node和项目路径，读取当前目录下的.env文件，并生成一个正确的launchd plist配置文件，将其安装到~/Library/LaunchAgents/目录下，并立即加载启动。

手动管理：

# 查看服务状态 launchctl list | grep openclaw-claude-bridge # 重启服务（例如在修改.env后） launchctl bootout gui/$(id -u)/com.openclaw.claude-bridge launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.openclaw.claude-bridge.plist # 查看日志（日志默认输出到项目目录下的 bridge.log） tail -f ~/openclaw-claude-bridge/bridge.log

Linux (使用 systemd user service)：

# 1. 复制服务文件到用户systemd目录 cp service/openclaw-claude-bridge.service ~/.config/systemd/user/ # 2. （可选）编辑服务文件，确认WorkingDirectory和ExecStart路径正确 # WorkingDirectory=/path/to/your/openclaw-claude-bridge # ExecStart=/usr/bin/node /path/to/your/openclaw-claude-bridge/src/index.js # 3. 重载systemd配置 systemctl --user daemon-reload # 4. 启用并立即启动服务 systemctl --user enable --now openclaw-claude-bridge # 5. 允许用户服务在未登录时启动（关键步骤！） loginctl enable-linger $USER

Linux服务管理：

# 查看状态 systemctl --user status openclaw-claude-bridge # 查看最新日志 journalctl --user -u openclaw-claude-bridge -n 50 -f # 重启服务 systemctl --user restart openclaw-claude-bridge # 停止服务 systemctl --user stop openclaw-claude-bridge

5.3 常见问题与排查技巧

在实际部署和运行中，你可能会遇到以下问题。这里提供一套排查思路：

问题一：OpenClaw智能体无响应或返回“Provider Error”

检查桥接器服务状态：首先确认npm start进程是否在运行，或systemd/launchd服务是否处于active (running)状态。运行curl http://localhost:3456/health看是否返回ok。
检查OpenClaw配置：确认openclaw.json中baseUrl的端口（默认3456）与桥接器启动端口一致。确认模型id拼写正确。
检查网络连接：如果OpenClaw和桥接器不在同一台机器，确保防火墙放行了3456端口的访问（但出于安全考虑，建议部署在同一台机器，桥接器API端口只绑定localhost）。
查看桥接器日志：在终端或bridge.log文件中查看是否有错误输出。常见的错误包括Claude CLI未找到、认证失败等。

问题二：Claude CLI进程启动失败或立即退出

验证CLI安装与登录：在终端直接运行claude --version和claude auth status。确保CLI在运行桥接器的用户环境下已正确安装并登录。
检查环境变量：桥接器进程是否继承了正确的PATH？对于systemd服务，有时需要在全路径下指定claude二进制文件，或在服务文件中设置Environment=PATH=...。
查看详细错误：桥接器在启动CLI子进程失败时，会在日志中打印stderr输出。这通常是权限问题或CLI自身错误。

问题三：工具调用不工作，Claude回复“我不知道如何使用这个工具”

检查工具协议注入：在仪表盘的“实时活动流”中，查看请求事件。是否能看到“工具协议已注入”相关的日志？如果没有，说明请求中可能没有携带tools数组，或者桥接器的tools.js模块解析失败。
检查OpenClaw Gateway：工具的实际执行由OpenClaw Gateway负责。确认Gateway服务（端口18789）正在运行，并且智能体配置的工具在Gateway中已正确注册和启用。
查看Claude的输出：在仪表盘展开有问题的请求详情，查看原始的活动日志。有时Claude可能输出了不符合预期格式的XML，导致解析失败。这可能需要调整工具描述的提示词。

问题四：会话记忆似乎丢失了

确认会话路由键：记忆是基于channel_id + agent_name的。如果你更改了智能体的名称，或者频道ID发生了变化（例如在开发测试中频繁创建/删除频道），就会创建一个全新的会话。
检查state.json文件：查看项目根目录下的state.json文件。里面是否保存了你期望的会话记录？文件权限是否正确（桥接器进程有读写权限）？
检查CLI会话文件：Claude CLI的会话文件默认在~/.config/claude/sessions/目录下。查看是否存在与state.json中session ID对应的文件。如果文件丢失，记忆就无法恢复。
查看恢复方式：在仪表盘的请求表中，“恢复方式”列会显示每个请求是如何处理的。New表示创建了新会话，Resume表示恢复了旧会话。如果本该恢复的会话却显示New，说明会话查找失败了。

问题五：性能缓慢或请求超时

监控并发数：查看仪表盘顶部的“活跃请求数”。如果接近或达到MAX_GLOBAL限制，新的请求会被排队。考虑根据服务器配置适当调高该值，但注意每个Claude CLI进程都会消耗显著的内存和CPU。
检查思考级别：reasoning_effort设置为high或xhigh会显著增加Claude的响应时间。对于不需要深度推理的简单对话，可以设置为low或不设置（关闭思考）。
查看CLI进程资源占用：使用top或htop命令查看claude进程的CPU和内存使用情况。处理复杂请求时，Claude模型（尤其是Opus）可能非常消耗资源。
网络问题：如果Claude CLI需要联网访问API（取决于你的CLI配置），网络延迟也会影响速度。确保服务器网络通畅。

问题六：仪表盘无法访问或白屏

检查端口绑定：确认桥接器启动日志中显示Dashboard server listening on port 3458。
检查防火墙：如果从局域网其他机器访问，确保服务器防火墙放行了3458端口（例如sudo ufw allow 3458）。
检查前端构建：如果仪表盘是白屏，打开浏览器开发者工具（F12）查看控制台（Console）是否有JavaScript错误。可能是前端资源未正确构建。尝试进入dashboard/目录重新运行npm run build。
Basic认证问题：如果你设置了DASHBOARD_PASS但忘记了密码，只能通过修改.env文件并重启服务来重置。