1. 项目概述：当Claude Code遇上OpenClaw，一个更聪明的AI工作流诞生了

如果你和我一样，是OpenClaw的深度用户，那么过去几个月的心情大概像坐过山车。我们投入了大量时间，精心调教自己的AI助手，构建了复杂的技能库、记忆系统和自动化流程，结果Anthropic一纸政策调整，直接让通过第三方工具（比如OpenClaw）使用Claude Max订阅变得不再免费。要么接受高昂的API账单，要么放弃我们熟悉的Opus 4.6模型，转向性能稍逊的GPT-5.4或本地模型。这感觉就像你精心装修的房子，突然被告知水电费要按商业标准收取，让人进退两难。

但问题恰恰出在我们的思考惯性上。我们一直把OpenClaw看作“运行Claude的容器”，而Claude Code CLI只是Anthropic官方推出的一个“写代码的工具”。这个认知需要被彻底翻转。FlipClaw的核心洞见在于： Claude Code CLI本身就是目前最强大的AI代理界面，它天然支持你的Max订阅，无需经过任何第三方网关。 我们真正需要的，不是让OpenClaw去“运行”Claude，而是让OpenClaw去“增强”Claude Code。这就是“翻转”架构的精髓。

FlipClaw所做的，就是完成这个翻转。它不再让OpenClaw调用Claude API（从而产生费用），而是让Claude Code CLI成为你与AI交互的主界面，享受Max订阅的无限畅聊。同时，它将OpenClaw降级（或者说升级）为一个强大的“后台操作系统”，专门负责Claude Code天生不具备的能力： 持久化记忆、定时任务、技能库管理和自动化流程 。最终，你得到的是一个“二合一”的超级助手：前端是性能无损、完全免费的Claude Opus 4.6，后端是你熟悉的、功能强大的OpenClaw基础设施，两者共享同一套记忆和知识库。

1.1 核心需求解析：我们到底在解决什么问题？

在深入技术细节之前，我们先明确FlipClaw瞄准的三大核心痛点：

痛点一：成本失控。 这是最直接的驱动力。通过OpenClaw等第三方工具使用Claude，现在会触发API计费。对于重度用户，月度账单轻松突破数百甚至上千美元。FlipClaw通过架构翻转，让你直接使用Claude Code CLI，完美规避了API费用，成本归零。

痛点二：能力割裂。 以前，你的记忆、技能、自动化脚本都“活”在OpenClaw里。一旦切换到Claude Code（无论是为了省钱还是用其更好的代码编辑器），你就进入了一个“失忆”状态。每次对话都是全新的开始，AI助手对你过去的项目、决策、习惯一无所知。FlipClaw通过建立双向记忆桥梁，彻底解决了这个问题。

痛点三：体验降级。 很多人尝试过用GPT-5.4替代Claude Opus 4.6，或者在本地部署开源模型。但社区共识很明确：在需要深度推理、复杂任务规划和创造性工作的“代理性”任务上，这些替代方案与Opus 4.6仍有明显差距。FlipClaw让你无需妥协，就能继续使用最强的模型。

简单来说，FlipClaw不是另一个AI工具，它是一个 架构胶水 和 能力增强层 。它承认Claude Code CLI在交互体验和成本上的优势，也承认OpenClaw在记忆、自动化等基础设施上的不可替代性，然后将两者无缝融合，产生“1+1>2”的效果。接下来，我将带你深入这套系统的每一个齿轮，看看它是如何运作的。

2. 架构翻转：从“容器”到“操作系统”的思维转变

理解FlipClaw，首先要抛弃“OpenClaw运行AI模型”的传统观念。我们来看一张对比图，它清晰地展示了架构的演变：

传统架构 (OpenClaw-centric): 

用户 -> OpenClaw Gateway -> Claude API (付费) -> 响应返回用户
      (记忆、技能、自动化在此处)

在这个模型里，OpenClaw是中心，它负责一切，包括调用昂贵的Claude API。

FlipClaw架构 (Claude Code-centric): 

用户 -> Claude Code CLI (免费，Max订阅) -> 响应返回用户
      ^
      |
      v
OpenClaw Gateway (作为记忆/自动化后台服务运行)
      |
      v
共享记忆库、技能库、定时任务

在这个新模型里，Claude Code CLI是用户直接交互的前端，享受免费订阅。OpenClaw退居后台，变成一个纯粹的“记忆与自动化服务”，通过一系列钩子（Hooks）和桥接脚本，与Claude Code CLI保持同步。

2.1 核心组件交互详解

