FAQ 常见问题

Published channels differ in timing and platform support:

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

# Cargo (needs Rust 1.88+)
cargo install codewhale-cli --locked
cargo install codewhale-tui --locked

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

# 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 these built-in providers:

• 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.
• OpenAI-compatible, 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

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 an OpenRouter model:
codewhale --model openrouter/deepseek/deepseek-v4-pro

# Or set it as default in config.toml:
default_text_model = "openrouter/deepseek/deepseek-v4-pro"

OpenRouter uses the same reasoning/cache parser as the native DeepSeek provider. Model IDs follow the provider/model-id pattern (e.g. openrouter/deepseek/deepseek-v4-flash).

• Plan — Read-only investigation. Can grep, read files, list directories, fetch URLs. Cannot write or execute shell.
• Act — 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 Act. 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 checks API key, network, sandbox, and MCP servers. Full report is written to ~/.codewhale/doctor.log.

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 deepseek-tui

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