✦claudeHarness

安装与使用指南

把 Claude 请进团队，
像同事一样交代工作。

这份指南带你从零把 claudeHarness 装到自己的服务器上，再到团队用飞书扫码登录、开始干活。跟着做就行，每一步都有示例。

⏱ 通读约 10 分钟 🧩 动手安装约 15 分钟 🎬 代码项目、网页终端有录屏演示 💬 遇到问题看末尾常见问题

AI 工作台：左边是项目和对话，中间是和 Claude 的对话，右边是产出的文件 — AI 工作台的真实界面

开始前，准备好三样东西

都备齐了，后面会很顺

🖥一台 Linux 服务器（64 位，x86_64，带 systemd——常见的 Ubuntu、Debian、CentOS 都行），你能用它的管理员账号（可以 sudo）。
🔑一个安装 Key，形如 CH-XXXX-XXXX-XXXX-XXXX，由发行方发给你。一个 Key 对应一台服务器。
📱一个飞书账号，用来扫码登录。第一个登录的人会成为这套系统的超级管理员。

💡

用订阅账号的客户：发行方若让你用 Claude 订阅登录，先在服务器上用官方命令装好并登录一次 Claude（curl -fsSL https://claude.ai/install.sh | bash 然后执行 claude 按提示登录）。用 API Key 方式的客户不需要这一步，装完在网页里填 Key 即可——按发行方告诉你的方式来。

安装：一条命令

自己敲，或交给 AI 助手

🤖 交给 AI 助手不想自己动手？把下面这段话复制给你的 AI 助手（Claude 等），让它远程帮你装。

请帮我在我的 Linux 服务器上安装 claudeHarness。
详细安装步骤见这份说明，请先完整读它再按步骤操作：https://pkg.feiyushuju.com/dl/guide.md

我可以提供：
1) 安装 Key：CH-XXXX-XXXX-XXXX-XXXX（把这里换成发行方给我的 Key）
2) 域名（可选，没有就用服务器 IP 访问）：
3) 服务器上哪个账号登录了 Claude（通常就是我 SSH 登录的账号）：

服务器是 Linux x86_64、带 systemd、我有 sudo 权限。请通过 SSH 连上去按说明一步步安装；遇到需要我在浏览器里完成的步骤（飞书扫码授权、登录），请告诉我怎么做。

记得先把里面的 Key 换成你自己的

或者自己来：登录到你的服务器，从下面挑一条和你情况相符的命令，点「复制命令」，把 CH-XXXX-… 换成发行方给你的 Key 后粘贴执行。参数都写在 -- 后面，域名必须跟在 --domain 后面，不要把域名直接当成参数写。

A · 没有域名，用服务器 IP 访问（最常见）

# 把 CH-XXXX-… 换成你的 Key
$ curl -fsSL https://pkg.feiyushuju.com/dl/install.sh | sudo bash -s -- --key CH-XXXX-XXXX-XXXX-XXXX

B · 有域名，自动配好 HTTPS

# 换成你的 Key 和域名（域名要先解析到这台服务器）
$ curl -fsSL https://pkg.feiyushuju.com/dl/install.sh | sudo bash -s -- --key CH-XXXX-XXXX-XXXX-XXXX --domain ai.example.com

C · 登录 Claude 的账号不是执行 sudo 的账号

# ubuntu 换成在服务器上登录过 Claude 的那个 Linux 账号
# 没有域名就去掉 --domain 和后面的域名
$ curl -fsSL https://pkg.feiyushuju.com/dl/install.sh | sudo bash -s -- --key CH-XXXX-XXXX-XXXX-XXXX --domain ai.example.com --claude-user ubuntu

容易写错的地方：❌ --ai.example.com（域名前少了 --domain，脚本会提示「不认识的参数」）；❌ --key=CH-…（不要用等号，参数和值之间用空格）。参数顺序随意，每个参数都是「--名字值」。

💡

服务器上已经有宝塔或 nginx 在用 80/443 端口？没关系，不用你动手：脚本会自动在你现有的宝塔/nginx 里加好这个域名的 HTTPS 站点，不影响你已有的网站。80/443 被其他程序占用时，会改用 https://你的域名:8443 或 http://…:8787，并在安装结束时告诉你要在安全组放行哪些端口。其余步骤不变。

脚本会自己检查环境、校验 Key、下载并核对安装包、装好并启动服务。顺利的话，最后你会看到这样的结果：

安装输出

✓ 系统：Ubuntu 24.04，x86_64，systemd
✓ Key 有效（尾号 2R64，认证方式：Claude 订阅登录）
✓ 已下载并核对 SHA-256 和发行方签名
✓ 服务已启动（开机自动启动）

