1. 从一次进程列表说起：qoderwork 编排器到底在干什么
如果你在 macOS 上执行过ps aux | grep qodercli，大概率会被刷屏。一个看起来只是「帮我列个计划、迭代实现方案」的任务，背后却拉起了十几个qodercli进程，每个都带着一长串参数：--session-id、--mcp-config、--disallowed-tools、--yolo、--input-format stream-json。第一次看到这种场面，很容易怀疑是不是哪里死循环了。
其实这正是 qoderwork 编排器（orchestrator）的核心设计：它不把「一个任务」当成一次函数调用，而是当成一个独立的 AI agent 进程来跑。编排器本身只负责调度、通信和状态流转，真正的执行体是那些qodercli子进程。理解这一点，后面所有的参数、channel、黑名单就都能串起来了。
这篇文章聚焦 qoderwork 编排器的运行机制，从任务调度、执行链路到状态流转逐层拆解。我会给出可复制的配置片段和验证步骤，让你能在本地环境复现关键流程，并亲眼观察调度行为。适合已经用过 qoderwork、想搞清楚它内部协作逻辑的开发者，也适合正在设计多 agent 编排系统的同学参考。
核心检索词先明确：qoderwork 编排器是一个基于进程隔离 + MCP 通信总线 + stream-json 双向流的多 agent 任务调度系统。它解决的问题是——让一个主任务能安全地派生、监控、回收多个子 agent，同时防止 agent 自己无限套娃。
2. 任务调度与执行链路拆解：qodercli 进程隔离机制详解
2.1 一个 Task 一个进程，session-id 是唯一身份证
qoderwork 编排器最底层的设计原则是隔离执行。每当你提交一个任务，编排器不会在当前进程里直接跑逻辑，而是 fork 出一个新的qodercli进程。这个进程通过--session-id参数获得一个全局唯一的 UUID，比如df7a0b08-b839-4a9e-9a80-7eeee5ce0493。
这个 session-id 的作用远超「日志追踪」。它是编排器识别「这个进程属于哪个任务」的唯一依据，也是 MCP channel 路由的 key。换句话说，进程是物理隔离的，session-id 是逻辑关联的。
为什么不用线程而用进程？我实测下来的体会是：AI agent 执行过程中会加载大量上下文、工具定义、模型状态，线程之间共享内存容易互相污染；而进程隔离让每个 agent 的崩溃、超时、内存泄漏都被限制在自己的沙箱里。编排器只需要监控进程退出码，就能判断任务成败。
2.2 工具黑名单：防止 agent 自己启动新任务
看那串--disallowed-tools参数：
--disallowed-tools qoder_cron,qoder_send_channel_media,qoder_start_task,qoder_list_tasks,qoder_get_task_detail,qoder_cancel_task,qoder_send_message,qoder_respond_task这是整个编排机制里最精妙的一环。注意被禁掉的工具：qoder_start_task、qoder_list_tasks、qoder_cancel_task、qoder_send_message……全是任务编排类工具。
原因很直接：如果子 agent 也能调用qoder_start_task，它就能自己派生新任务，新任务再派生新任务，形成无限递归。这不仅是资源问题，更是逻辑灾难——你永远不知道最终会跑出多少个进程。
所以 qoderwork 的权限模型是：任务编排权只在 App 层（编排器）手里，子 agent 只能干活，不能派活。子 agent 可以调用文件读写、代码执行、搜索等工具，但涉及「创建/查询/取消任务」和「跨 channel 发消息」的工具被硬性屏蔽。这是一种典型的「能力降级」设计，用参数层面的黑名单实现，比在 prompt 里写「请不要自己启动任务」可靠得多。
2.3 MCP 作为通信总线：channel 就是任务的信箱
每个qodercli进程都带一个--mcp-config：
{ "mcpServers": { "qoder-work-mcp-adaptor": { "type": "http", "url": "http://127.0.0.1:52345/chat/c9bab46c-6003-4f53-a582-c74d670a9e84", "isProxy": true } } }这里的127.0.0.1:52345是编排器启动的本地 MCP 服务，/chat/{channel_id}中的 channel_id 就是任务的「信箱」。每个任务有独立的 channel，编排器往 channel 里投递消息（用户输入、补充指令、中断信号），agent 从 channel 里读取并回复。
这种设计的妙处在于解耦。编排器不需要知道 agent 内部在干什么，它只管往信箱里放信、从信箱里取信。agent 也不需要知道编排器的存在，它只面对一个标准的 MCP HTTP 接口。双方通过 channel 这个中间层通信，任何一方重启都不影响协议本身。
2.4 stream-json 双向流：支持中途注入
--input-format stream-json和--output-format stream-json这一对参数，让 agent 的输入输出都变成增量 JSON 流，而不是一次性请求响应。
这意味着编排器可以在 agent 执行到一半时，往 stdin 里注入新消息。比如你看到 agent 计划列得不对，可以直接追加一句「第三个步骤改成先写测试」，这条消息会作为 stream-json 的一个新事件被 agent 消费。输出侧同理，--include-partial-messages让编排器能实时看到 agent 的思考片段，而不是等它全部跑完。
这就是为什么 qoderwork 能做到「列计划不断迭代」——迭代能力不是模型自带的，而是 stream-json 双向流 + channel 注入机制共同实现的。
2.5 --yolo 模式：无确认自动执行
--yolo参数表示跳过工具调用的确认环节，agent 决定调用什么工具就直接执行。在交互式 CLI 里，这通常意味着「危险但高效」；但在 qoderwork 的编排场景下，它是必要的——因为编排器本身就是那个「确认者」，子 agent 不需要再弹一次确认。
配合--setting-sources project,user和--output-style qoder-work，整个进程的配置来源和行为风格都被编排器统一接管。子 agent 是一个「被完全配置好的执行单元」，而不是一个需要用户交互的独立程序。
3. 可复制配置：本地复现 qoderwork 编排链路
要观察编排行为，最直接的方式是手动构造一个qodercli启动命令，模拟编排器的调用方式。下面这份配置可以直接复制修改。
3.1 启动命令模板
/Applications/QoderWork.app/Contents/Resources/bin/qodercli \ --output-format stream-json \ --verbose \ --storage-dir ~/.qoderwork \ --resource-dir ~/.qoderwork \ --disallowed-tools qoder_cron,qoder_send_channel_media,qoder_start_task,qoder_list_tasks,qoder_get_task_detail,qoder_cancel_task,qoder_send_message,qoder_respond_task \ --model qwork-auto \ --yolo \ --session-id $(uuidgen | tr 'A-Z' 'a-z') \ --mcp-config '{"mcpServers":{"qoder-work-mcp-adaptor":{"type":"http","url":"http://127.0.0.1:52345/chat/REPLACE_WITH_CHANNEL_ID","isProxy":true}}}' \ --include-partial-messages \ --setting-sources project,user \ --output-style qoder-work \ --input-format stream-json关键点说明：--session-id用uuidgen生成，保证唯一；--mcp-config里的 channel_id 需要替换成编排器实际分配的 ID；--storage-dir和--resource-dir指向同一个目录，这是 qoderwork 的默认约定。
3.2 MCP 配置片段（settings 风格）
如果你在项目里维护 MCP 配置，可以写成独立的 JSON 文件，比如.qoderwork/mcp.json：
{ "mcpServers": { "qoder-work-mcp-adaptor": { "type": "http", "url": "http://127.0.0.1:52345/chat/c9bab46c-6003-4f53-a582-c74d670a9e84", "isProxy": true, "timeout": 30000, "retries": 3 } } }isProxy: true表示这个 MCP server 是代理型，请求会被转发到编排器的 channel 路由层。timeout和retries是我自己加的，用于应对本地服务启动稍慢的情况——编排器刚起来时 52345 端口可能还没 ready，重试能避免首条消息丢失。
3.3 三件套对照表
无论你用 CC Switch、Cline MCP 还是 Codex 的 auth.json，接入任何模型服务都需要三件套：Base URL、Key、Model ID。以 TaoToken 为例，对照关系如下：
| 配置项 | 值 | 说明 |
|---|---|---|
| Base URL | https://taotoken.net/api | 不带 UTM，纯 API 入口 |
| API Key | 在控制台生成 | 形如sk-...，注意保密 |
| Model ID | 如claude-sonnet-4-5 | 按实际可用模型填写 |
如果你用 Codex，auth.json里对应写：
{ "base_url": "https://taotoken.net/api", "api_key": "sk-你的key", "model": "claude-sonnet-4-5" }Cline MCP 的配置则在cline_mcp_settings.json里，结构类似，把baseUrl、apiKey、model三个字段填对即可。CC Switch 用户直接在界面里填这三项，切换时不用改代码。
注意：Base URL 一定要用
https://taotoken.net/api，不要带任何查询参数。带 UTM 的地址是给网页跳转用的，API 调用会失败。
4. 验证请求：观察调度行为与成功结果
配置好之后，怎么确认编排链路真的通了？我分三步验证。
4.1 第一步：确认 MCP 端口存活
curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:52345/chat/test-channel如果返回 200 或 404，说明服务在跑（404 是因为 test-channel 不存在，但路由层响应了）。如果返回Connection refused，说明编排器没启动，或者端口被占用。
4.2 第二步：发一条 stream-json 输入
qodercli的 stdin 接受 stream-json 格式。构造一条最小消息：
echo '{"type":"user","message":{"role":"user","content":[{"type":"text","text":"列出实现一个 LRU 缓存的三个步骤"}]}}' | \ /Applications/QoderWork.app/Contents/Resources/bin/qodercli \ --output-format stream-json \ --input-format stream-json \ --model qwork-auto \ --yolo \ --session-id test-session-001 \ --mcp-config '{"mcpServers":{"qoder-work-mcp-adaptor":{"type":"http","url":"http://127.0.0.1:52345/chat/test-channel","isProxy":true}}}' \ --include-partial-messages你会看到 stdout 里逐条吐出 JSON 事件：先是message_start，然后是若干content_block_delta（增量文本），最后message_stop。这就是 stream-json 双向流的实际形态。
4.3 第三步：观察进程树
在另一个终端执行：
ps -ef | grep qodercli | grep -v grep | awk '{print $2, $NF}'你应该能看到刚才启动的进程，以及它的--session-id。如果编排器在跑，还会看到它派生的其他子进程。对比 session-id，就能确认「哪个进程属于哪个任务」。
成功的结果是：输入消息被 agent 消费，输出流里出现完整的计划文本，进程在任务结束后正常退出。如果进程卡住不退出，通常是 channel 没收到结束信号，检查 MCP 配置里的 URL 是否和编排器分配的一致。
5. 常见报错排查：401、local proxy failed、reading choices、OAuth
这一节对照真实报错，给出排查路径。
5.1 401 Unauthorized
最常见。原因通常是 API Key 没填、填错，或者 Base URL 带了多余路径。检查顺序：先确认https://taotoken.net/api能通，再确认 Key 没有过期，最后看请求头里Authorization: Bearer sk-...格式对不对。如果用的是 Codex 的auth.json，注意字段名是api_key还是apiKey，不同版本有差异。
5.2 local proxy failed
这个报错通常出现在 MCP 代理层。isProxy: true时，qodercli 会把请求转发给本地 52345 服务。如果编排器没启动，或者 channel_id 写错，就会报 local proxy failed。排查方法：先用curl直接打http://127.0.0.1:52345/chat/{你的channel_id}，看是否返回 404（正常）还是连接拒绝（异常）。连接拒绝说明编排器没起来。
5.3 reading choices 相关错误
这类报错一般出现在模型响应解析阶段。stream-json 模式下，如果模型返回的不是标准 OpenAI/Anthropic 格式，解析器会报reading choices或reading content。解决方法是确认 Model ID 和 Base URL 匹配——比如用 Anthropic 格式的模型，就要走对应的 endpoint。TaoToken 的/api入口会自动适配，但 Model ID 必须写对。
5.4 OAuth 相关报错
如果你用的是需要 OAuth 的模型服务，报错可能提示 token 过期或 scope 不足。qoderwork 场景下，建议直接用 API Key 模式，避免 OAuth 的刷新逻辑和编排器的进程生命周期冲突。子 agent 进程是短生命周期的，OAuth token 刷新往往来不及完成。
5.5 进程不退出 / 死循环
如果发现qodercli进程越起越多，先检查--disallowed-tools是否完整。漏掉qoder_start_task就会导致 agent 自己派任务。另外确认--yolo模式下 agent 不会因为工具调用失败而无限重试，必要时在 MCP 配置里加retries: 1限制。
6. 把编排器用起来：从观察到接入
理解 qoderwork 编排器的运行机制之后，你可以做两件事：一是自己写脚本模拟编排器，批量管理qodercli进程；二是把模型服务接进来，让子 agent 真正跑起来。
如果你要长期跑编码类任务或 Agent 工作流，建议用 Coding Plan，它针对多轮、长上下文场景做了优化，配合编排器的 stream-json 双向流，迭代体验会顺很多。想先验证模型对话效果，可以直接在模型对话页面测试。接入过程中遇到 Key 或 Base URL 问题，去 API Keys 页面生成和管理，接入文档里有各客户端的完整配置示例。
回到最初那个ps aux刷屏的场景——现在你应该明白了，那不是 bug，而是 qoderwork 编排器在忠实地执行「一个任务一个进程」的设计。每个qodercli带着自己的 session-id、自己的 channel、自己的工具黑名单，在编排器的调度下协同工作。看懂这套机制，你就能自己复现、调试、甚至改造它。
