OpenRig：基于tmux+YAML+Rust的生产级AI Agent协作框架

1. 项目概述：不是又一个“Agent Demo”，而是一套能真正在生产环境里跑起来的协作骨架

OpenRig 这个名字乍一听有点硬核，像某种工业级钻探设备——其实它确实干的是“钻探”活：在一堆各自为政、临时起意、跑完就散的 AI Agent 中，硬生生凿出一条稳定通道，让它们能记住上下文、共享状态、按角色分工、失败后重试、甚至跨会话持续协作。它不造新模型，也不写新提示词，而是解决一个被大量 demo 忽略的现实问题：单个 Agent 跑得再快，也扛不住真实业务里“用户改主意”“数据断流”“中间步骤超时”“需要多人协同确认”这些毛刺。我去年带团队落地一个客户合同智能审核系统，最初用 LangChain 写了五个独立 Agent（条款提取、风险识别、法条匹配、历史案例比对、摘要生成），本地测试丝滑，一上测试环境就崩：Agent A 提取的字段名和 Agent B 期待的不一致；Agent C 调外部 API 失败，整个链路就卡死；用户中途问一句“上一步为什么这么判”，系统根本答不上来——因为每个 Agent 都是无状态的“一次性打火机”。OpenRig 就是为这类场景生的：它把 tmux 的会话持久化能力、YAML 的声明式配置逻辑、Rust 的内存安全与并发控制全拧在一起，让你定义的不是“一段流程”，而是一个“有记忆、有身份、有容错能力的协作组织”。关键词里反复出现的 “tmux” 和 “YAML”，绝不是凑数——前者是它实现进程级状态保持的物理载体，后者是它定义组织结构的“宪法”。你不需要懂 Rust 才能用它，但必须理解：这里没有魔法，只有对系统可靠性的务实妥协。适合谁？不是刚学完 LangChain 做完天气查询 demo 的新手，而是已经踩过三次“Agent 状态丢失”坑、正被老板追问“为什么不能支持用户中断后继续审合同”的中阶开发者；是手头有现成 Python 工具链、但苦于无法让多个脚本像人一样接力干活的运维/数据工程师；也是想把小红书自动发消息、期货交易信号分析、Django 后台智能审批这些零散需求，真正编织成一个可维护、可审计、可扩缩的智能体中台的技术负责人。

2. 核心设计思路：为什么放弃“纯 Python 编排”，而选择 tmux + YAML + Rust 的三角组合

2.1 拒绝“Python 里套 Python”：单进程编排的天然天花板

市面上绝大多数多 Agent 编排方案（LangGraph、LlamaIndex Agent Router、甚至扣子平台）本质都是单进程内调度：所有 Agent 共享同一个 Python 解释器、同一块内存、同一条线程或事件循环。这带来三个无法绕开的硬伤：

• 状态隔离脆弱：Agent A 修改了全局变量current_context，Agent B 下次读取时可能已是脏数据；用threading.local()或contextvars只能解决并发隔离，解决不了“用户 A 的会话状态”和“用户 B 的会话状态”长期共存问题；
• 故障传播不可控：Agent C 因网络超时抛出未捕获异常，整个事件循环直接中断，Agent D 和 E 就永远卡在等待响应的状态，没有超时兜底、没有重试策略、没有状态回滚；
• 资源绑定僵化：所有 Agent 共享同一份 CPU/内存配额，当 Agent X（比如做 YOLOv10 图像识别）突然吃满 GPU 显存，Agent Y（做文本摘要）就只能排队等，无法按角色动态分配资源。

我试过用 asyncio.create_task() 给每个 Agent 包一层超时和重试，代码量爆炸且难以调试；也试过用 Celery 分布式任务队列，结果发现：Celery 的 broker（Redis/RabbitMQ）成了新瓶颈，序列化/反序列化大模型输出耗时比推理本身还长，而且“任务完成”不等于“协作完成”——Agent Z 需要 Agent X 和 Y 的输出才能启动，Celery 的 workflow 编排太重，不适合轻量级、高频率的 Agent 协作。

