Repository navigation
Agent Logs Local Agents CN
适用于 1flowbase v0.5.6 的 Agent Logs 功能。采集 CLI 独立发布，本文以平台目录实际提供的安装命令和对应版本文档为准。
本文配图来自本机 3100 的实际页面（2026-10-13）。日志查看示例使用合成测试记录；安装截图未填写 API Key。界面和版本以你的部署为准。
你可以继续使用现有的 Codex、Claude Code 模型配置，在运行它们的电脑上安装采集器，将会话、用户输入、回答、工具调用和来源提供的 Token 同步到 1flowbase。日志采集不要求把模型请求切换到 1flowbase 网关。
本地 Codex / Claude Code
│ 原生 Hook 触发，读取当前会话增量
▼
本机采集 CLI ── 应用 API Key ──► 1flowbase 日志应用
├─ 日志记录与对话
├─ 客户端轨迹与子 Agent
└─ Token 与费用估算
- 1flowbase 已部署，本机能访问它的服务地址。以下用
https://YOUR_HOST表示该地址，上传端点为https://YOUR_HOST/api/logs/v1/events。 - 在运行 Agent 的同一个操作系统用户下安装 CLI；Codex / Claude Code 已能正常聊天，并支持对应的原生 Hook。
- 有创建日志应用、管理应用 API Key 的权限；将分发包安装到平台还需要扩展中心安装权限，可由管理员完成。
采集器为原生可执行程序，用户无需安装 Node.js、Rust 工具链或检出源码。官方分发包含 Linux、macOS、Windows 的 amd64 / arm64 包，实际可用版本以目录为准。上传携带应用凭据，远程连接使用 HTTPS；本机开发可以使用本机 HTTP 地址。另一台电脑上的 localhost 指的是那台电脑，不能用它连接你的 1flowbase 服务器。
- 登录工作区，进入「设置 → 应用管理」。
- 创建应用，类型选择 Agent Logs，填写名称，例如「本地开发 Agent 日志」。
- 打开该应用，确认「日志接收」为「接收中」。新建日志应用默认启用接收，无需编排或发布工作流。
- 打开应用的「采集 CLI」页面。
图 1：选择 Agent Logs 类型后，只需填写应用信息，无需编排工作流。
「API」页面可管理当前应用的 Key 和查看日志接收接口。日志应用 Key 用于上传日志，模型调用的网关 Key 属于另一用途。
在「采集 CLI → 全部」目录找到 Codex 或 Claude Code：
- 若显示「平台未安装」，点击「安装到 1flowbase」，按提示确认。平台会保存对应版本的完整分发包。
- 安装完成后点击「下载采集 CLI」，或点击对应客户端页签进入详情。
- 在「准备 API Key」中粘贴当前应用的 Key，也可以点击「快速生成 Key」。不填写时，本机安装器会提示输入。
- 选择 Shell（Linux / macOS） 或 PowerShell（Windows），点击「复制命令」。
- 在运行 Agent 的电脑上，用运行 Agent 的用户执行复制的完整命令，按终端提示完成安装。
图 2：Claude Code 尚未安装到平台；Codex 已留存采集包，显示「下载采集 CLI」与「更新平台采集包」。先完成平台安装，再进入客户端安装详情。
图 3：macOS / Linux 安装入口。可以填写 Key，也可以留空，让安装器在终端提示输入。
图 4：Windows 用户切换到 PowerShell，再点击「复制命令」。
**截图中的 127.0.0.1:3100、应用 ID 和 0.2.2 是本机已有包示例，不能照抄图片中的命令。**目录显示的版本可能高于已安装版本；请先点「更新平台采集包」，再使用自己应用详情生成的命令。本文 Codex 原生 Hook 流程要求采集 CLI 0.3.0 或更新版本。
「平台已安装」只说明下载包留存在 1flowbase，不代表本机 CLI 已安装或客户端在线。安装器、二进制和校验文件均从当前平台的版本固定地址下载；不需要用户电脑直接访问 GitHub。缺少平台包时应先完成平台安装。
页面命令预览会遮住 Key，使用「复制命令」取得可执行的真实命令；若手动复制预览，清空 Key 后让终端提示输入。输入框在离开或刷新详情后清空，Key 不进入下载 URL；本机安装器将它保存到私有 config.json。不要将包含真实 Key 的命令或配置分享出去。
- 选择 Codex 采集器，执行它的安装命令。
- 默认读取安装时的
CODEX_HOME，未设置时为~/.codex；来源包括sessions和archived_sessions。自定义目录请按对应版本安装说明设置--codex-home/--source。 - 安装器合并 Codex
hooks.json，保留其他 Hook 和notify。进入 Codex 的/hooks，检查并信任新增采集命令，确认 Hook 已启用。 - 发起一轮新的简单对话，例如「请回复：日志同步测试完成」，等待回答结束。
- 返回该应用「日志」页面刷新，找到这一轮记录，查看输入、回答和客户端轨迹。
采集器由 SessionStart、UserPromptSubmit、PostToolUse、Stop、SubagentStop、Interrupt、SessionEnd 等事件触发短任务。子 Agent 使用自己的 transcript，归属到对应轮次。Hook 未信任、被关闭或客户端不支持时不会自动同步。
安装不会自动上传整个历史目录。首次触发一个会话会补采该会话未上传内容；全部历史需按第 6 节显式导入。来源没有可靠轮次身份时等待来源事实，不生成猜测任务。
- 选择 Claude Code 采集器，执行它自己的安装命令，不能复用 Codex 安装命令。
- 默认客户端目录为
CLAUDE_CONFIG_DIR，未设置时为~/.claude；自定义目录按版本说明设置--client-home/--source。 - 安装器在 Claude Code
settings.json合并本采集器的 Hook，保留既有配置。确认原生 Hook 未被disableAllHooks禁用，并完成客户端要求的信任。 - 发起一轮新的对话并等待完成，返回 1flowbase 的应用「日志」页面检查。
采集器通过 SessionStart、UserPromptSubmit、工具事件、Stop、SubagentStop、SessionEnd 等回调读取当前转录。Claude Code 可能在 Hook 结束后才写入最后一条日志；若暂未出现终态，后续事件或手动 flush 会继续读取。单独发生 Stop 不等于转录已经声明任务成功。
如果目录中暂时没有 Claude Code，先核对扩展中心目录和对应发行是否可用；不要手工替换 Codex 命令中的名字。其他客户端（DeepSeek Harness、OpenCode）也使用自己的采集器与回调，按详情页对应版本文档安装。
安装器输出本机安装路径。默认路径如下，应用ID 为应用详情 URL 中的 ID；自定义过路径时使用实际路径：
| 系统 | Codex 安装目录 | Claude Code 安装目录 |
|---|---|---|
| Linux / macOS | ${XDG_DATA_HOME:-$HOME/.local/share}/1flowbase/collectors/codex/应用ID/ |
${XDG_DATA_HOME:-$HOME/.local/share}/1flowbase/collectors/claude-code/应用ID/ |
| Windows | %LOCALAPPDATA%\1flowbase\collectors\codex\应用ID\ |
%LOCALAPPDATA%\1flowbase\collectors\claude-code\应用ID\ |
目录内包含 bin、私有 config.json、state.json。CLI 不一定加入 PATH，以下使用完整路径。
将 YOUR_APPLICATION_ID 替换为真实应用 ID。Codex：
collector_dir="${XDG_DATA_HOME:-$HOME/.local/share}/1flowbase/collectors/codex/YOUR_APPLICATION_ID"
"$collector_dir/bin/codex-logs-collector" import --config "$collector_dir/config.json"Claude Code：
collector_dir="${XDG_DATA_HOME:-$HOME/.local/share}/1flowbase/collectors/claude-code/YOUR_APPLICATION_ID"
"$collector_dir/bin/claude-code-logs-collector" import --config "$collector_dir/config.json"import 一次性导入配置来源范围内的历史；只补传待处理会话时，将 import 替换为 flush。两者与 Hook 共用断点，不需要复制 Key。
Codex：
$collectorDir = Join-Path $env:LOCALAPPDATA '1flowbase\collectors\codex\YOUR_APPLICATION_ID'
& (Join-Path $collectorDir 'bin\codex-logs-collector.exe') import --config (Join-Path $collectorDir 'config.json')Claude Code：
$collectorDir = Join-Path $env:LOCALAPPDATA '1flowbase\collectors\claude-code\YOUR_APPLICATION_ID'
& (Join-Path $collectorDir 'bin\claude-code-logs-collector.exe') import --config (Join-Path $collectorDir 'config.json')同样可将 import 替换为 flush。导入前确认来源范围，历史日志可能包含提示词、代码、路径和工具输出，它们会被同步到所选应用。
- 日志记录：查看轮次、来源、模型、推理强度、真实状态及来源提供的用量。
- 对话：查看用户输入与来源明确声明的最终回答；子 Agent 的过程在轨迹中查看。
- 客户端轨迹：查看上下文、工具调用和结果、推理、原始事件及子 Agent。长轨迹按视口加载。
- 费用：按模型 ID 匹配价格规则得到估算，不扣余额；来源缺少用量时不会补造。调整价格不自动重写历史费用。
图 5：使用标题搜索定位一轮记录，核对来源、模型、推理强度和状态。本例是 codex-041-turn-7 合成测试记录，未提供用量，界面显示 -，不会编造 Token。
点击表格右侧的「查看运行详情」（窄屏表格可能需要横向滚动），打开对话窗口：
图 6：运行详情中的对话示例。HUMAN_* / CLASSIFICATION_OK_* 是测试文本。每条回答下方的轨迹图标可打开「总轨迹」，查看上下文、工具与来源事件。
图 7：总轨迹窗口提供时间分布、事件分类、主 / 子 Agent 筛选和会话检索；这里展示的内容全部来自合成测试会话。
日志接收可以在应用管理或 API 页面停用。停用后已有日志与 Key 保留，新的上传被拒绝；重新启用后，下次 Hook 或手动 flush 补传。
| 现象 | 核对与处理 |
|---|---|
| 平台已安装，本机没有日志 | 平台状态不代表客户端安装；在 Agent 所在电脑执行对应命令，确认 Hook 信任与启用，再产生一轮新对话。 |
| 安装后没看到全部历史 | 安装只配置 Hook；当前会话触发时补采，全目录历史需手动 import。 |
| 上传被拒绝 | 确认使用当前日志应用的 Key、Key 未撤销、端点为 /api/logs/v1/events；HTTP 403 且错误为 agent_logs_ingestion_disabled 时重新启用日志接收。 |
| 断网后仍没同步 | 没有独立定时重试服务；恢复网络后继续聊天触发 Hook，或运行 flush。未完整确认的批次不会推进断点。 |
| 回答已结束但暂时没有终态 | 本地转录可能延迟落盘，运行 flush；若来源始终不声明终态，平台保持未知，不用最后一段文本猜测完成。 |
| 文件被移动到归档目录 | Codex 同一来源归档不改变事件身份；保留原配置和断点。修改或截断已确认内容会拒绝继续，应先核对源文件。 |
| 手动导入提示断点正在占用 | 与 Hook 共享排他断点，稍后重试；不要删除 state.json 或同时运行多个手动导入。 |
| 费用为零或模型 / 强度缺失 | 检查来源是否提供对应事实及价格是否匹配；采集器不猜模型、用量或计费。 |
| 删除平台日志后重跑 import 无记录 | 已确认断点不会因服务器删除自动回退；重导应按对应版本文档受控恢复，保留源日志与断点备份，不直接删除状态文件。 |
升级时先在平台更新采集包，再在本机重新执行新版本安装命令，使用相同应用 ID 和来源绑定。保留 config.json、state.json 和原日志；CLI 升级影响后续采集，不自动重写已上传记录。
卸载使用该版本安装器的 --uninstall --installation-id 应用ID（Windows 为 -Uninstall -InstallationId 应用ID）。自定义过安装、配置或客户端目录时需传入相同路径。卸载移除本应用采集 Hook 和可执行程序，保留其他 Hook、配置、断点及源日志。需要停止凭据使用时，在应用「API」页面撤销相应 Key。
操作时优先查看「采集 CLI → 查看文档」取得已安装版本说明；上面官方仓库的 main 文档可能包含后续版本变化。