01 · 安装

安装 Install

curl -fsSL https://codewhale.net/install.sh | sh

codewhale

macOS / Linux 安装脚本会从 GitHub Releases 下载经 SHA-256 校验的二进制，默认安装到 ~/.local/bin，并安装 codewhale、codew 和 codewhale-tui。先审阅脚本可运行 curl -fsSL https://codewhale.net/install.sh。下方「其他安装方式」列出 npm、Cargo、GitHub Releases、 CNB、国内镜像、Homebrew、预编译二进制和 Docker。

02 · 验证

codewhale --version   # 0.8.68
codewhale doctor

codewhale doctor 检查 API 密钥、网络、沙箱可用性、 MCP 服务器，并在终端输出修复建议；需要结构化输出时可加 --json。

03 · 更新

codewhale update

curl -fsSL https://codewhale.net/install.sh | sh

检查 GitHub Releases 是否有新版本并就地替换二进制。通过 install.sh 安装的用户也可以重跑同一条 curl 命令覆盖更新。通过包管理器安装的话，用包管理器升级更稳：npm 安装的运行 npm update -g codewhale； Cargo 安装的重跑两个 cargo install 命令并加 --force；旧版 Homebrew tap 用 brew upgrade deepseek-tui。

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 · 其他安装方式

其他安装方式

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

npm · Node 18+

npm install -g codewhale

npm wrapper 会从 GitHub Releases 下载经 SHA-256 校验的二进制，并安装 codewhale、codew 和 codewhale-tui 三个命令。

Rust 工具链

cargo install codewhale-cli --locked
cargo install codewhale-tui --locked

编译并安装 codewhale 和 codewhale-tui 到 ~/.cargo/bin。需要 Rust 1.88+；Linux 用户先安装 pkg-config 和 libdbus-1-dev 等构建依赖。如未安装 Rust，可访问 rustup.rs。

GitHub Releases

# Download your platform archive:
https://github.com/Hmbown/CodeWhale/releases/latest

CNB 镜像

cargo install --git https://cnb.cool/codewhale.net/codewhale --tag v0.8.68 codewhale-cli --locked --force
cargo install --git https://cnb.cool/codewhale.net/codewhale --tag v0.8.68 codewhale-tui --locked --force

中国大陆网络

官方源：GitHub Releases 为唯一官方发布源。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
cargo install codewhale-tui --locked

npm 安装时设置 CODEWHALE_USE_CNB_MIRROR=1， wrapper 会改从 CNB 镜像下载二进制而不是 GitHub。Cargo + Tuna 或 CNB 路径同样可以绕开 GitHub 下载瓶颈。 DeepSeek API（api.deepseek.com）在国内直连，无需代理。

Homebrew · macOS / Linux · 旧版 tap

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

这是旧版 deepseek-tui tap，在 formula 重命名为 codewhale 期间保留以保证兼容，安装的同样是当前版本的二进制。

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

curl -fsSL -O https://github.com/Hmbown/CodeWhale/releases/latest/download/codewhale-artifacts-sha256.txt
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
grep -E ' (codewhale|codewhale-tui)-macos-arm64$' codewhale-artifacts-sha256.txt | shasum -a 256 -c -
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

grep -E ' (codewhale|codewhale-tui)-macos-arm64$' codewhale-artifacts-sha256.txt | shasum -a 256 -c -

Docker

docker volume create codewhale-home
docker run --rm -it \
  -e DEEPSEEK_API_KEY=$DEEPSEEK_API_KEY \
  -v codewhale-home:/home/codewhale/.codewhale \
  -v "$PWD:/workspace" -w /workspace \
  ghcr.io/hmbown/codewhale:latest

发布镜像位于 GHCR。需要固定版本时，把 latest 替换成具体的发布标签。

从源码编译

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 服务器、钩子、技能和配置覆盖（例如提供商密钥）。首次运行时，如果缺少配置文件，系统会询问是否交互式创建。旧版 ~/.deepseek 和 ./.deepseek 路径仍会作为兼容回退读取。

07 · 来源与镜像

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

官方发布

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

CNB 镜像

面向无法稳定访问 GitHub 的用户，提供 CNB 镜像（docs/CNB_MIRROR.md）。镜像仓库由社区成员维护，发布延迟可能为几小时。

TUNA / 包镜像

Cargo 用户可通过 TUNA（清华大学开源镜像站）加速下载。这些镜像由第三方维护，CodeWhale 项目不控制镜像内容。

自行部署

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

08 · 下一步