故障排查与最佳实践

本文档涵盖常见问题解决方案和使用优化建议。

---

安装问题

Node.js 版本要求

CodeBuddy Code 需要 Node.js v18.20 或更高版本。

node -v          # 检查版本

升级地址：https://nodejs.org/en/download/

Windows 平台

Git Bash 依赖

Windows 平台推荐安装 Git Bash。缺失时 CodeBuddy Code 会启动时打印一次性提示并自动降级到 PowerShell 执行 shell 命令，/enter-worktree、/leave-worktree 等 Git Bash 特有功能将不可用。

• 下载：https://git-scm.com/downloads/win
• 安装时勾选 "Git Bash" 组件

自定义路径（非标准安装位置）：

# CMD
set CODEBUDDY_CODE_GIT_BASH_PATH=C:\Program Files\Git\bin\bash.exe

# PowerShell
$env:CODEBUDDY_CODE_GIT_BASH_PATH="C:\Program Files\Git\bin\bash.exe"

抑制启动提示（例如上游进程已管理 shell）：

# PowerShell
$env:CODEBUDDY_SKIP_GIT_BASH_CHECK="1"

"codebuddy 不是内部或外部命令"

npm 全局目录未加入 PATH。

npm config get prefix    # 查找安装路径

将路径添加到系统 PATH（默认：%USERPROFILE%\AppData\Roaming\npm），重启终端。

搜索工具 (Ripgrep)

CodeBuddy 自动处理 ripgrep 依赖，无需手动安装。如需最佳性能：

# macOS
brew install ripgrep

# Windows
choco install ripgrep

# Ubuntu/Debian
sudo apt install ripgrep

---

常见问题

额度共享

CLI、CodeBuddy IDE 和 CodeBuddy Plugin 共享同一账号的资源配额。

JetBrains IDE 中 ESC 键不生效

JetBrains 终端对 ESC 键处理不同，改用 Ctrl+ESC 或 Shift+ESC。

操作	标准终端	JetBrains 终端
退出/取消	ESC	Ctrl+ESC 或 Shift+ESC

模型切换

/model              # 交互式选择
/model [模型名称]    # 直接切换
/status             # 查看当前模型

--serve 模式网络访问问题

局域网 IP 访问报 ERR_EMPTY_RESPONSE

症状：使用 codebuddy --serve 启动后，通过局域网 IP（如 http://10.31.110.26:52477）访问时，浏览器报 ERR_EMPTY_RESPONSE（未发送任何数据）。

原因：HTTP 服务默认监听 127.0.0.1（本地回环地址），只接受本机连接。使用局域网 IP 访问时，请求到达了机器但被服务拒绝。

解决方案：启动时添加 --host 0.0.0.0 参数，使服务监听所有网络接口：

codebuddy --serve --host 0.0.0.0 --port 8080

非回环地址启动时会自动启用密码认证，密码在控制台输出中可见。

确认服务监听状态

可以通过以下命令检查服务是否正确监听：

# macOS / Linux
lsof -i :PORT_NUMBER

# 或
netstat -an | grep PORT_NUMBER

• 若显示 127.0.0.1:PORT — 只接受本机连接
• 若显示 0.0.0.0:PORT 或 *:PORT — 接受所有网络连接

---

权限确认框无响应 / ESC 才能关

症状：TUI 弹出工具权限确认框，按数字键 / 回车确认后弹框不消失，但 ESC 能正常关闭，且关闭后任务实际已在执行。

日志位置

ls -t ~/.codebuddy/logs/codebuddy-*.log | head -1   # 最新一份

可通过 CODEBUDDY_CONFIG_DIR 环境变量整体迁移配置目录。

关键 TAG（按时序）

正常确认走完应该看到这一串（grep -E '\[Approve\]|\[Reject\]|\[dequeue\]|\[tool-permission\]'）：

TAG	含义
[tool-permission] ASK ...	工具被拦下来要审批
[HandleInterruptions] Approval dialog shown	TUI 已显示弹框
[Approve] User approved tool: <name>	用户点了确认
[Approve] Deferred resolved	后端 promise 已 resolve（任务此时开始执行）
[dequeue] Queue empty, clearing interruptionSubject	pending$ 清空，弹框应消失
[Approve] Success: ... interruption dequeued	全流程结束

ESC 路径把 [Approve] 替换为 [Reject]。

现象 → 推断

