Buildify OpenCode Agent
Buildify 对 OpenCode 的封装。buildify-opencode-agent 连接 Buildify Agent Broker，拉取 opencode.task 任务，通过 opencode acp 在本地执行，并将结果、Token 用量、费用与错误回传 Broker。
npm 包： @buildify-cli/opencode-agent
官网下载： buildify.cn/download
环境要求
- Node.js 18 或更高版本
- 本地已安装 OpenCode CLI（
opencode命令可用） - Agent 机器能访问 Buildify Agent Broker
- 所用模型对应的 Provider API 凭证
检查 OpenCode：
bash
opencode --version
opencode models安装
bash
npm install -g @buildify-cli/opencode-agent验证安装：
bash
buildify-opencode-agent --version
buildify-opencode-agent --help快速开始
1. 初始化配置文件
bash
buildify-opencode-agent config init2. 设置 Broker 连接
bash
buildify-opencode-agent config set \
server=http://localhost:8080 \
token=<broker-token> \
clientId=<agent-client-id>3. 启动 Agent
前台运行：
bash
buildify-opencode-agent start --logs后台守护进程：
bash
buildify-opencode-agent start --daemon
buildify-opencode-agent status
buildify-opencode-agent stop4.（可选）安装为 macOS 系统服务
bash
buildify-opencode-agent install-service
buildify-opencode-agent status
buildify-opencode-agent uninstall-service配置文件
配置文件路径：
text
~/.buildify/opencode-agent.json查看当前配置：
bash
buildify-opencode-agent config show设置配置项：
bash
buildify-opencode-agent config set key=value [key=value ...]常用配置项
| 键 | 默认值 | 说明 |
|---|---|---|
server | http://localhost:8080 | Buildify Agent Broker 地址 |
clientId | 主机名 | 在 Broker 注册的 Agent Client ID |
token | 空 | Broker 认证 Token |
defaultCwd | ~/projects | Agent 机器上的默认工作目录 |
maxConcurrent | 1 | 最大并行任务数 |
opencodeBin | opencode | OpenCode 可执行文件路径 |
defaultModel | 空 | 默认模型，格式 provider/model |
defaultProviderNpm | @ai-sdk/openai-compatible | 动态 Provider 的默认 npm 包 |
logs | false | 是否打印本地 Agent 日志 |
acpLogs | false | 是否打印 OpenCode ACP 原始日志 |
reportUpdates | false | 是否将 ACP session/update 事件转发给 Broker |
配置优先级（高 → 低）：
- CLI 参数
- 环境变量
~/.buildify/opencode-agent.json- 内置默认值
环境变量
| 变量 | 说明 |
|---|---|
BUILDIFY_SERVER | Broker 服务地址 |
BUILDIFY_TOKEN | Broker 认证 Token |
BUILDIFY_CLIENT_ID | Agent Client ID |
BUILDIFY_LOGS | 启用本地日志 |
BUILDIFY_OPENCODE_ACP_LOGS | 打印 OpenCode ACP 原始日志 |
BUILDIFY_OPENCODE_REPORT_UPDATES | 转发 ACP 原始更新事件 |
BUILDIFY_OPENCODE_BIN | OpenCode 可执行文件路径 |
BUILDIFY_OPENCODE_DEFAULT_MODEL | 默认模型 |
BUILDIFY_OPENCODE_DEFAULT_PROVIDER_NPM | 默认 Provider npm 包 |
示例：
bash
BUILDIFY_SERVER=http://localhost:8080 \
BUILDIFY_TOKEN=<broker-token> \
BUILDIFY_CLIENT_ID=opencode-local \
buildify-opencode-agent start --logsCLI 命令
bash
buildify-opencode-agent start [options]
buildify-opencode-agent stop
buildify-opencode-agent status
buildify-opencode-agent install-service
buildify-opencode-agent uninstall-service
buildify-opencode-agent config init
buildify-opencode-agent config show
buildify-opencode-agent config set key=value [key=value ...]start 常用参数：
| 参数 | 说明 |
|---|---|
--daemon | 后台运行 |
--foreground | 前台运行 |
--server <url> | 覆盖 Broker 地址 |
--token <token> | 覆盖 Broker Token |
--client-id <id> | 覆盖 Client ID |
--opencode-bin <path> | 覆盖 OpenCode 可执行文件 |
--default-model <model> | 默认模型，格式 provider/model |
--logs | 启用本地日志 |
--acp-logs | 打印 OpenCode ACP 子进程原始日志 |
--report-updates | 将 ACP 原始更新转发给 Broker |
--request-timeout-ms <ms> | HTTP 请求超时 |
在 Buildify 中使用
使用 AgentOpenCodeSubmitTaskNode 节点提交 OpenCode 任务。
必填字段：
- Broker 实例
- Client ID（须与本地运行的
buildify-opencode-agent一致） - 通过
ModelSelect选择的模型 - Prompt（任务指令）
- 工作目录
cwd（Agent 机器上的本地路径）
WARNING
cwd 是 Agent 所在机器上的路径，不是 Buildify 服务器路径。若目录可能不存在，请启用「目录不存在时自动创建」。
Provider 与模型配置
Buildify 中 ModelSelect 的值会映射到任务 payload：
| 字段 | 说明 |
|---|---|
providerId | Provider 标识 |
model | 模型名称 |
providerNpm | Provider 对应的 npm 包 |
baseURL | API Base URL |
env | 环境变量（如 API Key） |
Agent 据此构建 OPENCODE_CONFIG_CONTENT，并启动：
bash
opencode acp --print-logsOpenAI 兼容 Provider 的默认 npm 包为 @ai-sdk/openai-compatible。
示例模型：
text
alibaba-cn/qwen3.7-plus请确保所选 Provider 通过 env 或 baseURL 传入真实的 API Key 或 Base URL，不能是脱敏占位符。
调试
启用普通日志：
bash
buildify-opencode-agent start --logs启用 ACP 原始日志：
bash
buildify-opencode-agent start --logs --acp-logs或通过环境变量：
bash
BUILDIFY_OPENCODE_ACP_LOGS=1 buildify-opencode-agent start --logs查看守护进程/服务状态：
bash
buildify-opencode-agent status本地 ACP 调试（开发用）：
bash
node debug-acp.mjs \
--model alibaba-cn/qwen3.7-plus \
--npm @ai-sdk/openai-compatible \
--api-key <api-key> \
--prompt "say hello"常见错误
OpenCode directory service failed
OpenCode 在初始化项目目录或 Provider 目录时失败。请检查：
cwd在 Agent 机器上是否存在- Agent 进程是否对
cwd有读写权限 - 必要时启用
createCwdIfMissing - Provider 配置、npm 包与
baseURL是否正确
Not Found
通常表示 OpenCode 加载目录/Provider 资源时收到 404。请加上 --acp-logs 启动，查看 Error handling request 相关日志。
Provider "…" requires an API key or baseURL
自定义 Provider 未向 Agent 传递凭证。请检查 Buildify ModelSelect 中的 env 配置。
API key was redacted
Agent 收到的是掩码占位符而非真实 API Key。请从 Buildify 传递原始 Key 值。
OpenCode returned no output and no token usage
OpenCode 结束但未返回文本或用量，通常与 Provider 认证、模型、配额或 API 错误有关。请启用 ACP 日志排查。