dores-agent

v4.0.4

Published

2 months ago

Unified resident Claude, Codex, and AIPY agent service for Dores

0High
0Medium
0Low

dores-agent

把 Dores 的 Claude、Codex 与 AIPY 常驻入口合并成一个独立 npm 包。

这个包只启动一个 macOS launchd 常驻服务，收到 websocket task.create 后会按 runner 分发：

runner: "claude" -> 走 Claude 执行链
runner: "codex" -> 走 Codex 执行链

同时支持收到 websocket start_aipy 后不弹 Terminal，直接在后台执行：

aipy agent

实际启动由 dores-agent 这个 launchd 常驻服务直接完成，使用 detached 后台进程运行 AIPY agent。因为不依赖 Terminal 窗口，用户关闭终端或编辑器后，AIPY agent 不会被窗口关闭带掉。

如果启动失败、命令不存在或短时间没有响应，会回传 start_aipy_result，错误内容放在顶层 text 和 payload.text。

正式安装

推荐直接从 npmjs 安装正式发布版本：

npm install -g dores-agent

如果你想固定版本，也可以显式指定：

npm install -g [email protected]

在 macOS 上安装完成后，包会自动注册并启动：

LaunchAgent label: ai.dores.unified-agent
主日志: ~/dores/logs/unified-agent.log
Claude job 目录: ~/dores/jobs
Codex job 目录: ~/dores/codex-jobs
AIPY job 目录: ~/dores/aipy-jobs
Codex trusted workspace 目录: ~/dores/codex-trusted-workspaces

如果你想关闭安装时的自动注册，可以在安装前设置：

DORES_UNIFIED_AGENT_AUTO_INSTALL=0 npm install -g dores-agent

安装完成后会触发 postinstall，在 macOS 上注册并启动 launchd 常驻服务。

默认就是：

mode=client
upstream=ws://127.0.0.1:8765

如果你不想在安装时自动注册常驻服务，可以先关闭自动安装，再手动执行安装命令：

DORES_UNIFIED_AGENT_AUTO_INSTALL=0 npm install -g dores-agent
dores-agent install

如何安装并启动常驻服务

如果你的目标是让常驻 unified-agent 连接到本地 Dores websocket 服务 ws://127.0.0.1:8765，最简命令就是：

dores-agent install

这条命令会直接写入 launchd 配置并立刻启动常驻服务。

切换模式或更新上游地址时，也不需要先执行 uninstall。再次执行 install 就会覆盖 LaunchAgent 配置并重启服务。

如果你想显式指定，或者覆盖之前已经安装过的模式配置，再执行：

dores-agent install --mode client --upstream ws://127.0.0.1:8765
dores-agent status

这才是“常驻服务主动连接上游 8765 websocket”的模式。

如果上游 8765 暂时没启动，常驻服务会按默认每 3 秒轮询重连一次；上游服务重启后，也会自动重新连接，无需手动重装。

websocket 回传消息也会写入日志，便于你确认 task.status 是否已经发出：

~/dores/logs/unified-agent.log

你可以在日志里看到类似：

[2026-03-31T06:30:00.000Z] Sending websocket message {"type":"task.status","jobId":"...","payload":{"status":"completed","runner":"codex","projectDir":"/Users/..."}}

为了兼容当前 Dores websocket broker，client 模式默认只向上游发送：

task.status
start_aipy_result

这样可以避免上游对 server.ready、task.accepted、task.confirmation_required、task.output、task.completed、task.failed 返回 400 未知或不支持的消息类型，同时保留 AIPY 启动结果回传。

如果你确实需要在 client 模式下保留这些全量事件，可以显式开启：

dores-agent install --mode client --upstream ws://127.0.0.1:8765 --client-forward-all-events

如果你想让 unified-agent 自己作为本机 websocket 服务常驻监听，才使用 server 模式：

dores-agent install --mode server --host 127.0.0.1 --port 8787
dores-agent status

这里的 8787 是 unified-agent 自己监听的端口，不会去连接 8765。

如果你只想前台启动做调试，不注册 launchd，可以使用：

dores-agent start --mode client --upstream ws://127.0.0.1:8765