2.2 tmux：不是终端复用工具，而是轻量级“进程状态沙盒”

OpenRig 的破局点，是把每个 Agent 当作一个独立的、有生命周期的 Linux 进程来管理，而 tmux 是目前最成熟、最轻量、最稳定的进程会话管理器。它的核心价值被严重低估了：

• 会话即状态容器：每个 Agent 启动时，OpenRig 为其创建一个专属 tmux 会话（如agent-contract-review-20240520-1432），该会话的 shell 环境、工作目录、环境变量、甚至history命令记录，都成为这个 Agent 的私有状态空间。Agent A 在自己的会话里export LAST_EXTRACTED_CLAUSE="第3.2条"，这个变量对 Agent B 完全不可见，天然实现状态隔离。
• 崩溃即重启，无需复杂恢复：如果 Agent 进程因 OOM 或 panic 崩溃，tmux 会话依然存在，OpenRig 的 Watchdog 进程能立刻检测到，并在原会话中重新拉起 Agent 进程，加载上次保存的 checkpoint 文件（YAML 格式），从断点续跑。这比任何 Python 的 try-catch 都更底层、更可靠。
• 资源可视化与可控：tmux list-sessions一眼看清当前运行的 Agent 实例；htop -u $USER能精确看到每个 tmux pane 对应的 Python 进程占用多少 CPU 和内存；tmux resize-pane -t agent-x -x 80 -y 20甚至可以动态调整某个 Agent 的终端窗口大小（虽然实际用不到，但说明其控制粒度之细）。

提示：别被“tmux 是终端工具”的刻板印象限制。它本质是一个进程会话的 namespace 管理器，和 Docker 的 namespace 逻辑同源，只是更轻量。OpenRig 没有封装 tmux 命令，而是直接调用 libtmux 库（Python binding），这意味着你可以用 Python 代码精确控制每个会话的创建、发送命令、捕获输出、监听退出事件——这才是工程化的关键。

2.3 YAML：不是配置文件，而是 Agent 组织的“宪法性文档”

OpenRig 的 YAML 文件（如rig.yaml）不是用来填数据库连接字符串的，它是定义整个协作系统的“宪法”：

# rig.yaml 示例：一个简化版的合同审核协作系统 name: "contract-audit-rig" version: "1.2" # 定义所有参与协作的 Agent 角色，每个角色是独立的进程模板 agents: - name: "clause-extractor" image: "python:3.11-slim" # 指定运行环境，非 Docker，指 Python 版本约束 command: ["python", "extractor.py"] env: MODEL_PATH: "/models/llm-7b" MAX_TOKENS: "512" resources: cpu: "1.0" # 逻辑 CPU 核数上限 memory: "2G" # 内存上限 # 关键：定义该 Agent 的输入/输出契约，是协作的基础 inputs: - name: "raw_contract_text" type: "string" required: true - name: "user_preferences" type: "json" required: false outputs: - name: "extracted_clauses" type: "json" description: "JSON array of clause objects with 'id', 'text', 'section'" - name: "risk-analyzer" command: ["python", "analyzer.py"] # ... 其他配置 inputs: - name: "extracted_clauses" # 注意：这个名字必须和 clause-extractor 的 outputs.name 严格一致 type: "json" required: true outputs: - name: "risk_report" type: "json" # 定义协作流程：谁触发谁，数据如何流转 workflow: - trigger: "user_upload_contract" # 外部事件，如 HTTP POST 到 /upload steps: - agent: "clause-extractor" input_map: raw_contract_text: "$event.body.text" # 从触发事件中提取 user_preferences: "$event.body.preferences" - agent: "risk-analyzer" input_map: extracted_clauses: "$clause-extractor.outputs.extracted_clauses" # 从上一步 Agent 输出中提取 - agent: "summary-generator" input_map: risk_report: "$risk-analyzer.outputs.risk_report"

