01 · 安装

安装 Install

npm install -g codewhale

codewhale

npm 包装器会从 GitHub Releases 下载对应平台的预编译二进制，安装 codewhale 和 codewhale-tui。需要 Node 18+。没有 Node？下方「其他安装方式」列出了 Cargo、Homebrew、直接下载二进制和国内镜像。

02 · 验证

codewhale --version
codewhale doctor

codewhale doctor 检查 API 密钥、网络、沙箱可用性、 MCP 服务器，并将完整报告写入 ~/.codewhale/doctor.log。

03 · 更新

codewhale update

检查 GitHub Releases 是否有新版本并就地替换二进制。通过 Homebrew 或 npm 安装的话，使用包管理器升级更稳：brew upgrade deepseek-tui 或 npm update -g codewhale。 Cargo 安装的可以重跑 cargo install codewhale-cli --locked --force。

04 · 首次运行

① 获取 API 密钥
在 platform.deepseek.com 注册并创建密钥，格式为 sk-...。

② 设置密钥

export DEEPSEEK_API_KEY=sk-...

或保存到 ~/.codewhale/config.toml：

codewhale auth set --provider deepseek --api-key sk-...

③ 在项目目录中运行
```
cd path/to/project
codewhale
```
默认 Plan 模式（只读调查）。按 Tab 切换到 Agent 模式（执行工具，按需审批）。再按一次进入 YOLO 模式（自动批准）。

05 · 其他安装方式

其他安装方式

如果上面的 Cargo 路径不适合你，从下面找到匹配你情况的一条。每条都安装同一个 codewhale 二进制。

Cargo · 需要 Rust 1.88+

cargo install codewhale-cli --locked

从源代码编译并安装 codewhale 到 ~/.cargo/bin。如未安装 Rust，可访问 rustup.rs。

中国大陆网络

Cargo 经清华 Tuna 镜像——添加到 ~/.cargo/config.toml：

# ~/.cargo/config.toml
[source.crates-io]
replace-with = "tuna"

[source.tuna]
registry = "sparse+https://mirrors.tuna.tsinghua.edu.cn/crates.io-index/"

cargo install codewhale-cli --locked

npm 经 npmmirror 镜像：

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

npm 包装器仍会从 github.com/Hmbown/CodeWhale/releases 下载二进制，国内可能较慢。Cargo + Tuna 完全绕开 GitHub。 DeepSeek API（api.deepseek.com）在国内直连，无需代理。

Homebrew · macOS / Linux

brew tap Hmbown/deepseek-tui
brew install deepseek-tui

预编译二进制 · 已自动检测

curl -fsSL -o codewhale \
  https://github.com/Hmbown/CodeWhale/releases/latest/download/codewhale-macos-arm64
curl -fsSL -o codewhale-tui \
  https://github.com/Hmbown/CodeWhale/releases/latest/download/codewhale-tui-macos-arm64
chmod +x codewhale codewhale-tui
xattr -d com.apple.quarantine codewhale codewhale-tui 2>/dev/null || true
sudo mv codewhale codewhale-tui /usr/local/bin/

校验 SHA256

curl -fsSL -O https://github.com/Hmbown/CodeWhale/releases/latest/download/codewhale-artifacts-sha256.txt
shasum -a 256 -c codewhale-artifacts-sha256.txt --ignore-missing

Docker

git clone https://github.com/Hmbown/CodeWhale
cd codewhale
docker build -t codewhale .

docker run --rm -it \
 -e DEEPSEEK_API_KEY=$DEEPSEEK_API_KEY \
 -v ~/.codewhale:/home/codewhale/.codewhale \
 -v "$PWD:/work" -w /work \
 codewhale

支持 multi-arch buildx。目前没有发布到镜像仓库，需要本地构建。

从源码编译

git clone https://github.com/Hmbown/CodeWhale
cd codewhale
cargo build --release --locked

# Install both binaries from the local checkout
cargo install --path crates/cli --locked # codewhale
cargo install --path crates/tui --locked # codewhale-tui

适合本地修改 workspace 或贡献补丁。

06 · 配置文件在哪

~/.codewhale/
├── config.toml API 密钥、模型、钩子、配置集
├── mcp.json MCP 服务器定义
├── skills/ 用户技能（每个含 SKILL.md）
├── sessions/ 检查点 + 离线队列
├── tasks/ 后台任务存储
└── audit.log 凭证 / 审批 / 提权审计日志

./.codewhale/ 项目级配置（可选，每个仓库）

项目级 ./.codewhale/ 目录是可选的——每个仓库可有独立的 MCP 服务器、钩子、技能和配置覆盖（例如提供商密钥）。首次运行时，如果缺少配置文件，系统会询问是否交互式创建。

07 · 下一步