CodeWhale Web客户端：codewhale web浏览器操作终端Agent完整教程
【免费下载链接】CodeWhaleOpen-source coding agent for your terminal, built in Rust and on a journey of continuous community improvement. Issues and PRs welcome.项目地址: https://gitcode.com/GitHub_Trending/de/CodeWhale
CodeWhale 是一款用 Rust 编写的开源终端编码 Agent（coding agent），而它的Web 客户端——一条codewhale web命令——就能把这位"终端 Agent"直接搬进你的浏览器：无需安装任何前端依赖，客户端页面内嵌在二进制里，启动即开。本教程带你 3 步跑通，并讲清它的安全边界。
适合人群：已经（或刚刚）安装好 CodeWhale 的新手用户。
一、先认识 CodeWhale 的终端 Agent
在启动 Web 客户端之前，先看一眼 CodeWhale 在终端里的样子——深色主题、鲸鱼 ASCII 艺术、顶部实时显示模型与 token 用量，底部输入框随时待命：
Web 客户端并不是"第二个 Agent"，而是同一本地 Runtime 的另一副视图：浏览器里看到的会话、工具回执、审批请求，和终端里看到的完全一致。相关实现位于 runtime_web/app.mjs 与 runtime_web/index.html。
二、安装 CodeWhale（前置条件）
如果你还没装好 CodeWhale，两种方式任选其一：
- 源码安装（适合开发者）：
git clone https://gitcode.com/GitHub_Trending/de/CodeWhale cd CodeWhale cargo build --release- 下载预编译发布包：项目每个版本都会发布预编译二进制，选择对应平台的压缩包解压即可，发布页如下所示：
验证安装成功：
codewhale --version能打印出版本号，就说明终端 Agent 已就位。🦄
三、三步启动 codewhale web 浏览器客户端
第 1 步：进入你的工作目录
Web 客户端会操作当前目录下的仓库，所以先进入你要让 Agent 干活的项目：
cd /path/to/your/project第 2 步：运行 codewhale web
codewhale web这条命令会同时做四件事：
- 启动 Runtime API 服务（默认地址
http://127.0.0.1:7878，端口参数见 lib.rs）； - 从二进制中释放内嵌的无依赖浏览器客户端；
- 在终端打印一个一次性启动 URL；
- 调用系统默认浏览器打开该 URL。
如果端口 7878 被占用，换个回环端口即可：
codewhale web --port 8788第 3 步：在浏览器里开始对话
打开后你会看到左侧的会话轨道（Threads 面板）和右侧的对话区：可以"New thread"新建线程、搜索历史线程、查看保存的会话。界面风格如下（深色 Web 客户端主题）：
⚠️ 注意：如果浏览器没有自动弹出，请在10 分钟内手动复制终端里打印的那个 URL（一次性引导凭证 10 分钟后失效）。
四、浏览器里能做什么：Agent 常用操作清单
这个内嵌客户端提供了和终端对等的核心能力：
| 操作 | 说明 |
|---|---|
| 🧵 新建 / 选择 / 重命名 / 归档线程 | 左侧会话轨道一键完成 |
| ▶️ 发起或引导对话轮次 | 在底部输入框描述任务即可 |
| ⏹️ 中断正在执行的任务 | 点击 Stop 按钮 |
| ✅ 处理审批请求 | Agent 执行敏感命令前的 approval 可直接在页面批准/拒绝 |
| ❓ 回答 Runtime 的用户输入请求 | Agent 提问时页面会弹出待办，直接作答 |
它还能实时呈现工具调用的回执（receipts）与完整转录。多个任务并行分发时的"扇出"效果，动画演示如下：
五、为什么它是安全的：只属于"本地"的本地
很多用户担心"把 Agent 放进浏览器会不会泄密"。CodeWhale 的设计答案很干脆——本地即本地（Local means local）：
- 服务永远绑定
127.0.0.1，codewhale web只提供--port，没有--host选项，无法重绑到局域网； - 浏览器启动 URL 里是随机、短效、一次性的引导凭证，绝不含 Runtime 令牌；访问后凭证立即作废，会话升级为进程本地的
HttpOnlyCookie； - 浏览器不创建第二套云账号，不往浏览器存储里拷贝模型密钥，也不削弱你已配置的审批与沙箱策略；
- 请勿把它当作公网网站，不要通过路由器端口转发、公网反向代理或隧道暴露该端口。
完整认证边界说明见官方文档 docs/WEB.md 与 docs/RUNTIME_API.md。
六、常见问题速查（Troubleshooting）
Q1：提示端口 7878 被占用？换一个空闲端口：codewhale web --port 8788。
Q2：浏览器没自动打开？把终端打印的一次性 URL 复制到同一台机器的浏览器里，10 分钟内有效；已用过或过期的 URL 需重新运行codewhale web生成新的。
Q3：页面能打开，但提示某个模型供应商（provider）不可用？Web 命令不负责配置模型密钥。运行codewhale doctor体检，并检查/provider接口输出，按提示补全供应商凭证。
Q4：提示会话已过期？Ctrl+C停掉旧进程，重新运行codewhale web即可铸造新的进程本地会话；旧引导 URL 复用失败是预期行为。
七、延伸阅读
- 📖 Web 客户端完整文档：docs/WEB.md
- 🔌 Runtime API 集成契约（端点、请求头、事件流）：docs/RUNTIME_API.md
- 📄 沙箱与审批策略：docs/SANDBOX.md
- 🏗️ 项目架构总览：docs/ARCHITECTURE.md
现在，打开终端，敲下codewhale web，你的终端 Agent 就已经住进浏览器了。🚀
【免费下载链接】CodeWhaleOpen-source coding agent for your terminal, built in Rust and on a journey of continuous community improvement. Issues and PRs welcome.项目地址: https://gitcode.com/GitHub_Trending/de/CodeWhale
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
