FAQ 常见问题

Published channels differ in timing and platform support:

# npm (recommended — no Rust toolchain needed)
npm install -g codewhale

# Cargo (needs Rust 1.88+; installs the codewhale command)
cargo install codewhale-cli --locked

# Homebrew (macOS)
brew tap Hmbown/deepseek-tui && brew install codewhale

# Direct download
# https://github.com/Hmbown/CodeWhale/releases

Run codewhale to start. First run creates ~/.codewhale/ automatically. Legacy ~/.deepseek/ is still read as a compatibility fallback. Android arm64 / Termux is preview support: npm works only when the selected package version has matching Android assets in its GitHub Release. See the full install guide for China mirrors, Docker, and troubleshooting.

# Method 1: Environment variable
export DEEPSEEK_API_KEY=sk-...

# Method 2: Saved config (recommended — survives shell restarts)
codewhale auth set --provider deepseek --api-key sk-...

# Method 3: config.toml
# Add to ~/.codewhale/config.toml:
api_key = "sk-..."

# Check what's active:
codewhale auth status    # shows config, keyring, and env-var state
codewhale doctor         # full connectivity check

Saved config keys take precedence over environment variables. Use codewhale auth clear --provider deepseek to remove a saved key.

Codewhale ships with 45 built-in provider routes:

• DeepSeek — bundled default with a native API route, reasoning streaming, cache metrics, and thinking effort control.
• OpenRouter — unified API for DeepSeek models and other open-model routes.
• 43 more routes — including OpenAI-compatible, Anthropic, Mistral AI, OpenAI Codex, xAI, Moonshot/Kimi, Z.ai, MiniMax, StepFun, Volcengine Ark, Baidu Qianfan, Model Studio, NVIDIA NIM, Fireworks AI, Together AI, DeepInfra, SiliconFlow, Novita AI, Hugging Face, Arcee AI, AtlasCloud, and the keyless local endpoints SGLang, vLLM, and Ollama. The full list is generated from the provider registry.

Set the corresponding env var (e.g. OPENROUTER_API_KEY) and your provider in ~/.codewhale/config.toml. Self-hosted OpenAI-compatible endpoints are supported through the provider config.

# 1. Set your OpenRouter key
export OPENROUTER_API_KEY=sk-or-v1-...

# 2. In ~/.codewhale/config.toml:
[providers.openrouter]
api_key = "sk-or-v1-..."

# 3. Run with the OpenRouter route:
codewhale --provider openrouter --model deepseek/deepseek-v4-pro

# Or make it the default route in config.toml:
# provider = "openrouter"
# default_text_model = "deepseek/deepseek-v4-pro"

OpenRouter uses the same reasoning/cache parser as the native DeepSeek provider. Model IDs are OpenRouter's own slugs (e.g. deepseek/deepseek-v4-flash); pick the route with --provider openrouter or top-level provider = "openrouter".

• Plan — Read-only investigation. Can grep, read files, list directories, fetch URLs. Cannot write or execute shell.
• Work — Normal interactive coding. Tool availability and approval prompts follow the active configuration and permission posture.
• Operate — Direct tools follow the same permission, sandbox, shell, and safety rules as Work. Fleet workers are preferred for independent, parallel, background, or long-running work, but delegation is not mandatory. Workflow is optional for ordered phases and gates.

When the composer is idle, press Tab to cycle modes. Press Shift+Tab to cycle the independent Ask / Auto-Review / Full Access permission posture; Plan remains read-only.

Use codewhale --model auto or /model auto to let Codewhale decide how much model power each turn needs.

Fin is the fast non-thinking path (deepseek-v4-flash with thinking off) used for routing decisions, summaries, RLM children, context maintenance, and other coordination work. Before the real turn is sent, Fin makes a small routing call to pick the concrete model and thinking level.

Short/simple turns can stay on Flash with thinking off. Coding, debugging, release work, architecture, or security review can move up to Pro and/or higher thinking. Fin is local to Codewhale — the upstream API never receives model: "auto".

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

# Cargo mirror (Tsinghua TUNA)
# Add to ~/.cargo/config.toml:
[source.crates-io]
replace-with = "tuna"
[source.tuna]
registry = "sparse+https://mirrors.tuna.tsinghua.edu.cn/crates.io-index/"

Prebuilt binaries are also available from GitHub Releases. A maintained CNB mirror covers its documented targets; no Gitee mirror is advertised until one exists.

codewhale.net and www.codewhale.net are the official Codewhale sites, deployed on Cloudflare. The website source is open and lives under web/ in the Hmbown/CodeWhale repository — anyone can self-deploy it as a mirror.

All official releases and SHA-256 checksums are distributed exclusively through GitHub Releases. The npm package downloads verified binaries from GitHub Releases.

A CNB mirror is maintained for users who cannot reliably reach GitHub (docs/CNB_MIRROR.md). Cargo users can use the TUNA mirror for faster downloads in China.

Self-deployed website copies, mirror sites, and third-party packages are not controlled by the Codewhale project. Verify download sources and checksums.

Run codewhale doctor — it prints a diagnostic report to stdout: config paths, credential-store state (values are never read or printed), provider/local/MCP probes, and release checks.

Common causes:

• Stale DEEPSEEK_API_KEY in shell startup file — open a fresh shell or use codewhale auth set
• Key from wrong provider — make sure the key matches the provider you're using
• Network connectivity — check curl https://api.deepseek.com/v1/models

# Release-binary updater (works for npm/release-binary installs)
codewhale update

# npm
npm install -g codewhale@latest

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

# Homebrew
brew update && brew upgrade codewhale

If you installed via npm, codewhale update downloads the latest release binaries. If a mirror is lagging, download directly from GitHub Releases.