这个 YAML 的设计哲学是：用声明式语法强制约定契约，而非用命令式代码隐式传递。input_map字段里的$clause-extractor.outputs.extracted_clauses不是 Python 变量引用，而是 OpenRig 运行时解析的路径表达式——它会去clause-extractor的 tmux 会话里，读取其标准输出流中最近一次成功执行后写入的outputs.json文件（由 Agent 自己生成），并提取extracted_clauses字段。这就把“数据依赖”变成了“文件依赖”，彻底规避了进程间复杂的 IPC（进程间通信）难题。

2.4 Rust：不是为了炫技，而是为“可靠性”支付的必要成本

OpenRig 的核心调度器（Rig Daemon）用 Rust 编写，原因很实在：

• 零成本抽象：Rust 的async运行时（Tokio）能高效管理数千个 tmux 会话的 I/O 监听（如tmux capture-pane -p -t agent-x读取输出），而不会像 Python 的 asyncio 那样在 GIL 下频繁切换导致性能抖动；
• 内存安全即可靠性：调度器要长期运行（7x24），任何空指针解引用、use-after-free 都会导致整个协作系统宕机。Rust 的所有权系统在编译期就杜绝了这类错误，省去了大量防御性检查代码；
• 无缝集成系统调用：Rust 的std::process和nixcrate 能直接、安全地调用fork()、exec()、waitpid()等系统调用，这是精细控制 tmux 会话生命周期的底层保障。Python 的subprocess模块在处理僵尸进程、信号传递时总有边界 case。

注意：你不需要写 Rust 代码就能用 OpenRig。Rust 只负责“管人”（调度 Agent 进程），而“干活”的 Agent 依然是你熟悉的 Python/Node.js/Shell 脚本。这种分层设计，让技术选型变得非常务实：用 Rust 守住底线（可靠、高效），用 Python 释放生产力（生态丰富、开发快）。

3. 实操全流程：从零搭建一个可持久化协作的“小红书自动发消息”系统

3.1 环境准备：三步到位，拒绝“pip install 一百遍”

OpenRig 对环境要求极简，但每一步都有其不可替代性：

1. 安装 tmux（必须 3.0a 或更高版本）：

   # Ubuntu/Debian sudo apt update && sudo apt install -y tmux # macOS (Homebrew) brew install tmux # 验证：必须支持 -L 参数（指定 socket 名称） tmux -L test-socket new-session -d && tmux -L test-socket list-sessions && tmux -L test-socket kill-server

   关键点：-L参数用于为不同 OpenRig 实例创建隔离的 tmux socket，避免多个 Rig 实例互相干扰。老版本 tmux（<2.9）不支持此参数，会导致多实例部署失败。

2. 安装 OpenRig CLI（Rust 编译好的二进制）：

   # 从 GitHub Releases 下载对应平台的预编译包（推荐，免编译） curl -L https://github.com/openrig/openrig/releases/download/v0.8.1/openrig-x86_64-unknown-linux-musl -o /usr/local/bin/openrig chmod +x /usr/local/bin/openrig # 验证 openrig --version # 应输出 v0.8.1

   为什么不用cargo install？因为普通用户很少装 Rust 工具链，预编译二进制能降低 90% 的入门门槛。CLI 本身只负责解析 YAML、调用 tmux、启动守护进程，不包含任何 AI 模型逻辑。

