agent-life-bridge

本地 Agent 网关，部署在客户本地机器上，通过长轮询连接 agent-life 平台，把消息转发给本机运行的 Claude Code / Codex 等 Agent 运行时。

核心特点：

• 客户端主动外连，无需暴露入站端口
• 支持 claude-cli/...、cursor-cli/...、codebuddy-cli/...、codex-cli/...、qwen-cli/...、copilot-cli/...、gemini-cli/...、goose-cli/...、continue-cli/...、opencode-cli/...、aider-cli/... 这类 CLI 模型引用
• 支持多个 agent-life account 与多 agent 配置，并按绑定规则路由
• 提供 onboard、add-agent、doctor、logs、config 等运维命令
• 支持前台运行和守护进程模式
• 支持消息进度草稿、附件下载、图片输入和 /br:* 桥接指令

架构概览

链路可以简化为：

agent-life cloud -> 长轮询 -> agent-life-bridge -> 本地 CLI backend / Agent Runtime

其中：

• agent-life 负责云端消息入口
• agent-life-bridge 通过 getUpdates 长轮询接收消息，负责路由、会话管理、日志、附件下载和回复回传
• 本地 Agent Runtime 负责实际执行 Claude Code、Codex、Qwen Code 等 CLI
• 每个 agent 拥有独立的 CLI 会话状态目录，agent-life 会话与 CLI runtime session 会持久化映射

快速开始

方式 A：npm 全局安装

npm install -g agent-life-bridge@latest

# 交互式初始化：gateway URL 可直接回车使用默认值，随后输入 bot token、选择模型
alb onboard

# 前台启动
alb start

# 或后台启动
alb start --daemon

方式 B：源码运行

cd agent-life-bridge
pnpm install
pnpm build
cp config.example.json config.json
# 编辑 config.json
node dist/entry.js start

开发模式：

pnpm dev

CLI 命令

alb start                  # 前台启动
alb start --daemon         # 后台启动
alb start -c ./config.json # 指定配置文件
alb restart --daemon       # 重启为后台模式
alb stop                   # 停止守护进程
alb restart                # 重启
alb status                 # 查看运行状态
alb onboard                # 交互式初始化
alb add-agent              # 交互式追加一个 agent
alb add-agent codex-assistant codex-cli/gpt-5.4 codex-bot /workspace/app
alb add-agent --account-id office-bot
alb add-agent --create-account office-bot --account-gateway-url https://agent-life.example.com --account-bot-token bot_xxx
alb doctor                 # 检查环境、CLI、API Key 和配置
alb logs                   # 查看最近日志
alb config                 # 输出当前配置
alb update                 # npm 全局自更新；如果当前实例有运行状态，会尝试更新后重启
alb version                # 查看版本
alb help                   # 查看帮助

配置

配置文件搜索顺序

当前实现会按以下顺序读取第一个存在的配置文件：

1. alb start -c /path/to/config.json
2. 环境变量 AGENT_LIFE_BRIDGE_CONFIG
3. 当前目录 ./config.json
4. 用户目录 ~/.agent-life-bridge/config.json

最小配置示例

{
  "channels": {
    "agent-life": {
      "accounts": {
        "dlb-default": {
          "gateway_url": "https://www.m2a.chat/gateway/api",
          "bot_token": "bot_xxx",
          "poll_timeout": 30,
          "retry_interval": 5,
          "max_retry_interval": 60
        }
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "claude-cli/opus-4.6"
      }
    },
    "list": [
      {
        "id": "default",
        "default": true
      }
    ]
  },
  "bindings": [
    {
      "agentId": "default",
      "match": {
        "channel": "*"
      }
    }
  ]
}

完整示例见：

• config.example.json
• config.multi-agent.example.json

agent-life channel 配置读取时兼容旧的顶层 gateway_url / bot_token 写法，但新的配置写入会统一落到 channels["agent-life"].accounts。

兼容性说明：

• 老配置仍可继续使用：顶层 channels["agent-life"].gateway_url / bot_token 仍然会被读取
• 新示例配置统一使用 channels["agent-life"].accounts 格式
• add-agent 会兼容读取老配置，并在保存时自动迁移成 channels["agent-life"].accounts
• onboard 会先备份已有配置，再按新的 channels["agent-life"].accounts 格式重建配置

关键配置项

• channels["agent-life"].accounts.<accountId>.gateway_url：agent-life 网关地址
• channels["agent-life"].accounts.<accountId>.bot_token：bot token
• channels["agent-life"].accounts.<accountId>.poll_timeout：长轮询超时时间，默认 30 秒，最大 60 秒
• channels["agent-life"].accounts.<accountId>.retry_interval：失败后的初始重试间隔，默认 5 秒
• channels["agent-life"].accounts.<accountId>.max_retry_interval：最大重试间隔，默认 60 秒
• agents.defaults.model.primary：主模型引用，例如 claude-cli/opus-4.6、cursor-cli/auto、codebuddy-cli/gpt-5.4、codex-cli/gpt-5.4、qwen-cli/qwen3-coder-plus、copilot-cli/gpt-5.2、gemini-cli/gemini-2.5-pro、goose-cli/default、continue-cli/default、opencode-cli/default 或 aider-cli/default
• agents.defaults.model.fallbacks：备用模型链配置；当前执行链路只使用 primary，自动 fallback 逻辑尚未接入
• agents.defaults.cliBackends：CLI backend 启动参数与运行模式
• agents.list：命名 agent 列表
• bindings：消息路由规则，可按 channel、accountId、peer.id 等条件匹配
• files.temp_dir：文件中转目录
• logging.level：日志级别