看到	推断
整套 TAG 都有但弹框不消失	UI 渲染卡住（如 IDE closeTab RPC 阻塞 await）
有 [Approve] User approved 但缺 [dequeue]	findSessionByItem 失败，附近会有 [Approve] Failed: Cannot find session
有 dequeue Start 但没 Queue empty	interruptionQueues 拿不到队列（多 session 错位）
完全没有 [tool-permission] ASK	该工具未走审批，可能 BypassPermissions 或被 allow 规则放行
有 [tool-permission] ASK 但没 Approval dialog shown	TUI 没订阅到 pending$（teammate 并发 session 错位）
[Approve] Failed: No pending deferred found	deferred 被重复消费

反馈给开发的最小信息

[Approve] / [Reject] / [dequeue] 三个 TAG 出现时间附近的连续 30 行日志即可定位是 UI 没刷、后端没出队、还是 IDE RPC 卡住。

---

更新

自动更新

默认开启，下次启动时自动应用新版本。通过 /config 管理开关。

手动更新

codebuddy update                                    # 内置命令（推荐）
npm install -g @tencent-ai/codebuddy-code@latest   # npm 更新

版本检查

codebuddy --version                                 # 当前版本
npm view @tencent-ai/codebuddy-code version        # 最新版本

更新不到最新版

如果 codebuddy update 或 npm install -g @tencent-ai/codebuddy-code@latest 始终拉取不到最新版本，通常是 npm 镜像源缓存延迟所致。可指定官方源重试：

npm install -g @tencent-ai/codebuddy-code@latest --registry=https://registry.npmjs.org/

确认本地 npm 配置的镜像源：

npm config get registry

若长期使用第三方镜像，可在更新命令中临时指定官方源，无需修改全局配置。

---

从 Claude Code 迁移

迁移内容

目录/文件	说明
agents/	自定义 agents 配置
commands/	斜杠命令定义
skills/	专业技能定义
CLAUDE.md → CODEBUDDY.md	AI 指令和记忆文档

方案一：符号链接（推荐）

共享配置，修改一处两边生效。

# macOS/Linux
cd ~/.codebuddy
ln -s ~/.claude/agents agents
ln -s ~/.claude/commands commands
ln -s ~/.claude/skills skills
ln -s ~/.claude/CLAUDE.md CODEBUDDY.md

# Windows (需管理员权限)
cd $env:USERPROFILE\.codebuddy
New-Item -ItemType SymbolicLink -Path agents -Target $env:USERPROFILE\.claude\agents
New-Item -ItemType SymbolicLink -Path commands -Target $env:USERPROFILE\.claude\commands
New-Item -ItemType SymbolicLink -Path skills -Target $env:USERPROFILE\.claude\skills
New-Item -ItemType SymbolicLink -Path CODEBUDDY.md -Target $env:USERPROFILE\.claude\CLAUDE.md

方案二：复制文件

独立配置，互不影响。

# macOS/Linux
cp -r ~/.claude/agents ~/.codebuddy/agents
cp -r ~/.claude/commands ~/.codebuddy/commands
cp -r ~/.claude/skills ~/.codebuddy/skills
cp ~/.claude/CLAUDE.md ~/.codebuddy/CODEBUDDY.md

# Windows
Copy-Item -Recurse $env:USERPROFILE\.claude\agents $env:USERPROFILE\.codebuddy\agents
Copy-Item -Recurse $env:USERPROFILE\.claude\commands $env:USERPROFILE\.codebuddy\commands
Copy-Item -Recurse $env:USERPROFILE\.claude\skills $env:USERPROFILE\.codebuddy\skills
Copy-Item $env:USERPROFILE\.claude\CLAUDE.md $env:USERPROFILE\.codebuddy\CODEBUDDY.md

插件 Skills 一键安装

Claude Code 插件中的 Skills 支持一键安装，安装后自动加载。

验证迁移

codebuddy         # 启动
/skills           # 检查 Skills
/config           # 查看配置

---

成本优化

核心原则

• 新任务用 /clear 开启新会话
• 长对话用 /compact 压缩历史
• 用 @filename 引用文件，避免粘贴代码

会话管理命令

命令	功能
/cost	查看 Token 消耗
/clear	开启新会话
/compact	压缩历史
/resume	恢复旧对话

成本对比

方式	输入 Token	相对成本
单会话连续 10 个任务	~50,000	高
每个任务新会话	~15,000	低
定期 /compact	~25,000	中

推荐做法

• ✓ 新任务开新会话
• ✓ 每 20-30 轮用 /compact
• ✓ 用 @filename 引用文件
• ✓ 精简提问

避免做法

• ✗ 同一会话处理多个无关任务
• ✗ 对话超过 30 轮不清理
• ✗ 重复粘贴已知代码

---

更多帮助：快速入门指南