Trình môi giới bí mật 1Password

Plugin onepassword đi kèm cung cấp cho các tác nhân một công cụ duy nhất được kiểm soát bằng chính sách để đọc một tập hợp trường 1Password đã tuyển chọn. Plugin bị tắt theo mặc định và không hoạt động cho đến khi có plugins.entries.onepassword.config.

Đây là công cụ dành cho tác nhân, không phải nhà cung cấp SecretRef. Công cụ này không chèn biến môi trường hoặc phân giải bí mật cấu hình OpenClaw.

Mô hình bảo mật

• Chỉ xác thực bằng tài khoản dịch vụ. Token nằm trong một tệp thông tin xác thực cục bộ và không bao giờ được chấp nhận trong openclaw.json.
• Chỉ dùng registry đã tuyển chọn. Tác nhân có thể liệt kê các slug đã cấu hình, nhưng plugin không bao giờ liệt kê nội dung của vault 1Password.
• Chính sách auto, approve hoặc deny cho từng slug.
• Quyền cấp phê duyệt sẽ hết hạn. Giá trị đã lưu trong bộ nhớ đệm không bao giờ bỏ qua chính sách hiện hành.
• Mọi lần thử truy cập đều được ghi lại trong trạng thái SQLite dùng chung của OpenClaw. Các hàng kiểm tra bao gồm lý do được cung cấp; hãy đảm bảo lý do không chứa thông tin nhạy cảm. Trình môi giới không bao giờ sao chép giá trị đã truy xuất hoặc token dịch vụ vào hàng kiểm tra.
• Sau khi quá trình thực thi công cụ hiện tại kết thúc, cơ chế lưu giữ bản chép lời do OpenClaw sở hữu sẽ thay thế giá trị get thành công bằng siêu dữ liệu đã che.
• Giá trị hiển thị với mô hình trong lần thực thi đó. Nếu mô hình sao chép giá trị này vào một lệnh gọi công cụ hoặc phản hồi sau đó, bản ghi riêng biệt đó nằm ngoài hook lưu giữ của plugin này. Hãy giới hạn chính sách chặt chẽ và không yêu cầu mô hình lặp lại giá trị.
• Plugin gọi op một lần cho mỗi lần trượt bộ nhớ đệm. Plugin không thử lại khi gặp giới hạn tốc độ hoặc lỗi khác.
• Mỗi lệnh gọi op chạy với môi trường tối thiểu vô hiệu hóa khả năng tích hợp ứng dụng máy tính 1Password (OP_LOAD_DESKTOP_APP_SETTINGS=false, OP_BIOMETRIC_UNLOCK_ENABLED=false), để ứng dụng 1Password được cài đặt trên máy chủ Gateway không bao giờ kích hoạt hộp thoại sinh trắc học hoặc quyền của macOS.

Chỉ cấp cho tài khoản dịch vụ quyền đọc các vault và mục đã đăng ký trong cấu hình plugin.

Trước khi bắt đầu

Bạn cần:

• CLI 1Password (op) được cài đặt trên máy chủ Gateway
• một tài khoản dịch vụ 1Password có quyền truy cập các mục đã chọn
• một tệp token chuyên dụng cho tài khoản dịch vụ

Bật plugin đi kèm:

openclaw plugins enable onepassword

Tạo thư mục và tệp token trong thư mục trạng thái OpenClaw:

mkdir -p ~/.openclaw/credentials/onepasswordchmod 700 ~/.openclaw/credentials/onepasswordprintf '%s' "$OP_SERVICE_ACCOUNT_TOKEN" > \  ~/.openclaw/credentials/onepassword/service-account-tokenchmod 600 ~/.openclaw/credentials/onepassword/service-account-tokenunset OP_SERVICE_ACCOUNT_TOKEN

Khi OPENCLAW_STATE_DIR được đặt, hãy thay ~/.openclaw bằng thư mục đó. Plugin cảnh báo một lần khi nhóm hoặc người dùng khác có thể đọc hoặc ghi tệp token.

Cấu hình bí mật đã đăng ký

Thêm cấu hình plugin vào openclaw.json:

{  "plugins": {    "entries": {      "onepassword": {        "enabled": true,        "config": {          "vault": "Automation",          "defaultPolicy": "approve",          "cacheTtlSeconds": 300,          "grantTtlHours": 720,          "opTimeoutMs": 15000,          "items": {            "repository-token": {              "item": "Repository automation token",              "field": "credential",              "policy": "approve",              "description": "Token for repository automation",            },            "model-key": {              "item": "Model provider key",              "vault": "Agent credentials",              "policy": "auto",            },          },        },      },    },  },}

Slug sử dụng chữ thường, chữ số và dấu gạch nối, bắt đầu bằng chữ cái hoặc chữ số và có tối đa 64 ký tự. Một registry có thể chứa tối đa 32 slug; phần mô tả có thể chứa tối đa 200 ký tự. field chấp nhận một nhãn hoặc ID trường, không được chứa dấu phẩy và mặc định là credential. vault ở cấp mục ghi đè vault mặc định. opBin có thể đặt đường dẫn tuyệt đối đến tệp thực thi op; nếu không, plugin phân giải op từ PATH. Tiêu đề mục không được bắt đầu bằng dấu gạch nối.

