opencode日志分析：执行过程追踪与问题定位教程

1. 为什么需要关注opencode的日志？

你刚在终端里敲下 opencode，界面亮了，Agent开始响应——但某次代码重构建议出错了，或者某个插件突然没反应，又或者模型调用卡在“思考中”长达半分钟。这时候，你第一反应是什么？重启？重装？还是翻 GitHub Issues 看别人有没有遇到一样问题？

其实，opencode 从启动到执行每一步操作，都会在后台默默记录详细日志。这些日志不是冷冰冰的报错堆栈，而是你和 AI 编程助手之间的一份“对话录音+操作录像”：它清楚地告诉你——

• 哪个 Agent 被激活了（是 build 还是 plan？）
• 当前用了哪个模型、请求发到了哪台服务器、用了多少 token
• 插件是否成功加载、LSP 是否完成初始化、上下文是否被截断
• 甚至能还原出“为什么它没听懂你那句‘把这段函数改成异步’”

换句话说：日志是你不用打断流程、不依赖 UI 反馈，就能看清 opencode 内部发生了什么的唯一窗口。
本教程不讲怎么写代码，也不教模型原理，只聚焦一件事：如何读懂 opencode 的日志，快速定位真实问题，而不是靠猜、靠试、靠重来。

2. 日志从哪里来？三种关键日志源

opencode 的日志不是单一路由输出，而是分层、分角色、分场景生成的。搞清来源，才能精准抓取。

2.1 客户端日志（TUI 启动时的实时输出）

当你直接运行 opencode 命令，终端里滚动的彩色文字就是客户端日志。它最直观，但默认只显示 INFO 及以上级别，且不持久化。

你能看到什么：

• TUI 初始化状态（如 “Loaded 3 plugins”, “LSP server connected”）
• 当前会话 ID、Agent 切换提示（如 “Switched to plan agent”）
• 模型调用摘要（如 “Using model Qwen3-4B-Instruct-2507 via myprovider”）
• 用户输入被解析后的指令类型（如 “Detected code edit request in file main.go”）

❌ 你看不到什么：

• HTTP 请求体、响应头、原始错误详情（比如 429 或 503 的完整原因）
• 插件内部执行耗时、token 计算过程、上下文长度预警
• 任何 DEBUG 级别细节（比如 LSP 是如何匹配符号的）

实操技巧：启动时加 -v 参数可提升日志级别：

opencode -v

再加一个 -v（即 -vv），就进入 DEBUG 模式，你会看到类似这样的输出：

DEBU[0002] [lsp] resolved symbol 'fmt.Println' at line 12, col 5 → found definition in /usr/local/go/src/fmt/print.go
DEBU[0003] [plugin:token-analyzer] received 128 tokens, estimated cost: $0.00012

2.2 服务端日志（vLLM + OpenCode 后端通信链路）

如果你按文档配置了本地 vLLM 服务（如 http://localhost:8000/v1），那么真正的模型推理发生在服务端。opencode 客户端只是“转发请求”，而 vLLM 才是真正干活的。它的日志，才是性能瓶颈和模型异常的真相所在。

你需要检查的关键点：

• vLLM 是否已启动？端口是否被占用？
• 请求是否成功抵达？有无连接超时（dial tcp 127.0.0.1:8000: connect: connection refused）
• 模型加载是否完成？有无显存不足报错（CUDA out of memory）
• 推理是否卡住？看是否有长时间无输出的 INFO 行（如连续 10 秒没新日志）

快速验证方式（无需进容器）：

curl -s http://localhost:8000/health | jq .  # 应返回 {"status":"ready"}
curl -s http://localhost:8000/v1/models | jq .  # 应列出 Qwen3-4B-Instruct-2507

查看 vLLM 日志（Docker 场景）：

docker logs opencode-vllm --tail 50 -f

常见有效线索：

• INFO 08-15 14:22:03 engine.py:212] Started engine with model 'Qwen3-4B-Instruct-2507' → 模型加载成功
• WARNING 08-15 14:23:11 engine.py:456] Request xxx timed out after 30.0s → 模型响应慢，需调参或换卡
• ERROR 08-15 14:24:02 http_server.py:189] Invalid model name 'Qwen3-4B-Instruct-2507' → 配置名与实际加载名不一致