安装完成
  网页地址：http://你的服务器IP:8787
  下一步 — 用浏览器打开一次性设置链接：
  http://你的服务器IP:8787/setup#token=…

记下最后那条 一次性设置链接，下一步要用。忘了也没关系：在服务器上执行 sudo claudeharness status 能再看到它。如果安装结束时提示“还需要你做一件事：在安全组里放行 TCP 端口 …”，请到云服务器控制台照做（腾讯云：实例 › 安全组；轻量服务器：防火墙），放行之后再打开链接。服务器自己的防火墙脚本已经自动放行了。

首次设置：用飞书授权

在浏览器里完成，只做一次

用浏览器打开刚才那条一次性设置链接。页面会让你用飞书扫码，自动创建一个飞书应用（用于团队登录），并提交一个审批。这个链接只能用一次——这样别人即使知道你的网址，也抢不走管理员。

🔒你的服务器IP:8787/setup

用飞书扫码，按页面提示创建应用并提交审批

示例二维码 · 实际请用你页面上的那个

首次设置页：扫码创建飞书应用

1管理员用飞书扫码，系统自动创建飞书应用，并提交审批。
2飞书里审批通过后，回页面点一下“重新检查/继续”，几秒即可生效。
3用飞书登录，你就成了这套系统的超级管理员，之后可以在后台授权其他同事进来，也可以在「成员」页把同事设为管理员，或把超级管理员转让给别人。

💡

想让同事用飞书登录更顺，建议配一个域名（安装时加 --domain）。飞书的登录回调会用你当前访问的地址，域名比纯 IP 更稳妥。

团队登录

以后每天就这一下

设置好以后，团队成员打开网址，点“使用企业飞书账号继续”扫码即可。只有管理员授权过的飞书成员能进来。

一切正常时页面顶部没有任何提示；如果哪里没配好，顶部会出现一条提醒，并给出下一步，例如：

Claude 尚未登录 —— 请在服务器上用对应账号执行 claude 登录

尚未填写 API Key —— 在「系统管理 › 授权中心」里填入自己的 Key

功能介绍

像给同事派活一样说话

下面每个功能都配了真实界面截图（点图看大图）和可以直接复制的示例。内容以一个亚马逊跨境电商团队为例，其他行业换成自己的业务即可。

首页

所有人

登录后先到首页：顶部输入框直接用大白话说要做什么，回车就开始。旁边是正在执行、等你处理、最近产出的文件；管理员还能看到团队近 7 天的用量和团队共享额度（Claude 订阅本身的 5 小时、7 天额度，大家一起用）。

首页：问候、输入框、正在执行和等你处理的数量、团队近 7 天用量 — 首页：一句话开工，待处理的事一眼看到

AI 工作台

所有人

左侧菜单「AI 工作台」点“新建对话”，可以拖入或粘贴文件（Excel、PDF、图片都行）。对话按项目归类；Claude 会读附件、写代码算数据、画图、出文件，产出的文件都在右边，点开就能预览和下载。

Claude 要执行命令前会先弹出“需要你确认”，你点「允许」它才动手——看一眼内容，没问题就允许。

对话里的审批卡片（已允许）、执行过程、结果表格 — 执行命令前先问你；结果直接是表格

试试这些说法（点「复制」，粘到输入框里改成你的情况）：

选品

附件是美国站宠物用品类目的热销榜。帮我找月销 300 单以上、评论少于 500 条、售价 15–35 美元的机会品，按机会分排序，输出 Excel，再画一张近 6 个月的销量趋势图。

写 Listing

帮我的 2.5L 静音宠物饮水机写英文 Listing：标题 200 字符以内，五点描述，再给 5 个后台搜索词。卖点：25 分贝、滤芯好清洗、不漏水、1.8 米电源线。

差评分析

这是竞品的评论导出，帮我找出差评里的主要痛点，按提及次数排序，给出我们产品的改进建议，结果做成 Excel。

算利润

售价 29.99 美元，采购 6.8 美元，头程按 0.45 公斤海运，帮我算一下 FBA 单件利润和利润率，广告按 ACoS 18% 估，做成能改数字自动重算的 Excel。

客服

有客户说饮水机用了一个月底座漏水，帮我写一封英文回复邮件，语气诚恳，提供免费换新，并请对方发一张漏水照片。

技能（打 / 或 $ 选用）

所有人

在输入框打 / 或 $ 会弹出技能菜单，选中的技能变成输入框上方的标签（点 × 去掉），可以选多个。只有选过的技能才交给 AI，没选的 AI 看不到；同一个对话里选过一次，后面几轮都能接着用。平台自带「写文档」（doc-writer）和「前端设计」（frontend-design）两个技能。