或者前台启动本地 websocket 服务模式：

dores-agent start --mode server --host 127.0.0.1 --port 8787

常驻服务位置

LaunchAgent label: ai.dores.unified-agent
Plist: ~/Library/LaunchAgents/ai.dores.unified-agent.plist
主日志: ~/dores/logs/unified-agent.log
launchd stdout: ~/dores/logs/unified-agent-launchd.stdout.log
launchd stderr: ~/dores/logs/unified-agent-launchd.stderr.log
Claude job 目录: ~/dores/jobs
Codex job 目录: ~/dores/codex-jobs
AIPY job 目录: ~/dores/aipy-jobs
Codex trusted workspace 目录: ~/dores/codex-trusted-workspaces

卸载常驻服务

dores-agent uninstall

消息格式

Claude:

{
  "type": "task.create",
  "jobId": "随机的id",
  "runner": "claude",
  "prompt": "我想开发一个游戏"
}

Codex:

{
  "type": "task.create",
  "jobId": "随机的id",
  "runner": "codex",
  "prompt": "我想开发一个游戏"
}

AIPY:

{
  "type": "start_aipy",
  "jobId": "随机的id"
}

AIPY 启动失败或没有响应时，会回传：

{
  "type": "start_aipy_result",
  "protocolVersion": 2,
  "jobId": "随机的id",
  "text": "zsh: command not found: aipy",
  "payload": {
    "success": false,
    "text": "zsh: command not found: aipy",
    "kind": "command_not_found",
    "command": "aipy agent"
  }
}

前端读取顶层 text 或 payload.text 显示都可以。如果终端里出现：

zsh: command not found: aipy

则 payload.text 会包含这条错误信息。

AIPY 启动成功时，会回传：

{
  "type": "start_aipy_result",
  "protocolVersion": 2,
  "jobId": "随机的id",
  "text": "",
  "payload": {
    "success": true,
    "text": "",
    "kind": "started",
    "command": "aipy agent",
    "pid": "12345",
    "outputPath": "/Users/zhangjun/dores/aipy-jobs/随机的id/aipy-agent.log",
    "exitCode": 0
  }
}

后台进程日志会写到对应 job 目录的 aipy-agent.log，启动状态会写到同目录的 status.json。

CLI

dores-agent install
dores-agent status
dores-agent uninstall
dores-agent start --mode server --port 8787

兼容说明：

npm 包名已切换为 dores-agent
全局主命令已切换为 dores-agent
仍保留旧命令 dores-unified-agent 作为兼容别名

常用环境变量

通用：

DORES_UNIFIED_AGENT_MODE
DORES_UNIFIED_AGENT_HOST
DORES_UNIFIED_AGENT_PORT
DORES_UNIFIED_AGENT_UPSTREAM_URL
DORES_UNIFIED_AGENT_RECONNECT_DELAY_MS
DORES_UNIFIED_AGENT_PING_INTERVAL_MS
DORES_UNIFIED_AGENT_PONG_TIMEOUT_MS
DORES_UNIFIED_AGENT_SEND_READY
DORES_UNIFIED_AGENT_CLIENT_FORWARD_ALL_EVENTS
DORES_UNIFIED_AGENT_LAUNCHD_LABEL

Claude：

DORES_CLAUDE_BIN
DORES_CLAUDE_EXEC_MODE
DORES_CLAUDE_MODELS
DORES_CLAUDE_SKIP_PERMISSIONS

Codex：

DORES_CODEX_BIN
DORES_CODEX_EXEC_MODE
DORES_CODEX_MODEL
DORES_CODEX_PROFILE
DORES_CODEX_SANDBOX
DORES_CODEX_APPROVAL
DORES_CODEX_FULL_AUTO
DORES_CODEX_BYPASS_APPROVALS
DORES_CODEX_SKIP_GIT_REPO_CHECK

AIPY：

DORES_AIPY_BIN
DORES_AIPY_NO_RESPONSE_TIMEOUT_MS

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

dores-agent

正式安装

如何安装并启动常驻服务

常驻服务位置

卸载常驻服务

消息格式

CLI

常用环境变量