常见问题 FAQ

已发布渠道的更新时间与平台覆盖各不相同：

# GitHub Releases 二进制（macOS / Linux 推荐方式）
curl -fsSL https://codewhale.net/install.sh | sh

# npm 其他方式 — 无需 Rust 工具链
npm install -g codewhale

# Cargo（需要 Rust 1.89+；安装 codewhale 命令）
cargo install codewhale-cli --locked

# Linux 上的 Homebrew（tap；已在 Ubuntu 上测试）
brew install Hmbown/deepseek-tui/codewhale

# 直接下载
# https://github.com/codewhale-hq/CodeWhale/releases

输入 codewhale 即可启动。首次运行会自动创建 ~/.codewhale/。旧版 ~/.deepseek/ 仍会作为兼容回退读取。 Android arm64 / Termux 仍是预览支持：只有当所选 npm 包版本对应的 GitHub Release 发布了匹配的 Android 资产时，npm 安装才可用。 查看 完整安装指南 了解国内镜像、Docker 和故障排除。

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

# 方法 2：保存密钥（推荐 — 重启 Shell 后仍然有效）
codewhale auth set --provider deepseek     # 会提示输入密钥
# 脚本中：用 --api-key-stdin 通过管道传入

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

已保存的密钥优先于环境变量。不要把密钥直接写在命令行里，否则会留在 Shell 历史中。 使用 codewhale auth clear --provider deepseek 移除已保存的密钥。

要实际测试连接，运行 codewhale doctor --probe-api 检查托管提供商，或用 codewhale doctor --probe-local 检查本地端点。本地探针可能启动由桌面应用管理的 Ollama 等服务。

Codewhale 内建 50 条提供商路由：

• DeepSeek — 内置默认原生 API 路由，支持推理流、缓存指标和思考力度控制。
• OpenRouter — 统一 API，可访问 DeepSeek 和其他开放模型路由。
• 另外 48 条路由——包括 OpenAI 兼容、Anthropic、Mistral AI、OpenAI Codex、xAI、Moonshot/Kimi、Z.ai、MiniMax、StepFun、Volcengine Ark、百度千帆、Model Studio、NVIDIA NIM、Fireworks、Together AI、DeepInfra、SiliconFlow、Novita、Hugging Face、Arcee AI、AtlasCloud，以及无需密钥的本地端点 SGLang、vLLM 和 Ollama。完整列表由提供商注册表生成。

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

要将 OpenRouter 设为默认路由，请在 ~/.codewhale/config.toml 中把提供商和模型设置放在提供商配置表之前：

# ~/.codewhale/config.toml
provider = "openrouter"
default_text_model = "deepseek/deepseek-v4-pro"

[providers.openrouter]
api_key = "sk-or-v1-..."

OpenRouter 使用与原生 DeepSeek 提供商相同的推理/缓存解析器。 模型 ID 使用 OpenRouter 自己的 slug（如 deepseek/deepseek-v4-flash）；通过 --provider openrouter 或顶层 provider = "openrouter" 选择路由。

• Plan（计划） — 只读调查。可以 grep、读文件、列目录、抓取 URL。不能写入或执行 Shell。
• Work（执行） — 交互式执行任务，可处理文件、运行命令并使用已连接的工具。工具是否可用以及何时请求批准，取决于当前配置和权限姿态。
• Operate（编排） — 直接工具遵循与 Work 相同的权限、沙箱、Shell 和安全规则。独立、并行、后台或长时间工作会优先交给 fleet worker，但不强制委派；只有需要有序阶段和门禁时才需要 Workflow。

输入区为空时，按 Tab 切换模式。 按 Shift+Tab 循环独立的 Ask / Auto-Review / Full Access 权限姿态；Plan 始终只读。

使用 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 直接下载预编译二进制。 维护中的 CNB 镜像覆盖其文档列出的目标；Gitee 镜像只有实际存在后才会对外展示。

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

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

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

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

先运行 codewhale doctor，查看配置路径、已声明的凭据来源和工具设置的离线报告。默认情况下，它不测试实际连接。

用 codewhale doctor --probe-api 明确测试托管提供商，或用 codewhale doctor --probe-local 检查本地端点。本地探针可能启动由桌面应用管理的 Ollama 等服务。

常见原因：

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

# 安装器或发布二进制安装
codewhale update

# npm（codewhale update 不会更新 npm 安装）
npm install -g codewhale@latest

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

# Homebrew tap
brew update && brew upgrade codewhale

如果通过 npm 或 Homebrew 安装，请用对应的包管理器更新；codewhale update 不会改动包管理器安装的版本。 如果镜像延迟，请从 GitHub Releases 直接下载。