这个架构的运转依赖于几个关键组件的精密配合：

  1. Claude Code CLI : 你的主工作界面。无论是在终端、VS Code还是桌面应用中使用，所有对话都发生在这里。
  2. SessionEnd / Stop Hooks : 这是Claude Code CLI提供的生命周期钩子。 SessionEnd 在会话正常结束时触发， Stop 在AI每生成完一次回复时触发。FlipClaw利用这两个钩子作为数据采集的入口。
  3. Claude Code Bridge ( claude-code-bridge.py ) : 这是FlipClaw的核心脚本之一。它被配置为 SessionEnd 钩子的处理器。每当你在Claude Code中结束一个会话（比如输入 /bye 或关闭窗口），这个脚本就会被调用，负责将完整的会话记录保存到共享文件系统中。
  4. Claude Code Turn Capture ( claude-code-turn-capture.py ) : 这是另一个核心脚本，绑定到 Stop 钩子。它的任务是“实时记忆”。在AI每回答完一个问题后，它立即运行，使用一个轻量级LLM（默认是GPT-5.4-nano）从刚结束的这轮对话中提取结构化的事实（例如：“用户决定将项目部署到AWS us-east-1区域”），并写入当天的日志文件。这解决了“会话崩溃导致记忆丢失”的问题。
  5. OpenClaw Gateway : 它持续在后台运行，通过PM2等进程管理器守护。它承载了 memory-bridge 等插件，监听来自OpenClaw Agent自身活动的事件（例如，Agent完成一个任务），同样触发事实提取，写入相同的共享记忆库。
  6. 共享文件系统 : 通常是服务器或本地的一个目录（ workspace ）。所有上述组件都向这个目录读写文件。这是Claude Code和OpenClaw之间唯一的“共享内存”。目录结构经过精心设计，便于管理和Dreaming（记忆整合）处理。

实操心得：钩子配置是关键 安装FlipClaw后，务必检查你的Claude Code配置（通常是 ~/.claude/config.json ）。你会看到类似 "hooks": {“sessionEnd”: “python3 /path/to/claude-code-bridge.py”} 的配置。如果这个配置丢失或路径错误，记忆同步就会失效。一个快速的验证方法是：在Claude Code里进行一次简短对话后退出，立刻去检查 workspace/memory/ 目录下是否生成了以当天日期命名的 .md 文件。

2.2 记忆流：数据如何流动与沉淀

