+ +

+ Claude Code Open 操作手册 + 从零开始，手把手教你使用开源 AI 编程平台 +

+ +

+ 在线体验 Demo + GitHub 源码 +

+ + +

一、什么是 Claude Code Open？

+ +

Claude Code Open 是一个开源的 AI 编程平台，它把 Claude AI 变成一个能直接操作你电脑的编程助手——不只是聊天，它能：

+ +
    +
  • 直接读写你的代码文件 — 不用复制粘贴
    • +
  • 运行终端命令 — npm、git、docker 都行
    • +
  • 搜索整个代码库 — 秒级定位任何代码
    • +
  • 操作浏览器 — 自动化测试、截图
    • +
  • 管理 Git 仓库 — 提交、推送、创建 PR
    • +
  • 多个 AI Agent 协作 — 复杂任务自动分解并行
    • +
+ +

简单说：它是一个住在你电脑里的全栈工程师。

+ +Web UI 主界面 +

Web UI 主界面 — 集聊天、代码编辑、蓝图规划于一体

+ + + +

二、安装

+ +

Windows 一键安装（推荐）

+ +

最简单的方式——下载双击即可：

+ +
+
1
+
+ 下载安装脚本： + install.bat + （国内用户：Gitee 镜像） +
+
+ +
+
2
+
双击运行 install.bat
+
+ +
+
3
+
等待自动完成（安装 Node.js、依赖、构建前端）
+
+ +
+
4
+
桌面出现 "Claude Code WebUI" 快捷方式，双击打开
+
+ +
+ 安装完成后 + 浏览器自动打开 http://localhost:3456，你就能看到 Web UI 了。 +
+ +

macOS / Linux 安装

+ +

一行命令搞定：

+
curl -fsSL https://raw.githubusercontent.com/kill136/claude-code-open/private_web_ui/install.sh | bash
+ +

国内镜像加速：

+
curl -fsSL https://gitee.com/lubanbbs/claude-code-open/raw/private_web_ui/install.sh | bash
+ +

Docker 部署

+ +
# 构建镜像
+docker build -t claude-code-open .
+
+# 运行 Web UI
+docker run -it \
+  -e ANTHROPIC_API_KEY=你的API密钥 \
+  -p 3456:3456 \
+  -v $(pwd):/workspace \
+  claude-code-open node /app/dist/web-cli.js --host 0.0.0.0
+ +

然后访问 http://localhost:3456。

+ +

手动安装（开发者）

+ +
git clone https://github.com/kill136/claude-code-open.git
+cd claude-code-open
+npm install
+
+# 构建前端
+cd src/web/client && npm install && npm run build && cd ../../..
+
+# 构建后端
+npm run build
+
+# 启动 Web UI
+npm run web
+ + + +

三、首次配置

+ +

获取 API Key

+ +

你需要一个 Anthropic API Key 来使用 Claude AI：

+ +
+
1
+
访问 console.anthropic.com
+
+
+
2
+
注册账号
+
+
+
3
+
进入 API Keys 页面
+
+
+
4
+
点击 Create Key，复制生成的密钥（以 sk-ant- 开头）
+
+ +
+ 费用说明 + Anthropic API 按使用量计费。Haiku 模型最便宜，Opus 最贵但最聪明。新用户通常有免费额度。 +
+ +

配置 API Key

+ +

方式一：通过 Web UI 设置（推荐）

+
    +
  1. 点击右上角 齿轮图标 打开设置
    2. +
  2. 点击左侧 "API 高级" 选项卡
    3. +
  3. 在 API Key 输入框粘贴你的密钥
    4. +
  4. （可选）修改 API Base URL 如果你使用代理/中转服务
    5. +
  5. 点击保存
    6. +
+ +

方式二：通过环境变量

+
# Linux / macOS
+export ANTHROPIC_API_KEY=sk-ant-你的密钥
+
+# Windows PowerShell
+$env:ANTHROPIC_API_KEY="sk-ant-你的密钥"
+
+# Windows CMD
+set ANTHROPIC_API_KEY=sk-ant-你的密钥
+ +

方式三：通过配置文件

+
// ~/.claude/settings.json
+{
+  "apiKey": "sk-ant-你的密钥"
+}
+ +

