1. 长时运行场景下，opencode 到底在解决什么问题
很多人第一次接触 opencode 这类终端里的 AI 编程助手，都是把它当成一个"问答机器人"来用的：敲一行命令，问一个问题，拿到答案，关掉窗口。这种用法当然没问题，但它其实只发挥了这套工具不到三成的能力。真正让 opencode 变得有意思的，是把它当成一个常驻在项目里的协作进程——让它长时间挂着，持续接收任务、持续读写文件、持续跑命令，而不是每次用完就退出。
这就是"长时运行"这个概念的核心。所谓长时运行，指的是让 opencode 进程在后台或前台持续存活，跨越多个任务、多个小时甚至多天，期间不断有新的输入进来、有新的文件被改动、有新的命令被执行。它和"一次性调用"最大的区别在于：状态是连续的。会话上下文、工作目录、已经读过的文件、已经建立的工具调用习惯，全都保留着，不需要每次重新交代一遍背景。
为什么这件事值得单独拿出来讲？因为长时运行会暴露出一堆短会话里根本遇不到的问题。短会话里，你问完就走，内存泄漏、日志膨胀、上下文超限、进程被系统回收，这些都不构成困扰。可一旦进程要连续跑几个小时，这些问题就会一个接一个冒出来，而且往往是在你最不希望它挂掉的时候挂掉。我见过太多人兴冲冲地把 opencode 挂上去跑一个批量重构任务，结果半小时后回来一看，进程没了，日志停在半截，前面的工作全白做。
所以这一篇要聊的，不是"怎么装 opencode"这种入门问题，而是怎么让它稳稳地跑下去。适合的读者是已经用过 opencode、想把它从"随手工具"升级成"常驻工作流"的人。如果你还没跑通过一次基本会话，建议先把基础流程走一遍再来看这篇，不然很多细节会缺少参照。
在展开之前，先把长时运行最容易踩的几个坑摆出来，后面会逐个拆解：
| 问题类型 | 典型表现 | 根因方向 |
|---|---|---|
| 进程被回收 | 挂后台一段时间后消失 | 会话与终端绑定、系统资源策略 |
| 上下文超限 | 跑到中途开始答非所问 | 会话历史无限增长 |
| 日志失控 | 磁盘被写满、检索困难 | 无轮转、无分级 |
| 任务中断不可恢复 | 崩了之后要从头再来 | 缺少检查点与幂等设计 |
| 资源争抢 | 机器变卡、其他任务受影响 | 并发与限流没做 |
这张表不是吓唬人，而是给你一个心理预期：长时运行的本质，是把一个"交互式工具"改造成"准服务"。心态上要先转变，后面所有配置才有意义。
2. 让进程活下来：会话保持与后台运行的几种做法
2.1 为什么直接&挂后台往往不靠谱
最直觉的做法是在命令后面加一个&，让它进后台，然后关掉终端去干别的。这个做法在短任务里能用，但在长时运行场景下几乎必然出问题。原因在于，用&启动的进程仍然是当前 shell 的子进程，它和这个终端会话（session）是绑定的。当你关闭终端、断开连接、或者 shell 因为某种原因退出时，系统会向这个会话下的所有进程发送挂断信号，opencode 收到之后就会跟着退出。
更隐蔽的一种情况是：终端没关，但网络断了。如果你是通过远程方式连到一台机器上操作，网络一断，会话就断了，进程照样被带走。很多人以为"我没关窗口啊"，其实窗口早就因为连接超时被回收了，只是本地还显示着旧画面。
所以第一条经验就是：长时运行的进程，必须和交互终端解绑。解绑的方式有好几种，各有取舍。
2.2 用会话管理工具做真正的解绑
最稳妥的方式是借助专门的会话管理工具，让进程脱离当前终端独立存在。常见的思路是创建一个"分离式会话"，进程在里面跑，你随时可以"附着"回去看它的输出，也可以随时"分离"出来而不影响它。
具体操作上，典型流程是这样的：
# 创建一个命名会话，在里面启动 opencode # 会话名建议带上项目标识，方便多任务时区分 <会话工具> new -s opencode-projectA # 在会话内启动，输出重定向到日志文件 opencode <你的参数> 2>&1 | tee -a ~/logs/opencode-projectA.log # 分离：按下对应的分离快捷键，进程继续在后台跑 # 之后想回来看： <会话工具> attach -t opencode-projectA这里有几个细节值得说。第一，给会话起一个有意义的名字。当你同时挂了三四个长时任务时，session-1、session-2这种命名会让你完全分不清哪个是哪个。用项目名或任务类型做前缀，回头排查时能省大量时间。
第二，输出一定要落盘。会话工具能让你附着回去看实时输出，但它的回滚缓冲区是有限的，跑久了前面的内容就被冲掉了。用tee同时写到文件，既能看到实时输出，又留下了完整记录。-a是追加模式，避免重启时把旧日志覆盖掉。
第三，分离之前确认进程真的起来了。我踩过的坑是：会话创建成功，命令敲下去，看着好像跑起来了，直接分离，结果命令其实因为参数错误秒退了，会话里空空如也，我还以为它在后台好好干活。养成习惯，分离前先看一眼输出，确认有正常的启动日志再走。
2.3 系统级守护：什么时候该上，什么时候别上
如果你的 opencode 任务需要"开机自启""崩溃自动拉起""长期无人值守"，那会话管理工具就不够了，得考虑系统级的守护机制。这类机制的核心能力是：监控进程状态，挂了就重启，还能配置开机自动运行。
但这里要泼一盆冷水：不是所有长时任务都适合上守护。守护机制适合的是"无状态、可重启、幂等"的任务。如果你的 opencode 会话是有状态的——比如它正在一个复杂的多步重构中间，重启意味着上下文全丢、要从头再来——那自动拉起反而可能造成更糟的结果：进程反复重启，每次都从头开始，把已经改了一半的文件又改一遍，最后项目一团糟。
判断标准很简单，问自己一个问题：这个任务如果中途挂掉，重启后从头跑一遍，会不会破坏已有成果？如果会，那就不要用自动拉起，而应该用"检查点 + 手动恢复"的方式。如果不会（比如它只是持续监听某个目录、处理新进来的文件），那守护机制就很合适。
对于适合守护的场景，配置思路上要抓住三点：启动命令要写绝对路径（守护进程的工作目录往往和你登录时不一样）、日志要单独配置轮转（守护进程的日志很容易失控）、重启策略要设上限（避免疯狂重启拖垮机器）。这三点任何一点没做好，都会在长时运行中变成事故。
2.4 一个容易被忽略的点：工作目录与相对路径
长时运行还有一个特别隐蔽的坑：工作目录漂移。你在终端里手动跑的时候，当前目录是你cd进去的那个项目目录，一切正常。但一旦换成后台运行或守护运行，进程的初始工作目录可能变成根目录或者用户主目录，这时候所有相对路径全部失效——读不到配置文件、写错输出位置、找不到项目文件。
解决办法是：在启动脚本里显式cd到目标目录，并且尽量在配置里使用绝对路径。别嫌麻烦，这一步能挡掉后面一大半"莫名其妙找不到文件"的问题。我现在的习惯是，任何要长时运行的启动脚本，第一行永远是cd /绝对路径/到/项目，第二行才是启动命令。
3. 上下文管理：跑得越久，越要主动"遗忘"
3.1 上下文为什么会成为长时运行的头号杀手
opencode 这类工具的工作方式，是把会话历史（你说了什么、它回了什么、它读了哪些文件、执行了哪些命令）作为上下文一起送给模型。会话越短，上下文越小，响应越快越准。可一旦长时运行，这个历史会不断累积，很快就会撞上模型能接受的上下文上限。
撞上限之后会发生什么？不同实现处理方式不一样，但常见的结果有这么几种：要么直接报错拒绝继续，要么悄悄截断最早的历史（于是它"忘了"你最开始交代的关键约束），要么开始出现明显的质量下降——答非所问、重复劳动、忘记已经改过的文件。最后这种最坑，因为它不报错，你以为一切正常，实际上它已经在乱来了。
所以长时运行的核心功课之一，就是主动管理上下文，而不是等它爆掉。
3.2 分而治之：把大任务拆成有边界的小会话
最有效的策略，其实不是技术手段，而是任务设计：不要试图用一个会话跑完一个巨大的任务。把大任务拆成若干个有明确边界的小阶段，每个阶段用一个相对干净的会话，阶段之间通过文件、脚本或明确的交接说明来传递状态。
举个例子，假设你要做一个跨多个模块的重构。与其让 opencode 从头到尾一口气改完，不如拆成：
- 第一阶段：只做分析和规划，产出一份改动清单文件。
- 第二阶段：按清单逐个模块改，每个模块一个会话。
- 第三阶段：跑测试、修问题，又是一个独立会话。
这样做的好处是，每个会话的上下文都是可控的，而且阶段产物落盘了。哪怕某个会话崩了，你损失的只是当前阶段，前面的成果都在文件里。这比"一个会话跑到底、崩了全丢"要稳得多。
3.3 会话内的上下文瘦身技巧
当然，有些任务确实没法拆得太碎，那就得在会话内部做上下文管理。几个实用手段：
及时清理无关历史。大多数这类工具都提供了清空或压缩会话历史的命令。当你完成一个子任务、确认结果没问题之后，主动清一下历史，把已经不需要的中间过程丢掉，只保留结论性的信息。这相当于给上下文"减负"。
把关键约束写进文件，而不是只靠对话记忆。这是我最推荐的一招。与其在对话里反复强调"记得用某某规范""不要动某个目录"，不如把这些约束写进项目里的一个说明文件（比如AGENTS.md或类似的约定文件），让 opencode 每次需要时去读。文件是持久的、不会随上下文截断而丢失的，而对话记忆是会丢的。把"记忆"外置成"文档"，是长时运行里最划算的投资。
控制单次读取的量。让 opencode 读文件时，尽量读它真正需要的部分，而不是整个大文件全塞进去。一个几千行的日志文件如果整个读进上下文，可能一次就把预算吃掉一大半。养成"先定位、再精读"的习惯。
3.4 上下文超限的早期信号
怎么判断上下文快满了？除了看工具本身的提示，还有一些行为信号值得警惕：
- 它开始重复问你已经回答过的问题。
- 它改动的文件和你之前明确说"不要动"的重合了。
- 它的回答开始变得笼统、不再引用具体文件内容。
- 响应时间明显变长。
一旦出现这些信号，别硬撑，主动开新会话并把当前状态交接过去。交接的方式很简单：让它先把当前进度、待办事项、关键约束写成一个文件，然后你在新会话里让它先读这个文件。这样状态就平滑迁移了，比硬扛着等它彻底崩掉强得多。
4. 日志、资源与稳定性：那些跑久了才会暴露的问题
4.1 日志不轮转，迟早写满磁盘
长时运行最容易被忽视、后果又最严重的问题，就是日志膨胀。opencode 在运行过程中会输出大量信息：工具调用、文件读写、命令执行、错误堆栈。短会话里这些输出一闪而过，长时运行里它们全都会累积到日志文件里。
我见过一个真实场景：一个任务挂了两天，日志文件涨到了几十个 G，直接把磁盘写满，然后不只是 opencode 崩了，机器上其他服务也跟着出问题。这种事故的代价远不止"任务失败"。
解决办法是配置日志轮转。核心参数就三个：单个文件大小上限、保留的历史文件数量、是否压缩旧文件。配置好之后，日志会自动切割，旧的被清理或压缩，磁盘占用始终可控。
# 日志轮转配置的核心思路（以常见日志工具为例） # 单文件超过 100M 就切割 size 100M # 最多保留 10 个历史文件 rotate 10 # 旧文件压缩，省空间 compress # 切割后通知进程重新打开日志文件（如果进程支持） copytruncate这里有个细节：copytruncate和"通知重开"是两种不同的策略。如果进程本身支持收到信号后重新打开日志文件，用信号方式更干净；如果不支持，就用copytruncate，它先复制再清空原文件，对进程透明。选哪种取决于你的进程行为，选错了会导致切割后日志继续往旧文件写，轮转形同虚设。
4.2 资源占用：CPU、内存与文件句柄
长时运行还会慢慢积累资源占用。内存方面，如果进程有轻微的内存泄漏，短时间看不出来，跑十几个小时后就可能吃掉几个 G。文件句柄方面，如果每次操作都打开文件却不关闭，句柄数会持续上涨，最终撞上系统上限，表现为"打不开任何文件"。
监控这些指标不需要多复杂的工具，几个基础命令就够：
# 查看进程的内存和 CPU 占用 ps -o pid,rss,pcpu,etime -p <进程号> # 查看进程打开的文件句柄数 ls /proc/<进程号>/fd | wc -l # 查看系统级句柄上限 cat /proc/sys/fs/file-max养成定期瞄一眼的习惯。如果发现内存占用随时间单调上涨、句柄数只增不减，那就是泄漏的信号，得考虑定期重启进程来"续命"。定期重启听起来很土，但在很多长时运行场景里，它是最简单有效的兜底手段——前提是任务本身支持从检查点恢复。
4.3 网络与外部依赖的抖动
长时运行意味着要跨越更长的时间窗口，而时间窗口越长，遇到外部依赖抖动的概率就越高。模型接口可能超时、可能限流、可能短暂不可用。短会话里遇到一次重试就好，长时运行里如果不做处理，一次抖动就可能让整个任务卡死或崩溃。
应对思路是给所有外部调用加上重试和退避。重试次数不要太多（避免雪崩），退避时间要递增（给外部服务恢复的时间），并且要区分"可重试错误"和"不可重试错误"——比如参数错误重试一万次也没用，而超时、限流这类才值得重试。
# 带指数退避的重试思路（伪代码） def call_with_retry(fn, max_retries=5): for i in range(max_retries): try: return fn() except RetryableError: wait = base * (2 ** i) + random_jitter() sleep(wait) raise MaxRetriesExceeded()那个random_jitter()很关键。如果多个任务同时失败、同时重试，没有抖动的话它们会在同一时刻一起打过去，形成"惊群"。加一点随机偏移，能把重试请求打散开。
4.4 一个稳定性检查清单
把上面这些点整理成一个上线前的检查清单，每次要挂长时任务之前过一遍：
- 进程是否已和交互终端解绑？
- 启动脚本是否显式设置了工作目录？
- 日志是否配置了轮转？磁盘剩余空间是否充足？
- 是否有内存/句柄的监控或定期重启策略？
- 外部调用是否有重试和退避？
- 任务是否支持从检查点恢复？检查点写在哪里？
- 崩溃后如何手动恢复？恢复步骤是否写下来了？
这份清单看着啰嗦，但每一条背后都是真实踩过的坑。尤其是最后两条，很多人根本不准备，等真崩了才手忙脚乱。
5. 任务设计：让长时运行真正产出价值
5.1 幂等：长时任务的生命线
前面反复提到"可恢复""可重启"，这些能力的前提是幂等。所谓幂等，就是同一个操作执行一次和执行多次，结果是一样的。为什么长时运行特别需要它？因为长时运行中，中断和重试是常态，不是例外。如果操作不幂等，重试就会造成重复写入、重复提交、数据错乱。
怎么让任务幂等？几个常见手法：
- 写文件前先检查：如果目标文件已经存在且内容符合预期，就跳过，不要重复写。
- 用唯一标识去重：处理每条记录时带上唯一 ID，处理前先查是否已处理过。
- 操作可覆盖而非追加：能整体覆盖的，就不要用追加，避免重复内容堆积。
- 状态显式记录：把"已完成到哪一步"写进一个状态文件，重启后先读状态再决定从哪继续。
这些手法不复杂，但需要在设计任务时就考虑进去，事后补很痛苦。
5.2 检查点：把进度固化下来
检查点是长时运行的"存档点"。理想情况下，任务每完成一个有意义的单元，就把进度写到一个持久化的地方。这样无论因为什么原因中断，重启后都能从最近的检查点继续，而不是从头再来。
检查点的粒度需要权衡。太粗，一次中断损失大量工作；太细，写检查点本身的开销就很大。经验值是：单个工作单元的处理时间在几十秒到几分钟之间时，每个单元结束写一次检查点比较合适。这样即使中断，最多损失一个单元的工作。
检查点的内容至少要包含：已完成到哪个单元、当前的关键状态、下一步该做什么。格式用简单的文本或 JSON 就行，别搞太复杂，因为它的第一要求是"崩溃后还能读出来"，而不是"好看"。
5.3 把长时任务拆成"可观测"的单元
长时运行最让人焦虑的一点是"不知道它现在在干嘛"。一个任务挂在那里几个小时，你完全不知道它是正常推进还是卡死了。解决办法是让任务可观测：定期输出进度、记录当前正在处理的单元、暴露一些简单的状态指标。
最简单的做法是让任务每隔一段时间往一个状态文件里写一行：当前时间、已处理数量、当前单元标识。你随时tail一下这个文件，就知道它活没活着、走到哪了。这个成本极低，但带来的安心感极高。
再进一步，可以记录每个单元的处理耗时。如果某个单元耗时异常长，那多半是卡住了，可以据此判断要不要干预。长时运行里，"能看见"比"跑得快"更重要，因为看不见的故障你根本无从下手。
5.4 失败处理：优雅降级而不是直接崩
长时任务遇到错误时，最糟的处理方式是直接抛异常退出。更好的方式是记录错误、跳过当前单元、继续处理后面的，最后统一汇总失败清单。这样一次运行能处理掉绝大部分正常数据，只有少数问题数据需要单独处理，而不是因为一条坏数据让整个批次全废。
当然，这要看错误的性质。如果是"这条数据本身有问题"，跳过继续是对的；如果是"整个环境都不可用了"（比如磁盘满了、依赖服务全挂了），那继续跑也没意义，应该停下来报警。区分这两类错误，是任务设计里必须想清楚的事。
6. 我踩过的几个真实坑与恢复手法
6.1 会话附着回去发现是空的
有一次我挂了个任务，分离之后过了两小时回来附着，发现会话里空空如也，只有一行提示说进程已退出。当时第一反应是"任务跑完了？"，但检查输出目录发现什么都没生成。后来才想明白：启动命令里有个参数写错了，进程其实秒退了，我分离前没确认输出，白白等了两小时。
教训就是前面说的：分离前一定确认进程真的在跑。现在我的习惯是，启动后等十几秒，tail一下日志，看到正常的启动信息再分离。这十几秒能省掉几小时的无效等待。
6.2 上下文悄悄截断导致重复劳动
还有一次，一个长会话跑到后半段，我发现它开始重复处理前面已经处理过的文件。查了半天才意识到，是上下文超限后系统悄悄截断了早期历史，它"忘了"自己已经做过哪些。结果就是重复劳动，还差点把已经改好的文件又改回去。
从那以后，我养成了把"已完成清单"写进文件的习惯。每完成一批，就更新这个清单文件。哪怕上下文被截断，只要它重新读一下这个文件，就知道进度到哪了。把记忆外置这个原则，就是那次踩坑换来的。
6.3 日志把磁盘写满的连锁反应
最惨的一次是日志写满磁盘。任务本身没崩，但机器上其他服务开始报错，因为写不进任何东西了。清理日志花了很久，期间服务一直是不可用状态。这件事让我彻底重视日志轮转，现在任何长时任务上线前，日志轮转是必配项，没有例外。
6.4 恢复流程要提前演练
最后一个心得：恢复流程一定要提前演练。别等到真崩了才第一次尝试恢复，那时候你手忙脚乱，很容易做出错误操作把现场破坏掉。正确的做法是，任务上线前，故意中断一次，走一遍恢复流程，确认能从检查点正常继续。演练过的流程才是可靠的流程，没演练过的都只是"理论上可行"。
7. 把长时运行变成一种工作方式
聊到这里，其实长时运行已经不只是一个技术配置问题了，它更像是一种工作方式的转变。短会话模式下，你是"操作者"，每一步都盯着；长时运行模式下，你更像"调度者"，设计好任务、配好环境、设好监控，然后让它自己跑，你只在关键节点介入。
这种转变带来的最大好处是时间被解放了。那些机械的、重复的、耗时的批量工作，可以挂上去自己跑，你去干更有价值的事。但代价是，你必须在前期把功课做足：任务要幂等、要有检查点、要可观测、要有恢复方案。前期偷的懒，后期都会以"任务崩了要从头再来"的形式还回来。
我现在的习惯是，任何要挂超过半小时的任务，上线前都过一遍第 4.4 节那份清单。刚开始觉得繁琐，做几次之后就成肌肉记忆了，反而比事后救火省心得多。长时运行这件事，稳比快重要，能恢复比跑得满重要。把这两条记牢，剩下的都是细节问题。
如果你也在用 opencode 跑长时任务，欢迎把你遇到的坑和解决办法记下来，这类经验往往比官方文档更有参考价值，因为它们是真实环境里磨出来的。
