Troubleshooting

App does not start

1. 确认 Node.js 版本满足项目要求。
2. 重新安装依赖并运行 native module rebuild。
3. 运行类型检查，先排除编译错误。

npm install
npm run postinstall
npm run typecheck

Docs build fails

文档站是独立 Next.js 应用，先进入 docs/ 再检查。

cd docs
npm install
npm run types:check
npm run build

常见原因：

• MDX frontmatter 缺少 title 或语法错误。
• meta.json 引用了不存在的页面。
• 组件名没有在 src/mdx-components.tsx 注册。

Model calls fail

• 检查 provider preset 是否启用。
• 检查 API key 或 OAuth 状态。
• 尝试切换到另一个 provider，确认是不是单个服务不可用。

Channel integration fails

• 先确认 channel credentials。
• 再检查平台侧 webhook、socket 或机器人权限。
• 最后看 OpenCowork channel 页面里的专项配置。

Tool result looks stale

• 确认当前 session 绑定的 workspace。
• 检查文件是否由外部进程改动。
• 重新打开 preview 或刷新对应面板。