2.3 插件与配置日志（JSON 加载与运行时行为）

opencode 的插件系统高度动态，所有插件加载、参数校验、权限检查都通过日志留痕。尤其当你修改了 opencode.json 或启用了新插件，这部分日志就是“配置是否生效”的判决书。

重点关注字段：

• plugin "google-search" loaded successfully → 插件加载 OK
• config: provider "myprovider" uses baseURL http://localhost:8000/v1 → 配置已读取
• WARN config: model "Qwen3-4B-Instruct-2507" not found in provider "myprovider" → 配置名拼错或模型未注册

一个真实排查案例：
用户反馈“Google 搜索插件点了没反应”。查日志发现：

WARN[0001] plugin "google-search" failed to initialize: missing required env GOOGLE_API_KEY

→ 立刻补上环境变量，无需重启，插件自动重载。

3. 日志结构解读：一行日志到底在说什么？

opencode 默认日志格式为：

LEVEL[HH:MM:SS] [component] message

我们拆解一条典型 DEBUG 日志：

DEBU[0042] [agent:plan] received user input: "refactor this function to use context.WithTimeout" → parsed as CodeRefactorRequest

字段	含义	实用价值
DEBU	日志级别（DEBUG）	表明这是详细追踪信息，非警告或错误
[0042]	当前会话内秒数（从启动起计）	快速定位问题发生时间点，配合用户操作节奏
[agent:plan]	组件标识	明确是 plan Agent 在处理，而非 build 或其他插件
received user input: ...	原始输入原文	确认用户意图是否被正确捕获（避免中文乱码、换行丢失）
→ parsed as CodeRefactorRequest	解析结果	验证 NLU 模块是否理解指令类型，若此处是 UnknownRequest，说明指令太模糊

再看一条服务端交互日志：

INFO[0045] [provider:myprovider] sending request to http://localhost:8000/v1/chat/completions (model=Qwen3-4B-Instruct-2507, tokens=217)

→ 这说明：

• 请求已发出（不是卡在客户端）
• 目标地址、模型名、当前上下文 token 数全部明确
• 若后续无 response received 日志，问题一定在 vLLM 侧

注意：opencode 不会打印敏感内容（如 API Key、完整代码片段），所有代码仅显示文件名+行号，token 数也只作估算，符合其“隐私安全”设计承诺。

4. 实战问题定位：三个高频场景手把手带查

不再空谈理论。下面三个真实高频问题，我们全程用日志驱动排查，每一步都告诉你该看哪行、为什么看、看出什么。

4.1 问题：输入后光标一直闪烁，“正在思考…” 卡住超过 1 分钟

第一步：确认是客户端卡，还是服务端没响应
打开另一个终端，执行：

docker logs opencode-vllm --since 2m | grep -i "completions\|timeout"

如果没有任何输出 → 请求根本没发出去，问题在客户端。
如果看到：

INFO 08-15 15:33:22 http_server.py:155] Received chat completions request
...（停在这里，1分钟后才出现下一行）

→ 说明 vLLM 收到了，但推理极慢。

第二步：查客户端 DEBUG 日志
重新以 -vv 启动：

opencode -vv 2>&1 | tee opencode-debug.log

在 opencode-debug.log 中搜索 sending request 和 response received：

• 若只有 sending request，无 response received → 网络或 vLLM 崩溃
• 若两者都有，但间隔 >30s → 检查 vLLM 启动参数（如 --max-num-seqs 256 是否过小导致排队）

解决方案：

• 临时降低请求复杂度（删掉大段注释再试）
• vLLM 启动时加 --enforce-eager 避免 CUDA 图编译卡顿
• 检查 GPU 显存：nvidia-smi，确认未被其他进程占满

4.2 问题：切换到 plan Agent 后，无法识别当前项目结构

现象：在项目根目录运行 opencode，切到 plan tab，输入“帮我规划这个项目的测试策略”，却回复“未检测到项目”或列出空文件列表。

日志线索：
搜索 [lsp] 和 [project] 关键字：

