适用场景
这套方案适合两类人：一是团队里已经用 Google Workspace 办公，希望把 Claude 直接嵌进文档、表格、邮件流程里的职场人；二是负责给同事开通账号、做权限与合规把关的 Workspace 管理员。
它能解决的问题很具体：在 Docs 里把一段零散笔记扩写成周报，在 Sheets 里给整列客户留言做分类和摘要，在 Gmail 里把一封二十轮的往来邮件压缩成三条待办。目标是不用复制粘贴到另一个网页，直接在原来干活的地方调用。
需要先说明一点：Claude 接入 Google Workspace 通常有两条路。一条是 Anthropic 在 Google Workspace Marketplace 上架的官方插件（是否上架、支持哪些地区和套餐，以官方页面与 Marketplace 列表为准）；另一条是用 Apps Script 自建，把 Claude API 接进 Docs、Sheets、Gmail。第二条不依赖插件是否对你所在区域开放，代码可照抄，本文把两条路都写清楚，重点放在第二条。
环境与前置条件
账号与权限
- 一个 Google Workspace 账号（企业版或教育版）。个人免费 Gmail 账号能用 Apps Script，但无法使用管理控制台批量放行应用。
- 管理员权限：超级管理员，或被授予「应用管理」相关权限的账号。
- 一个 Anthropic 账号。走自建方案需要 API Key；走官方插件通常需要对应的付费或企业套餐，具体以官方页面为准。
运行时与工具
- 不需要在本地装任何运行时。全部逻辑跑在 Google 的服务器上，客户端只需要一个现代浏览器。
- Apps Script 运行时选 V8（新建项目默认即为 V8）。
- 如果要自建一层转发网关（比如统一记账、限流），一台 1 核 1GB 内存的云主机足够，磁盘 20GB 起步；这类网关是纯文本转发，不需要 GPU 和显存。
合规前置（重要）
- 确认公司是否允许把内部文档内容发送到外部 API。涉及客户数据、合同、财务的表格，建议先在测试组织单元里跑通，再决定放行范围。
- 关掉「任何人都能安装 Marketplace 应用」，改成白名单制。
分步骤部署
第 1 步：判断走哪条路
先打开 Google Workspace Marketplace，搜索 Anthropic 相关的应用，看是否对当前账号所在地区、所用套餐开放。能看到并且能点「管理员安装」，就走官方插件路线；看不到、或者公司不允许装第三方插件，就直接跳到第 4 步走自建路线。
这一步的「成功标志」很简单：Marketplace 页面能正常打开，应用详情页显示支持你的 Workspace 版本。
第 2 步（官方插件路线）：管理员放行应用
用超级管理员登录 Google 管理控制台，进入「应用」→「Google Workspace Marketplace 应用」→「应用访问权限控制」相关页面。不同版本控制台的菜单名称会调整，以你实际看到的菜单为准。
在这里做三件事：
1. 把该应用加入允许列表，或对特定组织单元放行。
2. 选择安装范围：建议先只选一个测试组织单元（比如「技术部」，5～10 人），不要一上来就全员推送。
3. 检查 OAuth 授权范围。如果应用申请的是「读取所有邮件」这类大范围权限，先确认业务上确实需要，能在组织单元级别缩小就缩小。
放行成功后，被授权的用户登录 Gmail 时，右侧会出现该应用的侧边栏入口。
第 3 步（官方插件路线）：用户绑定账号
用户第一次打开侧边栏时，会看到授权引导页，要求用 Anthropic 账号登录并同意授权。走完这一步，侧边栏就能正常输入提示词了。
如果公司用的是 SSO 统一登录，这一步通常由管理员在 Anthropic 后台预先开通席位，用户登录即完成绑定。具体流程以官方文档当前版本为准。
第 4 步（自建路线）：创建 Apps Script 项目
打开一份测试用的 Google 表格，菜单「扩展程序」→「Apps Script」，新建一个绑定到该表格的脚本项目。
接着在左侧「项目设置」里勾选「在编辑器中显示 appsscript.json 清单文件」，然后把清单改成下面这样，声明需要的作用域：
```json
{
"timeZone": "Asia/Shanghai",
"runtimeVersion": "V8",
"exceptionLogging": "STACKDRIVER",
"oauthScopes": [
"https://www.googleapis.com/auth/script.external_request",
"https://www.googleapis.com/auth/script.container.ui",
"https://www.googleapis.com/auth/spreadsheets.currentonly",
"https://www.googleapis.com/auth/documents.currentonly"
]
}
```
script.external_request 是调用外部 API 的关键作用域，少了它会在运行时报「请求失败」。后面如果要处理邮件，再补上 Gmail 的只读作用域。
第 5 步（自建路线）：写入 API Key 与模型 ID
不要把密钥硬编码在代码里。在 Apps Script 左侧「项目设置」→「脚本属性」中新增两条：
ANTHROPIC_API_KEY：你的密钥CLAUDE_MODEL：你要使用的模型 ID，从官方文档当前版本的模型列表里取
这样做的意义是：脚本可以分享给同事，密钥不会跟着代码一起泄露。
第 6 步（自建路线）：写核心调用函数
在代码编辑器中新建 Code.gs，粘贴以下内容：
```javascript
const API_URL = 'https://api.anthropic.com/v1/messages';
const ANTHROPIC_VERSION = '2023-06-01';
function claude(prompt, maxAI 词典：Token">Tokens) {
const props = PropertiesService.getScriptProperties();
const apiKey = props.getProperty('ANTHROPIC_API_KEY');
const model = props.getProperty('CLAUDE_MODEL');
if (!apiKey || !model) {
throw new Error('请先在脚本属性中配置 ANTHROPIC_API_KEY 与 CLAUDE_MODEL');
}
const payload = {
model: model,
max_tokens: maxTokens || 1024,
messages: [{ role: 'user', content: prompt }]
};
const res = UrlFetchApp.fetch(API_URL, {
method: 'post',
contentType: 'application/json',
headers: {
'x-api-key': apiKey,
'anthropic-version': ANTHROPIC_VERSION
},
payload: JSON.stringify(payload),
muteHttpExceptions: true
});
const code = res.getResponseCode();
const body = JSON.parse(res.getContentText());
if (code !== 200) {
const msg = body && body.error && body.error.message ? body.error.message : res.getContentText();
throw new Error('API 返回 ' + code + '：' + msg);
}
return body.content.map(function (item) { return item.text || ''; }).join('');
}
```
这段代码做三件事：从脚本属性取密钥、拼装请求体、把返回的文本片段拼成完整字符串。max_tokens 控制输出长度，直接关系到费用，建议按场景分别设置：做摘要给 512，做改写给 1024，做长文起草再给更大值。
第 7 步（自建路线）：在 Sheets 里加一个自定义函数
同一个项目里新建 Sheets.gs：
```javascript
function CLAUDE(prompt) {
if (!prompt) return '';
const cache = CacheService.getScriptCache();
const digest = Utilities.computeDigest(
Utilities.DigestAlgorithm.SHA_256, String(prompt)
);
const key = 'claude_' + Utilities.base64EncodeWebSafe(digest);
const hit = cache.get(key);
if (hit) return hit;
const out = claude(String(prompt), 512);
cache.put(key, out, 21600); // 缓存 6 小时，避免重复计费
return out;
}
```
保存后回到表格，在任意单元格输入：
```
=CLAUDE("把这句话改写成专业但不生硬的客户回复：" & A2)
```
第一次运行会弹出授权窗口，同意即可。缓存这一步别省，表格每次重算都会触发函数调用，没有缓存会反复产生费用。
一个实际用法：A 列是客户留言，B 列放公式 =CLAUDE("用不超过 20 字概括这条反馈的问题类型：" & A2)，向下填充，几百条留言几分钟就能分类完。
第 8 步（自建路线）：在 Docs 里做起草与改写
新建 Docs.gs，加一个菜单入口：
```javascript
function onOpen() {
DocumentApp.getUi()
.createMenu('Claude 助手')
.addItem('润色选中段落', 'polishSelection')
.addItem('生成待办清单', 'makeTodo')
.addToUi();
}
function polishSelection() {
const doc = DocumentApp.getActiveDocument();
const selection = doc.getSelection();
if (!selection) {
DocumentApp.getUi().alert('请先选中一段文字');
return;
}
const text = selection.getRangeElements()
.map(function (el) { return el.getElement().asText().getText(); })
.join('\n');
const out = claude('把下面的文字润色成正式的周报语气，保持原意，不要加新事实：\n\n' + text, 1024);
const body = doc.getBody();
body.appendParagraph('【润色结果】');
body.appendParagraph(out);
}
```
保存后刷新文档页面，顶部菜单栏会出现「Claude 助手」。选中一段草稿，点「润色选中段落」，几秒后文档末尾会追加润色版本。保留原文、把结果追加在后面，是为了方便对照，不满意直接删掉即可。
常用的几个提示词模板，可以直接抄：
- 起草：
根据以下三条要点，写一封给合作方的项目延期说明邮件，语气坦诚，给出新的时间点：…… - 总结：
把下面的会议记录整理成「决议 / 待办 / 待确认」三部分：…… - 改写：
把这段技术描述改写成非技术同事能看懂的话，不超过 150 字：……
第 9 步（自建路线）：把 Gmail 邮件接进来
在项目里补上 Gmail 只读作用域，然后新建 Gmail.gs：
```javascript
function summarizeLatestThread() {
const threads = GmailApp.getInboxThreads(0, 1);
if (!threads.length) return '收件箱为空';
const msgs = threads[0].getMessages();
const text = msgs
.map(function (m) { return m.getPlainBody(); })
.join('\n--- 分隔 ---\n')
.slice(0, 8000); // 控制长度，避免超出上下文
return claude(
'请用中文总结这个邮件线程，输出三部分：1) 三句话摘要 2) 待办事项列表 3) 需要回复的要点。\n\n' + text,
1024
);
}
```
运行一次，在「执行记录」里就能看到摘要结果。想做正式的话，可以在 Google Cloud 项目里把它发布成 Gmail 加载项，让侧边栏直接出现在邮件阅读界面；加载项的部署需要额外配置 Cloud 项目与部署 ID，步骤以官方文档当前版本为准。
.slice(0, 8000) 这行是刻意的：邮件线程动辄几万字，全量丢进去既慢又贵，截断到前 8000 字符通常已经覆盖了核心信息。
验证部署是否成功
按顺序做这四项检查，全部通过即部署成功。
检查一：核心函数能通
在 Apps Script 编辑器运行：
```javascript
function testClaude() {
Logger.log(claude('用一句话说明什么是电子表格', 128));
}
```
预期结果：执行记录里出现一行通顺的中文回答，没有红色报错。
检查二：表格公式可用
在任意单元格输入 =CLAUDE("把 A1 的内容概括成 10 个字：" & A1)。预期结果：单元格显示概括文本，而不是 #ERROR!。
检查三：文档菜单出现
刷新 Google 文档页面，顶部菜单栏应出现「Claude 助手」。点击「润色选中段落」并选中文字，预期结果：文档末尾追加润色后的段落。
检查四：网络与鉴权正常
如果返回的是 HTTP 状态码，正常应为 200。看到 401 说明密钥或请求头有问题，看到 403 说明权限或账号状态有问题，看到 429 说明调用频率超限。这三类在下一节展开。
常见报错与解决
报错 1：API 返回 401：invalid x-api-key
原因：脚本属性里的密钥写错、粘贴时带了空格，或者请求头里没带 x-api-key 字段。
解决：打开「项目设置」→「脚本属性」，删除 ANTHROPIC_API_KEY 后重新粘贴，注意首尾不要有空格。改完重新运行验证脚本。
```
重新写入后运行 testClaude()，确认返回 200
```
报错 2：API 返回 429：rate_limit_error 或 overloaded_error
原因：并发请求太多，或者表格公式在大范围重算时瞬间打出几十个请求。
解决：一是确保第 7 步的缓存已经生效；二是给调用加退避重试。
```javascript
function claudeWithRetry(prompt) {
let lastErr;
for (let i = 0; i < 3; i++) {
try {
return claude(prompt, 512);
} catch (e) {
lastErr = e;
Utilities.sleep(1000 * Math.pow(2, i)); // 1s / 2s / 4s
}
}
throw lastErr;
}
```
报错 3：Exception: 对 URL 的请求失败 或 Address unavailable
原因：清单文件里缺少 https://www.googleapis.com/auth/script.external_request 作用域，或公司网络策略限制了出站访问。
解决：检查 appsscript.json 中的 oauthScopes，补上该作用域后保存，重新运行一次触发授权。如果仍失败，联系网络管理员确认出站白名单。
报错 4：安装插件时提示「此应用已被屏蔽」
原因：管理员没有在 Google 管理控制台把该 Marketplace 应用加入允许列表。
解决：管理员登录管理控制台，进入「应用」→「Google Workspace Marketplace 应用」，把该应用加入允许列表并对目标组织单元放行。放行后用户需要刷新页面或重新登录。
报错 5：Exceeded maximum execution time
原因：自定义函数单次执行有时间上限，长文本或多轮处理容易超时。
解决：把长任务从公式改成菜单触发的批处理，一次只处理若干行，分批跑；同时通过 max_tokens 和输入截断控制单次请求规模。
报错 6：model: not found 或类似的模型 ID 报错
原因：CLAUDE_MODEL 填了已下线或账号无权访问的模型 ID。
解决：到官方文档当前的模型列表里取一个可用 ID，更新脚本属性后重跑验证。
后续维护
密钥与配置
- 密钥只放在脚本属性或公司的密码管理器里，不进代码、不进共享文档。
- 把
ANTHROPIC_API_KEY、CLAUDE_MODEL、作用域清单整理成一页配置说明，交接时省事。 - 成员离职时，回收 Anthropic 侧席位，并在管理控制台移除对应的应用授权。
备份
- Apps Script 项目用「版本」功能打快照，每次改动前先存档一个版本。
- 表格和文档本身依赖 Workspace 的版本历史，重要文件另存一份到共享盘。
- 脚本属性不随文件一起流转，换项目或复制脚本时记得重新配置。
升级
- 官方插件由 Google 侧自动更新，管理员只需关注新增的授权范围，出现权限扩张时先复核再放行。
- 自建脚本升级模型 ID 或
anthropic-version头之前，先在测试组织单元跑一周，确认输出质量与费用都在预期内。 - 涉及版本号的地方，一律以官方文档当前版本为准，不要照抄旧文章里的 ID。
日志与成本
- Apps Script 的「执行记录」能查每次运行的耗时和错误，配合
exceptionLogging: STACKDRIVER可以把日志汇总到 Cloud Logging。 - 在 Anthropic 控制台的用量页面按周看调用量与 token 消耗，找出异常增长的调用方。
- 三个降本动作：给自定义函数加缓存、按场景区分
max_tokens、对输入做截断。 - 给批量处理加一条人工抽检规则：随机挑 10 条结果核对，尤其是给客户看的邮件草稿，Claude 生成的内容仍需要人来把关后再发送。