3. 准备你的第一个 Agent：小红书发消息脚本（Python）： 创建agents/xhs-poster.py：

   #!/usr/bin/env python3 import os import json import sys import time from datetime import datetime # OpenRig 会通过环境变量传入输入数据 # 这是约定：所有输入都来自 JSON 文件，路径由 OPENRIG_INPUT_FILE 环境变量指定 input_file = os.getenv("OPENRIG_INPUT_FILE") if not input_file or not os.path.exists(input_file): print(f"ERROR: Input file {input_file} not found") sys.exit(1) # 读取输入 with open(input_file, 'r') as f: inputs = json.load(f) # 模拟小红书 API 调用（此处替换为你的真实 SDK） message_content = inputs.get("content", "Hello from OpenRig!") target_user_id = inputs.get("user_id", "123456") # 实际业务逻辑：调用小红书 API 发送消息 # response = xhs_client.send_message(user_id=target_user_id, content=message_content) # 这里我们模拟成功 success = True error_msg = "" # 构建输出，必须写入 OPENRIG_OUTPUT_FILE output_file = os.getenv("OPENRIG_OUTPUT_FILE") if output_file: output_data = { "status": "success" if success else "failed", "message_id": f"msg_{int(time.time())}_{target_user_id[-4:]}" if success else None, "timestamp": datetime.now().isoformat(), "error": error_msg } with open(output_file, 'w') as f: json.dump(output_data, f, ensure_ascii=False, indent=2) # OpenRig 通过检查 exit code 判断 Agent 执行结果 sys.exit(0 if success else 1)

   实操心得：这个脚本的关键在于环境变量驱动和文件 I/O 交互。OPENRIG_INPUT_FILE和OPENRIG_OUTPUT_FILE是 OpenRig 注入的绝对路径，Agent 只需读写这两个文件，完全不知道自己运行在 tmux 里还是 Docker 里。这保证了 Agent 的高度可移植性。

3.2 编写 rig.yaml：定义你的“小红书协作组织”

创建rig.yaml：

name: "xhs-auto-poster" version: "1.0" # 定义 Agent 模板 agents: - name: "xhs-poster" # command 是相对路径，相对于 rig.yaml 所在目录 command: ["python3", "agents/xhs-poster.py"] # 指定 Python 解释器版本，确保环境一致 image: "python:3.11-slim" # 为这个 Agent 分配资源，防止它吃光服务器 resources: cpu: "0.5" memory: "512M" # 定义输入契约：外部触发时，必须提供哪些字段 inputs: - name: "content" type: "string" required: true - name: "user_id" type: "string" required: true - name: "schedule_time" type: "string" required: false description: "ISO format datetime, e.g., '2024-05-20T14:30:00'" # 定义输出契约：成功后，会生成哪些字段供下游使用 outputs: - name: "message_id" type: "string" description: "The unique ID of the sent message" - name: "timestamp" type: "string" description: "ISO format timestamp of sending" # 定义协作流程：目前只有一个 Agent，但已预留扩展空间 workflow: # 触发方式：HTTP webhook，OpenRig 内置一个轻量级 FastAPI 服务 - trigger: "http-webhook" endpoint: "/post-message" # POST 到这个 URL method: "POST" steps: - agent: "xhs-poster" # 将 HTTP 请求体中的字段，映射到 Agent 的输入 input_map: content: "$event.body.content" user_id: "$event.body.user_id" schedule_time: "$event.body.schedule_time"

注意：trigger的http-webhook类型是 OpenRig 内置的，无需额外部署 Web 服务器。你只需openrig start，它就会在:8000启动一个 FastAPI 服务，自动处理/post-message路由。$event.body.xxx是 OpenRig 的路径表达式语法，表示从 HTTP POST 请求的 JSON body 中提取字段。

3.3 启动与验证：三分钟见证“持久化协作”的威力

1. 启动 OpenRig 守护进程：

   # 在 rig.yaml 所在目录执行 openrig start --config rig.yaml --log-level info # 查看日志（实时） openrig logs -f # 查看当前运行的 Agent 会话 tmux list-sessions | grep xhs # 应看到类似：xhs-poster-20240520-1432: 1 windows (created Tue May 20 14:32:15 2024) (attached)

2. 发送第一条消息（模拟用户请求）：

   curl -X POST http://localhost:8000/post-message \ -H "Content-Type: application/json" \ -d '{ "content": "今天的小红书分享：OpenRig 让 AI Agent 真正协作起来！🚀", "user_id": "xhs_user_789" }'

   响应应为：

   {"status":"success","data":{"message_id":"msg_1716215535_0789","timestamp":"2024-05-20T14:32:15.123456"}}