多 agent 配置

多 agent 模式通过 agents.list 定义运行实例，通过 bindings 决定消息路由到哪个 agent。

运行时会把 agents.defaults 与 agents.list[] 中的 agent 配置合并：

• agent 未配置 workspace 时，使用启动进程的当前目录
• agent 的 model 可以是字符串，也可以是 { "primary": "...", "fallbacks": [...] }
• agent 级别的 cliBackends 会深度覆盖默认 backend 配置
• agent 级别的 env 会覆盖默认环境变量，clearEnv 会追加

追加 agent 时，也可以直接运行：

alb add-agent

该命令会在现有配置上：

• 追加一个 agents.list[] 项
• 可选绑定已有 agent-life accountId
• 可选创建新的 agent-life account 并立刻绑定
• 兼容旧的顶层 agent-life 配置写法，并在保存时自动迁移成 channels["agent-life"].accounts["dlb-default"]
• 写入前自动备份原配置文件

如果现有 account 已被其他 agent 占用，交互流程会提示该 account 当前绑定到哪个 agent，并允许直接创建新的 account 后继续绑定。

也可以显式指定：

alb add-agent codex-assistant codex-cli/gpt-5.4 codex-bot /workspace/app
alb add-agent --account-id office-bot
alb add-agent --create-account office-bot --account-gateway-url https://agent-life.example.com --account-bot-token bot_xxx

例如：

• 一个 bot 绑定到 Codex
• 一个 bot 绑定到 Claude Code
• 不同工作区使用不同 workspace
• 通过预置 cliSessionId 复用既有 CLI 会话

详见 config.multi-agent.example.json。

路由规则

bindings[].match 中声明的条件是 AND 关系，全部满足才会命中。多个 binding 同时命中时，按具体程度评分选择最具体的一条；同分时使用配置文件中靠前的 binding。

匹配字段包括：

• channel：通道 ID，当前内置 agent-life，也支持 * 兜底
• accountId：agent-life account ID
• peer.kind：private、group 或 multi_bot
• peer.id：会话或群 ID
• userId：发送者 ID

如果没有 binding 命中，会落到默认 agent；默认 agent 为第一个 default: true 的 agent，没有显式默认值时使用 agents.list[0]。

环境变量覆盖

环境变量可覆盖配置文件中的对应值：

| 环境变量 | 覆盖字段 | 说明 | |---|---|---| | AGENT_LIFE_BRIDGE_CONFIG | 配置文件路径 | 指定要加载的 config.json | | AGENT_LIFE_BRIDGE_GATEWAY_URL | channels["agent-life"].accounts["dlb-default"].gateway_url 或旧格式 channels["agent-life"].gateway_url | 优先覆盖默认 agent-life 账号；旧配置会覆盖顶层网关地址 | | AGENT_LIFE_BRIDGE_BOT_TOKEN | channels["agent-life"].accounts["dlb-default"].bot_token 或旧格式 channels["agent-life"].bot_token | 优先覆盖默认 agent-life 账号；旧配置会覆盖顶层 Bot Token | | AGENT_LIFE_BRIDGE_LOG_LEVEL | logging.level | 日志级别 | | AGENT_LIFE_BRIDGE_TEMP_DIR | files.temp_dir | 临时文件目录 | | ANTHROPIC_API_KEY | 环境变量 | 供诊断或后续 API 模式使用 | | OPENAI_API_KEY | 环境变量 | 供诊断或后续 API 模式使用 |

模型与运行模式

当前消息执行链路仅支持 CLI 模式模型，也就是：

• claude-cli/...
• cursor-cli/...
• codebuddy-cli/...
• codex-cli/...
• qwen-cli/...
• copilot-cli/...
• gemini-cli/...
• goose-cli/...
• continue-cli/...
• opencode-cli/...
• aider-cli/...

配置层已经允许 anthropic/...、openai/... 这类 API provider 引用，但当前主运行时尚未实现 API 模式；若把它们设为主模型，程序会返回“当前仅支持 CLI 模式模型”。

内置 CLI backend 默认行为：