理解了组件，我们再看看数据是如何在这个系统中流动和沉淀的，这是FlipClaw智能的源泉：

  1. 实时捕获（Turn-by-Turn） : 这是最高频的流。无论是Claude Code的 Stop 钩子，还是OpenClaw Agent的 agent_end 事件，都会触发 incremental-memory-capture.py 脚本。这个脚本会提取对话中的“事实颗粒”。例如，用户说“帮我用Docker部署Nginx，端口映射到8080”，捕获脚本可能会提取出 [事实] 用户计划部署Nginx服务。 [事实] 部署方式为Docker。 [事实] 计划映射主机端口8080到容器。 这些事实被立即追加到 memory/YYYY-MM-DD.md 文件中。
  2. 会话归档（Session-Level） : 当整个会话结束时（Claude Code的 SessionEnd 或OpenClaw任务完成）， claude-code-bridge.py 会将完整的、多轮对话的原始记录保存为 sessions/ 目录下的JSONL文件。这份存档用于后续的深度分析、搜索和技能自动捕获。
  3. 每日整合（Dreaming - Light Phase） : 每天凌晨（默认4点），OpenClaw内置的 memory-core 插件会启动“浅度睡眠”阶段。它扫描最新的每日日志文件，进行去重、合并相似事实、纠正矛盾陈述等操作。例如，同一天内关于“项目部署端口”的多个事实会被合并成一个最准确的版本。
  4. 长期记忆提升（Dreaming - Deep Phase） : 在浅度整合的基础上，系统会分析哪些事实被频繁提及或访问（高召回率）。这些被认定为重要的知识，会被从每日日志“提升”到永久的 MEMORY.md 文件或按主题分类的 memory/*.md 文件中。 MEMORY.md 是AI的“核心记忆”，每次会话开始前都会被自动加载到上下文，确保AI记得最关键的信息。
  5. 模式发现与洞察（Dreaming - REM Phase） : 这是最有趣的部分。系统会尝试在近期的事实中发现模式、趋势或潜在问题，并生成叙述性的洞察，记录在 DREAMS.md 文件中。例如，它可能发现“过去一周，用户三次询问了关于Kubernetes网络策略的问题”，从而生成一个洞察：“用户可能正在深入学习K8s网络，可准备相关技能或资料。”
  6. 技能自动化成（Auto-Skill Capture） : 这不是一个定时任务，而是一个由事件驱动的流程。当一个新的会话存档产生后，一个自动化流程会评估这个会话是否复杂到值得成为一个可复用的“技能”。如果通过评估，它会自动生成一个结构化的 SKILL.md 文件，包含步骤、前提条件、验证方法和常见陷阱，存放在 skills/ 目录下。

通过这六层处理，原始、杂乱的对话数据被逐步提炼、整合，最终形成高度结构化、易于检索和利用的知识体系。Claude Code和OpenClaw Agent都能从这个体系中读取信息，从而实现真正的“共享记忆”。

3. 部署实战：从零开始搭建你的FlipClaw系统

理论很美好，现在我们来动手搭建。FlipClaw提供了AI引导安装和手动安装两种方式。我强烈推荐 AI引导安装 ，它能处理绝大多数环境检测和配置分支，避免踩坑。但为了让你彻底理解整个过程，我会先详细拆解手动安装的每一步，然后说明AI安装器在背后帮你做了什么。

3.1 环境准备与核心依赖

无论哪种方式，你的系统都需要满足以下基础条件：

  • Node.js 18+ 和 npm : OpenClaw和Claude Code CLI都是Node.js应用。用 node --version 和 npm --version 检查。
  • Python 3.10+ : FlipClaw的许多桥接和捕获脚本是用Python编写的。
  • 基础工具集 : git , curl , jq , openssl 。在Ubuntu/Debian上可通过 sudo apt-get install git curl jq openssl 安装。
  • PM2 : 这是一个Node.js的进程守护管理器，用于确保OpenClaw网关持续运行。通过 npm install -g pm2 安装。
  • API密钥 :
    • Gemini API Key : 这是 必需项 ，用于记忆的语义搜索（向量嵌入）。在 Google AI Studio 申请，免费额度完全够用。
    • OpenAI API Key : 用于事实提取和技能捕获的LLM调用。在 OpenAI平台 申请。虽然会产生费用，但默认使用成本极低的GPT-5.4-nano/mini模型，月开销通常仅几美元。
    • Claude Max订阅或Anthropic API Key : 用于Claude Code CLI本身。没有这个，你根本无法启动 claude 命令。

注意事项：密钥管理 永远不要将API密钥硬编码在脚本或命令行历史中。FlipClaw的安装流程会引导你将密钥写入 openclaw.json 的 env.vars 部分。这是一个相对安全的位置。对于生产环境，可以考虑使用像 dotenv 加载环境变量或专门的密钥管理服务。

3.2 手动安装步骤拆解

假设我们在一台Ubuntu服务器上，为用户 devuser 部署，工作空间放在 /home/devuser/ai_agent 。

步骤1：安装Claude Code CLI并登录 

# 全局安装Claude Code命令行工具
sudo npm install -g @anthropic-ai/claude-code
# 进行认证，这会在浏览器打开Anthropic的登录页面
claude login

执行 claude login 后，跟随提示完成认证。这是使用Claude Code的唯一入口。

步骤2：创建工作空间并初始化OpenClaw配置 

export WORKSPACE="/home/devuser/ai_agent"
export PORT=3050
export AGENT_NAME="MyFlipClawAgent"
mkdir -p "$WORKSPACE"

# 使用openclaw onboard命令生成一个合法的配置文件骨架
OPENCLAW_CONFIG_PATH="$WORKSPACE/openclaw.json" openclaw onboard \
  --non-interactive --accept-risk \
  --flow manual --mode local \
  --gateway-port $PORT --gateway-bind loopback \
  --gateway-auth token --gateway-token "$(openssl rand -hex 16)" \
  --auth-choice skip \
  --workspace "$WORKSPACE" \
  --skip-health

这里有几个关键点：

  • --gateway-bind loopback : 将网关服务绑定到本地回环地址（127.0.0.1），增强安全性，避免服务暴露在公网。
  • --gateway-auth token : 使用令牌认证。后面生成的随机令牌需要妥善保管，虽然FlipClaw架构下外部直接访问网关的需求不大。
  • --auth-choice skip : 跳过复杂的OAuth提供商配置，因为我们的Claude调用已通过Claude Code CLI解决。

步骤3：注入API密钥到配置文件 onboard 命令不会添加API密钥。我们需要手动编辑 openclaw.json ，在 env.vars 部分添加密钥。使用 jq 命令可以安全地完成：

# 假设你的密钥如下（请替换为真实密钥）
OPENAI_KEY="sk-..."
GEMINI_KEY="AIza..."

jq --arg openai "$OPENAI_KEY" --arg gemini "$GEMINI_KEY" \
  '.env.vars = {
    "OPENAI_API_KEY": $openai,
    "GEMINI_API_KEY": $gemini,
    "GOOGLE_AI_API_KEY": $gemini
  }' "$WORKSPACE/openclaw.json" > /tmp/openclaw_new.json && mv /tmp/openclaw_new.json "$WORKSPACE/openclaw.json"

注意：这里设置了 GEMINI_API_KEY 和 GOOGLE_AI_API_KEY 为同一个值，因为OpenClaw内部不同模块可能查找不同的变量名。

步骤4：运行FlipClaw安装脚本 

# 克隆FlipClaw仓库
git clone https://github.com/bbesner/flipclaw.git /tmp/flipclaw-install
# 执行主安装脚本
bash /tmp/flipclaw-install/install.sh \
  --agent-name "$AGENT_NAME" \
  --workspace "$WORKSPACE" \
  --port $PORT \
  --gemini-key "$GEMINI_KEY"

这个 install.sh 脚本是一个总控脚本，它会按顺序调用两个子安装器：

  • install-memory.sh : 安装记忆系统（事实捕获、Dreaming、Wiki、搜索插件）。
  • install-claude-code.sh : 安装Claude Code集成（钩子脚本、桥接、健康检查）。

步骤5：启动OpenClaw网关服务 这是最关键也最容易出错的一步。 不能 使用 openclaw gateway start ，因为这个命令是为系统服务（systemd/launchd）设计的，在PM2下会立即退出。必须使用 openclaw gateway run 在前台运行，并由PM2管理。

cd "$WORKSPACE"
OPENCLAW_CONFIG_PATH="$WORKSPACE/openclaw.json" \
  pm2 start --name "${AGENT_NAME,,}-gateway" "openclaw gateway run"
pm2 save
pm2 startup
# 执行 pm2 startup 输出的命令，让PM2在系统启动时自动运行

pm2 save 保存当前进程列表， pm2 startup 生成启用自启动的命令，按照它的提示执行即可。

步骤6：验证安装 

# 检查网关健康状态
sleep 8 # 给网关一点启动时间
curl -sS http://localhost:$PORT/health
# 期望返回：{"ok":true,"status":"live"}

# 运行FlipClaw的健康检查脚本
bash "$WORKSPACE/scripts/claude-code-update-check.sh"
# 期望输出一系列 `[PASS]` 信息

如果健康检查失败，查看日志是最快的排错方式： pm2 logs ${AGENT_NAME,,}-gateway --lines 50 。

3.3 AI引导安装：让Claude自己搭建自己

手动安装能让你理解细节，但AI引导安装才是“FlipClaw哲学”的完美体现： 让AI工具来管理AI工具的部署 。你只需要对已经安装好的Claude Code CLI说一句话：

claude "Install FlipClaw. Read and follow the instructions at: https://raw.githubusercontent.com/bbesner/flipclaw/main/BOOTSTRAP.md"

接下来，Claude Code会：

  1. 读取 BOOTSTRAP.md 文件中的安装指南。
  2. 分析你的当前环境 ：检查是否已安装Node.js、Python、OpenClaw、Claude Code等。
  3. 交互式提问 ：根据检测结果，询问你几个关键决策，比如安装拓扑（同一台机器还是分开）、如何处理现有的OpenClaw配置、Agent名称和端口。
  4. 执行安装步骤 ：自动执行相应的命令，包括克隆仓库、运行安装脚本、配置钩子、注入API密钥等。
  5. 处理错误和依赖 ：如果中途遇到问题（如权限不足、依赖缺失），它会尝试解决或给出明确的修复指导。

这个过程不仅更简单，而且更健壮，因为它包含了针对各种环境的条件判断和错误处理逻辑。对于大多数用户，这是首选方案。

3.4 部署拓扑选择：合一还是分离？

FlipClaw支持两种部署模式，你需要根据实际情况选择：

特性 合一部署 (Cohabitating) 分离部署 (Split with MCP)
架构 Claude Code CLI 和 OpenClaw 运行在同一台机器 Claude Code CLI 运行在本地电脑，OpenClaw 运行在远程服务器
记忆访问 直接文件系统访问，速度极快 通过网络（SSH + MCP协议），速度较快
设置复杂度 简单 中等，需配置SSH和MCP服务器
离线工作 支持 需要网络连接
适用场景 个人服务器、VPS、开发机 希望在本地IDE（如VS Code）获得良好体验，同时利用远程服务器资源

如何选择？

  • 如果你是个人用户，拥有一台一直开机的机器（如家里的NAS、云上的VPS） ，选择 合一部署 。简单直接，性能最好。
  • 如果你希望在本地的MacBook或Windows电脑上使用Claude Code Desktop或VS Code插件，但希望记忆和自动化任务在24小时运行的远程服务器上执行 ，选择 分离部署 。你需要运行安装脚本时加上 --with-mcp 标志，并在本地Claude Code配置中连接远程MCP服务器。

实操心得：从合一迁移到分离 如果你开始用了合一部署，后来想换成分离部署，并不需要推倒重来。你可以在远程服务器上重新安装一个OpenClaw+FlipClaw实例（使用新端口），然后在本地的Claude Code配置中，通过MCP连接到它。原有的合一部署实例可以保留作为备份或用于其他用途。

4. 核心功能深度解析与配置调优

安装完成只是开始，FlipClaw的真正威力在于其丰富的功能。我们来深入看看几个核心模块，并了解如何根据你的需求进行调优。

4.1 记忆系统：不止是日志，而是知识引擎

FlipClaw的记忆系统是一个多层级的、动态演化的知识库。理解每一层的用途，能帮助你更好地组织和利用信息。

4.1.1 各层存储详解

层级 文件/目录 内容 更新频率 用途
核心记忆 MEMORY.md 最重要、最常被回忆的事实和决策。 低（由Dreaming Deep Phase提升） 每次会话的初始上下文，确保AI记得“你是谁”、“你在做什么”。
结构化记忆 memory/*.md (如 projects.md , people.md ) 按主题分类的参考信息。 中（手动或由Dreaming/技能捕获生成） 存储项目详情、联系人信息、技术栈等结构化数据。
每日日志 memory/YYYY-MM-DD.md 当天捕获的所有原始事实颗粒。 高（每轮对话都可能追加） 记忆的“草稿纸”，是Dreaming处理的原材料。
梦境报告 memory/dreaming/ Dreaming各阶段（Light/Deep/REM）的处理报告。 每日 用于审计记忆整合过程，了解系统“思考”了什么。
梦境洞察 DREAMS.md REM阶段生成的模式发现和叙事性洞察。 每日 提供高层次的项目趋势、潜在问题或学习机会分析。
技能库 skills/*/SKILL.md 可重复执行的操作流程。 事件驱动（由技能捕获或手动创建） AI助手可以调用的标准化操作手册。
会话存档 sessions/*.jsonl 完整的、原始的会话记录。 每个会话结束 用于深度搜索、审计和后续分析。

4.1.2 Dreaming（记忆整合）调度与配置

Dreaming是记忆系统的“消化”过程。默认在每天凌晨4点（美国东部时间）运行。你可以在 openclaw.json 中调整其计划：

{
  "dreaming": {
    "enabled": true,
    "frequency": "30 3 * * *", // 改为每天UTC时间3:30运行
    "timezone": "UTC"
  }
}
  • Light Phase（浅度睡眠） : 主要做去重和合并。例如，同一天内“用户喜欢喝咖啡”和“用户每天早上一杯咖啡”会被合并。
  • Deep Phase（深度睡眠） : 基于“回忆频率”算法，将重要的每日事实提升到 MEMORY.md 。一个事实如果在近期会话中被多次提及或引用，它就更可能被提升。
  • REM Phase（快速眼动睡眠） : 尝试在不同事实间建立关联，生成洞察。例如，它可能发现“修改数据库schema”的事实常与“服务部署失败”的事实相继出现，从而提示“数据库变更可能是部署失败的原因”。

注意事项：监控Dreaming运行 安装后，建议在第二天检查 memory/dreaming/ 目录下是否有报告生成，以及 MEMORY.md 文件是否被更新。如果Dreaming没有运行，检查PM2日志和OpenClaw的cron任务状态。一个常见问题是OpenClaw 2026.4.10之前的版本存在调度bug，FlipClaw v3.2.2+ 会自动安装修复脚本。

4.2 技能自动捕获：将经验转化为可重复的资产

这是FlipClaw中最具革命性的功能之一。它能够自动将你的一次性复杂操作，转化为团队（或未来的你）可重复使用的技能。

4.2.1 技能捕获流水线

当一个会话结束时，自动技能捕获流程被触发，它像一条流水线一样工作：

  1. 启发式门控（Heuristic Gate） : 首先进行快速过滤，剔除明显不合适的会话。过滤标准包括：

    • 会话是否太短（少于一定轮数）？
    • 用户是否使用了足够多的工具调用（表明是操作型任务）？
    • 会话的复杂性评分是否超过阈值（基于令牌数、交互深度等）？ 这个阶段不用LLM，速度快，成本为零。

  2. LLM分类门控 : 通过第一关的会话，会被送入一个轻量级LLM（默认GPT-5.4-mini）进行评估。LLM需要判断：“这个会话是否包含一个清晰、可重复的操作流程？” 例如，“帮我写一封邮件”可能不会通过，而“帮我配置Nginx反向代理到本地3000端口，并设置SSL”就很可能通过。

  3. 去重检查 : 系统会提取候选技能的核心意图，并与技能库中所有现有技能的意图进行向量相似度比较。如果发现高度相似的技能（例如“部署到AWS EC2”和“在AWS EC2上启动一个实例”），它会选择合并建议或跳过，避免技能库冗余。

  4. 技能生成 : 对于通过所有检查的会话，系统会调用一个更强的LLM（默认GPT-5.4-mini，可配置为Sonnet等）来生成结构化的 SKILL.md 文件。这个文件包含：

    • 概述 : 技能是做什么的。
    • 前提条件 : 执行前需要满足什么条件。
    • 步骤 : 详细、可操作的分步指南。
    • 验证 : 如何确认技能执行成功。
    • 潜在问题 : 可能遇到的坑及解决方法。

  5. 安全写入 : 生成的技能会保存到 skills/{技能名}/SKILL.md 。 关键点 ：如果该技能目录已存在（即已有手动编写的技能），FlipClaw不会覆盖，而是将建议的更新内容写入 skills/{技能名}/_suggested-update.md ，供你手动审阅合并。这保护了你的手工成果。

4.2.2 配置技能捕获模型

你可以在安装时或之后通过修改配置，来指定用于分类和生成的模型。例如，如果你更信任Claude模型，可以这样配置：

# 在安装时指定
bash install.sh ... \
  --capture-provider anthropic \
  --capture-model claude-haiku-4-5-20251001 \
  --extraction-model claude-haiku-4-5-20251001 \
  --generation-model claude-sonnet-4-6
  • --capture-model : 用于事实提取（每轮对话后运行）的模型。需要速度快、成本低，Haiku很合适。
  • --extraction-model : 用于技能分类的模型。需要一定的推理能力判断会话价值。
  • --generation-model : 用于生成最终技能文档的模型。需要较强的总结和结构化写作能力，Sonnet或Opus更佳。

4.3 远程访问与多用户支持

FlipClaw考虑到了团队协作和灵活的使用场景。

4.3.1 MCP服务器实现远程记忆访问

对于分离式部署，FlipClaw内置了一个 Model Context Protocol (MCP) 服务器。MCP是Anthropic推出的一种标准协议，允许工具以结构化的方式向AI模型暴露能力。

启动MCP服务器后，运行在本地笔记本电脑上的Claude Code CLI，可以通过SSH隧道连接到远程服务器的OpenClaw记忆库，并调用诸如 memory_search 、 skill_read 等工具。这让你在本地享受流畅的IDE集成体验，同时所有记忆和技能都存储在中央服务器上。

安装时添加 --with-mcp 参数即可启用。之后需要在本地Claude Code配置中，添加该MCP服务器连接。

4.3.2 多用户共存于单服务器

FlipClaw支持在同一台物理服务器上为多个用户部署独立的、隔离的FlipClaw实例。每个用户有自己的工作空间、自己的OpenClaw网关进程、自己的记忆库。这非常适合小团队或家庭实验室场景。

安装时，通过 --user <username> 参数为不同用户指定其家目录下的Claude Code配置路径，并通过 --group <groupname> 参数设置文件组权限，确保网关进程可以写入共享的工作空间。

# 为用户alice安装
bash install-claude-code.sh --agent-name AliceAgent --workspace /opt/agents/alice --port 31001 --user alice --group ai-team

这样，Alice和Bob可以互不干扰地使用自己的AI助手，同时共享服务器资源。

4.4 健康检查与自我更新

FlipClaw引入了运维友好的特性。

4.4.1 健康检查脚本 ( claude-code-update-check.sh ) 这个脚本执行12项检查，包括：

  • OpenClaw网关是否在运行且健康。
  • 必要的目录和文件是否存在。
  • Claude Code钩子配置是否正确。
  • 记忆插件是否已加载。
  • FlipClaw组件版本是否匹配。
  • 是否有新版本可用 （通过检查GitHub的VERSION文件）。

该脚本被设置为每6小时通过cron运行一次。当检测到新版本时，它会在日志中打印提示，并在 /tmp/flipclaw-update-available 创建一个标志文件。

4.4.2 自我更新器 ( flipclaw-update.sh ) 这是FlipClaw的“杀手级”运维功能。更新一个复杂的AI代理栈通常是令人头疼的，但FlipClaw让它变得安全简单。

# 检查更新
bash ~/myagent/scripts/flipclaw-update.sh --check
# 模拟更新，看会有什么变化
bash ~/myagent/scripts/flipclaw-update.sh --dry-run
# 执行更新
bash ~/myagent/scripts/flipclaw-update.sh

更新器会：

  1. 创建完整快照 ：备份整个工作空间的脚本、配置和状态文件。
  2. 下载新版工具包 。
  3. 重新应用模板 ：用你最初的安装参数（保存在 .flipclaw-install.json 中）重新生成所有脚本。
  4. 验证更新 ：语法检查所有脚本。 如果验证失败，会自动提示并执行回滚 。
  5. 清理旧备份 ：只保留最近的10个备份。

这种“原子性”更新机制极大降低了升级风险，鼓励用户保持系统最新。

5. 故障排除与性能优化实战

即使有完善的安装程序，在实际运行中仍可能遇到问题。这里我分享一些常见的故障场景和排查思路，以及提升系统性能的技巧。

5.1 常见问题速查表

症状 最可能原因 排查与修复步骤
Claude Code会话后， memory/ 目录没有生成新文件。 1. Claude Code钩子配置错误或丢失。
2. 钩子脚本执行权限不足。
3. API密钥错误，导致脚本静默失败。		 1. 检查 ~/.claude/config.json ，确认 hooks.sessionEnd 和 hooks.stop 路径正确指向FlipClaw脚本。
2. 确保钩子脚本有执行权限 ( chmod +x )。
3. 手动运行钩子脚本，看是否有错误输出。检查OpenAI/Gemini密钥是否有效。
pm2 logs 显示 memory-core: plugin disabled 。 1. openclaw.json 中 memory 插件的 slot 未设置或设置错误。
2. 插件不在网关的 allow 列表中。		 1. 运行 openclaw memory status 查看状态。如果是v3.2.1+，重新运行安装脚本，其预检功能会自动修复此问题。
2. 检查 openclaw.json 中 gateway.plugins.allow 是否包含 "memory-core" 。
Dreaming（记忆整合）从未运行。 1. OpenClaw版本低于2026.4.10，存在已知的cron调度bug。
2. PM2进程崩溃或网关未运行。
3. 系统时区设置错误。		 1. 升级OpenClaw: npm install -g openclaw@latest 。
2. 运行 pm2 status 确认网关进程在线。
3. 检查 openclaw.json 中 dreaming.timezone 设置，并与 date 命令对比系统时区。
记忆搜索返回结果很差或报错。 1. Gemini API密钥未设置或无效。
2. 向量索引未成功构建或已损坏。		 1. 确认 GEMINI_API_KEY 和 GOOGLE_AI_API_KEY 已正确设置在 env.vars 中。
2. 尝试重建索引: openclaw memory index --rebuild 。查看网关日志中是否有嵌入模型相关的错误。
自动技能捕获似乎从未触发。 1. 技能捕获的启发式或LLM分类阈值设置过高。
2. 用于分类的LLM调用失败（如额度用尽）。
3. 会话复杂度确实不够。		 1. 检查 sessions/ 目录是否有存档。检查 auto-skill-capture 扩展的日志（在网关日志中搜索相关条目）。
2. 确认用于分类的OpenAI/Anthropic API密钥有效且有额度。
3. 尝试进行一个非常复杂的、多步骤的运维或编码会话，看是否能触发。
更新FlipClaw后，某些功能异常。 1. 更新过程中脚本模板应用出错。
2. 新版本与当前OpenClaw版本不兼容。		 1. 立即使用回滚功能 ： bash flipclaw-update.sh --rollback 。
2. 检查 CHANGELOG.md 查看版本兼容性说明。可能需要先升级OpenClaw。

5.2 性能优化与成本控制

FlipClaw设计时已考虑了效率，但你仍可以根据使用模式进行调优。

5.2.1 控制LLM调用成本 FlipClaw的主要运营成本来自用于事实提取和技能捕获的LLM调用（默认是OpenAI的GPT-5.4-nano/mini）。以下方法可以控制成本：

  • 调整事实提取频率 ：默认每轮对话后都提取。如果你对话非常频繁且碎片化，可以考虑修改 incremental-memory-capture.py ，使其仅在对话达到一定长度或包含特定关键词时才触发。但需谨慎，以免丢失重要信息。
  • 使用更便宜的模型 ：事实提取对模型要求不高。可以尝试切换到 gpt-5.4-nano （如果默认不是它）或 claude-haiku 。在安装时通过 --extraction-model 指定。
  • 监控用量 ：定期查看OpenAI API使用仪表板。FlipClaw的调用量应该非常稳定且低。

5.2.2 管理记忆库规模 随着时间推移， MEMORY.md 和 memory/*.md 文件会增长，可能影响AI加载上下文的速度和令牌消耗。

  • 定期审查 MEMORY.md ：Dreaming的Deep Phase是自动的，但算法可能不够精准。每月手动浏览一次 MEMORY.md ，移出过时或不再重要的信息。
  • 利用结构化记忆 ：鼓励将信息存入 memory/projects.md , memory/people.md 等文件，而不是全部堆在 MEMORY.md 中。AI可以通过搜索找到它们。
  • 清理会话存档 ： sessions/ 目录可能增长很快。可以设置一个定期任务（cron job），压缩或删除超过一定天数的旧会话JSONL文件。

5.2.3 确保系统稳定性

  • 监控PM2和网关 ：将 pm2 status 和 curl localhost:$PORT/health 加入你的监控系统（如Zabbix, Prometheus）。
  • 设置日志轮转 ：PM2和OpenClaw网关的日志文件可能变大。配置 logrotate 来管理它们。
  • 定期备份工作空间 ：虽然FlipClaw更新器会备份脚本，但你的核心资产—— memory/ 、 skills/ 、 MEMORY.md ——需要单独备份。可以写一个简单的脚本，定期将整个工作空间打包上传到云存储。

5.3 高级调试技巧

当遇到棘手问题时，可以按以下层次深入排查：

  1. 检查Claude Code钩子 ：在Claude Code中执行一个简单会话并退出，然后立刻查看系统日志（如 journalctl -f 或 tail -f /var/log/syslog ），看钩子脚本是否被调用，是否有错误输出。
  2. 直接测试脚本 ：找到钩子脚本路径，例如 python3 /path/to/claude-code-bridge.py --test （如果支持）或直接使用一个示例会话文件作为输入，手动运行，观察输出。
  3. 启用详细日志 ：修改OpenClaw网关的启动命令，增加日志级别。例如，在PM2启动命令中设置环境变量 DEBUG=memory-core,openclaw:* （具体变量名需参考OpenClaw文档）。
  4. 检查文件权限 ：这是多用户部署或Docker环境中常见问题。确保运行OpenClaw网关的用户对工作空间目录有读写权限。使用 ls -la /path/to/workspace 检查。
  5. 审查网络连接 ：如果使用MCP远程模式，确保防火墙允许SSH端口，并且Claude Code CLI可以成功建立到远程服务器的SSH隧道。测试基本的网络连通性。

FlipClaw是一个将前沿AI能力与实用主义工程结合的优秀项目。它没有试图重新发明轮子，而是巧妙地整合了Claude Code和OpenClaw这两个生态位不同的工具，通过架构翻转解决了真实用户的痛点。从成本归零、记忆共享到技能自动化，它一步步地将AI助手从“一次性的聊天对象”转变为“持续成长的工作伙伴”。部署过程虽有细节需要注意，但其提供的AI引导安装和健壮的更新机制，大大降低了运维门槛。如果你正在为Claude的API费用苦恼，或苦于AI助手缺乏持久记忆，FlipClaw值得你投入一个下午的时间去搭建和体验。它的价值，会在日复一日的使用中逐渐显现出来。

Logo
亚马逊云科技技术品牌专区

更多推荐

cover

一次 API 调用搞定时序预测：时序大模型 TimechoAI 使用与能力全解析

avatar 亚马逊云科技技术品牌专区

AI Agent 面试题 353：A2A协议的服务发现和注册机制详解

A2A 协议 是 AI Agent 技术体系中的重要组成部分。简单来说，它涉及到 Agent 如何在 工具使用与函数调用 层面实现智能化的行为和决策。在实际应用中，A2A 协议 的核心目标是让 Agent 能够更加高效、准确地完成特定任务。这需要我们深入理解其底层原理和实现机制。从学术角度来看，A2A 协议 的研究可以追溯到人工智能的早期阶段。早在 1950 年代，Alan Turing 就提出了

avatar 亚马逊云科技技术品牌专区
cover

智能软件工程AI4SE（十六）——需求工程工具Jira

avatar 亚马逊云科技技术品牌专区