3. 制造故障并验证持久化：

   • 手动杀死 Agent 进程：tmux kill-session -t xhs-poster-20240520-1432
   • 等待 5 秒，查看日志：openrig logs | grep "restarting"
   • 日志应显示：[INFO] Restarting agent 'xhs-poster' in session 'xhs-poster-20240520-1432' after crash
   • 再次发送消息，依然成功。证明：会话崩溃 ≠ 协作中断，状态在文件中持久化，重启即恢复。

3.4 扩展协作：加入“内容审核 Agent”，构建两级流水线

现在，我们让“发消息”前先经过“审核”。新增agents/content-moderator.py：

#!/usr/bin/env python3 import os import json import sys input_file = os.getenv("OPENRIG_INPUT_FILE") if not input_file or not os.path.exists(input_file): print("ERROR: Input file not found") sys.exit(1) with open(input_file, 'r') as f: inputs = json.load(f) content = inputs.get("content", "") # 简单的敏感词过滤（实际应调用专业审核 API） blocked_words = ["违禁", "诈骗", "赌博"] is_blocked = any(word in content for word in blocked_words) output_file = os.getenv("OPENRIG_OUTPUT_FILE") if output_file: output_data = { "is_approved": not is_blocked, "reason": "Blocked by keyword filter" if is_blocked else "Approved", "original_content": content } with open(output_file, 'w') as f: json.dump(output_data, f, ensure_ascii=False, indent=2) sys.exit(0 if not is_blocked else 1) # 退出码 1 表示审核不通过

更新rig.yaml的agents和workflow：

agents: # ... 保留原有的 xhs-poster - name: "content-moderator" command: ["python3", "agents/content-moderator.py"] image: "python:3.11-slim" inputs: - name: "content" type: "string" required: true outputs: - name: "is_approved" type: "boolean" - name: "reason" type: "string" workflow: - trigger: "http-webhook" endpoint: "/post-message" method: "POST" steps: - agent: "content-moderator" # 第一步：审核 input_map: content: "$event.body.content" - agent: "xhs-poster" # 第二步：仅当审核通过才执行 input_map: content: "$event.body.content" user_id: "$event.body.user_id" # 关键：添加条件，只有上一步输出 is_approved == true 才执行 condition: "$content-moderator.outputs.is_approved == true"

实操心得：condition字段是 OpenRig 的分支逻辑核心。它不是 Python 表达式，而是 OpenRig 自研的轻量级表达式引擎，只支持基本比较和逻辑运算，目的就是避免在调度层引入复杂脚本语言带来的安全风险和调试难度。你无法在这里写os.system("rm -rf /")，只能做==,!=,and,or这些安全操作。

4. 深度解析与避坑指南：那些官方文档不会告诉你的实战细节

4.1 YAML 文件的“陷阱地带”：命名、路径、类型校验

OpenRig 的 YAML 解析器看似宽容，实则暗藏玄机。以下是我在三个项目中踩过的坑：

陷阱类型	错误示例	后果	正确做法	原因
Agent 名称非法字符	name: "xhs-poster!"	openrig start报错：Invalid agent name: contains '!'	name: "xhs_poster"或name: "xhs-poster"	OpenRig 用 Agent 名生成 tmux 会话名和文件路径，只允许字母、数字、下划线、短横线。!会被 shell 解释为历史命令扩展。
input_map 路径错误	input_map: {content: "$event.body.content_text"}	Agent 启动失败，日志报KeyError: 'content_text'	确保content_text是 HTTP 请求 body 中真实存在的 key，或用"$event.body.content"	OpenRig 的路径表达式是严格字符串匹配，不支持模糊查找或默认值 fallback。
resources.memory 单位缺失	memory: "512"	启动失败，报Invalid memory limit: '512'	memory: "512M"或memory: "2G"	OpenRig 使用 cgroups v2 的内存限制，必须带单位（K,M,G）。裸数字会被解释为字节，512 字节显然不够。
YAML 缩进错误（最隐蔽）	inputs:下面的- name:缩进 3 个空格	解析失败，报while parsing a flow sequence	严格使用 2 个空格缩进，-和name:对齐	YAML 对缩进极其敏感，inputs:是列表，每个-是列表项，其下的name:type:必须是该列表项的键值对，缩进错一位就语法错误。

