迁移指南
将 CoderClaw 迁移到新机器
Section titled “将 CoderClaw 迁移到新机器”本指南将 CoderClaw Gateway 网关从一台机器迁移到另一台，无需重新进行新手引导。
迁移在概念上很简单：
- 复制状态目录（
$CODERCLAW_STATE_DIR，默认：~/.coderclaw/）— 这包括配置、认证、会话和渠道状态。 - 复制你的工作区（默认
~/.coderclaw/workspace/）— 这包括你的智能体文件（记忆、提示等）。
但在配置文件、权限和部分复制方面有常见的陷阱。
开始之前（你要迁移什么）
Section titled “开始之前（你要迁移什么）”1）确定你的状态目录
Section titled “1）确定你的状态目录”大多数安装使用默认值：
- 状态目录：
~/.coderclaw/
但如果你使用以下方式，可能会不同：
--profile <name>（通常变成~/.coderclaw-<profile>/）CODERCLAW_STATE_DIR=/some/path
如果你不确定，在旧机器上运行：
coderclaw status在输出中查找 CODERCLAW_STATE_DIR / profile 的提及。如果你运行多个 Gateway 网关，对每个配置文件重复此操作。
2）确定你的工作区
Section titled “2）确定你的工作区”常见默认值：
~/.coderclaw/workspace/（推荐的工作区）- 你创建的自定义文件夹
你的工作区是 MEMORY.md、USER.md 和 memory/*.md 等文件所在的位置。
3）了解你将保留什么
Section titled “3）了解你将保留什么”如果你复制两者——状态目录和工作区，你将保留：
- Gateway 网关配置（
coderclaw.json） - 认证配置文件 / API 密钥 / OAuth 令牌
- 会话历史 + 智能体状态
- 渠道状态（例如 WhatsApp 登录/会话）
- 你的工作区文件（记忆、Skills 笔记等）
如果你只复制工作区（例如通过 Git），你不会保留：
- 会话
- 凭证
- 渠道登录
这些存储在 $CODERCLAW_STATE_DIR 下。
迁移步骤（推荐）
Section titled “迁移步骤（推荐）”步骤 0 — 备份（旧机器）
Section titled “步骤 0 — 备份（旧机器）”在旧机器上，首先停止 Gateway 网关，这样文件不会在复制过程中发生变化：
coderclaw gateway stop（可选但推荐）归档状态目录和工作区：
# 如果你使用配置文件或自定义位置，请调整路径cd ~tar -czf coderclaw-state.tgz .coderclaw
tar -czf coderclaw-workspace.tgz .coderclaw/workspace如果你有多个配置文件/状态目录（例如 ~/.coderclaw-main、~/.coderclaw-work），分别归档每个。
步骤 1 — 在新机器上安装 CoderClaw
Section titled “步骤 1 — 在新机器上安装 CoderClaw”在新机器上，安装 CLI（如果需要还有 Node）：
- 参见：安装
在这个阶段，如果新手引导创建了一个新的 ~/.coderclaw/ 也没关系 — 你将在下一步覆盖它。
步骤 2 — 将状态目录 + 工作区复制到新机器
Section titled “步骤 2 — 将状态目录 + 工作区复制到新机器”复制两者：
$CODERCLAW_STATE_DIR（默认~/.coderclaw/）- 你的工作区（默认
~/.coderclaw/workspace/）
常见方法：
scp压缩包并解压- 通过 SSH 使用
rsync -a - 外部驱动器
复制后，确保：
- 包含了隐藏目录（例如
.coderclaw/） - 文件所有权对于运行 Gateway 网关的用户是正确的
步骤 3 — 运行 Doctor（迁移 + 服务修复）
Section titled “步骤 3 — 运行 Doctor（迁移 + 服务修复）”在新机器上：
coderclaw doctorDoctor 是”安全可靠”的命令。它修复服务、应用配置迁移，并警告不匹配问题。
然后：
coderclaw gateway restartcoderclaw status常见陷阱（以及如何避免）
Section titled “常见陷阱（以及如何避免）”陷阱：配置文件/状态目录不匹配
Section titled “陷阱：配置文件/状态目录不匹配”如果你在旧 Gateway 网关上使用了配置文件（或 CODERCLAW_STATE_DIR），而新 Gateway 网关使用了不同的配置，你会看到如下症状：
- 配置更改不生效
- 渠道丢失/已登出
- 会话历史为空
修复：使用你迁移的相同配置文件/状态目录运行 Gateway 网关/服务，然后重新运行：
coderclaw doctor陷阱：只复制 coderclaw.json
Section titled “陷阱：只复制 coderclaw.json”coderclaw.json 是不够的。许多提供商在以下位置存储状态：
$CODERCLAW_STATE_DIR/credentials/$CODERCLAW_STATE_DIR/agents/<agentId>/...
始终迁移整个 $CODERCLAW_STATE_DIR 文件夹。
陷阱：权限/所有权
Section titled “陷阱：权限/所有权”如果你以 root 身份复制或更改了用户，Gateway 网关可能无法读取凭证/会话。
修复：确保状态目录 + 工作区由运行 Gateway 网关的用户拥有。
陷阱：在远程/本地模式之间迁移
Section titled “陷阱：在远程/本地模式之间迁移”- 如果你的 UI（WebUI/TUI）指向远程 Gateway 网关，远程主机拥有会话存储 + 工作区。
- 迁移你的笔记本电脑不会移动远程 Gateway 网关的状态。
如果你处于远程模式，请迁移 Gateway 网关主机。
陷阱：备份中的密钥
Section titled “陷阱：备份中的密钥”$CODERCLAW_STATE_DIR 包含密钥（API 密钥、OAuth 令牌、WhatsApp 凭证）。将备份视为生产密钥：
- 加密存储
- 避免通过不安全的渠道共享
- 如果怀疑泄露，轮换密钥
验证检查清单
Section titled “验证检查清单”在新机器上，确认：
coderclaw status显示 Gateway 网关正在运行- 你的渠道仍然连接（例如 WhatsApp 不需要重新配对）
- 仪表板打开并显示现有会话
- 你的工作区文件（记忆、配置）存在