常见问题 FAQ

四种方式，殊途同归：

# npm（推荐 — 无需 Rust 工具链）
npm install -g codewhale

# Cargo（需要 Rust 1.88+）
cargo install codewhale-cli --locked
cargo install codewhale-tui --locked

# Homebrew（macOS）
brew tap Hmbown/deepseek-tui && brew install deepseek-tui

# 直接下载
# https://github.com/Hmbown/CodeWhale/releases

输入 codewhale 即可启动。首次运行会自动创建 ~/.codewhale/。旧版 ~/.deepseek/ 仍会作为兼容回退读取。 查看 完整安装指南 了解国内镜像、Docker 和故障排除。

# 方法 1：环境变量
export DEEPSEEK_API_KEY=sk-...

# 方法 2：保存在配置中（推荐 — 重启 Shell 后仍然有效）
codewhale auth set --provider deepseek --api-key sk-...

# 方法 3：config.toml
# 在 ~/.codewhale/config.toml 中添加：
api_key = "sk-..."

# 查看当前状态：
codewhale auth status    # 显示配置、密钥环和环境变量状态
codewhale doctor         # 完整连接检查

配置中保存的密钥优先于环境变量。 使用 codewhale auth clear --provider deepseek 移除已保存的密钥。

CodeWhale 内建以下提供商：

• DeepSeek — 一级支持，原生 API。推理流、缓存指标、思考力度控制。
• OpenRouter — 统一 API，可访问 DeepSeek 和其他开放模型路由。
• OpenAI 兼容、NVIDIA NIM、AtlasCloud、Wanjie Ark、Volcengine Ark、Xiaomi MiMo、Novita、Fireworks、SiliconFlow、SiliconFlow CN、Arcee AI、Moonshot/Kimi、Hugging Face、DeepInfra、Together AI、Z.ai、StepFun、MiniMax、OpenAI Codex、Anthropic、SGLang、vLLM、Ollama

设置对应的环境变量（如 OPENROUTER_API_KEY）并在 ~/.codewhale/config.toml 中配置你的提供商。 自托管 OpenAI 兼容端点可通过 provider 配置接入。

# 1. 设置 OpenRouter 密钥
export OPENROUTER_API_KEY=sk-or-v1-...

# 2. 在 ~/.codewhale/config.toml 中：
[providers.openrouter]
api_key = "sk-or-v1-..."

# 3. 使用 OpenRouter 模型运行：
codewhale --model openrouter/deepseek/deepseek-v4-pro

# 或在 config.toml 中设为默认：
default_text_model = "openrouter/deepseek/deepseek-v4-pro"

OpenRouter 使用与原生 DeepSeek 提供商相同的推理/缓存解析器。 模型 ID 遵循 provider/model-id 格式（如 openrouter/deepseek/deepseek-v4-flash）。

• Plan（计划） — 只读调查。可以 grep、读文件、列目录、抓取 URL。不能写入或执行 Shell。
• Agent（代理） — 默认模式。多步工具调用。Shell 和有副作用的工具根据 approval_mode 设置审批。
• YOLO（全权） — 自动批准所有操作并启用信任模式。工作区边界解除。请谨慎使用。

按 Tab 切换模式。 审批模式（建议 / 自动 / 拒绝）是独立的——例如你可以在 Agent 模式下使用自动审批。

使用 codewhale --model auto 或 /model auto 让 CodeWhale 为每个回合自动选择最合适的模型和推理深度。

Fin 是快速非推理路径（deepseek-v4-flash，推理关闭），用于路由决策、摘要、RLM 子任务、上下文维护等协调工作。在真实请求发送前，Fin 会做一个小的路由调用来选择具体的模型和推理级别。

简短简单的请求可以留在 Flash + 推理关闭的状态。编码、调试、发布工作、架构设计或安全审查则会提升到 Pro 和/或更高的推理级别。Fin 是 CodeWhale 本地逻辑——上游 API 永远不会收到 model: "auto"。

# npm 镜像
npm config set registry https://registry.npmmirror.com
npm install -g codewhale

# Cargo 镜像（清华 TUNA）
# 在 ~/.cargo/config.toml 中添加：
[source.crates-io]
replace-with = "tuna"
[source.tuna]
registry = "sparse+https://mirrors.tuna.tsinghua.edu.cn/crates.io-index/"

也可以从 GitHub Releases 直接下载预编译二进制。 Gitee 镜像和 CNB 镜像也可能可用。

codewhale.net 和 www.codewhale.net 是 CodeWhale 的官方站点，部署在 Cloudflare 上。网站源码存放于 Hmbown/CodeWhale 仓库的 web/ 目录下，任何人都可自行部署为镜像。

所有正式发布和 SHA-256 校验文件仅通过 GitHub Releases 分发。 npm 包从 GitHub Releases 下载经校验的二进制。

面向无法稳定访问 GitHub 的用户，提供 CNB 镜像（docs/CNB_MIRROR.md）。 Cargo 用户可使用 TUNA 镜像在国内加速下载。

自行部署的网站副本、镜像站和第三方包不受 CodeWhale 项目控制。 请验证下载来源和校验和。

运行 codewhale doctor——它会检查 API 密钥、网络、沙箱和 MCP 服务器。完整报告写入 ~/.codewhale/doctor.log。

常见原因：

• Shell 启动文件中的 DEEPSEEK_API_KEY 已过期——打开新 Shell 或使用 codewhale auth set
• 密钥来自错误的提供商——确保密钥与你使用的提供商匹配
• 网络连接问题——检查 curl https://api.deepseek.com/v1/models

# 发布二进制更新器（适用于 npm/二进制安装）
codewhale update

# npm
npm install -g codewhale@latest

# Cargo
cargo install codewhale-cli --locked --force

# Homebrew
brew update && brew upgrade deepseek-tui

如果通过 npm 安装，codewhale update 会下载最新发布二进制。 如果镜像延迟，请从 GitHub Releases 直接下载。