INFO[0001] [lsp] starting LSP client for /path/to/myproject
WARN[0002] [project] failed to detect project type: no go.mod or package.json found
DEBU[0003] [project] fallback to filesystem scan, depth=3

→ 这说明：opencode 尝试用标准文件（go.mod、package.json、pyproject.toml）识别项目，失败后降级为文件扫描。

继续查：

DEBU[0004] [filesystem] scanned 12 files, skipped 87 (binary, node_modules, .git)

→ 扫描了，但跳过了大量目录。问题可能出在 .opencodeignore 或默认忽略规则。

验证方法：
在项目根目录新建 .opencodeignore，内容仅一行：

node_modules

然后重启 opencode，再看日志是否出现：

INFO[0001] [project] loaded ignore rules from .opencodeignore

4.3 问题：启用语音通知插件后，没有声音，也无报错

直觉反应：是不是没装 ffmpeg？但日志不会骗人。
搜索 plugin:voice：

INFO[0001] [plugin:voice] initialized with provider "macos-say"
DEBU[0002] [plugin:voice] generating speech for text: "Code refactored successfully"
DEBU[0002] [plugin:voice] executing command: say -v "Alex" -o "/tmp/voice-xxx.aiff" "Code refactored successfully"

→ 命令已生成，但没后续。

下一步：手动执行这行命令，看终端报错：

say -v "Alex" -o "/tmp/test.aiff" "test"

如果报错 say: No voice specified，说明系统语音引擎异常；
如果静音，检查系统声音设置或尝试换 -v "Ting-Ting"（中文）。

根本解决：

• macOS 用户：say -v ? 查看可用音色，选一个支持中文的（如 Ting-Ting）
• Linux 用户：改用 pico2wave + aplay 组合，并在 opencode.json 中配置 command 字段

5. 日志管理进阶：让排查更高效

日常开发中，反复 docker logs、grep、开多个终端，效率低还易漏。这里分享三个轻量但极实用的技巧。

5.1 一键日志聚合脚本（推荐）

将以下内容保存为 opencode-log.sh，放在项目根目录：

#!/bin/bash
echo "=== opencode client log (last 50 lines) ==="
opencode -v 2>&1 | tail -50

echo -e "\n=== vLLM server log (last 30 lines) ==="
docker logs opencode-vllm --tail 30 2>/dev/null || echo "vLLM container not found"

echo -e "\n=== Plugin debug hints ==="
docker exec opencode-ai-opencode cat /tmp/opencode-debug.log 2>/dev/null | tail -10 || echo "No debug log found"

赋予执行权限后，随时运行：

chmod +x opencode-log.sh && ./opencode-log.sh

5.2 日志级别动态调整（无需重启）

opencode 支持运行时热更新日志级别。在 TUI 界面中：

• 按 Ctrl+Shift+L → 弹出日志级别选择菜单
• 选 DEBUG → 立即看到详细追踪
• 选 WARN → 回到安静模式
  所有变更即时生效，不影响当前会话。

5.3 关键事件打点（自己加日志）

你完全可以在 opencode.json 中配置自定义钩子，让特定操作自动记日志：

{
  "hooks": {
    "onCodeEditStart": {
      "command": "echo '[HOOK] Code edit started at $(date)' >> /tmp/opencode-hooks.log"
    }
  }
}

这样，每次触发编辑，都会在 /tmp/opencode-hooks.log 留下时间戳，方便事后回溯。

6. 总结：日志不是终点，而是你掌控 opencode 的起点

回顾整个教程，我们没写一行新代码，也没改一个配置项，却完成了三类典型问题的闭环定位。靠的是什么？

• 分清日志层级：客户端看流程，服务端看性能，插件看集成
• 读懂日志语言：时间戳是节奏，组件名是角色，级别是优先级，消息体是事实
• 建立排查路径：从现象 → 查对应组件日志 → 对比预期行为 → 验证假设 → 调整

记住：opencode 的设计哲学是“终端优先、隐私安全、可插拔”。这意味着它不会替你做决定，也不会隐藏执行细节——所有决策依据，都坦诚写在日志里。
你不需要成为 Go 专家或 vLLM 调优大师，只要学会看日志，就能稳稳握住这个 AI 编程助手的方向盘。

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。