Sử dụng công cụ tác nhân

Tên công cụ là onepassword.

Liệt kê các slug đã đăng ký:

{ "action": "list" }

Kết quả chỉ chứa slug, mô tả, chính sách và trạng thái quyền cấp thường trực có đang hoạt động hay không. Kết quả không bao giờ chứa giá trị bí mật và không truy vấn 1Password.

Yêu cầu một bí mật:

{  "action": "get",  "slug": "repository-token",  "reason": "Authenticate the requested repository operation"}

reason là bắt buộc, không được để trống và bị giới hạn ở 300 ký tự. Một get thành công trả về giá trị cùng với slug, tiêu đề mục và nhãn trường đã cấu hình.

Lược đồ công cụ cũng khai báo một tham số authorizationNonce nội bộ. Lớp chính sách chèn tham số này sau khi đánh giá yêu cầu để chuyển quyền cho lệnh gọi công cụ đang thực thi. Không bao giờ đặt tham số này theo cách thủ công: hook chính sách sẽ ghi đè mọi giá trị được cung cấp và giá trị không xác định sẽ khiến yêu cầu thất bại.

Các cấp chính sách và phê duyệt

• auto: truy xuất ngay lập tức và kiểm tra yêu cầu.
• deny: chặn và kiểm tra yêu cầu.
• approve: sử dụng quyền cấp thường trực chưa hết hạn hoặc yêu cầu một người cho phép một lần, luôn cho phép hoặc từ chối.

Cho phép một lần chỉ cấp quyền cho lệnh gọi công cụ hiện tại. Luôn cho phép ghi một quyền cấp thường trực cho tác nhân và slug đó vào SQLite; các tác nhân khác phải được phê duyệt riêng. OpenClaw chỉ cung cấp tùy chọn luôn cho phép khi bên gọi có danh tính tác nhân cụ thể. Quyền cấp hết hạn sau grantTtlHours, mặc định là 720 giờ. Yêu cầu phê duyệt chưa được giải quyết hoặc hết thời gian chờ sẽ bị từ chối; thời gian chờ phê duyệt tối đa là 600 giây. Plugin lưu giữ tối đa 1.024 quyền cấp thường trực; khi đạt giới hạn này, quyền cấp cũ nhất sẽ bị loại bỏ và tác nhân tương ứng phải phê duyệt lần truy cập tiếp theo.

Mỗi quyền được đánh giá chỉ dùng một lần và được chuyển cho lệnh gọi công cụ đang thực thi thông qua trạng thái SQLite dùng chung, vì vậy quá trình chuyển giao cũng hoạt động khi có nhiều hơn một phiên bản plugin đang hoạt động trong tiến trình Gateway. Các quyền không được sử dụng sẽ hết hạn sau cửa sổ phê duyệt 600 giây.

Bộ nhớ đệm trong bộ nhớ mặc định là 300 giây và bị giới hạn theo registry slug đã cấu hình. Đặt cacheTtlSeconds thành 0 để vô hiệu hóa. Chính sách được đánh giá trước mỗi lần tra cứu bộ nhớ đệm và các lần trúng bộ nhớ đệm đều được kiểm tra. Việc tải lại cấu hình trong thời gian chạy có hiệu lực tại mỗi ranh giới chính sách và thực thi; tắt plugin hoặc xóa, từ chối hay đổi đích một slug sẽ làm mất hiệu lực quyền đang chờ và các giá trị đã lưu trong bộ nhớ đệm.

Kiểm tra trạng thái và lịch sử kiểm tra

Hiển thị trạng thái sẵn sàng và số lượng trong registry:

openclaw onepassword status

Lệnh này báo cáo tệp token có tồn tại hay không, op có được phân giải hay không cùng đường dẫn của nó, số lượng mục đã đăng ký và số lượng theo từng chính sách. Lệnh không bao giờ đọc hoặc in token hay giá trị bí mật.

Hiển thị 50 hàng kiểm tra gần nhất:

openclaw onepassword auditopenclaw onepassword audit --limit 100

Các hàng mới nhất được hiển thị trước và cho biết dấu thời gian, tác nhân, slug, kết quả, một errorCode khi lần thử thất bại và lý do đã rút gọn. Lý do được lưu đúng như đã cung cấp; trình môi giới không bao giờ thêm giá trị đã truy xuất vào nhật ký kiểm tra.

Hành vi của CLI 1Password

Mỗi lần trượt bộ nhớ đệm sẽ chạy op item get với mục, vault và bộ chọn trường chính xác đã cấu hình, đầu ra JSON, thời gian chờ hữu hạn và --cache=false. Tiến trình con chỉ nhận trường đó thay vì toàn bộ mục. Chỉ OP_SERVICE_ACCOUNT_TOKEN và HOME có trong môi trường của tiến trình con.

Plugin chỉ thử một lần. Các lỗi RATE_LIMITED nên được xử lý bằng cách chờ trước khi tác nhân gửi yêu cầu sau; plugin không tạo vòng lặp thử lại tự động.

Mã lỗi

Các lần thử thất bại mang một mã lỗi đóng trong kết quả công cụ và hàng kiểm tra.

Lỗi truy cập 1Password:

Lỗi chính sách và xác thực đầu vào: