Skip to content

配置参考 ​

~/.xacpx/config.json 是 xacpx 的主配置文件。若需从终端管理聊天频道(微信、飞书、元宝),请参阅频道管理。若需从聊天界面修改部分字段,请参阅 /config 命令。

文件位置 ​

文件默认路径用途
配置文件~/.xacpx/config.json主配置
状态文件~/.xacpx/state.json会话、聊天上下文、守护进程状态
插件目录~/.xacpx/plugins/由 xacpx plugin add 安装的插件包
运行时日志~/.xacpx/runtime/app.log应用日志
性能日志~/.xacpx/runtime/perf.log性能调试日志(启用后生效)

环境变量覆盖——规范前缀为 XACPX_:所有读取方优先取 XACPX_<后缀>,并回退到旧前缀 WEACPX_<后缀>:

变量说明
XACPX_CONFIG(旧 WEACPX_CONFIG)覆盖配置文件路径(默认:~/.xacpx/config.json)
XACPX_STATE(旧 WEACPX_STATE)覆盖状态文件路径(默认:~/.xacpx/state.json)
XACPX_ILINK_APP_ID(旧 WEACPX_ILINK_APP_ID)微信频道出站请求中发送的 iLink-App-Id 请求头;省略则不发送该头(向后兼容)

不存在 WEACPX_WEIXIN_SDK 覆盖项——weixin-agent-sdk 入口由依赖解析,而非环境变量。

顶层结构 ​

jsonc
{
  "language": "zh",
  "transport": { ... },
  "logging": { ... },
  "channel": { ... },
  "channels": [ ... ],
  "plugins": [ ... ],
  "agents": { ... },
  "workspaces": { ... },
  "orchestration": { ... },
  "later": { ... }
}

最小可用配置: 以下内容即可启动 xacpx。transport.type 默认为 "acpx-bridge";agents 和 workspaces 可在之后通过聊天命令填充。

json
{
  "transport": {},
  "agents": {},
  "workspaces": {},
  "orchestration": {}
}

语言 ​

字段类型是否必填说明
language"en" | "zh"否选择 xacpx 运行时输出(聊天回复、CLI 输出、编排提示词等)的语言;缺省时首次启动按系统 locale($LANG 等,zh* → 中文,否则英文)推断并写入配置;可用 /config set language en 修改;改后需 xacpx restart 生效

传输层配置 ​

控制 xacpx 与 acpx 后端的通信方式。

字段类型是否必填说明
type"acpx-cli" | "acpx-bridge"否通信模式;省略时默认为 "acpx-bridge"
commandstring否acpx 二进制文件的显式路径;覆盖自动解析逻辑
sessionInitTimeoutMsnumber否会话初始化超时时间(毫秒,默认:120000)
permissionMode"approve-all" | "approve-reads" | "deny-all"否权限模式;省略时默认为 "approve-all",即非交互式提示词回合不会因权限请求停止,除非显式配置更严格的策略
nonInteractivePermissions"deny" | "fail"否非交互式场景的权限策略(默认:"deny")
permissionPolicystring否acpx 权限策略文件路径;以 acpx --permission-policy <value> 形式传入
queueOwnerTtlSecondsnumber否acpx 队列所有者进程的空闲存活时间(秒);以 --ttl 形式传入(默认:1800;0 = 永久保活)
turnIdleTimeoutSecondsnumber否针对进行中代理回合的不活跃看门狗。若某回合在指定秒数内未产生任何流式代理活动(output/tool/thought/usage/plan/command 事件),该回合将被中止并报告为 Turn timed out due to inactivity,同时释放其占用的槽位。计时器会在每个流式事件到来时重置,因此耗时较长但持续有活动的回合不受影响——但若单个工具调用在整个窗口内保持静默(例如 sleep、无交错输出的长时间编译/克隆)仍会触发;对于存在长时间静默操作的工作负载,请调大该值或设为 0。默认 600(10 分钟);0 禁用看门狗。每次回收都会记录 control.turn.idle_timeout(含会话及具体阈值)以便诊断
preferLocalAgentsboolean否当 PATH 上存在本地安装的原生代理 CLI 时,优先使用它而非 acpx 的 npx -y <pkg> 回退(目前为 opencode、kilocode,以及本地回退驱动 reasonix 和 omp——它们不在 acpx 注册表中,但通过 <bin> acp 讲 ACP)。可避免每次冷启动时的 npm registry 拉取——更快,且不受网络波动影响(例如代理初始化时的 ECONNRESET)。默认 true;设为 false 则始终使用 acpx 的默认解析。代理级的 command 覆盖仍然优先
adapterVersions{ "codex"?: string, "claude"?: string }否xacpx 管理的 ACP 适配器的本地精确版本覆盖。取值必须是精确的 semver 版本,不能是范围或标签。省略的条目使用 xacpx 经过测试的默认值(本版本为 codex 2.2.2、claude 0.107.2)。建议使用下方的 xacpx adapter CLI,而非手工编辑该对象
adapterRegistrystring否仅用于 xacpx 管理的 Codex/Claude 适配器的 npm registry。默认 https://registry.npmjs.org/,且不会继承机器/公司的 npm 默认设置。可通过 xacpx adapter registry set <url> 修改;仅接受无凭据的 HTTP(S) URL
acpxMaxIncomingMessageBytesnumber | null否高级:覆盖 acpx 0.15.1+ 对 agent → acpx 入站 ACP 消息的默认 64 MiB 上限。适用于 CLI 队列所有者通道和 Runtime 工作线程通道(宿主进程环境,绝非代理环境)。null/缺省遵循上游;0 禁用该限制(不推荐)。修改后需要回收预热的队列所有者 / Runtime 工作线程
acpxTerminalMaxOutputBytesnumber | null否高级:对保留的终端 stdout+stderr 字节数的宿主级上限。null/缺省遵循上游行为。通道覆盖范围与回收要求同上

传输类型 ​

"acpx-cli" — 每次操作(prompt/cancel/ensureSession)都启动一个新的 acpx 子进程,使用 node-pty 分配 PTY。适合本地开发和调试。

"acpx-bridge" — 启动一个持久的桥接子进程(bridge-main.ts)。所有操作通过 stdin/stdout JSON RPC 发送;acpx 进程在命令之间不重启。适合生产环境和长期运行的部署。

acpx 二进制文件解析顺序 ​

解析顺序(优先级从高到低):

  1. transport.command——显式覆盖,直接获胜。
  2. 内置 acpx 依赖——xacpx 自身 node_modules/acpx,精确锁版(当前 0.22.0,无 caret)。
  3. shell PATH 中的 acpx——没有内置依赖时的回退。

显式设置 transport.command 会完全跳过第 2、3 级。

减少冷启动(queueOwnerTtlSeconds) ​

acpx 收到提示词时会启动一个队列所有者后台进程,用于持有 ACP 代理和模型上下文。xacpx 后续的每条消息都通过 Unix socket 连接到同一个所有者——跳过适配器启动 + session/new/load 冷启动阶段(通常需要数秒至数十秒)。

所有者的空闲存活时间由 --ttl 设置。xacpx 默认为 1800 秒(30 分钟),可覆盖大多数对话间歇。真正空闲后,代理会在 30 分钟内自动回收。

  • 较大的值(如 3600)可使代理保持更长时间的预热状态,但会延长守护进程停止后的残留窗口。
  • 0 = 永久保活;每个会话维持一个持久的代理进程;资源占用最高。
  • 执行 xacpx stop 时,xacpx 会尽力终止已知会话的队列所有者进程(失败不阻塞关闭)。ttl=0 且在非正常关闭后存活的会话需要手动清理。
  • 修改此值需要重启守护进程。

编排 MCP 自动注入 ​

向 acpx 会话发送提示词之前,xacpx 会启动 acpx 队列所有者,并通过 ACPX_QUEUE_OWNER_PAYLOAD 注入一个名为 xacpx 的 MCP stdio 服务器。因此 MCP 工具前缀为 mcp__xacpx__*(例如 mcp__xacpx__delegate_request),使托管代理能够访问编排工具(delegate_request 等)和定时任务工具。

此注入不会修改 .acpxrc.json、~/.acpx/config.json 或替换 acpx 主目录,因此已有的会话、流式日志和索引映射均不受影响。

注入命令解析顺序:

  1. 环境变量 XACPX_CLI_COMMAND(仍兼容旧名 WEACPX_CLI_COMMAND)
  2. XACPX_DAEMON_ARG0 + 当前 Node 可执行文件(回退旧名 WEACPX_DAEMON_ARG0)
  3. process.argv[1] + 当前 Node 可执行文件
  4. xacpx

若 xacpx 不是通过标准 CLI 或守护进程方式启动,请显式设置 XACPX_CLI_COMMAND:

bash
XACPX_CLI_COMMAND="node /path/to/xacpx/dist/cli.js" xacpx run

代理 ​

已注册的代理映射表。键为代理名称,用于 /agent add、/session new --agent 等命令。

字段类型是否必填说明
driverstring是代理驱动类型;作为第一个位置参数传给 acpx
commandstring否自定义代理的原始命令;内置驱动不推荐使用

内置模板(仅需设置 driver,由 acpx 解析别名):

模板Driver
codex"codex"
claude"claude"
ante"ante"
pi"pi"
openclaw"openclaw"
gemini"gemini"
cursor"cursor"
copilot"copilot"
droid"droid"
deepseek-harness"deepseek-harness"
factory-droid"factory-droid"
factorydroid"factorydroid"
goose"goose"
grok-build"grok-build"
hermes"hermes"
iflow"iflow"
kilocode"kilocode"
kimi"kimi"
kiro"kiro"
mcode"mcode"
mux"mux"
octomind"octomind"
omp"omp"
opencode"opencode"
pool"pool"
qoder"qoder"
qwen"qwen"
reasonix"reasonix"
trae"trae"
zeroclaw"zeroclaw"

通过聊天使用 /agent add <name> 添加模板,或在终端使用 xacpx agent add <name> 添加。添加配置完全相同的代理是幂等的;若名称冲突但配置不同,会提示先删除现有代理。

json
{
  "agents": {
    "codex": { "driver": "codex" },
    "claude": { "driver": "claude" },
    "kimi": { "driver": "kimi" },
    "my-agent": { "driver": "custom", "command": "/usr/local/bin/my-agent" }
  }
}

工作区 ​

已注册的工作区映射表。键为工作区名称,用于 /workspace new、/session new --ws 等命令。

首次运行时会自动创建 home 工作区(cwd: "~");可使用 xacpx workspace rm home 删除。

字段类型是否必填说明
cwdstring是工作区路径;以 acpx --cwd 形式传入;支持 ~ 展开
descriptionstring否在 /workspaces 输出中显示的描述
json
{
  "workspaces": {
    "backend": {
      "cwd": "/Users/name/Projects/backend",
      "description": "backend repo"
    },
    "frontend": {
      "cwd": "/Users/name/Projects/frontend"
    }
  }
}

频道 ​

channels 数组列出需要启动的消息频道运行时。

在终端管理频道:

bash
xacpx channel list
xacpx channel add feishu
xacpx channel disable weixin
xacpx restart

ChannelRuntimeConfig 字段 ​

字段类型是否必填说明
idstring是唯一频道标识符;须与 type 匹配(内置:"weixin";插件:"feishu"、"yuanbao" 等)
typestring是频道类型。内置:"weixin"。"feishu" 来自 @ganglion/xacpx-channel-feishu;"yuanbao" 来自 @ganglion/xacpx-channel-yuanbao
enabledboolean否频道是否激活(默认:true)
optionsobject视情况而定频道专属配置(见下文)

飞书频道选项 ​