先选 doc-writer

按我们饮水机的情况，做一份 Q4 黑五广告投放方案，写成 Word，包含目标、节奏、预算分配和关键词。

代码项目：让 Claude 直接改网站

管理员打开可选，默认关闭

把服务器上的网站或项目文件夹交给 Claude：在对话里说要什么，它直接改这个文件夹，说一句“启动预览”就能在浏览器里看效果。下面这段 1 分钟的录屏，演示了从提要求到看到做好的网站的全过程（无声，有字幕讲解）：

01管理员把服务器上的网站文件夹登记成代码项目
02在对话里提要求，选上「前端设计」技能
03Claude 改好文件；说“启动预览”
04点「打开预览」，看到做好的网站

代码项目详情：项目目录、运行身份、授权开发者 — 项目页：项目所在的文件夹、谁能改它

在「系统管理 › 代码项目」打开后，管理员可以把服务器上的项目文件夹交给 Claude：先选项目所在的文件夹——有文件的直接登记，空文件夹（或当场新建的）从空项目开始，也可以上传压缩包解压进去。项目里的对话直接改这个文件夹，改了马上生效（大家可以同时改，互相看得到会话）；平台在每次改动前后自动存档（保留 30 天），你在对话里说“撤销”或“回到某个时间点”就从存档恢复；需要构建的项目说“重启”。预览在单独的一份拷贝里运行，不影响正在运行的网站。改 nginx、装系统软件这类撤销不了的事，Claude 会先问你（切到完全访问权限后不再问）。

缺 git、python3 时，在那一页点「让平台安装」即可；成员要由管理员在项目页逐个授权。卸载平台不会删除任何项目文件夹。脚本自动加到宝塔/nginx 里的站点已经设好了上传上限，不用改；只有你自己配的反向代理，上传大压缩包前才需要在站点配置里加 client_max_body_size 500m;。

先选前端设计

给我们的宠物饮水机做一个独立站首页，面向美国客户，英文。要有首屏主张、三个卖点、规格、用户评价和黑五优惠按钮，风格温暖、高级一点。

看效果

启动预览，让我看看效果。

改错了

撤销刚才那一轮的改动。

网页终端

默认只有管理员

管理员在「系统管理 › 网页终端」可以直接在网页上操作服务器（以服务账号运行，和 SSH 登录一样），也可以给成员授权，被授权的人只能在自己有权限的代码项目对话里打开终端。终端里输入的命令有记录。想在服务器上彻底关掉：sudo claudeharness terminal off（terminal on 恢复）。

01打开「系统管理 › 网页终端」，就是服务器的命令行
02输入命令、回车执行：进目录、看文件、改文件
03查看磁盘、内存等服务器状态
04每条命令都有记录；也能授权给成员

常用的几条命令（点「复制」，粘到终端里回车）：

磁盘

df -h

内存

free -h

平台状态

claudeharness status

宝塔网站目录

cd /www/wwwroot && ls -lh

终端以服务账号运行，能打开终端的人就能操作整台服务器（服务以 root 运行时就是 root）。只授权给信得过的人；删除、改配置这类命令，执行前看清楚。

完全访问与成员联网

管理员设置

完全访问（默认关闭）：平时 Claude 每执行一条命令都要你点「允许」。管理员在「系统管理 › 完全访问」打开总开关并给成员授权后，被授权的人可以在输入框下方把项目切到完全访问权限：命令自动执行，不再逐条询问（Claude 向你提问时仍由你选）。关机重启、改写磁盘、删除项目以外的目录、修改系统账号仍会先问你。不想要这个功能：把 /etc/claudeharness/env 里的 CH_FULL_ACCESS 改成 off 并重启服务。

成员联网（默认开启）：成员的对话默认可以访问外网（AI 执行的命令、技能里的脚本、联网搜索）。管理员在「系统管理 › 成员联网」可以关掉总开关或单独关掉某个成员。开着也访问不了这台服务器自己和云平台内部接口。

飞书通知与额度预警

管理员设置可选

管理员在「系统管理 › 飞书通知」里绑定一个飞书群机器人后，谁的会话产出了文件，群里就会收到一条消息并真的 @ 到这个人，还带文件的下载链接。也可以在那里立即发送一条消息到群，默认 @全体、也能单独 @ 某几个人。只有管理员看得到这个设置。

