openclaw 更改运行目录：OPENCLAW_STATE_DIR 环境变量配置与验证

1. 默认目录被撑爆之后openclaw 更改运行目录到底改的是什么openclaw 是一个本地优先的智能体运行框架它会把会话记录、凭据、缓存、日志、agent 定义等一堆东西落到磁盘上。默认情况下这些内容全部塞在用户主目录下的~/.openclawWindows 上是C:\Users\你的用户名\.openclaw。这个设计在刚装好、只跑一两个小任务时完全没问题但只要开始高频调用模型、跑长会话、挂多个 agent状态目录就会以肉眼可见的速度膨胀。我见过最夸张的一次一个做代码审查的 agent 连续跑了三天sessions 目录直接干到 40 多个 G系统盘飘红连 IDE 都开始卡。这时候你要找的核心检索词就是openclaw 更改运行目录而实现它的关键开关就是OPENCLAW_STATE_DIR环境变量。它的作用非常直接一旦设置openclaw 会把所有内部路径的解析基准从默认的~/.openclaw换成你指定的目录包括 agent 目录、sessions 路径、credentials 路径、缓存和日志。换句话说它不是只挪一个文件夹而是把整个「状态根」整体搬家。适合谁看这篇三类人最需要第一系统盘空间紧张、想把状态目录迁到数据盘或外挂盘的第二默认路径因为权限问题写不进去、启动就报错的常见于公司电脑或受限账户第三想把 openclaw 的状态和配置集中管理、方便备份和迁移的。如果你只是偶尔跑一下、磁盘也宽裕那默认路径其实够用但提前知道这个变量怎么配早晚用得上。需要先分清两个容易混的变量OPENCLAW_STATE_DIR管的是状态目录数据落地的地方OPENCLAW_CONFIG_PATH管的是配置文件openclaw.json的具体位置。很多人只设了前者结果发现配置还是从老地方读就是因为没同时处理配置文件路径。下面会两个一起讲清楚。另外openclaw 调用模型时需要 API 通道这部分我建议统一走 TaoToken 的 Key/API 通道这样状态目录搬家之后凭据和模型接入配置不会散落在各处迁移时更省心。官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end API 基址是 https://taotoken.net/api 后面配置环节会具体用到。2. 动手前的准备TaoToken 通道与目录规划在改环境变量之前先把两件事定下来状态目录放哪、模型通道怎么接。顺序反了的话你搬完目录发现凭据还得重新配等于白折腾一遍。先说目录规划。选目标路径有三个原则。第一别选需要管理员权限才能写的目录比如 Windows 的C:\Program Files或 Linux 的/usr/local下面否则 openclaw 启动时写 sessions 会直接失败。第二优先选独立的数据盘或大容量分区比如 Windows 的E:\openclaw-state、Linux 的/data/openclaw这样状态膨胀不会影响系统盘。第三路径里尽量别带空格和中文虽然大部分情况能跑但个别脚本拼接路径时容易出幺蛾子用纯英文加短横线最稳。然后是模型通道。openclaw 本身不生产模型能力它要连一个兼容的 API 端点。我实测下来把 Base URL 指向 TaoToken 的https://taotoken.net/api用统一的 Key 管理好处是换模型、换额度、查用量都在一个地方状态目录迁移时只要保证凭据文件跟着走就行。你需要提前准备好三件套Base URL、API Key、Model ID。Key 在控制台的 API Keys 页面生成地址是 https://taotoken.net/api-keys 生成后先复制存好页面关掉就看不全了。这里有个细节值得强调openclaw 的凭据默认存在状态目录下的 credentials 路径里。也就是说当你把OPENCLAW_STATE_DIR指到新目录后openclaw 会去新目录找凭据。如果你之前已经在默认目录登录或配置过要么把老的 credentials 文件复制过去要么在新目录下重新配一次。我建议后者干净利落避免旧文件里残留过期 token 导致 401。规划阶段还要确认一件事你的 openclaw 版本是否支持这个变量。OPENCLAW_STATE_DIR是官方提供的配置项主流版本都认。可以在终端跑openclaw --version确认版本如果版本特别老建议先升级再改目录否则可能出现「变量设了但不生效」的假象。最后提醒一句改环境变量属于「改完要重启终端」的操作。很多人设完变量在当前窗口测试没反应就是因为当前 shell 还是旧环境。下面每个平台的配置都会带上「重开终端」这一步别跳过。3. 可复制配置各平台 OPENCLAW_STATE_DIR 设置片段这一节是全文最核心的可复制部分。我按 Windows 图形界面、PowerShell、Linux/macOS 三类场景给出完整片段你对着抄就行。所有示例统一用E:\openclaw-stateWindows和/data/openclaw-stateLinux/macOS作为目标目录你替换成自己的实际路径即可。先看 Windows 图形界面方式适合不想碰命令行的同学。按Win R输入sysdm.cpl回车进入「高级」选项卡点「环境变量」。在「系统变量」区域点「新建」变量名填OPENCLAW_STATE_DIR变量值填E:\openclaw-state。再新建一个OPENCLAW_CONFIG_PATH值填E:\openclaw-state\openclaw.json。两个都确定保存后关掉所有终端窗口重新打开否则不生效。如果你更习惯命令行PowerShell 里可以这样临时设置仅当前会话有效适合先测试$env:OPENCLAW_STATE_DIR E:\openclaw-state $env:OPENCLAW_CONFIG_PATH E:\openclaw-state\openclaw.json想永久生效用setx写入用户级环境变量setx OPENCLAW_STATE_DIR E:\openclaw-state setx OPENCLAW_CONFIG_PATH E:\openclaw-state\openclaw.json注意setx写完后同样要重开终端。setx有个坑它写入的是用户变量如果你之前用图形界面设了系统变量两者可能冲突建议只保留一种方式。Linux 和 macOS 下临时生效用 exportexport OPENCLAW_STATE_DIR/data/openclaw-state export OPENCLAW_CONFIG_PATH/data/openclaw-state/openclaw.json永久生效写进 shell 配置文件。bash 用户写~/.bashrczsh 用户写~/.zshrcecho export OPENCLAW_STATE_DIR/data/openclaw-state ~/.zshrc echo export OPENCLAW_CONFIG_PATH/data/openclaw-state/openclaw.json ~/.zshrc source ~/.zshrc目录本身要先建好并给足权限。Linux/macOS 下mkdir -p /data/openclaw-state chmod 700 /data/openclaw-statechmod 700是让只有当前用户能读写执行因为状态目录里有凭据权限别开太大。Windows 下如果目录在数据盘一般当前用户就有完全控制权不用额外设如果遇到写入失败右键目录 →「属性」→「安全」确认你的账户有「修改」和「写入」权限。配置文件的 JSON 片段长这样放在E:\openclaw-state\openclaw.json或对应 Linux 路径里重点是模型通道指向 TaoToken{ model: { baseUrl: https://taotoken.net/api, apiKey: sk-你的TaoToken密钥, modelId: claude-sonnet-4-5 }, stateDir: E:\\openclaw-state }这里三件套齐全Base URL 是https://taotoken.net/apiapiKey 填你在 https://taotoken.net/api-keys 生成的 KeymodelId 按你实际要用的模型填。注意 JSON 里 Windows 路径的反斜杠要写成双反斜杠\\否则解析会报错。Linux 路径用正斜杠即可。如果你用的是 Claude Code 这类工具配合 openclaw配置思路一致Base URL 和 Key 都走同一套。需要看更细的接入说明可以翻接入文档 https://taotoken.net/doc 。长期跑编码和 agent 任务的话Coding Plan 的额度模型更适合高频场景入口在 https://taotoken.net/coding-plan 。4. 验证目录是否真的生效三个确认动作配置写完不代表生效必须验证。我一般用三个动作确认从环境变量到实际落盘层层递进。第一个动作确认环境变量在当前终端里读得到。Windows PowerShellecho $env:OPENCLAW_STATE_DIRLinux/macOSecho $OPENCLAW_STATE_DIR如果输出是你设的路径说明变量生效如果输出为空或还是老路径说明终端没重开或者写错了配置文件。这一步是最基础的别跳过。第二个动作启动 openclaw 并观察它的启动日志。openclaw 启动时通常会打印状态目录的解析结果类似state dir resolved to: /data/openclaw-state。如果日志里显示的还是~/.openclaw那说明变量没被读到。这时候检查两件事变量名有没有拼错是OPENCLAW_STATE_DIR不是OPENCLAW_STATEDIR以及是不是在正确的 shell 里启动的。第三个动作也是最实在的去新目录里看文件有没有真的写进去。启动 openclaw 跑一个简单任务然后ls -la /data/openclaw-state你应该能看到 sessions、credentials、agents 之类的子目录被创建出来。Windows 下用资源管理器打开E:\openclaw-state看也一样。如果新目录是空的而老目录~/.openclaw还在更新那基本可以断定变量没生效。验证模型通道是否通可以在 openclaw 里发一条测试消息或者直接用 curl 打一下 TaoToken 的端点curl https://taotoken.net/api/v1/models \ -H Authorization: Bearer sk-你的TaoToken密钥返回模型列表就说明 Key 和通道没问题。如果这里报 401先别怀疑目录配置那是 Key 的问题去 https://taotoken.net/api-keys 重新确认。想直接在网页里试模型对话可以用 https://taotoken.net/chat 快速验证 Key 是否可用。三个动作都过了才算真正完成迁移。我建议迁移完成后把老的~/.openclaw先改名备份比如加个.bak后缀观察几天确认新目录一切正常再决定要不要删。直接删老目录风险太大万一新配置有遗漏回滚都来不及。5. 常见报错排查401、local proxy failed、reading choices、OAuth迁移目录过程中报错基本集中在四类。我把真实遇到过的现象和排查路径列出来对照着看能省不少时间。401 Unauthorized。这个最常见但要注意它跟目录迁移的关系如果你把状态目录换了凭据文件也跟着换了位置新目录下没有有效凭据openclaw 就会拿不到 Key 而报 401。排查顺序是先确认openclaw.json里的 apiKey 填对了再确认这个 Key 在 TaoToken 控制台还有效、没被删。如果 Key 没问题检查是不是新目录下的 credentials 文件缺失必要时重新登录一次让 openclaw 重新写凭据。记住三件套要齐Base URLhttps://taotoken.net/api、Key、Model ID缺一个都可能 401。local proxy failed。这个报错通常出现在 openclaw 尝试通过本地代理转发请求时。迁移目录本身不会直接导致它但如果你在openclaw.json里配了代理相关字段而新目录下的配置没同步就可能触发。排查时先看配置文件里有没有残留的 proxy 设置把它清掉让请求直连https://taotoken.net/api。另外确认网络能正常访问该域名公司网络如果有出口限制也会表现为 proxy failed。reading choices 相关报错类似error reading choices或解析响应失败。这类多半是模型返回格式和 openclaw 预期不一致。常见原因是 modelId 填错或者 Base URL 指向了一个不兼容的端点。确认你的 Base URL 是https://taotoken.net/apimodelId 用通道支持的模型名。如果换了模型后突然报这个先把 modelId 换回之前能用的那个测试定位是不是模型名的问题。OAuth 相关报错。openclaw 某些登录流程走 OAuth凭据会存在状态目录下。迁移后如果 OAuth token 路径变了旧 token 找不到就会提示重新授权或报 OAuth 错误。处理方式是重新走一遍授权流程让新目录下生成新的 token 文件。如果反复失败检查新目录权限是不是太严导致写不进去chmod 700一般够用但如果你用的是更严格的 ACL要确认当前用户有写权限。排查时有个通用技巧把 openclaw 的日志级别调高启动时加详细输出能看到它到底从哪个路径读配置、往哪个路径写状态。日志里路径不对就回到第 3 节检查环境变量路径对但请求失败就查 Key 和模型通道。分清楚「目录问题」和「通道问题」能少走很多弯路。6. 迁移完成后的收尾与通道统一目录迁移做完、验证通过之后还有几件收尾的事值得做能让后续维护省心不少。第一把环境变量固化下来。临时 export 只对当前会话有效重启就没了。Linux/macOS 写进~/.zshrc或~/.bashrcWindows 用setx或图形界面写系统变量。固化之后无论从哪个终端启动 openclaw都会自动用新目录。第二统一模型通道的配置位置。既然状态目录已经集中到一处模型接入的三件套Base URL、Key、Model ID也建议只在这一处维护别在多个工具里各配一份。openclaw 用https://taotoken.net/api配套的 Key 在 https://taotoken.net/api-keys 管理需要查接入细节看 https://taotoken.net/doc 。这样以后换 Key 或换模型改一个地方就行。第三建立备份习惯。状态目录里有 sessions 和 credentials前者是工作记录后者是访问凭据。定期把整个状态目录打包备份迁移机器或重装系统时直接还原比重新配置快得多。备份时注意凭据文件的权限别随手丢到共享目录里。第四如果你同时用 Claude Code 之类的编码工具让它们和 openclaw 共用同一套 TaoToken 通道配置逻辑是一致的。需要长期高频跑 agent 和编码任务Coding Plan 的额度模式比按量更划算入口 https://taotoken.net/coding-plan 。想快速验证某个模型对话效果用 https://taotoken.net/chat 就行。最后说个我踩过的坑迁移目录后第一次启动openclaw 可能会因为新目录下缺少某些初始化文件而重建这个过程如果中途被打断可能留下半成品状态。所以迁移后第一次启动让它完整跑完别急着 CtrlC。确认 sessions、credentials、agents 这些子目录都正常生成后再开始正式用。整套流程走下来默认目录磁盘占满和权限受限这两个老问题基本就一次性解决了。