故障排除与常见问题

常见问题

我可以在没有 API 密钥的情况下使用 InnoClaw 吗？

可以。 工作空间管理、文件浏览、上传、编辑和 GitHub 克隆功能无需 API 密钥即可使用。只有 AI 对话和笔记生成功能需要 API 密钥。界面会显示提示，说明 AI 功能不可用。

如何使用第三方兼容服务（代理、自托管模型）？

Set OPENAI_BASE_URL, ANTHROPIC_BASE_URL, or GEMINI_BASE_URL in your .env.local file to point to any API-compatible endpoint:

OPENAI_BASE_URL=https://api.your-proxy.com/v1
OPENAI_API_KEY=sk-your-key

如果您的代理不支持 Embedding 端点，请配置单独的 Embedding 服务：

EMBEDDING_API_KEY=sk-your-embedding-key
EMBEDDING_BASE_URL=https://api.your-embedding-proxy.com/v1
EMBEDDING_MODEL=text-embedding-3-small

How do I configure Google Gemini?

Set GEMINI_API_KEY in your .env.local file. Optionally set GEMINI_BASE_URL if using a custom proxy:

GEMINI_API_KEY=your-gemini-key
# GEMINI_BASE_URL=https://api.your-provider.com

Then select "Gemini" as the provider in the Settings UI, or set the default:

LLM_PROVIDER=gemini
LLM_MODEL=gemini-2.5-flash

What is Agent mode and how does it differ from RAG Chat?

RAG Chat answers questions grounded in your workspace files using retrieval-augmented generation. It searches indexed files for relevant context and generates answers with source citations.

Agent mode provides an autonomous AI with tool access (bash, file operations, kubectl, article search, etc.). It can execute multi-step tasks, run commands, edit files, search papers, and submit K8s jobs. Agent mode supports three sub-modes:

  • Agent — Full tool access for autonomous execution

  • Plan — Read-only tools for analysis and planning

  • Ask — Read-only tools for simple Q&A

RAG 索引支持哪些文件格式？

分类

扩展名

文档

.pdf、.txt、.md、.html

数据

.json、.csv

代码

.js、.ts、.py、.java、.go、.rs、.cpp、.c、.rb、.php 等

大型工作空间的索引速度慢吗？

首次同步会处理所有文件（提取文本 → 分块 → 生成嵌入），速度取决于文件的数量和大小。后续同步仅处理新增或修改的文件（基于文件哈希比较），因此速度会显著加快。

我可以在 Linux 上运行 InnoClaw 吗？

可以。 将 WORKSPACE_ROOTS 设置为 Linux 路径：

WORKSPACE_ROOTS=/home/user/research,/home/user/projects

How do Scheduled Tasks work?

Scheduled tasks use cron expressions to automate recurring operations. The scheduler polls every 60 seconds and runs due tasks. Available task types:

Type

Description

daily_report

Generate daily workspace activity report

weekly_report

Generate weekly workspace activity report

git_sync

Automatically pull Git repositories

source_sync

Re-index workspace files

custom

User-defined workflows

Create tasks via the UI or the POST /api/scheduled-tasks endpoint with a cron expression (e.g., "0 0 * * *" for daily at midnight).

How do I download a dataset from HuggingFace or ModelScope?

Use the Datasets page or the POST /api/datasets endpoint:

  1. Navigate to the Datasets page

  2. Enter the repository ID (e.g., username/dataset-name)

  3. Select the source (HuggingFace or ModelScope)

  4. Optionally set file patterns to include/exclude

  5. Start the download

For private HuggingFace repos, set HF_TOKEN in .env.local or via the Settings UI.

How do I configure a proxy for outbound API calls?

Set HTTP_PROXY and HTTPS_PROXY in your .env.local file:

HTTP_PROXY=http://your-proxy:3128
HTTPS_PROXY=http://your-proxy:3128
NO_PROXY=localhost,127.0.0.1,10.0.0.0/8

All outbound fetch() calls (AI API, GitHub, HuggingFace, etc.) will route through the proxy. Hosts in NO_PROXY bypass it.

Database errors on NFS or network filesystems

SQLite requires a local filesystem for reliable locking. If the project is on NFS/CIFS, set DATABASE_URL to a local path:

DATABASE_URL=/tmp/innoclaw/innoclaw.db

Also set NEXT_BUILD_DIR to avoid Turbopack cache errors:

NEXT_BUILD_DIR=/tmp/innoclaw-next

How do I submit K8s / GPU jobs?

  1. Configure Kubernetes access in .env.local:

    KUBECONFIG_PATH=/path/to/your/kubeconfig
K8S_SUBMITTER=your-ad-account
K8S_IMAGE_PULL_SECRET=your-secret-name

  2. Use Agent mode and ask the AI to submit a job, or use the submitK8sJob tool directly

  3. Jobs require explicit user confirmation before submission (the agent will ask)

  4. Use collectJobResults to retrieve logs and status after completion

See Environment Variables for all K8S_* configuration options.

GitHub 克隆失败 —— 我应该检查什么？

  1. 验证 git 已安装：git --version

  2. 检查 .env.local 中的 GITHUB_TOKEN 是否设置正确

  3. 确保令牌具有用于私有仓库的 repo 权限范围

  4. 检查到 github.com 的网络连通性

如何重置数据库？

# Remove the database file
rm ./data/innoclaw.db

# Re-run migrations
npx drizzle-kit migrate

这将创建一个全新的数据库。所有工作空间、对话历史、笔记和设置都将丢失，但磁盘上的工作空间文件不受影响。

如何备份我的数据？

备份以下内容：

项目

位置

数据库

./data/innoclaw.db

配置

.env.local

工作空间文件

WORKSPACE_ROOTS 中列出的目录

开发服务器无法启动

  1. 确保已安装 Node.js 18+：node --version

  2. 确保已安装依赖：npm install

  3. 确保数据库已初始化：npx drizzle-kit migrate

  4. 确保 WORKSPACE_ROOTS 目录在磁盘上存在

  5. 检查端口 3000 是否有冲突

如何更改端口？

# Development
PORT=8080 npm run dev

# Production
PORT=8080 npm run start

获取帮助