字段类型是否必填说明
options.appIdstring单 Bot 模式必填飞书 App ID
options.appSecretstring单 Bot 模式必填飞书 App Secret
options.domain"feishu" | "lark"否API 域名(默认:"feishu")
options.requireMentionboolean否群聊中是否需要 @提及(默认:true)
options.textMessageFormat"text"否消息发送格式;目前仅支持 "text"
options.dedupTtlMsnumber否消息去重 TTL(毫秒,默认:43200000,即 12 小时)
options.dedupMaxEntriesnumber否去重缓存最大条目数(默认:5000)
options.defaultAccountstring否多 Bot 模式的默认账号 ID;回退顺序:"default" → 第一个条目
options.accountsobject否按 accountId 索引的账号级覆盖;每个条目可覆盖 appId、appSecret、domain、requireMention、dmPolicy、groupPolicy、allowFrom、enabled、name
options.dmPolicy"open" | "allowlist" | "disabled"否私聊准入策略(默认:"open")
options.groupPolicy"open" | "allowlist" | "disabled"否群聊准入策略(默认:"open");requireMention 独立生效
options.allowFromstring[]否发送者 open_id 白名单;当任一策略为 "allowlist" 时生效
options.replyMode"static" | "streaming" | "auto"否回复渲染模式;默认 "auto"(私聊 → streaming,群聊 → static)。"streaming" 使用 CardKit v2 交互卡片实时更新(思考 → 流式 → 完成/中止/错误,含实时页脚计时器、推理折叠、详细模式下可折叠的工具调用面板、Markdown 图片 URL → image_key 解析、字符级流式传输)。需要机器人权限 cardkit:card:write + im:message:send_as_bot;首次卡片创建失败时回退到 static 并记录 feishu.streaming.fallback。可通过 options.accounts.<id>.replyMode 按账号覆盖

元宝频道选项 ​

由 @ganglion/xacpx-channel-yuanbao 提供。使用 xacpx plugin add @ganglion/xacpx-channel-yuanbao 安装,然后添加频道。

字段类型是否必填说明
options.appKeystring与 appSecret 一起必填元宝机器人 App Key
options.appSecretstring与 appKey 一起必填元宝机器人 App Secret
options.tokenstring否静态 token;也接受 appKey:appSecret 形式(加载时拆分)。真正的静态认证 token 还需要 botId
options.botIdstring否用于 @提及识别和自身消息过滤的机器人账号 ID;通常由 sign-token 返回并自动填充
options.apiDomainstring否元宝 API 域名(默认:"bot.yuanbao.tencent.com")
options.wsUrlstring否元宝 WebSocket URL(默认:"wss://bot-wss.yuanbao.tencent.com/wss/connection")
options.requireMentionboolean否群聊中是否需要 @提及(默认:true)
options.replyToMode"off" | "first" | "all"否引用回复策略(默认:"first")
options.overflowPolicy"stop" | "split"否长输出溢出策略(默认:"split")
options.maxCharsnumber否出站文本的字符数拆分阈值(默认:3000)
options.mediaMaxMbnumber否最大媒体文件大小(MB,默认:20)
options.fallbackReplystring否代理无文本输出时发送的文本
options.accountsobject否账号级覆盖;条目继承顶层配置

微信扩展配置(openclaw.json) ​

内置 weixin 频道的 options 是空对象。附加的微信字段从 ~/.xacpx/state/openclaw.json 读取(可通过 OPENCLAW_CONFIG 覆盖路径)。该文件独立于 ~/.xacpx/config.json。

json
{
  "channels": {
    "openclaw-weixin": {
      "routeTag": "...",
      "botAgent": "MyApp/1.0",
      "accounts": {
        "<accountId>": {
          "routeTag": "...",
          "botAgent": "MyApp/1.0 (account-A)"
        }
      }
    }
  }
}
字段类型是否必填说明
routeTagstring | number否写入 SKRouteTag 请求头,用于后端路由或 A/B 测试;账号级配置优先
botAgentstring否写入 base_info.bot_agent 的客户端标识;语法为 name/version[ (comment)];截断至 256 字节;为空时回退为 xacpx;账号级配置优先
accounts.<id>object否routeTag 和 botAgent 的账号级覆盖

向后兼容性 ​

  • 旧的单频道配置 channel.type 仍可加载,并自动映射为单条 channels[] 记录。
  • 旧的顶层 feishu 对象仍作为遗留别名被识别;新配置应使用 options。
  • wechat.replyMode 在加载时仍会映射到 channel.replyMode。

权限 ​

/pm(或 /permission)命令在聊天中暴露以下配置值:

