01 · 安装

安装 Install

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

codewhale

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

02 · 验证

codewhale --version   # latest published: 0.9.11
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 安装的重跑 codewhale-cli 这一条 cargo install 命令并加 --force； Cargo 只安装 codewhale，如需短名称可自行定义 codew shell alias； Homebrew 用 brew upgrade codewhale。

04 · 首次运行

① 打开第一个会话——无需密钥
无需任何 API 密钥即可启动。简短设置后进入完整界面。先在只读的 Plan 模式里看看。模型回复需要提供商——那是下一步。
```
codewhale
```
② 连接提供商
用托管 API 密钥、网关，或不需要密钥的本地运行时（Ollama、vLLM、SGLang）。提供商和模型都由你来选。模型名不会替你切换提供商。
```
codewhale auth set --provider deepseek
```
提供商与模型 →
③ 在项目目录中运行
```
cd path/to/project
codewhale
```
新会话使用你选择的默认模式（未修改则为 Act）。输入区空闲时，按 Tab 循环 Plan → Act → Operate；按 Shift+Tab 循环 Ask → Auto-Review → Full Access。也可以运行 /mode 选择模式或运行 /config 查看权限。Plan 始终只读；Full Access 仅应用于你信任的工作区。

05 · 其他安装方式

其他安装方式

如果上面的脚本不适合你的环境，从下面选一种。每种方式都写明了它安装什么。

下方的命令安装 v0.9.11，即 GitHub 上最新的发布版本。源码与该版本一致。

npm · Node 18+

npm install -g codewhale

npm wrapper 会从 GitHub Releases 下载经 SHA-256 校验的二进制，并安装 codewhale 和 codew两个命令名；两者运行同一个 runtime。

Rust 工具链

cargo install codewhale-cli --locked

codewhale-cli 这一个 Cargo package 只会把 codewhale 安装到 ~/.cargo/bin。如需较短的 codew 名称，可自行定义 shell alias。需要 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.9.11 codewhale-cli --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

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

Homebrew · macOS / Linux

brew tap Hmbown/deepseek-tui
brew install codewhale

formula 是 codewhale。tap 仓库在重命名前仍叫 Hmbown/homebrew-deepseek-tui；brew tap Hmbown/deepseek-tui 继续有效。旧的 deepseek-tui formula 作为一轮重叠的弃用别名保留。

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

curl -fsSL -O https://github.com/Hmbown/CodeWhale/releases/latest/download/codewhale-artifacts-sha256.txt
curl -fsSL -O \
  https://github.com/Hmbown/CodeWhale/releases/latest/download/codewhale-macos-arm64
curl -fsSL -O \
  https://github.com/Hmbown/CodeWhale/releases/latest/download/codew-macos-arm64
grep -E ' (codewhale|codew)-macos-arm64$' codewhale-artifacts-sha256.txt | shasum -a 256 -c -
chmod +x codewhale-macos-arm64 codew-macos-arm64
xattr -d com.apple.quarantine codewhale-macos-arm64 codew-macos-arm64 2>/dev/null || true
sudo mv codewhale-macos-arm64 /usr/local/bin/codewhale
sudo mv codew-macos-arm64 /usr/local/bin/codew

校验 SHA256

curl -fsSL -O https://github.com/Hmbown/CodeWhale/releases/latest/download/codewhale-artifacts-sha256.txt
verify_binary() {
  asset="$1"
  installed="$2"
  expected=$(awk -v asset="$asset" '$2 == asset { print $1 }' codewhale-artifacts-sha256.txt)
  actual=$(shasum -a 256 "$installed" | awk '{ print $1 }')
  if [ -z "$expected" ] || [ "$actual" != "$expected" ]; then
    echo "$installed checksum mismatch" >&2
    return 1
  fi
}
verify_binary codewhale-macos-arm64 /usr/local/bin/codewhale
verify_binary codew-macos-arm64 /usr/local/bin/codew

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 the compiled runtime as codewhale
cargo install --path crates/cli --locked

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

06 · 配置文件在哪

$CODEWHALE_HOME/（默认：~/.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 · 下一步