选择模型

+ +

在输入框左下角的模型下拉菜单中选择：

+ + + + + + +
模型特点适合场景
Opus最强大、最聪明复杂架构设计、深度代码分析
Sonnet性价比最高 推荐日常编程、代码修改
Haiku最快、最便宜简单问答、快速搜索
+ +
+ 建议 + 日常使用选 Sonnet，遇到复杂问题切换到 Opus。 +
+ + + +

四、Web UI 快速上手

+ +

界面总览

+ +
┌─────────────────────────────────────────────────────────┐ +│ 📁 项目选择 💬 会话选择 ➕ 🔍 ⚙️ 设置 │ ← 顶部导航栏 +├─────────────────────────────────────────────────────────┤ +│ 💬 聊天 📋 蓝图 🐝 蜂群 ⏰ 定时任务 │ ← 功能标签页 +├─────────────────────────────────────────────────────────┤ +│ │ +│ 对话内容区域 │ +│ │ +├─────────────────────────────────────────────────────────┤ +│ 输入框 模型选择 权限模式 📎 🎤 ... │ ← 底部工具栏 +└─────────────────────────────────────────────────────────┘
+ +

右上角功能按钮（从左到右）：

+
    +
  • API Console — API 探针，查看请求详情
    • +
  • ≡ / </> — 切换对话视图、代码视图
    • +
+ +

发送第一条消息

+ +
+
1
+
在底部输入框输入你的问题，例如：帮我分析一下当前项目的目录结构
+
+
+
2
+
点击发送按钮（或按 Enter）
+
+
+
3
+
AI 开始分析并实时流式输出回复
+
+ +

你可以让它做的事情（示例）：

+ + + + + + + + + +
你说的话AI 做的事
"帮我读一下 src/index.ts"调用 Read 工具读取文件内容
"在 utils.ts 里加个日期格式化函数"调用 Edit 工具直接修改代码
"运行 npm test 看看测试结果"调用 Bash 工具执行命令
"搜索项目里所有用到 useState 的地方"调用 Grep 工具搜索代码
"帮我把这个 Bug 修了"综合使用多个工具分析并修复
"帮我写个完整的用户认证模块"蓝图系统分解任务，多 Agent 协作完成
+ +

权限模式说明

+ +

底部工具栏有一个权限模式下拉菜单，控制 AI 操作文件的权限：

+ + + + + + + +
模式安全性说明
🔒 询问最安全每次修改文件前都会问你确认
📝 自动编辑中等自动执行文件编辑，危险操作仍会询问
⚡ YOLO高风险全自动，不询问直接执行
📋 计划安全AI 先制定计划让你审核，批准后再执行
+ +
+ 新手建议 + 先用"询问"模式熟悉 AI 的操作方式，之后根据信任程度提升到"自动编辑"。 +
+ + + +

五、核心功能详解

+ +

5.1 聊天对话

+ +

这是最基础的功能——和 AI 对话。但它不只是聊天，AI 可以调用 37+ 种工具来实际操作你的系统。

+ +

对话中的工具调用：当 AI 需要操作时，会展示工具调用的过程。例如：

+
🔧 Read — 读取 src/index.ts
+   ✅ 成功读取 245 行
+ +

附件上传：点击底部 📎 图标可以上传文件（图片、代码文件等），AI 能直接分析上传的内容。

+ +

语音输入：点击 🎤 图标开启语音识别，说出你的需求，自动转为文字发送。

+ +

5.2 代码视图

+ +

点击右上角 </> 图标切换到代码视图，类似 VS Code 的三栏布局：

+ +
┌──────────┬────────────────────┬─────────────┐ +│ 文件树 │ 代码编辑器 │ 对话面板 │ +│ │ (Monaco Editor) │ │ +│ 📁 src │ │ 你: ... │ +│ 📁 docs │ function foo() │ AI: ... │ +│ 📄 ... │ { ... } │ │ +└──────────┴────────────────────┴─────────────┘
+ +

功能亮点：

