故障排除

安装与命令找不到

现象：forgeax: command not found

• 确认安装的是 @forgeax/cli：npm ls -g @forgeax/cli
• 检查 npm 全局 bin 是否在 PATH：npm prefix -g → …/bin
• 临时：npx @forgeax/cli --version

--demo 都跑不起来

• 确认 Node ≥ 18：node -v
• 重装：npm uninstall -g @forgeax/cli && npm install -g @forgeax/cli
• 若从源码/tarball 安装，确认 dist/ 已 build 且 bin 指向 dist/cli/main.js

API / 模型错误

症状	可能原因
提示缺 key	未设 ANTHROPIC_API_KEY（或 openai 族的 OPENAI_API_KEY）
404 DeploymentNotFound	模型名被当成网关 deployment；试 FORGEAX_PROVIDER_API=openai-compat 并设对 OPENAI_BASE_URL
401 / 403	key 无效、或 base URL 指错环境
空响应 / 超时	网关限流、代理截断；换 --model 或检查 ANTHROPIC_BASE_URL

无 key 时先用：

forgeax --demo -p "hi"

TUI 异常 / 乱码

forgeax --no-tui
# 或
export FORGEAX_NO_TUI=1

确认终端支持 UTF-8；SSH / 精简环境优先 readline。

权限一直弹 / 被拒绝

• 查看 .forgeax/settings.json 的 permissions.deny / ask
• 确认没有误设 --permission-mode bypassPermissions 却被 root / killswitch 拒绝启动
• Shell 规则是结构感知的：allow Bash(git *) 管不住后面的 && rm

MCP 工具不出现

见 MCP · 排错。先本机手动跑 server 的 command。

会话续不上

ls .forgeax/sessions/
forgeax --resume <id>
# 或
forgeax -c

确认 --sessions-dir 与上次一致；空 WAL 的新 id 不会「假续聊」。

沙箱打不开

--sandbox 需要平台工具：

• macOS：sandbox-exec
• Linux：bwrap

缺失时会明确降级；不要假设已隔离。

仍然卡住

1. forgeax -h / forgeax -v 收集版本
2. 最小复现：--demo → 再加真实 key 的 -p
3. 到公开仓开 Issue：ForgeaX-Games/forgeax-cli

附上：OS、Node 版本、完整命令行（打码 key）、相关 settings 片段（无密钥）。