同一页还有额度预警与限制：团队共享的 Claude 额度（5 小时、7 天）剩余低于设定比例（默认 10%）时，往群里提醒一次、重置时报「已恢复」，成员发消息时网页上也提醒一次；还可以选择达到阈值后停止成员使用，直到额度重置（管理员不受限）。群里收到的预警文字可以改（5 小时、7 天各一份，可插入已用、剩余、重置时间等占位，旁边实时预览）。额度只读 Claude 自己记录的数据，不额外请求。

飞运营群 · claudeHarness 机器人

✅ 会话《美国站宠物用品选品分析》已完成，产出 2 个文件：
• 选品机会表.xlsx　下载
• 月销趋势.png　下载
@运营-小林

群里收到的通知（@ 为真实提醒，文件链接点开需登录）

成员与全部会话

管理员

「系统管理 › 成员管理」里授权飞书同事进来、停用、设为管理员，或把超级管理员转让给别人；「用量统计」能看到每个人用了多少（成员自己看不到别人的）。「全部会话」以只读方式查看成员的对话记录，每次打开都会记在审计日志里。

技能仓库

管理员

管理员在「系统管理 › 技能仓库」点「上传技能」：先选平台技能（只在平台对话里用，重名时优先）或服务器技能（放进 ~/.claude/skills/，服务器终端里的 Claude 也能用），再选一个压缩包（zip、tar.gz 等，最大 10 MB），平台检查后列出要装的技能，确认就装好。服务器技能也可以直接把技能文件夹放进服务运行账号的 ~/.claude/skills/，几秒后自动出现。开着的技能才会出现在对话的菜单里；Claude 自带的技能默认关着，用得上的再打开。技能文件所有人都能读到，不要把密钥直接写在里面。

技能仓库：平台技能、服务器技能、Claude 自带技能，每个一个开关 — 技能仓库：一个开关管一个技能

授权中心

管理员

「系统管理 › 授权中心」一页看清：授权是否正常、用的是 Claude 订阅还是 API Key、团队共享额度、当前版本。有新版本时这里会提示，点「立即更新」即可（见下一节）。

网站设计

管理员

「系统管理 › 网站设计」可以改网站名称、主题色、布局、页脚和水印，「网站标志」换成自己公司的 LOGO，对所有成员生效。

🌐

想换成域名访问？请联系我们帮你换；也可以在服务器上重新运行安装命令并带上 --domain 新域名（原来的数据和飞书设置都保留，飞书登录地址会自动更新）。重新运行安装命令时不带 --domain，访问地址保持不变。

升级与卸载

都在服务器上执行

① 网页一键升级（推荐，不用敲命令）

有新版本时，管理员打开「系统管理 › 授权中心」页会看到提示，点 「立即更新」 → 二次确认 → 系统自己下载、校验、备份、切换、重启，全程有进度动画；更新会中断正在进行的对话（更新完成后可以继续聊），升级前核对数据库备份、启动失败时尝试回滚、永不降级。从 1.12.0 或更早版本升级、服务以普通账号运行的，第一次请在服务器上执行 sudo claudeharness update，之后网页上的「立即更新」就能用了。网页上的更新、装工具由平台的 root 助手执行；sudo claudeharness doctor 报它没在运行时，执行 sudo bash /opt/claudeharness/install.sh install-root-helper 修复。

授权中心：有新版本时出现「立即更新」 — ① 授权中心出现新版本，点「立即更新」

更新进度：下载、校验、备份、切换重启、完成 — ② 自动下载、校验、备份、重启，全程看得到进度

② 或在服务器上执行命令

升级到最新版

# 会中断正在进行的对话，完成后可继续
$ sudo claudeharness update

扫码创建飞书应用时默认拒绝升级，下载前和停服前都会检查。sudo claudeharness update --force 会绕过保护并打断创建，仅在确认可以中断时使用。备份失败会停止升级；回滚结果以更新日志为准。

首次创建失败且尚未记录应用时，先核查飞书应用列表，再重置并刷新原安装页面：

恢复首次安装

# 先确认没有残留应用；保留访问地址和安装会话
$ sudo claudeharness setup-reset

想自检一下有没有问题、或看当前状态：

查看状态 / 自检

# 状态、网址、授权、Claude 登录
$ claudeharness status

# 一键自检，有问题会标出来
$ sudo claudeharness doctor

卸载时，默认保留你的数据（对话、文件、设置都还在，重装会接着用）：

卸载

# 卸载，保留数据（重装会接着用）
$ sudo claudeharness uninstall

# 连数据一起删，不可恢复
$ sudo claudeharness uninstall --purge --yes

--purge 会把对话、上传的文件、设置和 Key 全部删掉且无法恢复，确认要删才加 --yes。你自己的 Claude 登录不受影响。

💡