+
    +
  • 文件树 — 浏览和打开项目文件
    • +
  • Monaco Editor — 语法高亮、多标签页编辑
    • +
  • AI 对话面板 — 边看代码边和 AI 讨论
    • +
  • 右键菜单 — 选中代码后右键可以 "Ask AI"
    • +
+ +
+ 技巧 + 在代码视图中选中一段代码，然后对 AI 说"解释这段代码"或"优化这段代码"，它能精准定位你选中的内容。 +
+ +

5.3 蓝图系统（Blueprint）

+ +

点击 "蓝图" 标签页进入蓝图系统。

+ +蓝图系统 +

蓝图页面 — 可视化展示项目模块结构

+ +

什么是蓝图？蓝图是对项目的"全景扫描"——AI 分析你的整个代码库，识别出模块结构、业务流程和依赖关系。

+ +

使用场景：

+
    +
  • 新接手一个项目，想快速了解架构
    • +
  • 要做大型重构，需要先理解依赖关系
    • +
  • 向团队成员介绍项目结构
    • +
+ +

如何使用：在聊天中说：

+
帮我分析一下当前项目，生成蓝图
+ +

5.4 蜂群多 Agent 协作（Swarm）

+ +

点击 "蜂群" 标签页进入蜂群面板。

+ +蜂群系统 +

蜂群面板 — 多个 AI Agent 并行工作

+ +

什么是蜂群？当你有一个复杂的大任务（比如"帮我从零搭建一个电商后端"），单个 AI 处理太慢。蜂群系统会：

+ +
+
1
+
Smart Planner 分解任务为多个子任务
+
+
+
2
+
Lead Agent 分配任务给多个 Worker
+
+
+
3
+
多个 Worker Agent 并行工作
+
+
+
4
+
Reviewer 检查每个 Worker 的产出质量
+
+ +

在聊天中描述复杂任务即可触发。也可以明确要求：

+
用蓝图系统帮我实现一个完整的用户管理模块，包含注册、登录、权限控制
+ +

5.5 定时任务

+ +

点击 "定时任务" 标签页管理定时任务。

+ + + + + + +
类型说明示例
单次在指定时间执行一次"2小时后提醒我检查构建结果"
周期性按固定间隔重复执行"每天早上9点运行代码审查"
文件监控监控文件变化自动触发"src/ 有变动时自动运行测试"
+ +

创建方式——在聊天中用自然语言：

+
帮我创建一个定时任务，每天上午10点检查 Git 仓库状态并生成报告
+ +

或者在定时任务页面点击 "+ 新建任务" 按钮。

+ +

5.6 斜杠命令

+ +

在输入框输入 / 可以看到所有可用命令：

+ + + + + + + + + + + + + +
命令说明
/help显示帮助信息
/clear清空当前对话
/compact压缩对话历史（节省 Token）
/status查看当前会话状态
/model查看/切换模型
/fast切换快速模式
/tools列出所有可用工具
/config查看配置
/export导出会话（JSON/Markdown）
/resume恢复之前的会话
+ + + +

六、进阶用法

+ +

6.1 CLAUDE.md 项目规则

+ +

在项目根目录创建 CLAUDE.md 文件，写入你的项目规则和约束。AI 每次启动都会自动读取这个文件。

+ +

这是最强大的配置手段——相当于给 AI 员工一份"工作手册"。

+ +
## 项目约定
+- 使用 TypeScript strict 模式
+- 所有组件用函数式写法，禁止 class 组件
+- CSS 使用 Tailwind，不写内联样式
+
+## 代码风格
+- 缩进 2 空格
+- 字符串用单引号
+
+## 禁止事项
+- 不要动 package.json 的依赖版本
+- 不要修改 .env 文件
+- 不要"顺手优化"不相关的代码
+ +
+ 关键理解 + 每次新对话，AI 都是全新实例（没有记忆）。CLAUDE.md 是唯一跨对话持久生效的"规则约束"。 +
+ +

6.2 Skills 技能系统

+ +

Skills 是封装好的工作流，可以通过 / 命令一键触发。

+ +

内置技能举例：

+
    +
  • /code-review — 代码审查
    • +
  • /analyze-logs — 分析运行日志
    • +
  • /skill-hub — 搜索和安装社区技能
    • +
+ +