• claude-cli：执行 claude --print --verbose --output-format stream-json --include-partial-messages --dangerously-skip-permissions，支持 --resume {sessionId}，按 JSONL 流式输出草稿
• cursor-cli：执行 cursor-agent --print --output-format stream-json --stream-partial-output --force --trust，支持 --resume {sessionId}；cursor-cli/auto 会显式传 --model auto，适配 Cursor Free 计划
• codebuddy-cli：执行 codebuddy --print --output-format stream-json --dangerously-skip-permissions，支持 --resume {sessionId}；首次使用前需要执行 /login 或预先完成账号登录
• codex-cli：默认使用 Codex app-server 运行模式，session 复用策略为 existing
• qwen-cli：执行 qwen -p --output-format json，支持 --resume {sessionId}
• copilot-cli：执行 copilot -p --output-format json --allow-all，支持 --resume={sessionId}，建议配置 XDG_CACHE_HOME=/tmp/copilot-cache
• gemini-cli：执行 gemini -p --output-format stream-json，支持 --resume {sessionId}
• goose-cli：执行 goose run --output-format stream-json -t <prompt>，新会话使用 --name {sessionId}，恢复会话使用 --resume --name {sessionId}；goose-cli/default 不传 --model，沿用 Goose 本地 provider/model 配置
• continue-cli：执行 cn -p --format json <prompt>；continue-cli/default 不传 --model，如需指定 Continue Hub model slug 可使用 continue-cli/<slug>；只有在 Continue JSON 输出包含 session id 时才会使用 --fork {sessionId} 续接
• opencode-cli：执行 opencode run --format json --dangerously-skip-permissions <prompt>，输出按 JSONL events 解析；opencode-cli/default 不传 --model，其他模型引用会作为 OpenCode provider/model 传给 --model
• aider-cli：执行 aider --message <prompt>，按纯文本输出解析；aider-cli/default 不传 --model，沿用 Aider 本地 provider/model 配置。当前按单轮文本 backend 支持，不依赖稳定续会话

可以在 agents.defaults.cliBackends 或单个 agent 的 cliBackends 中覆盖 command、参数、环境变量、session 参数、图片参数、输出格式和 watchdog 超时。

消息行为

收到 agent-life 消息后，bridge 会把消息封装成统一的 session envelope：

• 文本使用 message.text 或 message.caption
• 文档和图片会先下载到 files.temp_dir
• 图片在支持 imageArg 的 backend 中会作为独立图片参数传入；其他附件会以 Attachment: <localPath> 形式追加到 prompt
• 群聊发送者信息会作为不可信 metadata 附加到 prompt，便于本地 CLI 区分用户

回复时会优先发送草稿进度并最终编辑成完整回复。如果最终文本包含 /tmp/... 或 file:///tmp/... 文件路径，bridge 会尝试把这些文件作为图片或文档回传；用户请求中带有“发给我/发送给我”等回传意图时，也会从请求文本中提取这类临时文件路径。文本类文件会补 UTF-8 BOM 以便客户端打开。

消息内指令

bridge 会拦截以下 slash 指令：

• /br:status：返回 bridge 运行状态、当前 agent、provider 和 session ID
• /br:new：为当前会话创建新的 CLI 会话分支；/new 是兼容别名
• /br:stop：返回停止请求提示；当前后端暂不支持强制终止正在执行的 CLI turn
• /cli:commit ...：以 CLI passthrough 模式转发为 /commit ...，仅保留安全的选项参数

其他消息会直接交给当前 agent 的 CLI backend。

数据目录

运行时数据默认保存在 ~/.agent-life-bridge/：

~/.agent-life-bridge/
├── config.json
├── agent-life-bridge.pid
├── runtime.json
├── agents/
│   └── <agentId>/
│       └── cli-sessions.json
├── data/
│   ├── files/
│   ├── logs/
│   └── sessions/
│       ├── agent-life-session-map.json
│       └── cli-sessions.json
└── skills/

其中：

• config.json：全局配置文件
• agent-life-bridge.pid：守护进程 PID 文件
• runtime.json：当前运行实例的启动参数和工作目录，用于自更新后的重启
• agents/<agentId>/cli-sessions.json：每个 agent 的 CLI 会话映射
• data/sessions/agent-life-session-map.json：agent-life 消息与本地 agent/session 的映射
• data/sessions/cli-sessions.json：旧版 CLI 会话文件；首次启动会复制到默认 agent 的状态目录作为迁移备份
• data/files/：从 agent-life 下载的附件
• data/logs/：按天写入的日志文件，文件名形如 agent-life-bridge-YYYY-MM-DD.log
• skills/：自定义技能目录

项目结构

agent-life-bridge/
├── bin/                    # CLI 入口
├── scripts/                # 构建脚本
├── src/
│   ├── cli/                # start / stop / onboard / doctor 等命令
│   ├── agents/             # Agent 解析、路由、CLI 执行
│   ├── channels/           # Channel 插件（如 agent-life）
│   ├── commands/           # 消息内 slash 指令路由
│   ├── config/             # 配置加载、校验、默认值
│   ├── providers/          # 预留 provider 扩展目录
│   ├── types/              # 类型定义
│   └── logger.ts           # 日志
├── extensions/             # workspace 扩展点
├── packages/               # workspace 包目录
├── skills/                 # 本地技能目录
├── config.example.json
├── config.multi-agent.example.json
└── package.json

开发

pnpm install
pnpm build
pnpm typecheck
pnpm start
pnpm dev

环境要求：

• Node.js >= 22.0.0
• pnpm >= 9.0.0

许可证

MIT