提示：用 VS Code 安装redhat.vscode-yaml插件，它能实时校验 YAML 语法并高亮错误。别信肉眼判断缩进。

4.2 tmux 会话的“幽灵残留”：如何清理失控的 Agent

当 OpenRig 守护进程异常退出（如kill -9），它无法优雅清理 tmux 会话，导致“幽灵 Agent”残留：

• 现象：tmux list-sessions看到一堆xhs-poster-20240520-*会话，但openrig status显示无运行中 Agent；
• 危害：这些会话占用内存和文件描述符，tmux进程数过多会拖慢整个服务器；
• 安全清理命令：

  # 1. 只杀掉 OpenRig 创建的、名称匹配的会话（最安全） tmux list-sessions | grep "xhs-poster-" | awk '{print $1}' | sed 's/:$//' | xargs -I {} tmux kill-session -t {} # 2. 如果想批量清理所有 OpenRig 会话（谨慎！） tmux list-sessions | grep "openrig\|xhs\|contract" | awk '{print $1}' | sed 's/:$//' | xargs -I {} tmux kill-session -t {}

  注意：永远不要用tmux kill-server，它会杀死所有 tmux 会话，包括你正在用的开发终端！务必用kill-session -t精准定位。

4.3 Agent 的“输出契约”为何必须严格？—— 一个真实的期货交易案例

客户想用 OpenRig 搭建期货信号分析 Agent（分析 K 线，生成买卖信号），并接入实盘交易 Agent。他们最初的rig.yaml是这样写的：

agents: - name: "signal-analyzer" # ... outputs: - name: "action" # 期望值是 "buy" 或 "sell" type: "string" - name: "price" # 期望值是 float type: "number"

但他们的 Python 脚本analyzer.py输出是：

{"action": "BUY", "price": "3250.50"} // 注意：price 是字符串！

结果：交易 Agent 启动时报错TypeError: expected float, got str，因为 OpenRig 的type: "number"会在调度层做类型校验，"3250.50"字符串不满足number类型，直接拒绝传递给下游。

解决方案：

• 上游修正：analyzer.py输出时，price字段必须是float类型，json.dump()会自动序列化为数字；
• 下游兼容：交易 Agent 的输入解析逻辑，增加类型转换：float(inputs.get("price", "0"))；
• 最佳实践（推荐）：在rig.yaml的outputs中，明确写出example字段，作为契约文档：

  outputs: - name: "price" type: "number" example: 3250.5 # 这个 example 会出现在 OpenRig 的自动生成 API 文档中

4.4 性能调优：当“AI Agent 怎么扛并发”成为真实问题

OpenRig 本身不是高并发框架，但它提供了关键的调优杠杆：

• Agent 并发度控制：rig.yaml中agents[].resources.cpu不仅是限制，也是调度器的并发提示。设为cpu: "0.5"，调度器会尽量让两个此类 Agent 共享一个 CPU 核，避免过度抢占；设为cpu: "2.0"，则会独占两核。根据你的 Agent 类型（CPU 密集型 vs IO 密集型）调整。
• HTTP Webhook 的并发瓶颈：内置 FastAPI 服务默认是单 worker。高并发时，/post-message会排队。解决方案：

  # 启动时指定多个 worker（需安装 uvicorn） openrig start --config rig.yaml --uvicorn-workers 4

• tmux I/O 瓶颈：当 Agent 数量 > 100 时，tmux capture-pane频繁调用会成为瓶颈。OpenRig v0.8+ 引入了--tmux-batch-mode参数，它会将多个 Agent 的输出读取合并为一次 tmux 命令，降低 70% 的 tmux 调用开销。