/pm 命令配置值效果
/pm set allowtransport.permissionMode: "approve-all"更多操作自动批准
/pm set readtransport.permissionMode: "approve-reads"读取自动批准;写入更为谨慎
/pm set denytransport.permissionMode: "deny-all"拒绝需要审批的操作
/pm auto denytransport.nonInteractivePermissions: "deny"非交互式场景自动拒绝
/pm auto failtransport.nonInteractivePermissions: "fail"非交互式场景立即失败

默认值 ​

日志 ​

字段默认值
logging.level"info"
logging.maxSizeBytes2097152(2 MB)
logging.maxFiles5
logging.retentionDays7
logging.perf.enabledfalse
logging.perf.maxSizeBytes5242880(5 MB)
logging.perf.maxFiles3
logging.perf.retentionDays7

logging.perf 追踪器在 buildApp() 时绑定;修改后需重启守护进程。目前仅内置微信频道写入性能追踪数据;即使启用该选项,其他频道也不会发出回合记录。

回复模式 ​

channel.replyMode 默认为 "verbose"。使用 /replymode 设置会话级覆盖;使用 /replymode reset 清除覆盖。

定时任务 ​

later.defaultMode 默认为 "temp"(在临时会话中执行)。设置为 "bind" 可在创建任务的会话中执行。

编排 ​

字段默认值
orchestration.maxPendingAgentRequestsPerCoordinator3
orchestration.allowWorkerChainedRequestsfalse
orchestration.allowedAgentRequestTargets[](无限制)
orchestration.allowedAgentRequestRoles[](无限制)
orchestration.progressHeartbeatSeconds300(非有限值时回退为 300)
orchestration.maxParallelTasksPerAgent3

示例 ​

完整示例 ​

json
{
  "language": "zh",
  "transport": {
    "type": "acpx-bridge",
    "command": "acpx",
    "sessionInitTimeoutMs": 120000,
    "permissionMode": "approve-all",
    "nonInteractivePermissions": "deny",
    "queueOwnerTtlSeconds": 1800
  },
  "logging": {
    "level": "info",
    "maxSizeBytes": 2097152,
    "maxFiles": 5,
    "retentionDays": 7,
    "perf": {
      "enabled": false,
      "maxSizeBytes": 5242880,
      "maxFiles": 3,
      "retentionDays": 7
    }
  },
  "channel": {
    "replyMode": "verbose"
  },
  "channels": [
    { "id": "weixin", "type": "weixin", "enabled": true }
  ],
  "plugins": [],
  "agents": {
    "codex": { "driver": "codex" },
    "claude": { "driver": "claude" }
  },
  "workspaces": {
    "backend": {
      "cwd": "/absolute/path/to/backend",
      "description": "backend repo"
    }
  },
  "orchestration": {
    "maxPendingAgentRequestsPerCoordinator": 3,
    "allowWorkerChainedRequests": false,
    "allowedAgentRequestTargets": [],
    "allowedAgentRequestRoles": [],
    "maxParallelTasksPerAgent": 3
  },
  "later": {
    "defaultMode": "temp"
  }
}

仅微信 ​

json
{
  "channels": [
    { "id": "weixin", "type": "weixin", "enabled": true }
  ]
}

微信 + 飞书 ​

json
{
  "channels": [
    { "id": "weixin", "type": "weixin", "enabled": true },
    {
      "id": "feishu",
      "type": "feishu",
      "enabled": true,
      "options": {
        "appId": "cli_xxx",
        "appSecret": "...",
        "domain": "feishu"
      }
    }
  ]
}

元宝(需要 @ganglion/xacpx-channel-yuanbao) ​

json
{
  "plugins": [
    { "name": "@ganglion/xacpx-channel-yuanbao", "enabled": true }
  ],
  "channels": [
    {
      "id": "yuanbao",
      "type": "yuanbao",
      "enabled": true,
      "options": {
        "appKey": "yb_xxx",
        "appSecret": "...",
        "requireMention": true
      }
    }
  ]
}

更严格的编排限制 ​

json
{
  "orchestration": {
    "maxPendingAgentRequestsPerCoordinator": 5,
    "allowWorkerChainedRequests": false,
    "allowedAgentRequestTargets": ["claude", "codex"],
    "allowedAgentRequestRoles": ["reviewer", "planner"],
    "maxParallelTasksPerAgent": 5
  }
}

基于 MIT 许可证发布。