创建自定义 Skill：在 .claude/skills/my-skill/SKILL.md 创建文件：

+ +
---
+description: "自动化部署到测试环境"
+user-invocable: true
+---
+
+# 部署到测试环境
+
+1. 运行 `npm run build` 构建项目
+2. 运行 `npm test` 确保测试通过
+3. 执行 `rsync -avz dist/ user@server:/app/`
+4. 验证部署成功
+ +

然后在对话中输入 /my-skill 即可触发。

+ +

6.3 MCP 协议扩展

+ +

MCP (Model Context Protocol) 让 AI 能连接外部工具和服务。编辑 ~/.claude/settings.json：

+ +
{
+  "mcpServers": {
+    "filesystem": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/your/path"]
+    },
+    "github": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "env": { "GITHUB_TOKEN": "你的 GitHub Token" }
+    }
+  }
+}
+ +

或者在 Web UI 设置页面的 "MCP" 选项卡中配置。

+ +

6.4 Hooks 钩子系统

+ +

Hooks 让你在 AI 的工具调用前后自动执行自定义脚本：

+ +
{
+  "hooks": [
+    {
+      "event": "PostToolUse",
+      "matcher": "Write",
+      "command": "npx prettier --write ${FILE_PATH}",
+      "blocking": false
+    }
+  ]
+}
+ + + + + + + + + +
事件触发时机
PreToolUse工具调用前
PostToolUse工具调用后
PrePromptSubmit用户发消息前
PostPromptSubmit用户发消息后
NotificationAI 发通知时
StopAI 停止响应时
+ +

6.5 自我进化模式

+ +

这是最独特的功能——AI 可以修改自己的代码。

+ +
npm run web:evolve
+ +

启用后，AI 可以：

+
    +
  • 阅读自己的源代码
    • +
  • 修改系统提示词、工具逻辑
    • +
  • 添加新工具
    • +
  • 安装 MCP 服务器
    • +
  • 热重载自动生效
    • +
+ +
+ 安全机制 + 每次修改前会运行 TypeScript 编译检查，确保不会搞坏自己。 +
+ + + +

七、CLI 命令行模式

+ +

除了 Web UI，你也可以在终端中使用命令行模式：

+ +
# 交互式对话
+node dist/cli.js
+
+# 带初始问题
+node dist/cli.js "帮我分析这个项目"
+
+# 打印模式（非交互，适合脚本）
+node dist/cli.js -p "解释一下 src/index.ts"
+
+# 指定模型
+node dist/cli.js -m sonnet "简单问题用便宜模型"
+
+# 恢复上次对话
+node dist/cli.js --resume
+
+# 列出历史对话
+node dist/cli.js --list
+ + + +

八、常见问题

+ +
+

Q: API Key 报错 "Invalid API Key"

+

确认密钥以 sk-ant- 开头；检查是否有多余空格；确认 Anthropic 账号有余额；如果用代理，检查 API Base URL 是否正确。

+
+ +
+

Q: npm install 报错

+

检查 Node.js 版本 >= 18（node -v）；设置 npm 镜像：npm config set registry https://registry.npmmirror.com；Windows 原生编译失败通常不影响使用。

+
+ +
+

Q: Web UI 打开是空白页

+

确认前端已构建：ls src/web/client/dist/；如果没有 dist 目录，运行 cd src/web/client && npm run build。

+
+ +
+

Q: AI 回复很慢

+

切换到 Haiku 模型（最快）；使用 /compact 压缩对话历史；检查网络连接。

+
+ +
+

Q: 如何使用中转 API / 第三方 API？

+

在设置 "API 高级" 中修改 API Base URL，例如 https://your-proxy.com/v1，支持任何兼容 Anthropic API 格式的服务。

+
+ +
+

Q: AI 修改了不该改的文件

+

使用"询问"权限模式；在 CLAUDE.md 中明确写入"禁止修改 xxx"；使用 Git 随时 git checkout -- . 回滚。

+
+ + + +

九、获取帮助

+ +

+ 提交 Issue + 加入 Discord + 在线体验 +

+ + + + + +
+

本手册最后更新：2026-02-26

+

Claude Code Open — 让 AI 不只是聊天，而是真正帮你干活

+
+ +