实测数据：在 16C32G 服务器上，OpenRig v0.8 配合--tmux-batch-mode和 4 个 Uvicorn worker，可持续处理 120 QPS 的 Agent 触发请求，平均端到端延迟 < 800ms（含模型推理时间）。这已经远超大多数中小企业的实际需求。

4.5 与现有技术栈的融合：不是取代，而是编织

OpenRig 的设计哲学是“编织者”，而非“替代者”。它和你现有的技术栈关系如下：

现有技术	如何与 OpenRig 协作	实操示例
FastAPI/Django	OpenRig 是你的“智能后台服务”，你的 Web 框架是“前端控制器”。Web 框架接收用户请求，调用 OpenRig 的 HTTP webhook 或直接调用其 CLI。	Django 视图中：import subprocess; subprocess.run(["openrig", "trigger", "--config", "/path/to/rig.yaml", "--event", json.dumps(event)])
LangChain/LangGraph	OpenRig 不碰 LLM 调用逻辑，它只管调度。你的 LangChain Chain 就是一个完美的 Agent。	agents/langchain-chain.py中，用from langchain.chains import LLMChain构建 chain，输入输出按 OpenRig 契约处理。
Rust 生态	OpenRig 的调度器是 Rust，但你的 Agent 可以是任何语言。用rust-lang写一个高性能的图像处理 Agent，完全没问题。	agents/image-processor.rs编译为image-processor二进制，command: ["./image-processor"]。
YAML 工具链（如 yq）	rig.yaml是标准 YAML，可用yq动态修改。CI/CD 流水线中，用yq替换 API Key、切换模型地址。	yq eval '.agents[0].env.API_KEY = strenv(API_KEY)' rig.yaml > rig-prod.yaml

最后一个技巧：OpenRig 支持--dry-run模式。openrig start --config rig.yaml --dry-run会解析 YAML、校验语法、打印所有将要创建的 tmux 会话名和命令，但不真正执行。这是上线前必做的安全检查，能提前发现 90% 的配置错误。

5. 常见问题速查表与独家排查技巧

问题现象	可能原因	排查命令/步骤	解决方案	我的独家技巧
openrig start后无反应，openrig status显示No rig running	tmux 未正确安装或权限不足	which tmux；tmux -V；tmux new-session -d && echo "OK"	重装 tmux；确保当前用户对/tmp有写权限（tmux socket 默认在此）	在openrig start前加echo $TMUX，如果非空，说明你已在 tmux 里，OpenRig 会拒绝启动以避免嵌套。退出当前 tmux 再试。
Agent 启动后立即退出，openrig logs显示exit code 1	Agent 脚本中sys.exit(1)被调用，或OPENRIG_INPUT_FILE不存在	tmux attach -t <session-name>进入会话，手动执行python3 agents/xxx.py，看报错	检查脚本开头是否正确读取了OPENRIG_INPUT_FILE；用ls -l $OPENRIG_INPUT_FILE确认文件存在且可读	在 Agent 脚本开头加print(f"DEBUG: INPUT_FILE={os.getenv('OPENRIG_INPUT_FILE')}")，然后tmux capture-pane -p -t <session>查看输出。
HTTP webhook 返回 500，日志显示Failed to parse event body	POST 请求的Content-Type不是application/json，或 body 不是合法 JSON	curl -v -X POST http://localhost:8000/xxx -d '{"key":"val"}'看详细响应头和 body	确保curl加-H "Content-Type: application/json"；用在线 JSON 校验器检查 body	OpenRig 的 webhook 服务会记录原始请求 body 到logs/webhook-raw-*.log，直接tail -f logs/webhook-raw-*.log查看原始输入。
多个 Agent 之间数据传递失败，input_map路径找不到	上游 Agent 未成功生成outputs.json，或outputs.json中缺少指定字段	tmux capture-pane -p -t <upstream-session>查看上游 Agent 的 stdout；cat <upstream-output-file>查看文件内容	确保上游 Agent