用了「代码项目」的：不管哪种卸载，你的项目文件夹都不会被删，网站和代码都还在原处；不需要的话请自己删除。带 --purge 卸载时，项目的存档（“撤销到之前的样子”用的记录）会一起删掉，之后就不能再撤销了。

更新记录

只展示历史最近的 5 个版本，每个版本更新了哪些地方

升级方法见上一节。有没有新版本、能不能升级，以「系统管理 › 授权中心」里的提示为准。

1.15.02026-10-17

技能：新增「技能仓库」，管理员统一上传、开关技能；对话里打 / 或 $ 选技能，选中的以标签显示
内置技能：新增「前端设计」，做网页、界面更有设计感
安装：服务器上已有宝塔或 nginx 时，自动在其中配好访问地址，不影响原有网站
界面：操作结果改为右上角通知；稳定性改进

升级后，服务器上原有的技能先关着，需要的在「技能仓库」里打开。

1.14.02026-10-16

网页终端：统一为深色样式
首页：更简洁，授权和新版本提醒移到页面顶部
稳定性改进

1.13.02026-10-16

多管理员：可以设置、取消管理员，超级管理员可以转让
团队额度：首页显示 Claude 订阅的共享额度，快用完时可在飞书群提醒
升级：网页上的「立即更新」更稳定
飞书通知：设置页重新设计

1.12.02026-10-15

代码项目：把服务器上的项目文件夹交给 Claude 直接改，自动存档、可以撤销，能预览效果
完全访问：管理员可以给成员开启，命令自动执行、不再逐条询问
网页终端：在网页上直接操作服务器，命令有记录
安装：自动装好需要的工具；稳定性改进

1.11.02026-10-13

界面：网页整体改版，首页、AI 工作台、系统管理各页重新设计
网站设计：可以改主题色和布局，换成自己公司的 LOGO
对话：底部显示上下文用量
首页卡顿等问题修复

常见问题

大多数卡点都在这里

安装停在了中间怎么办？＋

仍在显示二维码或创建中时，先等结果或过期。页面有“重试”时，完成飞书审批后重试配置；有“重新开始”时，先到飞书开放平台确认没有残留应用，或已删除本次失败创建的残留应用，再勾选确认并重新开始。也可核查后执行 sudo claudeharness setup-reset，刷新原安装页面。已记录应用、安装完成或仍在创建时不能重置。旧版没有该入口或命令时，等创建进入失败状态，再更新后恢复。

提示“Key 无效”怎么办？＋

先核对 Key 有没有填错（形如 CH-XXXX-XXXX-XXXX-XXXX）。如果发行方刚给你重新生成过 Key，要用新的那个，并在服务器上执行 sudo claudeharness set-key 新Key。

提示“这个 Key 已绑定在另一台机器上”？＋

一个 Key 只能用在一台服务器上。换机器需要联系发行方在后台解绑，之后新机器才能用同一个 Key 激活。

安装或更新时提示“现在下载的人比较多”？＋

发行服务器同一时间下载的人数有限，满了会先请你等一会儿。这时什么都还没改，已经安装的版本照常能用。过 1–2 分钟重新执行安装命令，或在网页上再点一次「立即更新」即可。

网页打不开？＋

多半是云服务器的安全组没放行。在服务器上执行 sudo claudeharness status，按里面“还需要你做一件事”提示的端口（可能是 80/443、8443 或 8787），到云控制台放行即可（腾讯云：实例 › 安全组；轻量服务器：防火墙）。服务器自己的防火墙安装脚本已自动放行。证书还在申请中时也会暂时打不开，一般几分钟。还不行就执行 sudo claudeharness doctor --fix。

卸载会动我的网站吗？＋

不会。卸载只撤掉安装脚本自己加的东西：加到宝塔/nginx 里的那个站点、它的证书、放行的端口。你原有的网站和设置不动。

网页上点「立即更新」没反应、一直卡住？＋

多半是从 1.12.0 或更早版本升级、服务以普通账号运行：旧版的网页按钮执行不了。请在服务器上执行一次 sudo claudeharness update，之后网页上的「立即更新」就能用了。sudo claudeharness doctor 可以检查是否一切正常。

想换一台服务器怎么办？＋

在旧服务器上 sudo claudeharness uninstall（如需带走数据另行备份 /var/lib/claudeharness），请发行方解绑这个 Key，然后在新服务器上用同一条安装命令重新安装即可。

“审批”是什么？为什么要点？＋

当 Claude 需要执行某些动手操作（比如运行命令）时，会先弹出审批让你确认。这是为了安全——你同意了它才会做。看一眼内容，没问题就允许。