1. 先理清楚OpenClaw为什么绕不开命令1.1 OpenClaw到底是个什么东西我猜点进这个标题的人大概率已经搜过“openclaw部署”“openclaw ubuntu安装教程”之类的词。简单说OpenClaw是一个开源的智能体运行时框架你可以把它理解成一个“自带执行能力的对话式自动化平台”你用自然语言交代任务它负责拆解、调用工具、读写文件、执行命令最后把结果汇报给你。它和Claude Code、WorkBuddy这类工具算同一赛道但OpenClaw更强调本地部署、多云服务接入和可插拔的技能包适合喜欢自己掌控整个运行链路的人。既然要自己掌控命令就是躲不掉的。因为OpenClaw不管界面做得多么友好底层还是跑在进程、端口、配置文件和日志这三样东西上。部署的时候要拉代码、装依赖、起服务运行的时候要改配置、看日志、调参数出问题的时候要查进程、测端口、看谁锁了文件。这三类需求几乎每一项都要回到命令行去解决。所以这份备忘的定位不是“OpenClaw入门教程”而是“围绕OpenClaw会用到的命令学习指南”我把自己实际敲过的命令、遇到的报错、总结出的套路都放进来。1.2 命令学习解决的三类问题我在整理的时候把OpenClaw相关的命令分成了三类这也是绝大多数人从零到一必然经历的过程先有一个大致框架后面查起来才不会乱阶段典型问题对应命令族部署阶段装依赖、拉代码、初始化git、apt、npm、pip运行阶段改配置、管服务、看日志vim、systemctl、journalctl、top排障阶段找进程、测端口、解文件锁ps、lsof、kill、telnet、curl这三个阶段的命令互相之间有明显的依赖关系。你部署时要用git把代码拉下来运行时要靠systemd或者nohup让它在后台稳定跑排障时要先用ps和lsof搞清楚“系统现在的真实状态”然后才能判断是配置问题还是进程问题。我见过不少新人卡在部署后第一次启动直接报错其实不是OpenClaw难用而是不习惯用命令去看“它到底卡在哪”。所以这篇备忘会刻意把每一步的命令都写出来并且解释为什么要用这条命令而不是只丢一堆“可复制粘贴的魔法咒语”。2. 部署阶段从空服务器到OpenClaw跑通2.1 环境检查与依赖安装部署OpenClaw我建议优先选Ubuntu这类的Linux发行版原因不只是社区资料多更关键的是OpenClaw的很多核心能力都依赖Unix生态下的进程管理、文件权限和网络工具Windows上虽然也能跑但你会额外踩到路径分隔符、权限模型、防火墙弹窗这些坑没必要。拿到一台全新服务器或者本地虚拟机后先做环境检查这一步能帮你省掉后面至少一半的“为什么装不上”问题。cat /etc/os-release uname -m node -v python3 --version git --version这里每条命令都有它的目的。cat /etc/os-release是确认系统版本比如Ubuntu 22.04和20.04在依赖包版本上有差异uname -m是确认架构x86_64还是arm64有些依赖包在ARM架构上需要不同的编译参数后面三个版本号则是确认Node、Python和Git是否满足OpenClaw官方README里写的最低要求。如果缺Git直接装sudo apt update sudo apt install -y git curl build-essentialbuild-essential看起来很基础但很多依赖包在编译原生模块时会用到gcc和make缺少它会出现一些莫名其妙的编译错误。我踩过一次的坑是在最小化安装的Ubuntu上跳过了这一步结果npm install阶段报gyp错误最后只能回头补装来回折腾小半个小时。2.2 拉取代码、装依赖和首次启动环境检查完毕接下来就是从官方仓库拉代码。不同版本的OpenClaw安装方式略有差异但主流的安装套路基本是“Git拉取 包管理器安装依赖 启动脚本”三步。以我当时用的方式为例git clone OpenClaw官方仓库地址 openclaw cd openclaw npm install # 如果仓库是Node技术栈 npm run setup # 首次初始化生成配置文件和依赖如果仓库里带有Python侧的依赖通常会有一个requirements.txt这种情况下建议先建虚拟环境再装避免污染系统Pythonpython3 -m venv .venv source .venv/bin/activate pip install -r requirements.txt用虚拟环境的原因很简单隔离。系统自带的Python往往被很多其他工具依赖你要是直接pip install很可能把某些包升到一个不兼容的版本导致别的服务启动失败。虚拟环境则把全部依赖限制在.venv目录里删掉就可以重来非常适合OpenClaw这种要频繁升级和换分支的项目。首次启动我建议先在前台跑一次不要急着用nohup或者systemdnpm start前台启动的好处是你能第一时间看到启动日志、模型连接状态、端口监听信息。如果前台能跑通再考虑后台托管如果前台都报错那就先解决报错不要盲目加后台逻辑增加排障难度。启动后看到类似“HTTP server listening on 0.0.0.0:3000”的输出就说明服务本身起来了。2.3 云服务器上让OpenClaw稳定后台运行本地跑通之后很多人会把它放到阿里云这种云服务器上长期挂着。这里有两个和本地明显不同的点一是云服务器重启后服务不会自动起来二是一旦退出SSH终端前台进程会直接被断开。所以需要把OpenClaw托管给systemd让系统自己管理它的启动、崩溃重启和日志。创建一个服务文件比如/etc/systemd/system/openclaw.service内容大致是这样[Unit] DescriptionOpenClaw agent service Afternetwork.target [Service] Userubuntu WorkingDirectory/home/ubuntu/openclaw ExecStart/usr/bin/npm start Restartalways RestartSec5 EnvironmentFile/home/ubuntu/openclaw/.env [Install] WantedBymulti-user.target保存后执行sudo systemctl daemon-reload sudo systemctl enable --now openclaw sudo systemctl status openclawenable是设置开机自启--now表示立即启动status是看当前运行状态。这里有个细节值得注意ExecStart里的路径要写成绝对路径而且最好用which npm查一下npm真实路径因为有些发行版里npm在/usr/bin/npm有些在/usr/local/bin/npm路径写错系统会直接报“找不到命令”。我一开始就是直接从网上复制了一份service文件忘了改User和WorkingDirectory结果服务起不来journalctl一看全是权限错误。如果你只是临时用一下不想搞systemd这么正式也可以用nohup方案nohup npm start /home/ubuntu/openclaw/logs/app.log 21 用nohup的好处是简单坏处是没有自动重启策略进程一旦崩了就是崩了。所以我的建议是真正长期跑的服务一定用systemdnohup只适合调试阶段临时代跑。3. 日常使用编辑、版本管理、进程监控的命令基本功3.1 vim改配置文件避不开的编辑器OpenClaw的核心配置基本都集中在.env和若干个yaml/json文件里比如模型API Key、接入渠道开关、插件列表。这些文件在服务器上没有图形界面可以直接编辑所以vim几乎是必修课。哪怕你觉得vim难用至少要把下面这几个操作变成肌肉记忆vim .env # 按 i 进入插入模式修改内容 # 按 Esc 退出插入模式 # 输入 :wq 回车保存并退出 # 如果改乱了不想保存输入 :q! 回车不保存退出刚上手的人最容易遇到两个问题一是按了方向键发现光标没有移动而是出现ABCD这是vim没有兼容方向键导致的解决办法是用h、j、k、l移动或者干脆换用nano这种更直觉的编辑器二是不小心按了CtrlS终端会被冻结看起来像卡死了实际上只是进入了XOFF状态按CtrlQ就能恢复。这两个坑我第一次遇到时都懵了很久后来才知道都是终端层面和编辑器交互的经典案例。我整理了一份vim高频操作速查操作命令说明进入插入模式i在光标前插入保存退出Esc后:wq最常用不保存退出Esc后:q!改坏了就重来搜索关键字/keyword回车按 n 继续下一个显示行号:set nu报错定位方便跳到指定行:行号回车配合日志行号改完配置文件后一定要记得重启OpenClaw服务让配置生效这一点经常被忽略。你可以在vim里改半天发现OpenClaw还是旧行为不是没保存而是服务没重启重读配置这一步被省掉了。3.2 git把OpenClaw的配置和技能包管起来OpenClaw的玩法很大程度建立在“技能包”“插件”“工作流”这些可扩展文件上而这些文件本质上也是代码。既然家里装了一套会随着你使用不断变化的配置和技能目录那为什么不顺便用Git把整个目录管起来呢先给自己的技能目录初始化一个仓库cd ~/.openclaw/skills git init git add . git commit -m initial skills snapshot之后每次改动配置、新增技能或调整工作流前先提交一次当前状态git status git diff git add . git commit -m backup before tweaking config git log --oneline -5这样做的核心价值在于可以随时回滚。我曾经调过一个技能包把一段对话上下文规则改错了导致OpenClaw每次回答都带了一堆无关的前缀问题排查了半天才定位到是配置文件改坏了。如果当时没有Git快照就只能靠记忆慢慢往回改有了commit记录直接git reset --hard HEAD~1就能回到改动前的状态五分钟解决。另外如果OpenClaw是通过Git拉取的官方仓库升级新版本前也建议先git stash自己的本地改动再pull避免冲突。很多人一升级就报错十有八九是本地改了仓库里的文件和上游更新冲突了。3.3 进程与服务让OpenClaw知道自己活着OpenClaw跑起来之后你最先要学会的不是怎么用而是怎么确认它还活着、它在哪里、它占了多少资源。top是几乎所有Linux排障里都会用到的命令我在这里把它讲透一点。toptop打开后第一行显示的是系统平均负载三个数字分别代表1分钟、5分钟、15分钟的平均活跃进程数第三行是CPU占用里面有us用户态、sy内核态、waI/O等待等列第四五行是内存和交换分区的使用情况。下面进程列表里我最常用的操作是按P按CPU排序按M按内存排序按q退出。看进程时不要只看PID还要看COMMAND列。如果你看到node或python的进程CPU持续100%说明OpenClaw可能在死循环里打转这时候再用ps定位具体路径ps aux | grep -i openclawps aux输出的每一行都包含用户、PID、CPU占用、内存占用和启动命令能从这里面看出当前启动的完整进程链。如果要停止某个异常进程先用温和的方式kill PID如果进程毫无反应再考虑强制杀kill -9 PID对systemd管理的服务日常维护基本就这三条sudo systemctl status openclaw sudo systemctl restart openclaw journalctl -u openclaw -fjournalctl -f是实时跟踪日志的好工具排障时开着它再去复现问题能看到第一现场的报错输出效率比反复重启高得多。4. 集成外部服务Teams和Obsidian的命令链路4.1 把OpenClaw接入Microsoft Teams很多人折腾OpenClaw就是为了把它接到Microsoft Teams里让整个团队都能在同一个聊天界面跟智能体对话不用每次跑到终端里去操作。接入的本质很简单OpenClaw提供一个HTTP服务Teams通过Bot Framework把用户消息转发给这个服务再把回复拿回来。所以你在Azure工作台里真正要做的是创建一个Bot Channel Registration把OpenClaw的HTTPS地址告诉它。大致的操作链路在Azure门户创建一个Bot Channels Registration名称随便起比如“OpenClawBot”。在配置里找到Messaging endpoint填成https://你的OpenClaw域名/api/messages。注意这里是HTTPS如果没配域名开发阶段可以用内网穿透工具临时开一个HTTPS地址。创建后你会拿到两个关键凭证Microsoft App ID和Client Secret。把这两个凭证填入OpenClaw的Teams接入配置里字段一般叫“MicrosoftAppId”和“MicrosoftAppPassword”具体字段名以你用的版本为准但思路都是让OpenClaw能认得出Teams发来的请求。在Teams管理后台发布应用或直接侧载测试发送“ping”OpenClaw回“pong”说明通道打通了。说一个比较隐蔽的坑Azure中创建的Bot默认是不放行所有已知渠道的你要把Teams这个channel开启。有些教程只讲到这里没提这个开关导致配置看起来都对消息却发不进来。排查时如果看到OpenClaw日志里完全没有请求进来先回Azure确认channel有没有enable。4.2 用Obsidian给OpenClaw做知识库OpenClaw和Obsidian的组合我理解最实用的场景是把Obsidian的Vault当作智能体的外部记忆或知识库。Obsidian本身只是Markdown文件的集合而OpenClaw恰好擅长读写Markdown文件所以两者可以直接通过文件系统对接不需要什么特殊协议。具体做法是在Vault里建一个专门给智能体用的目录mkdir -p /path/to/your/vault/00-Agent-Memory然后在OpenClaw的配置里把允许访问的目录列表加上这一条。我用的时候会给它一个明确的角色设定把日常对话中产生的知识点、命令备忘、项目决策记录都写成按日期命名的Markdown文件放进这个目录。比如2025-01-15-teams-integration.md里面用简洁的标题和列表记录当时的操作步骤、报错和结论。这样下次问OpenClaw“上次Teams接入怎么做的”它会主动去读这个文件而不是凭空编一个答案。需要提醒的是文件锁问题。Obsidian本身在运行时可能会锁住它正在编辑的文件如果OpenClaw同时去写同一个文件轻则写入失败重则出现我们在标题里见到的那种session file locked报错。我的建议是约定俗成让OpenClaw只往00-Agent-Memory目录写新文件不直接改Obsidian库里的笔记两边各管各的互不打扰。4.3 网络连通性测试命令接入Teams、连接模型API、访问外部Webhook本质上都是网络请求。当你发现OpenClaw突然“没反应”先不要怀疑智能体能力先确认网络链路通不通。这里有一组非常接地气的命令telnet api.example.com 443 curl -I https://api.example.com ping -c 3 192.168.1.10telnet ip 端口用来测试某个IP和端口是否可达并监听。如果IP能通但端口没开你会看到 “Connection refused”如果IP本身就不可达会一直卡在连接阶段直到超时。测试成功后要退出来先按Ctrl ]再输入quit否则不熟悉的人会直接关掉窗口其实没关干净。Windows上默认没有telnet可以用这条命令开启dism /online /enable-feature /featurename:TelnetClient执行后需要重开一个命令行窗口再执行telnet就能用了。这个技巧对Windows上本地调试OpenClaw特别有用可以快速确认指定端口是否有程序在监听。curl -I则可以测HTTPS接口的响应头如果返回200或者301说明网络和应用层都是通的如果超时就要回到防火墙和安全组层面找原因。5. 高频报错与排查命令实录5.1 拆解“session file locked”的完整排查过程就先从标题里那个最扎眼的报错说起吧“agent failed before reply: session file locked (timeout 60000ms)”。这个问题在OpenClaw的使用反馈里出现频率非常高它读起来很可怕但其实逻辑很简单。OpenClaw在会话过程中会把上下文、消息历史、状态保存到一个名为session的文件里为了确保并发时数据不会被写坏它会对这个文件加锁。当你同时启动了两个OpenClaw进程、或者上一次进程没有正常退出、或者用了NFS这类不擅长文件锁的文件系统时锁没有被正确释放下一次会话请求就会等待锁释放等满60秒仍然拿不到锁于是抛出timeout。完整的排查步骤我建议按顺序执行# 第一步确认是不是并发启动 ps aux | grep -i openclaw如果看到两个以上相关进程那就是多实例冲突停掉多余进程。# 第二步看谁占用了会话文件 lsof ~/.openclaw/sessions/lsof会列出占用目录下文件的进程PID。如果输出为空说明锁文件只是残留直接清理就行。# 第三步杀掉残留进程清理锁文件 kill -9 上一步看到的PID rm -rf ~/.openclaw/sessions/*.lock第四步很关键清理完之后不要立刻盲目重启先想想“为什么会锁住”。最常见的原因是你同时用了终端直接跑npm start和systemd服务两个实例同时启动必然争抢同一个会话锁。如果是Docker部署还要检查volumes挂载方式避免宿主机和容器同时访问同一份会话目录。步骤不重要重要的是找到根因否则清完锁过半小时又出现了。5.2 “agent failed before reply”的三层定位思路如果报错里不包含上面那个锁信息只是笼统的“agent failed before reply”那就把它理解成“智能体在回复之前就挂了”这通常发生在请求发出到模型返回结果的链路上。我的排查习惯是分三层走配置层、网络层、进程层。配置层最好查。确认.env里的API Key输入正确模型名称与供应商要求一致Endpoint没有多余空格或斜杠。很多人在一个框里粘贴Key时不小心复制了一个换行肉眼看不出来OpenClaw解析时会整体出错。排查方法很简单用文本编辑器打开.env检查每个key对应的value两端有没有诡异字符再确认有没有重复项重复项在后面会覆盖前面的值。网络层次之。用上面提到的curl -I或telnet测一下OpenClaw要连接的模型API是否可达。重点看超时还是拒连超时往往是网络策略或DNS解析问题拒连往往是端口错了或者服务下线。测的时候要记得看HTTP状态码403、401属于鉴权问题404说明Endpoint路径不对500则大概率是模型服务自身故障。进程层最后看。OpenClaw是否还在跑可以从systemctl status或者ps aux确认。如果进程还活着就去看journalctl -u openclaw -f输出的实时日志重点搜ERROR、WARN和timeout关键字。日志会告诉你具体是哪一步出错是调用模型失败还是工具执行失败。这三层走完绝大多数“agent failed before reply”都能定位到具体原因。5.3 其他高频命令问题速查表我在整理和OpenClaw相关的其他热词时发现很多问题其实不是OpenClaw本身而是周围的一圈基础命令。这里给一张速查表基本覆盖我踩过或见别人踩过的高频坑现象可能原因处理命令与思路部署时出现“rpm: command not found”系统是Debian系根本没有rpm工具不需要硬装rpm改用apt如果只是需要解析rpm包再考虑apt install rpmWindows下运行脚本一闪而过双击执行窗口自动关闭看不到报错用cmd /k 脚本路径运行窗口会保留Docker容器没能执行预期命令混淆entrypoint和run命令docker inspect查看Image的Entrypoint和Cmd理解它们的拼接关系git push反复要求密码没配SSH Key或者tokenssh-keygen生成密钥后把公钥提交到代码托管平台MinIO桶内容无法公开访问bucket默认私有mc anonymous set public 别名/桶名开通匿名读权限containerd导入镜像后看不到了宿主docker与containerd工具链不同用crictl images和crictl ps查询不要用docker命令查containerd运行时系统报“磁盘快满”但不知道谁占用没查大目录du -sh *这张表里的问题单个看都不难但它们会高频出现在OpenClaw的部署过程和日常运维里。把这些命令提前记下来相当于先给自己打了个疫苗。6. 把命令速查做成OpenClaw自己的备忘6.1 在Vault里维护一个命令手册前面说用Obsidian给OpenClaw做知识库其实最实用的启动项目就是从“命令速查”开始。我自己在Vault里维护了一个commands-cheatsheet.md每条命令按统一格式记录这样OpenClaw检索起来非常方便# 命令lsof ## 用途查看哪些进程打开了某个文件或目录 ## 示例lsof ~/.openclaw/sessions/ ## 坑没装的话先 apt install lsof ## 场景session file locked 报错时优先用当你把这一类速查条目积累到几十条以后就可以在OpenClaw里做一个“查备忘”的指令约定比如让它遇到报错先读这个文件再尝试处理。这样做的效果是你不再需要记住所有命令你只需要知道“命令手册放在哪里”剩下的交给OpenClaw去检索。这其实就是把标题里的“备忘”二字变成实际工作流的一部分。不过我建议初始写条目时千万别贪多一天最多沉淀两三条每条都写在真实解决问题之后。这样写出来的备忘才有上下文不是干巴巴的语法清单以后回看时很快能想起当时的坑在哪里。6.2 推荐一条从入门到排障的练习路径最后给刚接触OpenClaw的读者一套可以照着练的路径难度递增但每一步都有明确目标在一台Ubuntu服务器上完成OpenClaw部署用npm start前台跑通首次对话。用vim修改.env换一个模型或改一个参数学会通过systemd重启服务并确认配置生效。用Git给技能目录做初始化修改一个技能配置后提交一次再用git reset体验回滚。尝试接入Microsoft Teams用telnet或curl验证OpenClaw的HTTP接口公网可访问性。故意制造一次多实例启动复现session file locked用ps、lsof、kill完整清理并总结排查笔记。练完这五步你对OpenClaw的命令理解基本就过关了。我自己也是从第一步的报错里一路走过来的每次卡住的地方最后都会沉淀成一行命令或一个排查动作。这大概就是OpenClaw最值得学习的地方它逼着你把那些看似基础的命令真正用起来而不是停留在“我听说过”的阶段。我个人实际操作中的体会是命令这东西不用天天背诵但一定要在踩坑后马上记下来并且最好记到OpenClaw自己能读到的地方。当时为了排查session file locked我把lsof和ps的配合方法写进备忘后来再遇到类似问题从搜索到清理不到一分钟。希望这份OpenClaw命令学习指南备忘也能成为你下一步排查问题时的第一份工具清单。如果你在部署时也遇到了什么奇怪报错欢迎沿着这套思路自己拆一遍多半会发现“哪有那么玄就是一条命令没敲对”。
OpenClaw命令学习指南：从部署到排障的实用备忘
1. 先理清楚OpenClaw为什么绕不开命令1.1 OpenClaw到底是个什么东西我猜点进这个标题的人大概率已经搜过“openclaw部署”“openclaw ubuntu安装教程”之类的词。简单说OpenClaw是一个开源的智能体运行时框架你可以把它理解成一个“自带执行能力的对话式自动化平台”你用自然语言交代任务它负责拆解、调用工具、读写文件、执行命令最后把结果汇报给你。它和Claude Code、WorkBuddy这类工具算同一赛道但OpenClaw更强调本地部署、多云服务接入和可插拔的技能包适合喜欢自己掌控整个运行链路的人。既然要自己掌控命令就是躲不掉的。因为OpenClaw不管界面做得多么友好底层还是跑在进程、端口、配置文件和日志这三样东西上。部署的时候要拉代码、装依赖、起服务运行的时候要改配置、看日志、调参数出问题的时候要查进程、测端口、看谁锁了文件。这三类需求几乎每一项都要回到命令行去解决。所以这份备忘的定位不是“OpenClaw入门教程”而是“围绕OpenClaw会用到的命令学习指南”我把自己实际敲过的命令、遇到的报错、总结出的套路都放进来。1.2 命令学习解决的三类问题我在整理的时候把OpenClaw相关的命令分成了三类这也是绝大多数人从零到一必然经历的过程先有一个大致框架后面查起来才不会乱阶段典型问题对应命令族部署阶段装依赖、拉代码、初始化git、apt、npm、pip运行阶段改配置、管服务、看日志vim、systemctl、journalctl、top排障阶段找进程、测端口、解文件锁ps、lsof、kill、telnet、curl这三个阶段的命令互相之间有明显的依赖关系。你部署时要用git把代码拉下来运行时要靠systemd或者nohup让它在后台稳定跑排障时要先用ps和lsof搞清楚“系统现在的真实状态”然后才能判断是配置问题还是进程问题。我见过不少新人卡在部署后第一次启动直接报错其实不是OpenClaw难用而是不习惯用命令去看“它到底卡在哪”。所以这篇备忘会刻意把每一步的命令都写出来并且解释为什么要用这条命令而不是只丢一堆“可复制粘贴的魔法咒语”。2. 部署阶段从空服务器到OpenClaw跑通2.1 环境检查与依赖安装部署OpenClaw我建议优先选Ubuntu这类的Linux发行版原因不只是社区资料多更关键的是OpenClaw的很多核心能力都依赖Unix生态下的进程管理、文件权限和网络工具Windows上虽然也能跑但你会额外踩到路径分隔符、权限模型、防火墙弹窗这些坑没必要。拿到一台全新服务器或者本地虚拟机后先做环境检查这一步能帮你省掉后面至少一半的“为什么装不上”问题。cat /etc/os-release uname -m node -v python3 --version git --version这里每条命令都有它的目的。cat /etc/os-release是确认系统版本比如Ubuntu 22.04和20.04在依赖包版本上有差异uname -m是确认架构x86_64还是arm64有些依赖包在ARM架构上需要不同的编译参数后面三个版本号则是确认Node、Python和Git是否满足OpenClaw官方README里写的最低要求。如果缺Git直接装sudo apt update sudo apt install -y git curl build-essentialbuild-essential看起来很基础但很多依赖包在编译原生模块时会用到gcc和make缺少它会出现一些莫名其妙的编译错误。我踩过一次的坑是在最小化安装的Ubuntu上跳过了这一步结果npm install阶段报gyp错误最后只能回头补装来回折腾小半个小时。2.2 拉取代码、装依赖和首次启动环境检查完毕接下来就是从官方仓库拉代码。不同版本的OpenClaw安装方式略有差异但主流的安装套路基本是“Git拉取 包管理器安装依赖 启动脚本”三步。以我当时用的方式为例git clone OpenClaw官方仓库地址 openclaw cd openclaw npm install # 如果仓库是Node技术栈 npm run setup # 首次初始化生成配置文件和依赖如果仓库里带有Python侧的依赖通常会有一个requirements.txt这种情况下建议先建虚拟环境再装避免污染系统Pythonpython3 -m venv .venv source .venv/bin/activate pip install -r requirements.txt用虚拟环境的原因很简单隔离。系统自带的Python往往被很多其他工具依赖你要是直接pip install很可能把某些包升到一个不兼容的版本导致别的服务启动失败。虚拟环境则把全部依赖限制在.venv目录里删掉就可以重来非常适合OpenClaw这种要频繁升级和换分支的项目。首次启动我建议先在前台跑一次不要急着用nohup或者systemdnpm start前台启动的好处是你能第一时间看到启动日志、模型连接状态、端口监听信息。如果前台能跑通再考虑后台托管如果前台都报错那就先解决报错不要盲目加后台逻辑增加排障难度。启动后看到类似“HTTP server listening on 0.0.0.0:3000”的输出就说明服务本身起来了。2.3 云服务器上让OpenClaw稳定后台运行本地跑通之后很多人会把它放到阿里云这种云服务器上长期挂着。这里有两个和本地明显不同的点一是云服务器重启后服务不会自动起来二是一旦退出SSH终端前台进程会直接被断开。所以需要把OpenClaw托管给systemd让系统自己管理它的启动、崩溃重启和日志。创建一个服务文件比如/etc/systemd/system/openclaw.service内容大致是这样[Unit] DescriptionOpenClaw agent service Afternetwork.target [Service] Userubuntu WorkingDirectory/home/ubuntu/openclaw ExecStart/usr/bin/npm start Restartalways RestartSec5 EnvironmentFile/home/ubuntu/openclaw/.env [Install] WantedBymulti-user.target保存后执行sudo systemctl daemon-reload sudo systemctl enable --now openclaw sudo systemctl status openclawenable是设置开机自启--now表示立即启动status是看当前运行状态。这里有个细节值得注意ExecStart里的路径要写成绝对路径而且最好用which npm查一下npm真实路径因为有些发行版里npm在/usr/bin/npm有些在/usr/local/bin/npm路径写错系统会直接报“找不到命令”。我一开始就是直接从网上复制了一份service文件忘了改User和WorkingDirectory结果服务起不来journalctl一看全是权限错误。如果你只是临时用一下不想搞systemd这么正式也可以用nohup方案nohup npm start /home/ubuntu/openclaw/logs/app.log 21 用nohup的好处是简单坏处是没有自动重启策略进程一旦崩了就是崩了。所以我的建议是真正长期跑的服务一定用systemdnohup只适合调试阶段临时代跑。3. 日常使用编辑、版本管理、进程监控的命令基本功3.1 vim改配置文件避不开的编辑器OpenClaw的核心配置基本都集中在.env和若干个yaml/json文件里比如模型API Key、接入渠道开关、插件列表。这些文件在服务器上没有图形界面可以直接编辑所以vim几乎是必修课。哪怕你觉得vim难用至少要把下面这几个操作变成肌肉记忆vim .env # 按 i 进入插入模式修改内容 # 按 Esc 退出插入模式 # 输入 :wq 回车保存并退出 # 如果改乱了不想保存输入 :q! 回车不保存退出刚上手的人最容易遇到两个问题一是按了方向键发现光标没有移动而是出现ABCD这是vim没有兼容方向键导致的解决办法是用h、j、k、l移动或者干脆换用nano这种更直觉的编辑器二是不小心按了CtrlS终端会被冻结看起来像卡死了实际上只是进入了XOFF状态按CtrlQ就能恢复。这两个坑我第一次遇到时都懵了很久后来才知道都是终端层面和编辑器交互的经典案例。我整理了一份vim高频操作速查操作命令说明进入插入模式i在光标前插入保存退出Esc后:wq最常用不保存退出Esc后:q!改坏了就重来搜索关键字/keyword回车按 n 继续下一个显示行号:set nu报错定位方便跳到指定行:行号回车配合日志行号改完配置文件后一定要记得重启OpenClaw服务让配置生效这一点经常被忽略。你可以在vim里改半天发现OpenClaw还是旧行为不是没保存而是服务没重启重读配置这一步被省掉了。3.2 git把OpenClaw的配置和技能包管起来OpenClaw的玩法很大程度建立在“技能包”“插件”“工作流”这些可扩展文件上而这些文件本质上也是代码。既然家里装了一套会随着你使用不断变化的配置和技能目录那为什么不顺便用Git把整个目录管起来呢先给自己的技能目录初始化一个仓库cd ~/.openclaw/skills git init git add . git commit -m initial skills snapshot之后每次改动配置、新增技能或调整工作流前先提交一次当前状态git status git diff git add . git commit -m backup before tweaking config git log --oneline -5这样做的核心价值在于可以随时回滚。我曾经调过一个技能包把一段对话上下文规则改错了导致OpenClaw每次回答都带了一堆无关的前缀问题排查了半天才定位到是配置文件改坏了。如果当时没有Git快照就只能靠记忆慢慢往回改有了commit记录直接git reset --hard HEAD~1就能回到改动前的状态五分钟解决。另外如果OpenClaw是通过Git拉取的官方仓库升级新版本前也建议先git stash自己的本地改动再pull避免冲突。很多人一升级就报错十有八九是本地改了仓库里的文件和上游更新冲突了。3.3 进程与服务让OpenClaw知道自己活着OpenClaw跑起来之后你最先要学会的不是怎么用而是怎么确认它还活着、它在哪里、它占了多少资源。top是几乎所有Linux排障里都会用到的命令我在这里把它讲透一点。toptop打开后第一行显示的是系统平均负载三个数字分别代表1分钟、5分钟、15分钟的平均活跃进程数第三行是CPU占用里面有us用户态、sy内核态、waI/O等待等列第四五行是内存和交换分区的使用情况。下面进程列表里我最常用的操作是按P按CPU排序按M按内存排序按q退出。看进程时不要只看PID还要看COMMAND列。如果你看到node或python的进程CPU持续100%说明OpenClaw可能在死循环里打转这时候再用ps定位具体路径ps aux | grep -i openclawps aux输出的每一行都包含用户、PID、CPU占用、内存占用和启动命令能从这里面看出当前启动的完整进程链。如果要停止某个异常进程先用温和的方式kill PID如果进程毫无反应再考虑强制杀kill -9 PID对systemd管理的服务日常维护基本就这三条sudo systemctl status openclaw sudo systemctl restart openclaw journalctl -u openclaw -fjournalctl -f是实时跟踪日志的好工具排障时开着它再去复现问题能看到第一现场的报错输出效率比反复重启高得多。4. 集成外部服务Teams和Obsidian的命令链路4.1 把OpenClaw接入Microsoft Teams很多人折腾OpenClaw就是为了把它接到Microsoft Teams里让整个团队都能在同一个聊天界面跟智能体对话不用每次跑到终端里去操作。接入的本质很简单OpenClaw提供一个HTTP服务Teams通过Bot Framework把用户消息转发给这个服务再把回复拿回来。所以你在Azure工作台里真正要做的是创建一个Bot Channel Registration把OpenClaw的HTTPS地址告诉它。大致的操作链路在Azure门户创建一个Bot Channels Registration名称随便起比如“OpenClawBot”。在配置里找到Messaging endpoint填成https://你的OpenClaw域名/api/messages。注意这里是HTTPS如果没配域名开发阶段可以用内网穿透工具临时开一个HTTPS地址。创建后你会拿到两个关键凭证Microsoft App ID和Client Secret。把这两个凭证填入OpenClaw的Teams接入配置里字段一般叫“MicrosoftAppId”和“MicrosoftAppPassword”具体字段名以你用的版本为准但思路都是让OpenClaw能认得出Teams发来的请求。在Teams管理后台发布应用或直接侧载测试发送“ping”OpenClaw回“pong”说明通道打通了。说一个比较隐蔽的坑Azure中创建的Bot默认是不放行所有已知渠道的你要把Teams这个channel开启。有些教程只讲到这里没提这个开关导致配置看起来都对消息却发不进来。排查时如果看到OpenClaw日志里完全没有请求进来先回Azure确认channel有没有enable。4.2 用Obsidian给OpenClaw做知识库OpenClaw和Obsidian的组合我理解最实用的场景是把Obsidian的Vault当作智能体的外部记忆或知识库。Obsidian本身只是Markdown文件的集合而OpenClaw恰好擅长读写Markdown文件所以两者可以直接通过文件系统对接不需要什么特殊协议。具体做法是在Vault里建一个专门给智能体用的目录mkdir -p /path/to/your/vault/00-Agent-Memory然后在OpenClaw的配置里把允许访问的目录列表加上这一条。我用的时候会给它一个明确的角色设定把日常对话中产生的知识点、命令备忘、项目决策记录都写成按日期命名的Markdown文件放进这个目录。比如2025-01-15-teams-integration.md里面用简洁的标题和列表记录当时的操作步骤、报错和结论。这样下次问OpenClaw“上次Teams接入怎么做的”它会主动去读这个文件而不是凭空编一个答案。需要提醒的是文件锁问题。Obsidian本身在运行时可能会锁住它正在编辑的文件如果OpenClaw同时去写同一个文件轻则写入失败重则出现我们在标题里见到的那种session file locked报错。我的建议是约定俗成让OpenClaw只往00-Agent-Memory目录写新文件不直接改Obsidian库里的笔记两边各管各的互不打扰。4.3 网络连通性测试命令接入Teams、连接模型API、访问外部Webhook本质上都是网络请求。当你发现OpenClaw突然“没反应”先不要怀疑智能体能力先确认网络链路通不通。这里有一组非常接地气的命令telnet api.example.com 443 curl -I https://api.example.com ping -c 3 192.168.1.10telnet ip 端口用来测试某个IP和端口是否可达并监听。如果IP能通但端口没开你会看到 “Connection refused”如果IP本身就不可达会一直卡在连接阶段直到超时。测试成功后要退出来先按Ctrl ]再输入quit否则不熟悉的人会直接关掉窗口其实没关干净。Windows上默认没有telnet可以用这条命令开启dism /online /enable-feature /featurename:TelnetClient执行后需要重开一个命令行窗口再执行telnet就能用了。这个技巧对Windows上本地调试OpenClaw特别有用可以快速确认指定端口是否有程序在监听。curl -I则可以测HTTPS接口的响应头如果返回200或者301说明网络和应用层都是通的如果超时就要回到防火墙和安全组层面找原因。5. 高频报错与排查命令实录5.1 拆解“session file locked”的完整排查过程就先从标题里那个最扎眼的报错说起吧“agent failed before reply: session file locked (timeout 60000ms)”。这个问题在OpenClaw的使用反馈里出现频率非常高它读起来很可怕但其实逻辑很简单。OpenClaw在会话过程中会把上下文、消息历史、状态保存到一个名为session的文件里为了确保并发时数据不会被写坏它会对这个文件加锁。当你同时启动了两个OpenClaw进程、或者上一次进程没有正常退出、或者用了NFS这类不擅长文件锁的文件系统时锁没有被正确释放下一次会话请求就会等待锁释放等满60秒仍然拿不到锁于是抛出timeout。完整的排查步骤我建议按顺序执行# 第一步确认是不是并发启动 ps aux | grep -i openclaw如果看到两个以上相关进程那就是多实例冲突停掉多余进程。# 第二步看谁占用了会话文件 lsof ~/.openclaw/sessions/lsof会列出占用目录下文件的进程PID。如果输出为空说明锁文件只是残留直接清理就行。# 第三步杀掉残留进程清理锁文件 kill -9 上一步看到的PID rm -rf ~/.openclaw/sessions/*.lock第四步很关键清理完之后不要立刻盲目重启先想想“为什么会锁住”。最常见的原因是你同时用了终端直接跑npm start和systemd服务两个实例同时启动必然争抢同一个会话锁。如果是Docker部署还要检查volumes挂载方式避免宿主机和容器同时访问同一份会话目录。步骤不重要重要的是找到根因否则清完锁过半小时又出现了。5.2 “agent failed before reply”的三层定位思路如果报错里不包含上面那个锁信息只是笼统的“agent failed before reply”那就把它理解成“智能体在回复之前就挂了”这通常发生在请求发出到模型返回结果的链路上。我的排查习惯是分三层走配置层、网络层、进程层。配置层最好查。确认.env里的API Key输入正确模型名称与供应商要求一致Endpoint没有多余空格或斜杠。很多人在一个框里粘贴Key时不小心复制了一个换行肉眼看不出来OpenClaw解析时会整体出错。排查方法很简单用文本编辑器打开.env检查每个key对应的value两端有没有诡异字符再确认有没有重复项重复项在后面会覆盖前面的值。网络层次之。用上面提到的curl -I或telnet测一下OpenClaw要连接的模型API是否可达。重点看超时还是拒连超时往往是网络策略或DNS解析问题拒连往往是端口错了或者服务下线。测的时候要记得看HTTP状态码403、401属于鉴权问题404说明Endpoint路径不对500则大概率是模型服务自身故障。进程层最后看。OpenClaw是否还在跑可以从systemctl status或者ps aux确认。如果进程还活着就去看journalctl -u openclaw -f输出的实时日志重点搜ERROR、WARN和timeout关键字。日志会告诉你具体是哪一步出错是调用模型失败还是工具执行失败。这三层走完绝大多数“agent failed before reply”都能定位到具体原因。5.3 其他高频命令问题速查表我在整理和OpenClaw相关的其他热词时发现很多问题其实不是OpenClaw本身而是周围的一圈基础命令。这里给一张速查表基本覆盖我踩过或见别人踩过的高频坑现象可能原因处理命令与思路部署时出现“rpm: command not found”系统是Debian系根本没有rpm工具不需要硬装rpm改用apt如果只是需要解析rpm包再考虑apt install rpmWindows下运行脚本一闪而过双击执行窗口自动关闭看不到报错用cmd /k 脚本路径运行窗口会保留Docker容器没能执行预期命令混淆entrypoint和run命令docker inspect查看Image的Entrypoint和Cmd理解它们的拼接关系git push反复要求密码没配SSH Key或者tokenssh-keygen生成密钥后把公钥提交到代码托管平台MinIO桶内容无法公开访问bucket默认私有mc anonymous set public 别名/桶名开通匿名读权限containerd导入镜像后看不到了宿主docker与containerd工具链不同用crictl images和crictl ps查询不要用docker命令查containerd运行时系统报“磁盘快满”但不知道谁占用没查大目录du -sh *这张表里的问题单个看都不难但它们会高频出现在OpenClaw的部署过程和日常运维里。把这些命令提前记下来相当于先给自己打了个疫苗。6. 把命令速查做成OpenClaw自己的备忘6.1 在Vault里维护一个命令手册前面说用Obsidian给OpenClaw做知识库其实最实用的启动项目就是从“命令速查”开始。我自己在Vault里维护了一个commands-cheatsheet.md每条命令按统一格式记录这样OpenClaw检索起来非常方便# 命令lsof ## 用途查看哪些进程打开了某个文件或目录 ## 示例lsof ~/.openclaw/sessions/ ## 坑没装的话先 apt install lsof ## 场景session file locked 报错时优先用当你把这一类速查条目积累到几十条以后就可以在OpenClaw里做一个“查备忘”的指令约定比如让它遇到报错先读这个文件再尝试处理。这样做的效果是你不再需要记住所有命令你只需要知道“命令手册放在哪里”剩下的交给OpenClaw去检索。这其实就是把标题里的“备忘”二字变成实际工作流的一部分。不过我建议初始写条目时千万别贪多一天最多沉淀两三条每条都写在真实解决问题之后。这样写出来的备忘才有上下文不是干巴巴的语法清单以后回看时很快能想起当时的坑在哪里。6.2 推荐一条从入门到排障的练习路径最后给刚接触OpenClaw的读者一套可以照着练的路径难度递增但每一步都有明确目标在一台Ubuntu服务器上完成OpenClaw部署用npm start前台跑通首次对话。用vim修改.env换一个模型或改一个参数学会通过systemd重启服务并确认配置生效。用Git给技能目录做初始化修改一个技能配置后提交一次再用git reset体验回滚。尝试接入Microsoft Teams用telnet或curl验证OpenClaw的HTTP接口公网可访问性。故意制造一次多实例启动复现session file locked用ps、lsof、kill完整清理并总结排查笔记。练完这五步你对OpenClaw的命令理解基本就过关了。我自己也是从第一步的报错里一路走过来的每次卡住的地方最后都会沉淀成一行命令或一个排查动作。这大概就是OpenClaw最值得学习的地方它逼着你把那些看似基础的命令真正用起来而不是停留在“我听说过”的阶段。我个人实际操作中的体会是命令这东西不用天天背诵但一定要在踩坑后马上记下来并且最好记到OpenClaw自己能读到的地方。当时为了排查session file locked我把lsof和ps的配合方法写进备忘后来再遇到类似问题从搜索到清理不到一分钟。希望这份OpenClaw命令学习指南备忘也能成为你下一步排查问题时的第一份工具清单。如果你在部署时也遇到了什么奇怪报错欢迎沿着这套思路自己拆一遍多半会发现“哪有那么玄就是一条命令没敲对”。
