oh-langfuse

oh-langfuse 是用于给 Claude Code、OpenCode 和 Codex 配置 Langfuse 追踪的命令行工具。它提供交互式安装向导，也支持 setup / check 直接命令，方便在用户机器上安装、修复和校验配置。

当前 npm 版本：0.1.23

能做什么

• 给 Claude Code 安装 Stop hook，把会话事件写入 Langfuse。
• 给 OpenCode 安装并 patch opencode-plugin-langfuse，开启 OpenTelemetry。
• 给 Codex 安装 notify hook，增量读取 session JSONL 并写入 Langfuse。
• 安装完成后自动执行对应 check，尽早发现配置缺失。
• 校验员工号格式，必须匹配 ^[a-z](?:\d{8}|wx\d{7})$，例如 h00613222 或 hwx1234567。

快速使用

建议始终带 @latest，避免 npx 使用本地旧缓存：

npx oh-langfuse@latest
npx oh-langfuse@latest setup
npx oh-langfuse@latest check

也可以指定目标：

npx oh-langfuse@latest setup claude
npx oh-langfuse@latest setup opencode
npx oh-langfuse@latest setup codex

npx oh-langfuse@latest check claude
npx oh-langfuse@latest check opencode
npx oh-langfuse@latest check codex

本地开发运行：

npm install
npm start

交互式菜单

运行 npx oh-langfuse@latest 会打开交互式菜单：

• Up / Down 移动选项。
• 数字键快速定位。
• Space 勾选或取消。
• Enter 确认。
• q 或 Esc 退出。

多选菜单默认不勾选任何目标，避免误装。终端不支持原始按键输入时，会自动降级为数字输入模式。

OpenCode 说明

OpenCode 安装会写入：

• ~/.config/opencode/opencode.json
• ~/.config/opencode/plugins/opencode-plugin-langfuse
• ~/.config/opencode-plugin-langfuse/config.json
• Windows 下的 ~/.config/opencode/launch-opencode-langfuse.cmd
• Linux/macOS 下的 ~/.config/opencode/launch-opencode-langfuse.sh

Windows 下安装器会尝试写入用户级 LANGFUSE_PUBLIC_KEY、LANGFUSE_SECRET_KEY、LANGFUSE_BASEURL。这些变量对当前已经打开的终端不会立即生效，需要新开终端，或者使用生成的 launcher 启动 OpenCode。

check opencode 已按实际情况处理 Windows：如果当前终端还看不到 LANGFUSE_*，但用户级环境变量已写入，或 launcher 已生成，会显示 OpenCode 仍有可用的 Langfuse 环境变量来源，不再把这种情况误判为安装失败。

WSL 用户请直接在 WSL shell 中安装和检查：

npx oh-langfuse@latest setup opencode --userId=h00613222 --yes
npx oh-langfuse@latest check opencode

不会做 Windows 到 WSL 的转发；在 WSL 中运行时，配置写入 WSL 用户自己的 $HOME/.config/opencode。

Claude Code 说明

Claude Code 安装会：

• 安装 langfuse_hook.py
• 创建 ~/.claude/langfuse-venv
• 安装 Python 包 langfuse
• 合并更新 ~/.claude/settings.json
• 配置 Stop hook

Linux 如果缺少 venv 支持，请根据提示安装 python3-venv 或对应 Python 版本的 venv 包。

Codex 说明

Codex 安装会：

• 安装 codex_langfuse_notify.py
• 创建 ~/.codex/langfuse-venv
• 写入 ~/.codex/langfuse/config.json
• 更新 ~/.codex/config.toml 顶层 notify

配置后需要重启 Codex。notify hook 会增量读取 ~/.codex/sessions/**/*.jsonl，把新的 user、assistant、tool、token 事件转换为 Langfuse observation，并把读取偏移记录到 ~/.codex/langfuse/state.json。

环境变量

| 变量 | 作用 | | --- | --- | | LANGFUSE_BASEURL / LANGFUSE_HOST | Langfuse 服务地址 | | LANGFUSE_PUBLIC_KEY | Langfuse public key | | LANGFUSE_SECRET_KEY | Langfuse secret key | | LANGFUSE_USER_ID / CC_USER_ID | 用户标识，必须匹配员工号规则 | | CODEX_HOME | 自定义 Codex home 目录 | | OPENCODE_SKIP_PLUGIN_INSTALL | 跳过 OpenCode npm 插件安装 | | OPENCODE_NPM_REGISTRY | OpenCode 插件 npm 安装源 |

Secret key 不会在交互式界面中明文展示。

常用维护命令

npm run check
npm pack --dry-run

发布包暴露两个命令：

• oh-langfuse
• code-tool-langfuse，兼容旧入口